Arrays in Visual Basic

An array is a set of values that are logically related to each other, such as the number of students in each grade in a grammar school.

By using an array, you can refer to these related values by the same name, and use a number that’s called an index or subscript to tell them apart. The individual values are called the elements of the array. They’re contiguous from index 0 through the highest index value.

In contrast to an array, a variable that contain a single value is called a scalar variable.

In this topic

• Array Elements in a Simple Array

• Creating an Array

• Declaring an Array

• Storing Values in an Array

• Populating an Array with Initial Values

  • Nested Array Literals

• Iterating Through an Array

• Arrays as Return Values and Parameters

• Jagged Arrays

• Zero-Length Arrays

• Array Size

• Array Types and Other Types

• Collections as an Alternative to Arrays

Array Elements in a Simple Array

The following example declares an array variable to hold the number of students in each grade in a grammar school.

Dim students(6) As Integer

The array students in the preceding example contains seven elements. The indexes of the elements range from 0 through 6. Having this array is simpler than declaring seven variables.

The following illustration shows the array students. For each element of the array:

• The index of the element represents the grade (index 0 represents kindergarten).

• The value that’s contained in the element represents the number of students in that grade.

Elements of the "students" array

The following example shows how to refer to the first, second, and last element of the array students.

Dim kindergarten As Integer = students(0)
Dim firstGrade As Integer = students(1)
Dim sixthGrade As Integer = students(6)
MsgBox("Students in kindergarten = " & CStr(kindergarten))
MsgBox("Students in first grade = " & CStr(firstGrade))
MsgBox("Students in sixth grade = " & CStr(sixthGrade))

You can refer to the array as a whole by using just the array variable name without indexes.

The array students in the preceding example uses one index and is said to be one-dimensional. An array that uses more than one index or subscript is called multidimensional. For more information, see the rest of this topic and Array Dimensions in Visual Basic.

Creating an Array

You can define the size of an array several ways. You can supply the size when the array is declared, as the following example shows.

Dim cargoWeights(10) As Double 
Dim atmospherePressures(2, 2, 4, 10) As Short 
Dim inquiriesByYearMonthDay(20)()() As Byte

You can also use a New clause to supply the size of an array when it’s created, as the following example shows.

cargoWeights = New Double(10) {}
atmospherePressures = New Short(2, 2, 4, 10) {}
inquiriesByYearMonthDay = New Byte(20)()() {}

If you have an existing array, you can redefine its size by using the Redim statement. You can specify that the Redim statement should keep the values that are in the array, or you can specify that it create an empty array. The following example shows different uses of the Redim statement to modify the size of an existing array.

' Assign a new array size and retain the current element values. 
ReDim Preserve cargoWeights(20)
' Assign a new array size and retain only the first five element values. 
ReDim Preserve cargoWeights(4)
' Assign a new array size and discard all current element values. 
ReDim cargoWeights(15)

For more information, see ReDim Statement (Visual Basic).

Declaring an Array

You declare an array variable the same way as any other variable, by using the Dim statement. You follow the type or the variable name with one or more pairs of parentheses to indicate that it will hold an array rather than a scalar, which is a variable that contains a single value.

After you declare the array, you can define its size by using the ReDim Statement (Visual Basic).

The following example declares a one-dimensional array variable by adding a pair of parentheses after the type. The example also specifies the dimensions of the array by using the ReDim Statement (Visual Basic).

' Declare a one-dimensional array. 
Dim cargoWeights As Double()

' Dimension the array. 
ReDim cargoWeights(15)

The following example declares a multidimensional array variable by adding a pair of parentheses after the type and by placing commas inside the parentheses to separate the dimensions. The example also specifies the dimensions of the array by using the ReDim Statement (Visual Basic).

' Declare a multidimensional array. 
Dim atmospherePressures As Short(,,,)

' Dimension the array. 
ReDim atmospherePressures(1, 2, 3, 4)

To declare a jagged array variable, add a pair of parentheses after the variable name for each level of nested array.

Dim inquiriesByYearMonthDay()()() As Byte

The preceding examples declare array variables but don’t assign arrays to them. You must still create an array, initialize it, and assign it to the variable.

Storing Values in an Array

