Contents Prev Next Up

## The Virtual Machine Instruction Set

# Managing Arrays

newarray
anewarray
multianewarray
arraylength
iaload
laload
faload
daload
aaload
baload
caload
saload
iastore
lastore
fastore
dastore
aastore
bastore
castore
sastore

### newarray

Allocate new array

    ..., size => result

size should be an integer. It represents the number of elements in the new array.

atype is an internal code that indicates the type of array to allocate. Possible values for atype are as follows:
A new array of the indicated or computed atype, capable of holding size elements, is allocated. Allocation of an array large enough to contain nelem items of atype is attempted. All elements of the array are initialized to zero.

If size is less than zero, a NegativeArraySizeException is thrown. If there is not enough memory to allocate the array, an OutOfMemoryException is thrown.

### anewarray

Allocate new array
of objects

    ..., size=> result

size should be an integer. It represents the number of elements in the new array.

indexbyte1 and indexbyte2 are are used to construct an index into the constant pool of the current class. The item at that index is resolved. The resulting entry should be a class.

A new array of the indicated class type and capable of holding size elements is allocated. Allocation of an array large enough to contain size items of the given class type is attempted. All elements of the array are initialized to zero.

If size is less than zero, a NegativeArraySizeException is thrown. If there is not enough memory to allocate the array, an OutOfMemoryException is thrown.

anewarray is used to create a single dimension of an array of objects. For example, to create

    new Thread[7]

the following code is used:

    bipush 7
    anewarray <Class "java.lang.Thread">

anewarray can also be used to create the outermost dimension of a multi-dimensional array. For example, the following array declaration:

    new int[6][]

is created with the following code:

    bipush 6
    anewarray <Class "[I">

See CONSTANT_Class in the Class File Format chapter for information on array class names.

### multianewarray

Allocate new multi-dimensional array

    ..., size1 size2...sizen => result

Each size should be an integer. Each represents the number of elements in a dimension of the array.

indexbyte1 and indexbyte2 are are used to construct an index into the constant pool of the current class. The item at that index is resolved. The resulting entry should be a class.

dimensions has the following aspects:

- It should be an integer xb3 1.

- It represents the number of dimensions being created. It must be the number of dimensions of the array class.

- It represents the number of elements that are popped off the stack. All must be integers greater than or equal to zero. These are used as the sizes of the dimension. For example, to create:

    	new int[6][3][]

the following code is used:

    	bipush 6
    	bipush 3
    	multianewarray <Class "[[[I"> 2

If any of the size arguments on the stack is less than zero, a NegativeArraySizeException is thrown. If there is not enough memory to allocate the array, an OutOfMemoryException is thrown.

Note: It is more efficient to use newarray or anewarray when creating a single dimension.

See CONSTANT_Class in the Class File Format chapter for information on array class names.

### arraylength

Get length of array

    ..., handle => ..., length

handle should be the handle of an array. The length of the array is determined and replaces handle on the top of the stack.

If the handle is null, a NullPointerException is thrown.

### iaload

Load integer from array

    ..., array, index => ..., value

array should be an array of integers. index should be an integer. The integer value at position number index in array is retrieved and pushed onto the top of the stack.

If array is null a NullPointerException is thrown. If index is not within the bounds of array an ArrayIndexOutOfBoundsException is thrown.

### laload

Load long integer from array

    ..., array, index => ..., value-word1, value-word2

array should be an array of long integers. index should be an integer. The long integer value at position number index in array is retrieved and pushed onto the top of the stack.

If array is null a NullPointerException is thrown. If index is not within the bounds of array an ArrayIndexOutOfBoundsException is thrown.

### faload

Load single float from array

    ..., array, index => ..., value

array should be an array of single precision floating point numbers. index should be an integer. The single precision floating point number value at position number index in array is retrieved and pushed onto the top of the stack.

If array is null a NullPointerException is thrown. If index is not within the bounds of array an ArrayIndexOutOfBoundsException is thrown.

### daload

Load double float from array

    ..., array, index => ..., value-word1, value-word2

array should be an array of double precision floating point numbers. index should be an integer. The double precision floating point number value at position number index in array is retrieved and pushed onto the top of the stack.

