2.5. Arrays

An array is an aggregate of data of a common type, which can be accessed with one or more nonnegative indices. ECL stores arrays as a C structure with a pointer to the region of memory which contains the actual data. The cell of an array datatype varies depending on whether it is a vector, a bytevector, a multidimensional array or a string.

If x contains a vector, you can access the following fields:

x->vector.elttype

The type of the elements of the vector.

x->vector.dim

The maximum number of elements.

x->vector.fillp

Actual number of elements in the vector or "fill pointer".

x->vector.self

Union of pointers of different types. You should choose the right pointer depending on x->vector.elltype

x->vector.hasfillp

Whether x->vector.fillp can be smaller than x->vector.dim.

If x contains a multidimensional array, the cell elements become

x->array.elttype

The type of the elements of the array.

x->array.dim

Number of elements in the array.

x->array.rank

Number of dimensions of the array.

x->array.dims[]

Array with the dimensions of the array. The elements range from x->array.dim[0] to x->array.dim[x->array.rank-1].

x->array.self

Union of pointers to the actual data. You should choose the right pointer depending on x->array.elltype.

x->array.rank

Whether x->vector.fillp can be smaller than x->vector.dim.

Bitvectors and strings are treated separately.

Each array is of an specialized type which is the type of the elements of the array. ECL has arrays only a few following specialized types, and for each of these types there is a C integer which is the corresponding value of x->array.elttype or x->vector.elttype. We list those types together with the C constant that denotes that type:

T

aet_object

CHARACTER

aet_ch

FIXNUM

aet_fix

BIT

aet_bit

SINGLE-FLOAT

aet_sf

DOUBLE-FLOAT

aet_df

 Function: cl_elttype array_elttype (cl_object o)

Returns the element type of the array o, which can be a string, a bitvector, vector, or a multidimensional array. For example, the code array_elttype(c_string_to_object("\"AAA\"")) returns aet_ch, while the array_elttype(c_string_to_object("#(A B C)")) returns aet_object.

 Function: cl_object aref (cl_object array, cl_index index)
 Function: cl_object aset (cl_object array, cl_index index, cl_object value)

These functions are used to retrieve and set the elements of an array. The elements are accessed with one index, index, as in the lisp function ROW-MAJOR-AREF. For example

    cl_object array = c_string_to_object("#2A((1 2) (3 4))");
    cl_object x = aref(array, 3);
    cl_print(1, x);	/* Outputs 4 */
    aset(array, 3, MAKE_FIXNUM(5));
    cl_print(1, array); /* Outputs #2A((1 2) (3 5)) */
   
 Function: cl_object aref1 (cl_object vector, cl_index index)
 Function: cl_object aset1 (cl_object vector, cl_index index, cl_object value)

These functions are similar to aref and aset, but they operate on vectors.

    cl_object array = c_string_to_object("#(1 2 3 4)");
    cl_object x = aref1(array, 3);
    cl_print(1, x);	/* Outputs 4 */
    aset1(array, 3, MAKE_FIXNUM(5));
    cl_print(1, array); /* Outputs #(1 2 3 5) */