You can access each location in an array by using an index of type Integer. You can store and retrieve values in an array by referencing each array location by using its index enclosed in parentheses. Indexes for multi-dimensional arrays are separated by commas (,). You need one index for each array dimension. The following example shows some statements that store values in arrays.

Dim i = 4
Dim j = 2

Dim numbers(10) As Integer 
Dim matrix(5, 5) As Double

numbers(i + 1) = 0
matrix(3, j * 2) = j

The following example shows some statements that get values from arrays.

Dim v = 2
Dim i = 1
Dim j = 1
Dim k = 1
Dim wTotal As Double = 0.0
Dim sortedValues(5), rawValues(5), estimates(2, 2, 2) As Double 
Dim lowestValue = sortedValues(0)
wTotal += (rawValues(v) ^ 2)
Dim firstGuess = estimates(i, j, k)

Populating an Array with Initial Values

By using an array literal, you can create an array that contains an initial set of values. An array literal consists of a list of comma-separated values that are enclosed in braces ({}).

When you create an array by using an array literal, you can either supply the array type or use type inference to determine the array type. The following code shows both options.

Dim numbers = New Integer() {1, 2, 4, 8}
Dim doubles = {1.5, 2, 9.9, 18}

When you use type inference, the type of the array is determined by the dominant type in the list of values that’s supplied for the array literal. The dominant type is a unique type to which all other types in the array literal can widen. If this unique type can’t be determined, the dominant type is the unique type to which all other types in the array can narrow. If neither of these unique types can be determined, the dominant type is Object. For example, if the list of values that’s supplied to the array literal contains values of type Integer, Long, and Double, the resulting array is of type Double. Both Integer and Long widen only to Double. Therefore, Double is the dominant type. For more information, see Widening and Narrowing Conversions (Visual Basic). These inference rules apply to types that are inferred for arrays that are local variables that are defined in a class member. Although you can use array literals when you create class-level variables, you can’t use type inference at the class level. As a result, array literals that are specified at the class level infer the values that are supplied for the array literal as type Object.

You can explicitly specify the type of the elements in an array that’s created by using an array literal. In this case, the values in the array literal must widen to the type of the elements of the array. The following code example creates an array of type Double from a list of integers.

Dim values As Double() = {1, 2, 3, 4, 5, 6}

Nested Array Literals

You can create a multidimensional array by using nested array literals. Nested array literals must have a dimension and number of dimensions, or rank, that’s consistent with the resulting array. The following code example creates a two-dimensional array of integers by using an array literal.

Dim grid = {{1, 2}, {3, 4}}

In the previous example, an error would occur if the number of elements in the nested array literals didn’t match. An error would also occur if you explicitly declared the array variable to be other than two-dimensional.

Dim values = {({1, 2}), ({3, 4, 5})}

When you create a multidimensional array by using nested array literals, you can use type inference. When you use type inference, the inferred type is the dominant type for all the values in all the array literals for a nesting level. The following code example creates a two-dimensional array of type Double from values that are of type Integer and Double.

Dim a = {{1, 2.0}, {3, 4}, {5, 6}, {7, 8}}

For additional examples, see How to: Initialize an Array Variable in Visual Basic.

Iterating Through an Array

When you iterate through an array, you access each element in the array from the lowest index to the highest index.

The following example iterates through a one-dimensional array by using the For...Next Statement (Visual Basic). The GetUpperBound method returns the highest value that the index can have. The lowest index value is always 0.

Dim numbers = {10, 20, 30}

For index = 0 To numbers.GetUpperBound(0)
    Debug.WriteLine(numbers(index))
Next 
' Output: 
'  10 
'  20 
'  30

The following example iterates through a multidimensional array by using a For...Next statement. The GetUpperBound method has a parameter that specifies the dimension. GetUpperBound(0) returns the high index value for the first dimension, and GetUpperBound(1) returns the high index value for the second dimension.

Dim numbers = {{1, 2}, {3, 4}, {5, 6}}

For index0 = 0 To numbers.GetUpperBound(0)
    For index1 = 0 To numbers.GetUpperBound(1)
        Debug.Write(numbers(index0, index1).ToString & " ")
    Next
    Debug.WriteLine("")
Next 
' Output  
'  1 2  
'  3 4  
'  5 6

