jvref

jvref Accessor

Summary

Read and set an element in a Java array.

Package

lw-ji

Signatures

jvref array index => element

setf (jvref array index) new-value => new-value

Arguments

`array`⇩	A Java array.
`index`⇩	A non-negative integer.
`new-value`⇩	A valid value for `array`.

Values

`element`	A Lisp object, a jobject or `nil`.
`new-value`	A valid value for `array`.

Description

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

index must be in the right range:

0 <= index < (java-array-length array)

new-value must be a valid value to store in array (discussed below).

jvref returns the corresponding element from array. If the element is of a primitive type, or is of type java.lang.String, it is converted to the Lisp object, otherwise it is returned as a jobject or nil if it is null. See 15.1 Types and conversion between Lisp and Java.

(setf jvref) sets the element to new-value. new-value must be a valid element for array. For a primitive array, new-value must be a Lisp object of the correct type:

byte, short, int, long
	Integers with less than 8, 16, 32 and 64 bits respectively.
float, double	Any float.
boolean	`nil` or `t`.
char	Integers in the inclusive range `[0,#xffff]`.

For a non-primitive array, new-value must be convertible to a jobject of the correct class. If the element type of array is java.lang.Object (java-array-element-type returns :object), then any Lisp value that can converted to a Java primitive type is acceptable (see 15.1 Types and conversion between Lisp and Java), as well as strings and any Java object. If the element type of array is java.lang.String (java-array-element-type returns :string), then strings or Java objects of class java.lang.String are acceptable. In all other cases, only Java objects are acceptable, and need to be of the correct type.

Notes

For accessing multiple elements in the same array, the multiple access functions (map-java-object-array, primitive-array-to-lisp-array, lisp-array-to-primitive-array) can be much faster.

jvref and (setf jvref) access the top level of the array. If array is multi-dimensional, jvref and (setf jvref) will return and set the sub-array. See jaref for accessing elements in a multi-dimensional array.

jvref and (setf jvref) are slightly faster than jaref and (setf jaref) with one index, and give a proper error when called with the wrong number of arguments.