Function

Summary

Apply a function to the elements in an array.

Package

lw-ji

Signature

map-java-object-array function array &key collect reverse start end pass-args convert write-back => result

Arguments

function

A function designator or nil.

array

A Java array of non-primitive type.

collect

A generalized boolean.

reverse

A generalized boolean.

start, end

Bounding index designators for array.

pass-args

One of the keywords :element, :index and :element-index.

convert

nil, t, or one of the keywords :force-nil, :force-local and :force-global.

write-back

A generalized boolean.

Values

result

A list or a Lisp vector.

Description

The function map-java-object-array applies the function function to the elements in the Java array array.

The default behavior is simply to apply function to each element. The keyword arguments can be used to change this behavior, including modifying elements.

function should take one or two arguments, depending on pass-args. The default value of pass-args is :element, which means that function takes one argument, the element in the array. pass-args can also be :element-index, and then function should take two arguments, the element and the index. pass-args can also be :index in which case function just takes the index. The latter case is useful when map-java-object-array is used to modify the element in the array. When function is nil, the "result" of the function call is the element itself. That is useful for simple collection (that is, supplying a true value of collect).

Note: When the element that is passed to function is a jobject, it is by default a "local" object, which means it must not be used outside the dynamic scope of the function call. collect and convert can change this.

When write-back is nil the result of the call to function is ignored. When write-back is non-nil, the result of function is the new value to write back. The default value of write-back is nil.

When reverse is non-nil map-java-object-array starts from the highest index and maps down, otherwise it maps up. The default value of reverse is nil.

start and end specify the range in array to map: start defaults to 0 and is inclusive, and end defaults to the length of array and is exclusive. If either of these is not an integer or is out of bounds, or end is smaller than start, then an error of type java-out-of-bounds-error is signaled.

pass-args controls the arguments to function as described above.

collect, if non-nil, specifies that the results of applying function should be collected and returned from map-java-object-array. If collect is t, map-java-object-array returns a list of the results. collect can also be :vector or cl:vector, in which case result is a Lisp vector. When convert is either nil or t, collect overrides it and forces conversion of primitive types and strings to Lisp objects, and makes jobjects non-local, so they can be used outside the scope of the function calls and map-java-object-array. The default value of collect is nil.

convert controls conversion to Lisp objects. When convert is t, primitive types and strings are converted to Lisp objects before they are passed to function. When convert is nil, all elements are passed as jobjects. Note that when collect is non-nil and convert is nil or t, collect overrides convert as described above. The default value of convert is t.

When convert is one of :force-nil, :force-local or :force-global it overrides collect. :force-nil causes the object to pass as a jobject (the same as when collect is nil and convert is nil). :force-local causes primitive types to pass as Lisp objects, and other types as local jobjects (the same as when collect is nil and convert is t). :force-global causes primitive types to be passed as Lisp objects and other types as global objects.

Note: local jobjects, which you get when convert is either :force-nil or :force-local, or when collect is nil and convert is not :force-global, must not be used outside the scope of the function function that is passed to map-java-object-array. Using local objects out of scope can cause the system to crash (rather than signal an error). Note that you must not even use a local jobject from one call to function in another call to function within the same call to map-java-object-array.

Converting to global objects adds a substantial overhead to the system, though for small arrays this is not very bad. If you want to map over a large array, and dynamically decide to use only some of the jobjects out of scope, you can convert local jobjects to global using jobject-ensure-global.

When write-back is true, the result of the application of function is written back to array. The default value of write-back is nil.

If array is not a non-primitive Java array, or pass-args or collect is not one of the acceptable values, or write-back is non-nil and function returns an object of wrong type, map-java-object-array signals an error of type java-array-error.

Notes

1. map-java-object-array accesses only non-primitive arrays. For primitive arrays use one of primitive-array-to-lisp-array, lisp-array-to-primitive-array, get-primitive-array-region and set-primitive-array-region.
2. The function java-object-array-element-type can be used to test whether a Java object is a non-primitive array.
3. When accessing more than one element, map-java-object-array may be much faster than accessing the elements using jvref or jaref.
4. map-java-object-array traverses one level. If a multi-dimensional array is supplied, the elements that it passes to function are sub-arrays (which may be null too).

See also

jvref
jaref
primitive-array-to-lisp-array
lisp-array-to-primitive-array
get-primitive-array-region
set-primitive-array-region
java-object-array-element-type
jobject-ensure-global
Working with Java arrays