Some functions declared in listfuns.h are used to implement the
operations described in List Functions. These functions are able
to report error messages in the event of overflow or other exceptional
conditions, as described in Error Messages. The error messages are
represented as lists and returned to the caller. The occurrence of an
error can be detected by the *
fault flag being set to a
non-zero value. None of these functions ever causes a program exit except
in the event of an internal error.
This has to be called before any of the other functions in this section is called. It initializes the error message lists, among other things.
At the end of a run, a call to this function can verify that no unreclaimed storage attributable to these functions persists. If it does, a warning is printed to standard error. If
avm_count_lists
is also used, it must be called after this function.
The reversal of the list is returned by this function if no overflow occurs. A non-zero
*
fault and an error message are returned otherwise. The original operand still exists in its original order after this function is called. The amount of additional storage allocated is proportional only to the length of the list, not the size of its contents.
This function performs the operation described in Distribute. The invalid distribution message is returned in the event of a
NULL
operand. Otherwise, the returned value is the distributed list. In any event, the operand is unaffected.
The operand is treated as a pair of lists to be concatenated, with the left one in the
head
field and the right one in thetail
field. The invalid concatenation message is returned in the event of aNULL
operand. The result returned otherwise is the concatenation of the lists, but the given operand still exists unchanged.
The operation performed by this function corresponds to that of Transpose. Unlike other functions in this section, the operand passed to this function is deallocated, and must not be referenced thereafter. The transposed list is accessible as the returned value of this function. If the original operand is still needed after a call to
avm_transposition
, only a copy of it should be passed to it, obtained fromavm_copied
. The invalid transpose error message is the result if the operand does not represent a list of equal length lists.
This function computes the membership predicate described in Member. The operand is a list in which the
tail
field is a list that will be searched for the item in thehead
. If the item is not found, aNULL
list is returned, but otherwise a list withNULL
head
andtail
fields is returned. If the operand isNULL
, an error message of invalid membership is returned and*
fault is set to a non-zero value.The
avm_membership
function callsavm_binary_comparison
in order to compare lists, so the same efficiency and side-effect considerations are relevant to both (Comparison). It is not necessary to#include
the header filecompare.h
or to callavm_initialize_compare
in order to useavm_membership
, because they will be done automatically.
This function is the same as
avm_membership
except that it allows the element and the set of members to be passed as separate lists instead of being the head and the tail of the same list.
This function implements the operation described in Weight, which pertains to the weight of a tree. The returned value of this function is a list encoding the weight as a binary number, unless a counter overflow occurs, in which case it's an error message. As noted previously, the weight of a tree can easily be exponentially larger than the amount of memory it occupies, but this function uses native integer arithmetic for performance reasons. Hence, a counter overflow is a real possibility.