Array-Element Initializers
Collapse the table of content
Expand the table of content
The document is archived and information here might be outdated Array-Element Initializers

Visual Studio .NET 2003

An array-element initializer consists of a sequence of variable initializers, enclosed by curly braces ({}) and separated by commas. Each variable initializer is an expression or, in the case of a multidimensional array, a nested array-element initializer. Each expression must be classified as a value. Array-element initializers may also be used in array-creation expressions.

The type of expression or statement in which an array-element initializer is used determines the type of the array being initialized. In an array-creation expression, the array type immediately precedes the initializer. In a variable declaration, the array type is the type of the variable being declared. When an array-element initializer is used in a variable declaration, such as:

Private a As Integer() = { 0, 2, 4, 6, 8 }

it is simply shorthand for an equivalent array-creation expression:

Private a As Integer() = New Integer() { 0, 2, 4, 6, 8 }

In an array-element initializer, the outermost nesting level corresponds to the leftmost dimension, and the innermost nesting level corresponds to the rightmost dimension. The initializer must have the same number levels of nesting as there are dimensions in the array. All of the elements in the innermost nesting level must be implicitly convertible to the element type of the array. The number of elements in each nested array-element initializer must always be consistent with the size of the other array-element initializers at the same level.

The following example creates a two-dimensional array with a length of five for the leftmost dimension and a length of two for the rightmost dimension:

Module Test
    Sub Main()
        Dim b As Integer(,) = _
            { { 0, 1 }, { 2, 3 }, { 4, 5 }, { 6, 7 }, { 8, 9 } }
    End Sub
End Module

The example is equivalent to the following:

Module Test
    Sub Main()
        Private b(4, 1) As Integer

        b(0, 0) = 0: b(0, 1) = 1
        b(1, 0) = 2: b(1, 1) = 3
        b(2, 0) = 4: b(2, 1) = 5
        b(3, 0) = 6: b(3, 1) = 7
        b(4, 0) = 8: b(4, 1) = 9
    End Sub
End Module

If the array-creation expression specifies the bounds of the dimensions, the number of elements at any particular level must be the same as the size of the corresponding dimension. If the bounds are unspecified, the length of each dimension is the number of elements in the corresponding level of nesting.

Some valid and invalid examples follow:

' OK.
Private x() As Integer = New Integer(2) {0, 1, 2}
' Error, length/initializer mismatch.
Private y() As Integer = New Integer(2) {0, 1, 2, 3} 

Here, the initializer for y is in error because the length and the number of elements in the initializer do not agree.

An empty array-element initializer (that is, one that contains curly braces but no initializer list) is always valid regardless of the number of dimensions of the array. If the size of the dimensions of the array being initialized is known in an array-creation expression, the empty array-element initializer represents an array instance of the specified size where all the elements have been initialized to the element type's default value. If the dimensions of the array being initialized are not known, the empty array-element initializer represents an array instance in which all dimensions are size zero.

Because context is required to determine the type of an array initializer, it is not possible to use an array initializer in an expression context. Therefore, the following code is not valid:

Module Test
    Sub F(ByVal a() As Integer)
    End Sub

    Sub Main()
        ' Error, can't use without array creation expression.
        F({1, 2, 3})

        ' OK.
        F(New Integer() {1, 2, 3})
    End Sub
End Module

At run time, the expressions in an array-element initializer are evaluated in textual order from left to right.

ArrayElementInitializer ::= { [ VariableInitializerList ] }
VariableInitializerList ::=
   VariableInitializer |
   VariableInitializerList , VariableInitializer
VariableInitializer ::= Expression | ArrayElementInitializer

See Also Regular Initializers | Array-Size Initializers | | 9.6.3 Variable Initializers | 4.6 Accessibility | 4.3.3 Shadowing | 9.6 Instance and Shared Variables | 9.6.1 Read-Only Variables | 9.6.2 WithEvents Variables | 11. Expressions | Declarations and Constants Summary (Visual Basic Language Reference) | Variables (Visual Basic Language Concepts)

© 2016 Microsoft