Visual Basic 2005 in a Nutshell (In a Nutshell (OReilly))

Class

System.Array

Syntax

Array.Copy(sourceArray, destinationArray, length)

or:

Array.Copy(sourceArray, sourceIndex, destinationArray, _ destinationIndex, length)

sourceArray (required; any array)

The source array to be copied

sourceIndex (required in syntax 2; Integer or Long)

The index in sourceArray at which copying begins

destinationArray (required; any array)

The destination array for the copied array items

destinationIndex (required in syntax 2; Integer or Long)

The index in destinationArray where the first element is to be copied

length (required; Integer or Long)

The number of elements to copy

Description

The Copy method makes a copy of all or part of an array. Since arrays are reference types, setting one array variable equal to another simply assigns a new reference to the same array. Consider the following code:

Dim mainArray( ) As Integer = {1, 2, 3} Dim otherArray( ) As Integer otherArray = mainArray otherArray(0) = 10 MsgBox(mainArray(0)) ' Displays 10

Since changes to otherArray impacted mainArray, the two arrays are clearly the same.

The Copy method makes a true copy of the elements, not simply a new reference to the same array. For arrays of value types, the new elements will be truly distinct. For arrays of reference types, the new elements can still impact the original reference data.

Usage at a Glance

• The first syntax copies a range of values from the beginning of sourceArray to the beginning of destinationArray. The second syntax copies a range of values from anywhere in sourceArray to anywhere in destinationArray.

• sourceArray and destinationArray must have the same number of dimensions.

• length is the total number of elements to be copied. If sampleArray is a two-by-two array (four total elements), the statement:

  Array.Copy(sampleArray, 0, targetArray, 0, 3)

  copies elements (0,0), (0,1), and (1,0) from sampleArray to targetArray.

• To copy all elements, use UBound(sourceArray)+1 as an argument to length.

• If sourceArray and destinationArray are the same, and destinationIndex lies within the range of values being copied (that is, if the source and target ranges overlap), no data will be lost. The method behaves as if it copies length elements from sourceArray to a temporary buffer, then copies from the temporary buffer to destinationArray.

Example

This sample is similar to the code shown above in the "Description" section comments, but it uses the Copy method instead of a direct assignment.

Dim mainArray( ) As Integer = {1, 2, 3} Dim otherArray( ) As Integer ReDim otherArray(UBound(mainArray) + 1) Array.Copy(mainArray, otherArray, UBound(mainArray) + 1) otherArray(0) = 10 MsgBox(mainArray(0)) ' Displays 1

Version Differences

Since arrays were not reference types in VB 6, you could simply create a copy of an existing array through assignment, thus eliminating the need for a Copy method.

See Also

Array Class, Array.Sort Method