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
thats called an index or subscript to tell them apart. The individual values are called the
elements of the array. Theyre 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
o 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.
VB
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 thats 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.
VB
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.
VB
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 its created, as the following
example shows.
VB
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.
VB
' 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).
VB
' 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).
VB
' 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.
VB
Dim inquiriesByYearMonthDay()()() As Byte
The preceding examples declare array variables but dont 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.
VB
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.
VB
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.
VB
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 thats 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 cant 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 thats
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 cant 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 thats 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.
VB
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, thats consistent with the resulting array.
The following code example creates a two-dimensional array of integers by using an array literal.
VB
Dim grid = {{1, 2}, {3, 4}}
In the previous example, an error would occur if the number of elements in the nested array
literals didnt match. An error would also occur if you explicitly declared the array variable to be
other than two-dimensional.
Note
You can avoid an error when you supply nested array literals of different dimensions by
enclosing the inner array literals in parentheses. The parentheses force the array literal expression
to be evaluated, and the resulting values are used with the outer array literal, as the following
code shows.
VB
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.
VB
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.
VB
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.
VB
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).
VB
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 ForNext statement, as in a previous example, instead of a For EachNext
statement.
VB
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.
VB
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.
VB
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 dont form a rectangular
two-dimensional array. Therefore, a jagged array is used instead of a multidimensional array.
VB
' 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 doesnt 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.
VB
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.
Dimension
Length
The index of each dimension is 0-based, which means it ranges from 0 through
its upper bound. Therefore, the length of a given dimension is greater by 1 than
the declared upper bound for that dimension.
Length Limits
The length of every dimension of an array is limited to the maximum value of the
Integer data type, which is (2 ^ 31) - 1. However, the total size of an array is also
limited by the memory available on your system. If you attempt to initialize an
array that exceeds the amount of available RAM, the common language runtime
throws an OutOfMemoryException exception.
Size and
Element Size
An array's size is independent of the data type of its elements. The size always
represents the total number of elements, not the number of bytes that they
consume in storage.
Memory
Consumption
It is not safe to make any assumptions regarding how an array is stored in
memory. Storage varies on platforms of different data widths, so the same array
can consume more memory on a 64-bit system than on a 32-bit system.
Depending on system configuration when you initialize an array, the common
language runtime (CLR) can assign storage either to pack elements as close
together as possible, or to align them all on natural hardware boundaries. Also,
an array requires a storage overhead for its control information, and this
overhead increases with each added dimension.
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.
VB
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(Of T) to create a list collection of Customer objects.
VB
' 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.

How to: Sort An Array in Visual Basic
This example declares an array of String objects named zooAnimals, populates it, and then sorts
it alphabetically.
Example
Private Sub sortAnimals()
Dim zooAnimals(2) As String
zooAnimals(0) = "lion"
zooAnimals(1) = "turtle"
zooAnimals(2) = "ostrich"
Array.Sort(zooAnimals)
End Sub