If array is null a NullPointerException is thrown. If index is not within the bounds of array an ArrayIndexOutOfBoundsException is thrown.

### aaload

Load object reference from array

    ..., array, index => ..., value

array should be an array of handles to objects or arrays. index should be an integer. The object or array value at position number index in array is retrieved and pushed onto the top of the stack.

If array is null a NullPointerException is thrown. If index is not within the bounds of array an ArrayIndexOutOfBoundsException is thrown.

### baload

Load signed byte from array

    ..., array, index => ..., value

array should be an array of signed bytes. index should be an integer. The signed byte value at position number index in array is retrieved, expanded to an integer, and pushed onto the top of the stack.

If array is null a NullPointerException is thrown. If index is not within the bounds of array an ArrayIndexOutOfBoundsException is thrown.

### caload

Load character from array

    ..., array, index => ..., value

array should be an array of characters. index should be an integer. The character value at position number index in array is retrieved, expanded to an integer, and pushed onto the top of the stack.

If array is null a NullPointerException is thrown. If index is not within the bounds of array an ArrayIndexOutOfBoundsException is thrown.

### saload

Load short from array

    ..., array, index => ..., value

array should be an array of (signed) short integers. index should be an integer. The short integer value at position number index in array is retrieved, expanded to an integer, and pushed onto the top of the stack.

If array is null, a NullPointerException is thrown. If index is not within the bounds of array, an ArrayIndexOutOfBoundsException is thrown.

### iastore

Store into integer array

    ..., array, index, value => ...

array should be an array of integers, index should be an integer, and value an integer. The integer value is stored at position index in array.

If array is null, a NullPointerException is thrown. If index is not within the bounds of array, an ArrayIndexOutOfBoundsException is thrown.

### lastore

Store into long integer array

    ..., array, index, value-word1, value-word2 => ...

array should be an array of long integers, index should be an integer, and value a long integer. The long integer value is stored at position index in array.

If array is null, a NullPointerException is thrown. If index is not within the bounds of array, an ArrayIndexOutOfBoundsException is thrown.

### fastore

Store into single float array

    ..., array, index, value => ...

array should be an array of single precision floating point numbers, index should be an integer, and value a single precision floating point number. The single float value is stored at position index in array.

If array is null, a NullPointerException is thrown. If index is not within the bounds of array, an ArrayIndexOutOfBoundsException is thrown.

### dastore

Store into double float array

    ..., array, index, value-word1, value-word2 => ...

array should be an array of double precision floating point numbers, index should be an integer, and value a double precision floating point number. The double float value is stored at position index in array.

If array is null, a NullPointerException is thrown. If index is not within the bounds of array, an ArrayIndexOutOfBoundsException is thrown.

### aastore

Store into object reference array

    ..., array, index, value => ...

array should be an array of handles to objects or to arrays, index should be an integer, and value a handle to an object or array. The handle value is stored at position index in array.

If array is null, a NullPointerException is thrown. If index is not within the bounds of array, an ArrayIndexOutOfBoundsException is thrown.

The actual type of value should be conformable with the actual type of the elements of the array. For example, it is legal to store and instance of class Thread in an array of class Object, but not vice versa. An IncompatibleTypeException is thrown if an attempt is made to store an incompatible object reference.

### bastore

Store into signed byte array

    ..., array, index, value => ...

array should be an array of signed bytes, index should be an integer, and value an integer. The integer value is stored at position index in array. If value is too large to be a signed byte, it is truncated.

If array is null, a NullPointerException is thrown. If index is not within the bounds of array, an ArrayIndexOutOfBoundsException is thrown.

### castore

Store into character array

    ..., array, index, value => ...

array should be an array of characters, index should be an integer, and value an integer. The integer value is stored at position index in array. If value is too large to be a character, it is truncated.

If array is null, a NullPointerException is thrown. If index is not within the bounds of array, an ArrayIndexOutOfBoundsException is thrown.

### sastore

Store into short array

    ..., array, index, value => ...

array should be an array of shorts , index should be an integer, and value an integer. The integer value is stored at position index in array. If value is too large to be an short, it is truncated.

If array is null, a NullPointerException is thrown. If index is not within the bounds of array an ArrayIndexOutOfBoundsException is thrown.

Contents Prev Next Up

Generated with CERN WebMaker