:c-array FLI Type Descriptor

Summary

Converts between a FLI array and a C array type.

Package

keyword

Syntax

:c-array type &rest dimensions

Arguments

Description

The FLI type :c-array converts between FLI arrays and the C array type. In C, pointers are used to access the elements of an array. The implementation of the :c-array type takes this into account, by automatically dereferencing any pointers returned when accessing an array using foreign-aref.

When using the :c-array type in the specification of an argument to define-foreign-function, a pointer to the array is passed to the foreign function, as specified by the C language. You are allowed to call the foreign function with a FLI pointer pointing to an object of type type instead of a FLI array.

When using the :c-array type in other situations, it acts as an aggregate type like :foreign-array. In particular, :c-array with more than one dimension is an array containing embedded arrays, not an array of pointers.

dimensions is the dimensions of the array.

Notes

1. :c-array uses the C convention that the first index value of an array is 0.
2. Only use the :c-array type when the corresponding C code uses an array with a constant declared size. If you need a dynamically sized array, then use a pointer type, allocate the array using the nelems argument to allocate-foreign-object or with-dynamic-foreign-objects and use dereference to access the elements. The pointer type is more efficient than making :c-array types dynamically with different dimensions because the FLI caches information about every different FLI type descriptor that is used.

Examples

The following code defines a 3 by 3 array of integers:

(setq aaa (fli:allocate-foreign-object
              :type '(:c-array :int 3 3)))

The type of this is equivalent to the C declaration:

int aaa[3][3];

The next example defines an array of arrays of bytes:

(setq bbb (fli:allocate-foreign-object
              :type '(:c-array (:c-array :byte 3) 2)))

The type of this is equivalent to the C declaration:

int bbb[2][3];

Note the reversal of the 3 and 2.

See foreign-aref and foreign-array-pointer for more examples on the use of arrays.

See also

foreign-aref
:foreign-array
foreign-array-pointer
2.2.1 Arrays