3.1.4.2 One dimensional arrays

A couple of functions declared in ‘matcon.h’ are concerned mainly with one dimensional arrays or vectors. They have been used for vectors of double precision and complex numbers, but are applicable to any base type that is contiguous and of a fixed size.

The motivation for these functions is to enable a developer to present an API to virtual code applications wherein external library functions operating natively on one dimensional arrays of numbers are seen from the virtual side to operate on lists of numbers. Lists are the preferred container for interoperability with virtual code applications.

Function: void *avm_vector_of_list (list operand, size_t item_size, list *message, int *fault)

This function calls avm_value_of_list (Primitive types) for each item of the operand and puts all the values together into one contiguous block, whose address is returned.

The given item_size is required to be the lengths of the items, all necessarily equal, and is required only for validation. For example, item_size is 8 for a list of double precision numbers, because they occupy 8 bytes each and are represented as lists of length 8.

The total number of bytes allocated is the product of item_size and the length of the operand. Unlike the case of avm_value_of_list (Primitive types), the result returned by this function should be explicitly freed by the caller when no longer needed.

Any errors such as insufficient memory cause the integer referenced by fault to be assigned a non-zero value and the message to be assigned an error message represented as a list of strings. An error message of <'bad vector specification'> is possible in the case of an empty operand or one whose item lengths don’t match the given item_size. Error messages caused by avm_value_of_list can also be generated by this function. Any non-empty error message should be reclaimed by the caller using avm_dispose (Simple Operations). If an error occurs, a NULL pointer is returned.

Function: list avm_list_of_vector (void *vector, int num_items, size_t item_size, int *fault)

This function takes it on faith that an array of dimension num_items in which each item occupies item_size bytes begins at the address given by vector. A list representation of each item in the array is constructed by the function avm_list_of_value (Primitive types), and a list of all of the lists thus obtained in order of their position in the array is returned.

In the event of any errors caused by avm_list_of_value or errors due to insufficient memory, the error message is returned as the function result, and the integer referenced by fault is assigned a non-zero value. The error message is in the form of a list of character string representations. A segmentation fault is possible if vector is not a valid pointer or if the array size implied by misspecified values of num_items and item_size exceeds its actual size.

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