D.4.2- Array Functions and Statements

Array

Returns a comma-delimited list of values as a Variant subtype Array (8192).

Syntax

Array(arglist)

arglist is a comma-delimited list of values that is inserted into the one dimensional array in the order they appear in the list

Note

An array of zero length is created if arglist contains no arguments.

All arrays in VBScript are zero-based, which means that the first element in the list will be element 0 in the returned array.

Example

Dim arrstrTest

' Create an array with three elements

arrstrTest = Array( _
"Element0", "Element1", "Element2")
' Show the first list element
' now in the array
MsgBox arrstrTest(0)

MsgBox displays Element0

See Also

Dim

Erase

Reinitializes the elements if it is a fixed-size array and de-allocates the memory used if it is a dynamic array.

Syntax

Erase array

array is the array to be reinitialized or erased.

Note

You must know if you are using a fixed-size or a dynamic array, because this statement behaves differently depending on the array type.

Because the memory is de-allocated when using Erase with dynamic arrays, you must re-declare the array structure with the ReDim statement, before you use it again.

Fixed-size arrays are reinitialized differently depending on the contents of the elements:

Numeric Set to 0.
Strings Set to ""

Objects Set to Nothing.

Example

Dim arrstrDynamic()
Dim arrstrFixed(3)

' Allocate space for the
' dynamic array
ReDim arrstrDynamic(3)
' Free the memory used by
' the dynamic array
Erase arrstrDynamic
' Reinitialize the elements
' in the fixed-size array
Erase arrstrFixed

See Also

Dim and ReDim

For Each

Performs a group of statements repeatedly for each element in a collection or an array.

Syntax

For Each element In group

[statements]

[Exit For]

Next [element]

element is a variable used for iterating through the elements in a collection or an array.

group is the name of the object or array.

statements is one or more statements you want to execute on each item in the group.

Note

The For Each loop is only entered if there is at least one element in the collection or array. All the statements in the loop are executed for all the elements in the group. You can control this by executing the Exit For statement if a certain condition is met. This will exit the loop and start executing on the first line after the Next statement.

The For Each loops can be nested, but you must make sure that each loop element is unique.

Example

Dim arrstrLoop
Dim strElement

' Create the array
arrstrLoop = Array( "Element0", "Element1", "Element2")
' Loop through the array
For Each strElement In arrstrLoop
' Display the element content
MsgBox strElement
Next

IsArray

Returns a Variant subtype Boolean (11) indicating if a variable is
an array.

Syntax

IsArray(varname)

varname is a variable you want to check is an array.

Note

Only returns true if varname is an array.

Example

Dim strName
Dim arrstrFixed(3)

strName = "WROX rocks!"
MsgBox IsArray( strName) ' false
MsgBox IsArray( arrstrFixed) ' true

See Also

IsDate, IsEmpty, IsNull, IsNumeric, IsObject and VarType

LBound

Returns the smallest possible subscript for the dimension indicated.

Syntax

LBound(arrayname[, dimension])

arrayname is the name of the array variable.

dimension is an integer indicating the dimension you want to know the smallest possible subscript for. The dimension starts with 1, which is also the default that will be used if this argument is omitted.

Note

The smallest possible subscript for any array is always 0 in VBScript. LBound will raise a runtime error if the array has not
been initialized.

Example

Dim arrstrFixed(3)

MsgBox LBound(arrstrFixed)

MsgBox displays 0.

See Also

Dim, ReDim and UBound

ReDim

This statement is used to size or resize a dynamic array.

Syntax

ReDim [Preserve] varname(subscripts[, varname(subscripts)]...)

Preserve (Optional) is used to preserve the data in an existing array, when you resize it. The overhead of using this functionality
is quite high and should only be used when necessary.

varname is the name of the array variable.

subscripts is the dimension of the array variable varname. You can declare up to 60 multiple dimensions. The syntax is:

upper[, upper]...

where you indicate the upper bounds of the subscript. The lower bound is always zero.

Note

A dynamic array must already have been declared without dimension subscripts, when you size or resize it. If you use the Preserve keyword, only the last array dimension can be resized and the number of dimensions will remain unchanged.

Since an array can be made smaller when resizing, you should take care that you don't lose any data already in the array.

Example

Dim arrstrDynamic()

' Size the dimension to
' contain one dimension
' with 3 elements
ReDim arrstrDynamic(3)
' Put data in the array
arrstrDynamic(0) = "1"
arrstrDynamic(1) = "2"
arrstrDynamic(2) = "3"

' Resize the array, but
' keep the existing data
ReDim Preserve arrstrDynamic(5)
' Display the 3rd element
MsgBox arrstrDynamic(2)

MsgBox displays 3.

See Also

Dim and Set

UBound

Returns the largest possible subscript for the dimension indicated

Syntax

UBound(arrayname[, dimension])

arrayname is the name of the array variable.

dimension is an integer indicating the dimension you want to know the largest possible subscript for. The dimension starts with 1, which is also the default that will be used if this argument is omitted.

Note

UBound will raise a runtime error if the array has not been initialized. If the array is empty, -1 is returned.

Example

Dim arrstrFixed(3)

MsgBox UBound(arrstrFixed)

MsgBox displays 3.

See Also

Dim statement, UBound and ReDim statement