41.

prev next contents

---

multianewarray

allocate multi-dimensional array

Jasmin Syntax

     multianewarray <type> <n> 

<type> is the type descriptor of the array, e.g. for an array holding arrays of integers <type> is [[I.

<n> is an integer in the range 1-255.

Stack

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

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.

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. 

Exceptions

NegativeArraySizeException - size is less than zero

OutOfMemoryError - insufficient memory to allocate the array

Bytecode

In bytecode, after the multianewarray opcode is a 16-bit unsigned integer index. This is the index of an entry in the constant pool of the current class. The entry at that index is tagged a CONSTANT_Class entry. The name field of the entry is a string containing the characters given by <type> in Jasmin.

After the index is a single unsigned byte, <n>, the number of dimensions of the array to allocate.

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

See Also

newarray, anewarray, new

Notes

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

---

prev next contents

Java Virtual Machine, by Jon Meyer and Troy Downing, O'Reilly Associates