jaref

jaref Accessor

Summary

Read and set an element in a Java array.

Package

lw-ji

Signatures

jaref array &rest indices => element

setf (jaref array &rest indices) new-value => 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`.
`new-value`	A valid element for `array`.

Description

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

Each element of 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-array 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.