CIL array instructions: newarr, ldlen, ldelem, stelem, ldelema

Introduction

These instructions make and use vectors: one-dimensional arrays whose first index is 0 (int[] in C#). Arrays with more dimensions or other lower bounds have no instructions of their own: code creates them with newobj on the array type’s constructor and reads them with call to the type’s Get, Set and Address methods, which the runtime supplies. An array is an object; the stack holds a reference to it. An index on the stack is an int32 or a native int.

The load and store forms with a type in their name work on elements of that built-in kind; ldelem and stelem with a type token work on any element type. Loaded elements narrower than 32 bits are widened to int32 (sign-extended for i1 and i2, zero-extended for u1 and u2); stored ones are truncated.

Exceptions and verifiability, for the whole page. Every instruction that takes an array throws NullReferenceException if it is null, and every one that takes an index throws IndexOutOfRangeException if the index is negative or not less than the length. A store of an object reference (stelem.ref, or stelem with a reference type) also checks that the object fits the array’s real element type, and throws ArrayTypeMismatchException if not (an object[] that is really a string[] refuses an int). The forms are verifiable when the element kind matches the array.

Create and measure

Opcode	Instruction	Stack	What it does	Exceptions · verifiability
`8D` token	`newarr` type	…, length → …, array	Pops a length and pushes a new array of that many elements of the given type, all zero, false or null.	OverflowException if the length is negative; OutOfMemoryException.
`8E`	`ldlen`	…, array → …, native int	Pops an array and pushes its length as a native unsigned integer.	NullReferenceException.
`8F` token	`ldelema` type	…, array, index → …, address	Pushes the address of the element as a managed pointer. With the readonly. prefix the pointer is promised not to be written through.	NullReferenceException; IndexOutOfRangeException; ArrayTypeMismatchException if the array’s real element type is not exactly the type (not thrown with `readonly.`).

Load an element

Opcode	Instruction	Stack	What it does	Exceptions · verifiability
`90`	`ldelem.i1`	…, array, index → …, int32	Loads a signed byte element.	As the page introduction.
`91`	`ldelem.u1`	…, array, index → …, int32	Loads an unsigned byte element.	As above.
`92`	`ldelem.i2`	…, array, index → …, int32	Loads a signed 16-bit element.	As above.
`93`	`ldelem.u2`	…, array, index → …, int32	Loads an unsigned 16-bit element.	As above.
`94`	`ldelem.i4`	…, array, index → …, int32	Loads a 32-bit integer element.	As above.
`95`	`ldelem.u4`	…, array, index → …, int32	Loads an unsigned 32-bit element (an `int32` with the same bits).	As above.
`96`	`ldelem.i8`	…, array, index → …, int64	Loads a 64-bit integer element (there is no `ldelem.u8`).	As above.
`97`	`ldelem.i`	…, array, index → …, native int	Loads a native-sized integer element.	As above.
`98`	`ldelem.r4`	…, array, index → …, F	Loads a single-precision element.	As above.
`99`	`ldelem.r8`	…, array, index → …, F	Loads a double-precision element.	As above.
`9A`	`ldelem.ref`	…, array, index → …, O	Loads an object reference element.	As above.
`A3` token	`ldelem` type	…, array, index → …, value	Loads an element of the given type, of any kind (a struct is copied onto the stack).	As above.

Store an element

Opcode	Instruction	Stack	What it does	Exceptions · verifiability
`9B`	`stelem.i`	…, array, index, native int → …	Stores a native-sized integer.	As the page introduction.
`9C`	`stelem.i1`	…, array, index, int32 → …	Stores the low byte.	As above.
`9D`	`stelem.i2`	…, array, index, int32 → …	Stores the low 16 bits.	As above.
`9E`	`stelem.i4`	…, array, index, int32 → …	Stores a 32-bit integer.	As above.
`9F`	`stelem.i8`	…, array, index, int64 → …	Stores a 64-bit integer.	As above.
`A0`	`stelem.r4`	…, array, index, F → …	Narrows to single precision and stores.	As above.
`A1`	`stelem.r8`	…, array, index, F → …	Stores a double-precision float.	As above.
`A2`	`stelem.ref`	…, array, index, O → …	Stores an object reference, after checking that it fits the array’s real element type.	As above, and ArrayTypeMismatchException.
`A4` token	`stelem` type	…, array, index, value → …	Stores a value of the given type, of any kind.	As above; ArrayTypeMismatchException for a reference type that does not fit.

Not described

Known, not yet covered

Multi-dimensional and non-zero-based arrays: the methods the runtime supplies for them (Get, Set, Address, and the constructor) are not listed.

Unknown

None found.

.CIL File Format – Arrays