Array.Copy Method (Array, Int32, Array, Int32, Int32)
Copies a specified range of objects from an array (source array) and pastes them into another array (destination array). Copying starts at the specified index number in the source array; pasting starts at the specified index number in the destination array. You specify the length of the range to be copied and the starting index numbers for the range in both the source and destination arrays as 32-bit integers.
Namespace: System
Assembly: mscorlib (in mscorlib.dll)
Syntax
[MethodImplAttribute]
public static void Copy (
ArraysourceArray,
intsourceIndex,
ArraydestinationArray,
intdestinationIndex,
intlength
)
Parameters
- sourceArray
The array that contains the range of objects you want to copy. - sourceIndex
A 32-bit integer that represents the index number in the source array at which you want the copying to begin. - destinationArray
The array into which you want to paste the copied objects. - destinationIndex
A 32-bit integer that represents the index number in the destination array at which you want the pasting of copied objects to begin. - length
A 32-bit integer that represents the number of objects you want to copy.
Remarks
The sourceArray and destinationArray parameters must have the same number of dimensions.
When you copy objects between multidimensional arrays, the arrays behave like long one-dimensional arrays, where the rows or columns are conceptually laid end to end. For example, if an array has three rows (or columns) containing four objects each, copying six objects from the beginning of the source array would copy all four objects in the first row (or column) and the first two objects in the second row (or column).
If the values of the sourceArray and destinationArray parameters overlap, this method behaves as if the original sourceArray values were preserved in a temporary location before the destinationArray parameter was overwritten.
The arrays can be either reference-type arrays or value-type arrays. Type downcasting is performed, as required.
- When you copy objects from a reference-type array to a value-type array, each object is unboxed and then copied. When you copy objects from a value-type array to a reference-type array, each object is boxed and then copied.
- When you copy objects from a reference-type or value-type array to an Object array, an instance of the Object class is created for each reference or value to be copied, and then the objects are copied. When you copy objects from an Object array to a reference-type or value-type array and the assignment is not possible, an InvalidCastException exception is thrown.
- If the source array and the destination array are both reference-type arrays or are both Object arrays, a shallow copy is created. A shallow copy of an array is a new array that contains references to all of the objects in the source array, but not the objects themselves or anything referenced by those objects. By contrast, a deep copy of an array contains all of the objects from the source array and everything directly or indirectly referenced by those objects.
An ArrayTypeMismatchException exception is thrown if the source and destination arrays are of incompatible types. Type compatibility is defined as follows:
- Any array type is compatible with itself.
- A value-type array is compatible with an Object array and with an interface type implemented by that particular value type. Furthermore, a value-type array is considered connected to an interface only if it implements that interface directly. Disconnected array types are not compatible.
- Two intrinsic (predefined) value-type arrays are compatible if the copying process from the source array type to the destination array type is a widening conversion. A widening conversion never loses data, whereas a narrowing conversion can lose data. For example, converting a 32-bit signed integer to a 64-bit signed integer is a widening conversion; converting a 64-bit signed integer to a 32-bit signed integer is a narrowing conversion.
- A nonintrinsic (user-defined) value-type array is compatible only with itself.
If every object in the source array requires a downcast (for example, from a base class to a derived class or from an interface to an object) and one or more objects cannot be cast to the corresponding type in the destination array, an InvalidCastException exception is thrown.
If this method throws an exception while copying objects, the state of the destinationArray parameter is undefined.
Version Information
Available in the .NET Micro Framework versions 2.0, 2.5, 3.0, 4.0, and 4.1.