3.1.3 List Transformations

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.

Function: void avm_initialize_listfuns ()

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.

Function: void avm_count_listfuns ()

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.

Function: list avm_reversal (list operand, int *fault)

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.

Function: list avm_distribution (list operand, int *fault)

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.

Function: list avm_concatenation (list operand, int *fault)

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 the tail field. The invalid concatenation message is returned in the event of a NULL operand. The result returned otherwise is the concatenation of the lists, but the given operand still exists unchanged.

Function: list avm_transposition (list operand, int *fault)

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 from avm_copied. The invalid transpose error message is the result if the operand does not represent a list of equal length lists.

Function: list avm_membership (list operand, int *fault)

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 the head. If the item is not found, a NULL list is returned, but otherwise a list with NULL head and tail fields is returned. If the operand is NULL, an error message of invalid membership is returned and *fault is set to a non-zero value.

The avm_membership function calls avm_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 file compare.h or to call avm_initialize_compare in order to use avm_membership, because they will be done automatically.

Function: list avm_binary_membership (list operand, list members, int *fault);

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.

Function: list avm_measurement (list operand, int *fault)

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.

This document was generated on December 10, 2012 using texi2html 1.82.