Function

Summary

Read and set an element in a Java array.

Package

lw-ji

Signature

jvref array index => element

(setf jvref) new-value array index => 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.

Description

The function 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 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 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.

See also

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