The following example iterates through a one-dimensional array by using a For Each...Next Statement (Visual Basic).

Dim numbers = {10, 20, 30}

For Each number In numbers
    Debug.WriteLine(number)
Next 
' Output: 
'  10 
'  20 
'  30

The following example iterates through a multidimensional array by using a For Each...Next statement. However, you have more control over the elements of a multidimensional array if you use a nested For…Next statement, as in a previous example, instead of a For Each…Next statement.

Dim numbers = {{1, 2}, {3, 4}, {5, 6}}

For Each number In numbers
    Debug.WriteLine(number)
Next 
' Output: 
'  1 
'  2 
'  3 
'  4 
'  5 
'  6

Arrays as Return Values and Parameters

To return an array from a Function procedure, specify the array data type and the number of dimensions as the return type of the Function Statement (Visual Basic). Within the function, declare a local array variable with same data type and number of dimensions. In the Return Statement (Visual Basic), include the local array variable without parentheses.

To specify an array as a parameter to a Sub or Function procedure, define the parameter as an array with a specified data type and number of dimensions. In the call to the procedure, send an array variable with the same data type and number of dimensions.

In the following example, the GetNumbers function returns an Integer(). This array type is a one dimensional array of type Integer. The ShowNumbers procedure accepts an Integer() argument.

Public Sub Process()
    Dim numbers As Integer() = GetNumbers()
    ShowNumbers(numbers)
End Sub 

Private Function GetNumbers() As Integer()
    Dim numbers As Integer() = {10, 20, 30}
    Return numbers
End Function 

Private Sub ShowNumbers(numbers As Integer())
    For index = 0 To numbers.GetUpperBound(0)
        Debug.WriteLine(numbers(index) & " ")
    Next 
End Sub 

' Output: 
'   10 
'   20 
'   30

In the following example, the GetNumbersMultiDim function returns an Integer(,). This array type is a two dimensional array of type Integer. The ShowNumbersMultiDim procedure accepts an Integer(,) argument.

Public Sub ProcessMultidim()
    Dim numbers As Integer(,) = GetNumbersMultidim()
    ShowNumbersMultidim(numbers)
End Sub 

Private Function GetNumbersMultidim() As Integer(,)
    Dim numbers As Integer(,) = {{1, 2}, {3, 4}, {5, 6}}
    Return numbers
End Function 

Private Sub ShowNumbersMultidim(numbers As Integer(,))
    For index0 = 0 To numbers.GetUpperBound(0)
        For index1 = 0 To numbers.GetUpperBound(1)
            Debug.Write(numbers(index0, index1).ToString & " ")
        Next
        Debug.WriteLine("")
    Next 
End Sub 

' Output   
'  1 2   
'  3 4   
'  5 6

Jagged Arrays

An array that holds other arrays as elements is known as an array of arrays or a jagged array. A jagged array and each element in a jagged array can have one or more dimensions. Sometimes the data structure in your application is two-dimensional but not rectangular.

The following example has an array of months, each element of which is an array of days. Because different months have different numbers of days, the elements don’t form a rectangular two-dimensional array. Therefore, a jagged array is used instead of a multidimensional array.

' Declare the jagged array. 
' The New clause sets the array variable to a 12-element 
' array. Each element is an array of Double elements. 
Dim sales()() As Double = New Double(11)() {}

' Set each element of the sales array to a Double 
' array of the appropriate size. 
For month As Integer = 0 To 11
    Dim days As Integer =
        DateTime.DaysInMonth(Year(Now), month + 1)
    sales(month) = New Double(days - 1) {}
Next month

' Store values in each element. 
For month As Integer = 0 To 11
    Dim upper = sales(month).GetUpperBound(0)
    For day = 0 To upper
        sales(month)(day) = (month * 100) + day
    Next 
Next

Zero-Length Arrays

An array that contains no elements is also called a zero-length array. A variable that holds a zero-length array doesn’t have the value Nothing. To create an array that has no elements, declare one of the array's dimensions to be -1, as the following example shows.

Dim twoDimensionalStrings(-1, 3) As String

You might need to create a zero-length array under the following circumstances:

• Without risking a NullReferenceException exception, your code must access members of the Array class, such as Length or Rank, or call a Visual Basic function such as UBound.

• You want to keep the consuming code simpler by not having to check for Nothing as a special case.

