An array-creation-expression is used to create a new instance of an array-type.
An array creation expression of first form allocates an array instance of the type that results from deleting each of the individual expressions from the expression list. For example, the array creation expression new
int[10,
20]
produces an array instance of type int[,]
, and the array creation expression new
int[10][,]
produces an array of type int[][,]
. Each expression in the expression list must be of type int
or of a type that can be implicitly converted to int
. The value of each expression determines the length of the corresponding dimension in the newly allocated array instance.
If an array creation expression of the first form includes an array initializer, each expression in the expression list must be a constant and the rank and dimension lengths specified by the expression list must match those of the array initializer.
In an array creation expression of the second form, the rank of the specified array type must match that of the array initializer. The individual dimension lengths are inferred from the number of elements in each of the corresponding nesting levels of the array initializer. Thus, the expression
new int[,] {{0, 1}, {2, 3}, {4, 5}};
exactly corresponds to
new int[3, 2] {{0, 1}, {2, 3}, {4, 5}};
Array initializers are further described in §12.6.
The result of evaluating an array creation expression is classified as a value, namely a reference to the newly allocated array instance.
The run-time processing of an array creation expression consists of the following steps:
int
is performed. If evaluation of an expression or the subsequent implicit conversion causes an exception, then no further expressions are evaluated and no further steps are executed.IndexOutOfRangeException
is thrown and no further steps are executed.OutOfMemoryException
is thrown and no further steps are executed.An array creation expression permits instantiation of an array with elements of an array type, but the elements of such an array must be manually initialized. For example, the statement
int[][] a = new int[100][];
creates a single-dimensional array with 100 elements of type int[]
. The initial value of each element is null
. It is not possible for the same array creation expression to also instantiate the sub-arrays, and the statement
int[][] a = new int[100][5]; // Error
is an error. Instantiation of the sub-arrays must instead be performed manually, as in
int[][] a = new int[100][]; for (int i = 0; i < 100; i++) a[i] = new int[5];
When an array of arrays has a "rectangular" shape, that is when the sub-arrays are all of the same length, it is more efficient to use a multi-dimensional array. In the example above, instantiation of the array of arrays creates 101 objects—one outer array and 100 sub-arrays. In contrast,
int[,] = new int[100, 5];
creates only a single object, a two-dimensional array, and accomplishes the allocation in a single statement.