Function

Summary

Read and set an element in a Java array.

Package

lw-ji

Signature

jaref array &rest indices => element

(setf jaref) new-value array &rest indices => new-value

Arguments

array

A Java array, of any type.

indices

Non-negative integers.

new-value

A valid element for array.

Values

element

A Lisp object, a jobject or nil.

Description

The function jaref reads and sets the value of an element in the Java array array.

Each of the indices must be an integer in the right range, which means greater than or equal to 0, and less than than the length of the sub-array ("current array" below) for which they are used. There must be at least one index, and the number of indices must be smaller or equal to the array rank (that is, the number of dimensions) of array.

new-value must be a valid value to store in array. It has the same restrictions as new-value in (setf jvref). See the discussion in jvref for details.

The operation of jaref and (setf jaref) is as follows: For each index except the last, load the element from the "current array", which is the array itself for the first index or the element that was loaded for the previous index. When reaching the last index, jaref and (setf jaref) get or set the element in the "current array" the same way that jvref does. Note that this means that if there are less indices than number of the dimensions of the array, the access will be for a sub-array rather than actual element.

Notes

Because jaref needs to load the sub-srray for each index except the last, repeated calls to jaref for elements inside the same array are wasteful. It is much more efficient to get the sub-array and access it using jvref, or the multiple access functions.

See also

:jvref
map-java-object-array
primitive-array-to-lisp-array
lisp-array-to-primitive-array
Working with Java arrays