This documentation is archived and is not being maintained.

Array.Copy Method (Array, Int32, Array, Int32, Int32)

.NET Framework 1.1

Copies a range of elements from an Array starting at the specified source index and pastes them to another Array starting at the specified destination index. The length and the indexes are specified as 32-bit integers.

[Visual Basic]
Overloads Public Shared Sub Copy( _
   ByVal sourceArray As Array, _
   ByVal sourceIndex As Integer, _
   ByVal destinationArray As Array, _
   ByVal destinationIndex As Integer, _
   ByVal length As Integer _
)
[C#]
public static void Copy(
 Array sourceArray,
 int sourceIndex,
 Array destinationArray,
 int destinationIndex,
 int length
);
[C++]
public: static void Copy(
 Array* sourceArray,
 int sourceIndex,
 Array* destinationArray,
 int destinationIndex,
 int length
);
[JScript]
public static function Copy(
   sourceArray : Array,
 sourceIndex : int,
 destinationArray : Array,
 destinationIndex : int,
 length : int
);

Parameters

sourceArray
The Array that contains the data to copy.
sourceIndex
A 32-bit integer that represents the index in the sourceArray at which copying begins.
destinationArray
The Array that receives the data.
destinationIndex
A 32-bit integer that represents the index in the destinationArray at which storing begins.
length
A 32-bit integer that represents the number of elements to copy.

Exceptions

Exception Type Condition
ArgumentNullException sourceArray is a null reference (Nothing in Visual Basic).

-or-

destinationArray is a null reference (Nothing).

RankException sourceArray and destinationArray have different ranks.
ArrayTypeMismatchException sourceArray and destinationArray are of incompatible types.
InvalidCastException At least one element in sourceArray cannot be cast to the type of destinationArray.
ArgumentOutOfRangeException sourceIndex is less than the lower bound of the first dimension of sourceArray.

-or-

destinationIndex is less than the lower bound of the first dimension of destinationArray.

-or-

length is less than zero.

ArgumentException length is greater than the number of elements from sourceIndex to the end of sourceArray.

-or-

length is greater than the number of elements from destinationIndex to the end of destinationArray.

Remarks

The sourceArray and destinationArray parameters must have the same number of dimensions.

When copying between multidimensional arrays, the array behaves like a long one-dimensional array, where the rows (or columns) are conceptually laid end to end. For example, if an array has three rows (or columns) with four elements each, copying six elements from the beginning of the array would copy all four elements of the first row (or column) and the first two elements of the second row (or column). To start copying from the second element of the third row (or column), srcIndex must be the upper bound of the first row (or column) plus the length of the second row (or column) plus two.

If sourceArray and destinationArray overlap, this method behaves as if the original values of sourceArray were preserved in a temporary location before destinationArray is overwritten.

[C++] This method is equivalent to the standard C/C++ function memmove, not memcpy.

The arrays can be reference-type arrays or value-type arrays. Type downcasting is performed, as required.

  • When copying from a reference-type array to a value-type array, each element is unboxed and then copied. When copying from a value-type array to a reference-type array, each element is boxed and then copied.
  • When copying from a reference-type or value-type array to an Object array, an Object is created to hold each value or reference and then copied. When copying from an Object array to a reference-type or value-type array and the assignment is not possible, an InvalidCastException is thrown.
  • If sourceArray and destinationArray are both reference-type arrays or are both arrays of type Object, a shallow copy is performed. A shallow copy of an Array is a new Array containing references to the same elements as the original Array. The elements themselves or anything referenced by the elements are not copied. In contrast, a deep copy of an Array copies the elements and everything directly or indirectly referenced by the elements.

An ArrayTypeMismatchException is thrown if the arrays are of incompatible types. Type compatibility is defined as follows:

  • A type is compatible with itself.
  • A value type is compatible with Object and with an interface type implemented by that value type. A value type is considered connected to an interface only if it implements that interface directly. Disconnected types are not compatible.
  • Two intrinsic (predefined) value types are compatible if copying from the source type to the destination type is a widening conversion. A widening conversion never loses information, whereas a narrowing conversion can lose information. For example, converting a 32-bit signed integer to a 64-bit signed integer is a widening conversion, and converting a 64-bit signed integer to a 32-bit signed integer is a narrowing conversion. For more information about conversions, see Convert.
  • A nonintrinsic (user-defined) value type is compatible only with itself.

If every element in sourceArray requires a downcast (for example, from a base class to a derived class or from an interface to an object) and one or more elements cannot be cast to the corresponding type in destinationArray, an InvalidCastException is thrown.

If this method throws an exception while copying, the state of destinationArray is undefined.

Example

The following code example shows how to copy from one Array of type Object to another Array of type integer.

[Visual Basic] 
Imports System
Imports Microsoft.VisualBasic

Public Class SamplesArray    
    
    Public Shared Sub Main()
        
        ' Creates and initializes a new Array of type Int32.
        Dim myIntArray As Array = _
           Array.CreateInstance(Type.GetType("System.Int32"), 5)
        Dim i As Integer
        For i = myIntArray.GetLowerBound(0) To myIntArray.GetUpperBound(0)
            myIntArray.SetValue(i + 1, i)
        Next i 
        ' Creates and initializes a new Array of type Object.
        Dim myObjArray As Array = _
           Array.CreateInstance(Type.GetType("System.Object"), 5)
        For i = myObjArray.GetLowerBound(0) To myObjArray.GetUpperBound(0)
            myObjArray.SetValue(i + 26, i)
        Next i 
        ' Displays the initial values of both arrays.
        Console.WriteLine("Int32 array:")
        PrintValues(myIntArray)
        Console.WriteLine("Object array:")
        PrintValues(myObjArray)
        
        ' Copies the first element from the Int32 array to the Object array.
        Array.Copy(myIntArray, myIntArray.GetLowerBound(0), myObjArray, _
           myObjArray.GetLowerBound(0), 1)
        
        ' Copies the last two elements from the Object array to the Int32 array.
        Array.Copy(myObjArray, myObjArray.GetUpperBound(0) - 1, myIntArray, _
           myIntArray.GetUpperBound(0) - 1, 2)
        
        ' Displays the values of the modified arrays.
        Console.WriteLine("Int32 array - Last two elements should now be " _
           + "the same as Object array:")
        PrintValues(myIntArray)
        Console.WriteLine("Object array - First element should now be the " _
           + "same as Int32 array:")
        PrintValues(myObjArray)
    End Sub
    
    Public Shared Sub PrintValues(myArr As Array)
        Dim myEnumerator As System.Collections.IEnumerator = _
           myArr.GetEnumerator()
        Dim i As Integer = 0
        Dim cols As Integer = myArr.GetLength((myArr.Rank - 1))
        While myEnumerator.MoveNext()
            If i < cols Then
                i += 1
            Else
                Console.WriteLine()
                i = 1
            End If
            Console.Write(ControlChars.Tab + "{0}", myEnumerator.Current)
        End While
        Console.WriteLine()
    End Sub
End Class

' This code produces the following output.
' 
' Int32 array:
'     1    2    3    4    5
' Object array:
'     26    27    28    29    30
' Int32 array - Last two elements should now be the same as Object array:
'     1    2    3    29    30
' Object array - First element should now be the same as Int32 array:
'     1    27    28    29    30

[C#] 
using System;
public class SamplesArray  {

   public static void Main()  {

      // Creates and initializes a new Array of type Int32.
      Array myIntArray=Array.CreateInstance( Type.GetType("System.Int32"), 5 );
      for ( int i = myIntArray.GetLowerBound(0); i <= myIntArray.GetUpperBound(0); i++ )
         myIntArray.SetValue( i+1, i );

      // Creates and initializes a new Array of type Object.
      Array myObjArray = Array.CreateInstance( Type.GetType("System.Object"), 5 );
      for ( int i = myObjArray.GetLowerBound(0); i <= myObjArray.GetUpperBound(0); i++ )
         myObjArray.SetValue( i+26, i );

      // Displays the initial values of both arrays.
      Console.WriteLine( "Int32 array:" );
      PrintValues( myIntArray );
      Console.WriteLine( "Object array:" );
      PrintValues( myObjArray );

      // Copies the first element from the Int32 array to the Object array.
      Array.Copy( myIntArray, myIntArray.GetLowerBound(0), myObjArray, myObjArray.GetLowerBound(0), 1 );

      // Copies the last two elements from the Object array to the Int32 array.
      Array.Copy( myObjArray, myObjArray.GetUpperBound(0) - 1, myIntArray, myIntArray.GetUpperBound(0) - 1, 2 );

      // Displays the values of the modified arrays.
      Console.WriteLine( "Int32 array - Last two elements should now be the same as Object array:" );
      PrintValues( myIntArray );
      Console.WriteLine( "Object array - First element should now be the same as Int32 array:" );
      PrintValues( myObjArray );
   }


   public static void PrintValues( Array myArr )  {
      System.Collections.IEnumerator myEnumerator = myArr.GetEnumerator();
      int i = 0;
      int cols = myArr.GetLength( myArr.Rank - 1 );
      while ( myEnumerator.MoveNext() )  {
         if ( i < cols )  {
            i++;
         } else  {
            Console.WriteLine();
            i = 1;
         }
         Console.Write( "\t{0}", myEnumerator.Current );
      }
      Console.WriteLine();
   }
}
/*
This code produces the following output.

Int32 array:
    1    2    3    4    5
Object array:
    26    27    28    29    30
Int32 array - Last two elements should now be the same as Object array:
    1    2    3    29    30
Object array - First element should now be the same as Int32 array:
    1    27    28    29    30
*/

[C++] 
#using <mscorlib.dll>
using namespace System;

void PrintValues( Array* myArr );

void main()  {
 
       // Creates and initializes a new Array instance of type Int32.
       Array* myIntArray=Array::CreateInstance( Type::GetType("System.Int32"), 5 );
       for ( int i = myIntArray->GetLowerBound(0); i <= myIntArray->GetUpperBound(0); i++ )
          myIntArray->SetValue( __box(i+1), i );
 
       // Creates and initializes a new Array instance of type Object.
       Array* myObjArray = Array::CreateInstance( Type::GetType("System.Object"), 5 );
       for ( int i = myObjArray->GetLowerBound(0); i <= myObjArray->GetUpperBound(0); i++ )
          myObjArray->SetValue( __box(i+26), i );
 
       // Displays the initial values of both arrays.
       Console::WriteLine( "Int32 array:" );
       PrintValues( myIntArray );
       Console::WriteLine( "Object array:" );
       PrintValues( myObjArray );
 
       // Copies the first element from the Int32 array to the Object array.
       Array::Copy( myIntArray, myIntArray->GetLowerBound(0), myObjArray, myObjArray->GetLowerBound(0), 1 );
 
       // Copies the last two elements from the Object array to the Int32 array.
       Array::Copy( myObjArray, myObjArray->GetUpperBound(0) - 1, myIntArray, myIntArray->GetUpperBound(0) - 1, 2 );
 
       // Displays the values of the modified arrays.
       Console::WriteLine( "Int32 array - Last two elements should now be the same as Object array:" );
       PrintValues( myIntArray );
       Console::WriteLine( "Object array - First element should now be the same as Int32 array:" );
       PrintValues( myObjArray );
    }
 
 
void PrintValues( Array* myArr )  {
    System::Collections::IEnumerator* myEnumerator = myArr->GetEnumerator();
    int i = 0;
    int cols = myArr->GetLength( myArr->Rank - 1 );
    while ( myEnumerator->MoveNext() )  {
        if ( i < cols )  {
            i++;
        } 
        else  {
            Console::WriteLine();
            i = 1;
        }
        Console::Write( "\t{0}", myEnumerator->Current );
    }
    Console::WriteLine();
}

 /*
 This code produces the following output.
 
 Int32 array:
     1    2    3    4    5
 Object array:
     26    27    28    29    30
 Int32 array - Last two elements should now be the same as Object array:
     1    2    3    29    30
 Object array - First element should now be the same as Int32 array:
     1    27    28    29    30
 */

[JScript] 
import System;

// Creates and initializes a new System.Array of type Int32.
var myIntArray : System.Array = System.Array.CreateInstance( Type.GetType("System.Int32"), 5 );
for ( var i : int = myIntArray.GetLowerBound(0); i <= myIntArray.GetUpperBound(0); i++ )
  myIntArray.SetValue( Int32(i+1), i );

// Creates and initializes a new Array of type Object.
var myObjArray : System.Array = System.Array.CreateInstance( Type.GetType("System.Object"), 5 );
for ( var j : int = myObjArray.GetLowerBound(0); j <= myObjArray.GetUpperBound(0); j++ )
  myObjArray.SetValue( Int32(j+26), j);

// Displays the initial values of both arrays.
Console.WriteLine( "Int32 array:" );
PrintValues( myIntArray );
Console.WriteLine( "Object array:" );
PrintValues( myObjArray );

// Copies the first element from the Int32 array to the Object array.
System.Array.Copy( myIntArray, myIntArray.GetLowerBound(0), myObjArray, myObjArray.GetLowerBound(0), 1 );

// Copies the last two elements from the Object array to the Int32 array.
System.Array.Copy( myObjArray, myObjArray.GetUpperBound(0) - 1, myIntArray, myIntArray.GetUpperBound(0) - 1, 2 );

// Displays the values of the modified arrays.
Console.WriteLine( "Int32 array - Last two elements should now be the same as Object array:" );
PrintValues( myIntArray );
Console.WriteLine( "Object array - First element should now be the same as Int32 array:" );
PrintValues( myObjArray );
 
 
function PrintValues( myArr : System.Array )  {
   var myEnumerator : System.Collections.IEnumerator = myArr.GetEnumerator();
   var i : int = 0;
   var cols : int = myArr.GetLength( myArr.Rank - 1 );
   while ( myEnumerator.MoveNext() )  {
      if ( i < cols )  {
         i++;
      } else  {
         Console.WriteLine();
         i = 1;
      }
      Console.Write( "\t{0}", myEnumerator.Current );
   }
   Console.WriteLine();
}
 /*
 This code produces the following output.
 
 Int32 array:
     1    2    3    4    5
 Object array:
     26    27    28    29    30
 Int32 array - Last two elements should now be the same as Object array:
     1    2    3    29    30
 Object array - First element should now be the same as Int32 array:
     1    27    28    29    30
 */

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework, Common Language Infrastructure (CLI) Standard

See Also

Array Class | Array Members | System Namespace | Array.Copy Overload List

Show: