multianewarray : allocate multi-dimensional array : index : visitMultiANewArrayInsn()

Description

Allocates a multi-dimensional array. In Java, a multi-dimensional array is structured an array of arrays, i.e. an array whose elements are references to array objects. So constructing an array like:

new int [3][2]

produces a structure in memory like:

Click here for Picture



In this particular example the top level array is an array containing three 32-bit references. Each of these references identifies a two-element int array.

The same general approach applies to higher dimension arrays. For example, a three-dimensional array is structured as a top level array of arrayrefs, each of which refers to an array of arrayrefs, each of which refers to an array of items.

The lengths of each array within the multi-dimensional array are given as positive ints on the operand stack. The number of ints taken from the stack is specified by the unsigned byte parameter <n>. The type of the array is given as an array type descriptor by the <type> parameter.

The <type> is first resolved to a Java class (see Chapter 7 for a description of how array type descriptors are resolved). multianewarray then allocates the first <n> dimensions of a multidimensional array from the heap. If <n> is one, only the top-level array is created. So the statement:

new int [3][]

generates JVM code like:

bipush 3
multianewarray [[I 1    ; construct first dimension of the 2-D array

in this case only the three-element top-level array is created.

To construct both the top-level array and its sub-arrays, e.g. to fully construct

new int [3][2]

use the JVM code:

bipush 3
bipush 2
multianewarray [[I 2    ; construct both dimensions of the 2-D array

Here the second parameter given to multianewarray is 2, so the first and second dimensions are created (i.e. the top-level array and the array objects within the top-level array).

<n> must be less than or equal to the dimensionality given in the array's descriptor - i.e. it must be less than or equal to the number of '[' characters at the start of <type>.

The elements within the array are initialized to zero (for numeric and boolean arrays), or null for arrays of references. multianewarray leaves a reference to the newly constructed array on the operand stack.

Exceptions

NegativeArraySizeException - size is less than zero

OutOfMemoryError - insufficient memory to allocate the array

Example

; to allocate an array like:
;     new String[2][5]
    bipush 2
    bipush 5
    multianewarray [[Ljava/lang/String; 2   ; construct both dimensions
    ; stack now hold a reference two the new two dimensional array.
;
; multianewarray can be used to allocate only some of the
; dimensions of an array. For example, you write:
;
;     x = new int[6][3][]
;
; using:
    bipush 6
    bipush 3
    multianewarray [[[I 2  ; allocate 2 of the 3 dimensions
    astore_1               ; store array in local variable 1
; then you can create the final dimensions later using
; newarray or anewarray. e.g.
;
;    x[0][1] = new int[50];
;
; would be:
    aload_1         ; push the array
    iconst_0
    aaload          ; get x[0] - an array of arrays of ints
    iconst_1
    bipush 50
    newarray int    ; allocate an array of 50 ints
    aastore         ; store this in x[0][1]
;
; You can also use multianewarray to create
; single-dimensional arrays. e.g.
    bipush 50
    multianewarray [Ljava/lang/Thread; 1
; is the same as writing:
    bipush 50
    anewarray java/lang/Thread
; except that the latter is more efficient.

Notes

You can use multianewarray to allocate single-dimension arrays, though using anewarray or newarray is more efficient.

See also

newarray anewarray new

Stack

Before	After
sizeN	arrayref
---	...
size3	...
size2	...
size1	...
...	...

Bytecode

Type	Description
u1	multianewarray opcode = 0xC5 (197)
u2	index
u1	<n>