• Your code interacts with an application programming interface (API) that either requires you to pass a zero-length array to one or more procedures or returns a zero-length array from one or more procedures.

Array Size

The size of an array is the product of the lengths of all its dimensions. It represents the total number of elements currently contained in the array.

The following example declares a three-dimensional array.

Dim prices(3, 4, 5) As Long

The overall size of the array in variable prices is (3 + 1) x (4 + 1) x (5 + 1) = 120.

You can find the size of an array by using the Length property. You can find the length of each dimension of a multi-dimensional array by using the GetLength method.

You can resize an array variable by assigning a new array object to it or by using the ReDim statement.

There are several things to keep in mind when dealing with the size of an array.

Array Types and Other Types

Every array has a data type, but it differs from the data type of its elements. There is no single data type for all arrays. Instead, the data type of an array is determined by the number of dimensions, or rank, of the array, and the data type of the elements in the array. Two array variables are considered to be of the same data type only when they have the same rank and their elements have the same data type. The lengths of the dimensions in an array do not influence the array data type.

Every array inherits from the System.Array class, and you can declare a variable to be of type Array, but you cannot create an array of type Array. Also, the ReDim Statement (Visual Basic) cannot operate on a variable declared as type Array. For these reasons, and for type safety, it is advisable to declare every array as a specific type, such as Integer in the preceding example.

You can find out the data type of either an array or its elements in several ways.

• You can call the Object.GetType method on the variable to receive a Type object for the run-time type of the variable. The Type object holds extensive information in its properties and methods.

• You can pass the variable to the TypeName function to receive a String containing the name of run-time type.

• You can pass the variable to the VarType function to receive a VariantType value representing the type classification of the variable.

The following example calls the TypeName function to determine the type of the array and the type of the elements in the array. The array type is Integer(,) and the elements in the array are of type Integer.

Dim thisTwoDimArray(,) As Integer = New Integer(9, 9) {}
MsgBox("Type of thisTwoDimArray is " & TypeName(thisTwoDimArray))
MsgBox("Type of thisTwoDimArray(0, 0) is " & TypeName(thisTwoDimArray(0, 0)))

Collections as an Alternative to Arrays

Arrays are most useful for creating and working with a fixed number of strongly typed objects. Collections provide a more flexible way to work with groups of objects. Unlike arrays, the group of objects that you work with can grow and shrink dynamically as the needs of the application change.

If you need to change the size of an array, you must use the ReDim Statement (Visual Basic). When you do this, Visual Basic creates a new array and releases the previous array for disposal. This takes execution time. Therefore, if the number of items you are working with changes frequently, or you cannot predict the maximum number of items you need, you might obtain better performance using a collection.

For some collections, you can assign a key to any object that you put into the collection so that you can quickly retrieve the object by using the key.

If your collection contains elements of only one data type, you can use one of the classes in the System.Collections.Generic namespace. A generic collection enforces type safety so that no other data type can be added to it. When you retrieve an element from a generic collection, you do not have to determine its data type or convert it.

For more information about collections, see Collections (C# and Visual Basic).

Example

The following example uses the .NET Framework generic class System.Collections.Generic.List<T> to create a list collection of Customer objects.

' Define the class for a customer. 
Public Class Customer
    Public Property Name As String 
    ' Insert code for other members of customer structure. 
End Class 

' Create a module-level collection that can hold 200 elements. 
Public CustomerList As New List(Of Customer)(200)

' Add a specified customer to the collection. 
Private Sub AddNewCustomer(ByVal newCust As Customer)
    ' Insert code to perform validity check on newCust.
    CustomerList.Add(newCust)
End Sub 

' Display the list of customers in the Debug window. 
Private Sub PrintCustomers()
    For Each cust As Customer In CustomerList
        Debug.WriteLine(cust)
    Next cust
End Sub

The declaration of the CustomerFile collection specifies that it can contain elements only of type Customer. It also provides for an initial capacity of 200 elements. The procedure AddNewCustomer checks the new element for validity and then adds it to the collection. The procedure PrintCustomers uses a For Each loop to traverse the collection and display its elements.

Related Topics

See Also

Reference

Dim Statement (Visual Basic)

ReDim Statement (Visual Basic)

Array