Vector Instructions

Vector Instructions

Arrays and vectors are the only true generics implemented in the first release of the common language runtime. Vectors are “elementary” arrays, with one dimension and a zero lower bound. In signatures, vectors are represented by type ELEMENT_TYPE_SZARRAY, whereas “true” arrays are represented by ELEMENT_TYPE_ARRAY. We can, of course, declare a single-dimensional, zero-lower-bound array (whose ILAsm notation is <type>[0 ]), which will be a true array, as opposed to a vector (whose ILAsm notation is <type>[ ]).

The IL instruction set defines specific instructions dealing with vectors but not with arrays. To handle array elements and arrays themselves, you need to call the methods of the .NET Framework class [mscorlib]System.Array, from which all arrays are derived.

Vector Creation

In order to work with a vector, it is necessary to create one. The IL instruction set contains special instructions for vector creation and vector length querying:

• newarr <token> (0x8D)  Create a vector. <token> specifies the type of vector elements and must be a valid TypeDef, TypeRef, or TypeSpec token. This instruction pops the number of vector elements (native int) from the stack and pushes an object reference to the created vector on the stack. If the operation fails, an OutOfMemory exception is thrown. If the number of elements happens to be negative, an Overflow exception is thrown. The elements of the newly created vector are zero-initialized. Because newarr takes a token as a parameter, in ILAsm the full class names must be used for elementary types rather than the respective keywords. For example:

  .locals init (int32[] arr) ldc.i4 123 newarr [mscorlib]System.Int32 stloc.0

• For specific details about array creation, see the description of the newobj instruction.

• ldlen (0x8E)  Get the element count of a vector. This instruction takes an object reference to the vector instance from the stack and puts the element count (native int) on the stack.

Element Address Loading

You can obtain the managed pointer to a single vector element by using the following instruction:

• ldelema <token> (0x8F)  Get the address (a managed pointer) of a vector element. <token> specifies the type of the element and must be a valid TypeDef, TypeRef, or TypeSpec token. This instruction pops the element index (native int) and the vector reference (an object reference) from the stack and pushes the managed pointer to the element on the stack. To get an address of an array element, the System.Array class provides the Address method.

Element Loading

Element loading instructions load a vector element of an elementary type on the stack. All of these instructions take the element index (native int) and the vector reference (an object reference) from the stack and put the value of the element on the stack. If the vector reference is null, the instructions throw a NullReference exception. If the index is negative or greater than or equal to the element count of the vector, an IndexOutOfRange exception is thrown. If the type of the vector element does not correspond to the type of the instruction, a TypeMismatch exception is thrown.

• ldelem.i1 (0x90)  Load a vector element of type int8.

• ldelem.u1 (0x91)  Load a vector element of type unsigned int8.

• ldelem.i2 (0x92)  Load a vector element of type int16.

• ldelem.u2 (0x93)  Load a vector element of type unsigned int16.

• ldelem.i4 (0x94)  Load a vector element of type int32.

• ldelem.u4 (0x95)  Load a vector element of type unsigned int32.

• ldelem.i8 (ldelem.u8) (0x96)  Load a vector element of type int64.

• ldelem.i (0x97)  Load a vector element of type native int.

• ldelem.r4 (0x98)  Load a vector element of type float32.

• ldelem.r8 (0x99)  Load a vector element of type float64.

• ldelem.ref (0x9A)  Load a vector element of object reference type.

Element Storing

Element storing instructions store a value from the stack in a vector element of an elementary type. All of these instructions take the value to be stored, the element index (native int), and the vector reference (an object reference) from the stack and put nothing on the stack. Generally, the instructions can throw the same exceptions as the ldelem.* instructions described in the preceding section.

• stelem.i (0x9B)  Store a value in a vector element of type native int.

• stelem.i1 (0x9C)  Store a value in a vector element of type int8.

• stelem.i2 (0x9D)  Store a value in a vector element of type int16.

• stelem.i4 (0x9E)  Store a value in a vector element of type int32.

• stelem.i8 (0x9F)  Store a value in a vector element of type int64.

• stelem.r4 (0xA0)  Store a value in a vector element of type float32.

• stelem.r8 (0xA1)  Store a value in a vector element of type float64.

• stelem.ref (0xA2)  Store a value in a vector element of object reference type. This instruction involves casting of the object on the stack to the type of the vector element, so an InvalidCast exception can be thrown.

Special stelem.* instructions for unsigned integer types are missing for an obvious reason: the stelem.i* instructions are equally applicable to signed and unsigned integer types.