All Manuals > LispWorks® User Guide and Reference Manual > 39 The LW-JI Package

jvref Accessor


Read and set an element in a Java array.




jvref array index => element

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

A Java array.
A non-negative integer.
A valid value for array.
A Lisp object, a jobject or nil.
A valid value for array.

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.


nil or t.


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.


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.

See also

15.4 Working with Java arrays

LispWorks® User Guide and Reference Manual - 01 Dec 2021 19:30:46