Add a more functional (i.e. fewer-stubs) implementation of System.Data.Linq.

[mono.git] / mcs / docs / ecma334 / 14.5.10.2.xml

<?xml version="1.0"?>
<clause number="14.5.10.2" title="Array creation expressions">
  <paragraph>An <non_terminal where="14.5.10.2">array-creation-expression</non_terminal> is used to create a new instance of an <non_terminal where="19.1">array-type</non_terminal>. <grammar_production><name><non_terminal where="14.5.10.2">array-creation-expression</non_terminal></name> : <rhs><keyword>new</keyword><non_terminal where="19.1">non-array-type</non_terminal><terminal>[</terminal><non_terminal where="14.5.6">expression-list</non_terminal><terminal>]</terminal><non_terminal where="19.1">rank-specifiers</non_terminal><opt/><non_terminal where="19.6">array-initializer</non_terminal><opt/></rhs><rhs><keyword>new</keyword><non_terminal where="19.1">array-type</non_terminal><non_terminal where="19.6">array-initializer</non_terminal></rhs></grammar_production></paragraph>
  <paragraph>An array creation expression of the 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 <keyword>int</keyword>, <keyword>uint</keyword>, <keyword>long</keyword>, or <keyword>ulong</keyword>, or of a type that can be implicitly converted to one or more of these types. The value of each expression determines the length of the corresponding dimension in the newly allocated array instance. Since the length of an array dimension must be nonnegative, it is a compile-time error to have a constant expression with a negative value, in the expression list. </paragraph>
  <paragraph>Except in an unsafe context (<hyperlink>25.1</hyperlink>), the layout of arrays is unspecified. </paragraph>
  <paragraph>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. </paragraph>
  <paragraph>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 <code_example><![CDATA[
new int[,] {{0, 1}, {2, 3}, {4, 5}}  
]]></code_example>exactly corresponds to <code_example><![CDATA[
new int[3, 2] {{0, 1}, {2, 3}, {4, 5}}  
]]></code_example></paragraph>
  <paragraph>Array initializers are described further in <hyperlink>19.6</hyperlink>. </paragraph>
  <paragraph>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: <list><list_item> The dimension length expressions of the <non_terminal where="14.5.6">expression-list</non_terminal> are evaluated in order, from left to right. Following evaluation of each expression, an implicit conversion (<hyperlink>13.1</hyperlink>) to one of the following types is performed: <keyword>int</keyword>, <keyword>uint</keyword>, <keyword>long</keyword>, <keyword>ulong</keyword>. The first type in this list for which an implicit conversion exists is chosen. 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. </list_item><list_item> The computed values for the dimension lengths are validated, as follows: If one or more of the values are less than zero, a System.OverflowException is thrown and no further steps are executed. </list_item><list_item> An array instance with the given dimension lengths is allocated. If there is not enough memory available to allocate the new instance, a System.OutOfMemoryException is thrown and no further steps are executed. </list_item><list_item> All elements of the new array instance are initialized to their default values (<hyperlink>12.2</hyperlink>). </list_item><list_item> If the array creation expression contains an array initializer, then each expression in the array initializer is evaluated and assigned to its corresponding array element. The evaluations and assignments are performed in the order the expressions are written in the array initializer-in other words, elements are initialized in increasing index order, with the rightmost dimension increasing first. If evaluation of a given expression or the subsequent assignment to the corresponding array element causes an exception, then no further elements are initialized (and the remaining elements will thus have their default values). </list_item></list></paragraph>
  <paragraph>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. <example>[Example: For example, the statement <code_example><![CDATA[
int[][] a = new int[100][];  
]]></code_example>creates a single-dimensional array with 100 elements of type int[]. The initial value of each element is null. end example]</example> It is not possible for the same array creation expression to also instantiate the  sub-arrays, and the statement <code_example><![CDATA[
int[][] a = new int[100][5];    // Error  
]]></code_example>results in a compile-time error. Instantiation of the sub-arrays must instead be performed manually, as in <code_example><![CDATA[
int[][] a = new int[100][];  
for (int i = 0; i < 100; i++) a[i] = new int[5];  
]]></code_example></paragraph>
  <paragraph>When an array of arrays has a &quot;rectangular&quot; 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, <code_example><![CDATA[
int[,] = new int[100, 5];  
]]></code_example>creates only a single object, a two-dimensional array, and accomplishes the allocation in a single statement. </paragraph>
</clause>