foreign-aref

foreign-aref Accessor

Summary

Accesses and returns the value at a specified point in an array.

Package

fli

Signature

foreign-aref array &rest subscripts => value

setf (foreign-aref array &rest subscripts) value => value

Arguments

`array`⇩	A FLI array or a pointer to a FLI array.
`subscripts`⇩	A list of valid array indices for `array`.
`value`	An element of `array`.

Values

value

An element of array.

Description

The accessor foreign-aref accesses an element in array specified by subscripts and returns its value if the element is an immediate type. If it is an aggregate type, such as a :struct, :union, or :c-array, an error is signaled. The function foreign-array-pointer should be used to get access to such embedded aggregate data.

The value of an element in an array can be changed using the setf form of foreign-aref. See the examples section for an example of this.

Examples

In the first example, a 3 by 3 integer array is created, and the setf form of foreign-aref is used to set all the elements to 42.

(setq array1 (fli:allocate-foreign-object
              :type '(:c-array :int 3 3)))
 
(dotimes (x 3)
         (dotimes (y 3)
                  (setf (fli:foreign-aref array1 x y)
                        42)))

Next, foreign-aref is used to dereference the value at position 2 2 in array1. Remember that the count for the indices of an array start at 0.

(fli:foreign-aref array1 2 2)

In the following example, an array of arrays of integers is created. When an element is dereferenced, a copy of an array of integers is returned.

(setq array2 (fli:allocate-foreign-object
              :type '(:c-array (:c-array :int 3) 3)))
 
(fli:foreign-array-pointer array2 2)

The array returned can be bound to the variable array3, and accessed using foreign-aref again. This time an integer is returned.

(setq array3 *)
 
(fli:foreign-aref array3 1)