NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

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

Copies a range of elements from a one-dimensional Array starting at the specified source index, and pastes them into another one-dimensional Array starting at the specified destination index.

[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 one-dimensional Array containing the data to copy.
sourceIndex
The starting index in the sourceArray where copying begins.
destinationArray
The one-dimensional Array to receive the data.
destinationIndex
The starting index in the destinationArray where storing begins.
length
The number of elements to copy.

Return Value

None.

Exceptions

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

-or-

destinationArray is a null reference (Nothing).

RankException sourceArray is multidimensional.

-or-

destinationArray is multidimensional.

ArrayTypeMismatchException sourceArray and destinationArray are of incompatible types.
InvalidCastException At least one element in sourceArray could not be cast to destinationArray 's type.
ArgumentOutOfRangeException sourceIndex is less than sourceArray 's lower bound.

-or-

destinationIndex is less than destinationArray 's lower bound.

-or-

length is less than 0.

-or-

The sum of sourceIndex and length is greater than the number of elements in sourceArray.

-or-

The sum of destinationIndex and length is greater than the number of elements in destinationArray.

Remarks

Both the source array and the destination array must be one-dimensional. The source array can have zero elements.

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

Note that if this method throws an exception while copying, the elements of destination may be modified only up to the point where the exception occurs.

Supports multidimensional arrays, if their ranks and bounds are identical.

If the source and destination are both arrays of reference types, a shallow copy is performed. (The data members of the elements are not cloned, but rather referenced by the copy.) If the source and the destination are of incompatible types or if they differ by rank, an ArrayTypeMismatchException is thrown. If every element in the source requires a downcast (for example, from a base class to a subclass or from an interface to an object) and at least one element of the source cannot be cast to the corresponding type in the destination, an InvalidCastException is thrown.

If the source is an array of reference types and the destination is an array of value types, each element of source is unboxed and then copied into destination. If the source and the destination are of incompatible types or they differ by rank, an ArrayTypeMismatchException is thrown. If every element in the source requires a downcast and at least one element of the source cannot be cast to the corresponding type in the destination, an InvalidCastException is thrown.

Note that if the destination is an array of value types, the source must be either an array of the same value type, or an array of Object types or interface types implemented by that value type. Otherwise an ArrayTypeMismatchException is thrown because an interface and a value type that aren't directly connected are guaranteed not to be indirectly connected.

If source is an array of value types and destination is an array of reference types, each element of source is boxed and then copied to the reference array. If the source and the destination are of incompatible types or they differ by rank, an ArrayTypeMismatchException is thrown.

Note that if the source is a value type array, the destination can only be the same value type array, or an Object or interface array, where the interface is implemented by that value type. Down casting is not applicable in this situation, so an InvalidCastException will never occur.

If source and destination are both arrays of intrinsic value types, the copy will succeed. If the element types are identical or if the conversion from the source element type to the destination, element type is a widening coercion. An ArrayTypeMismatchException is thrown whenever a narrowing coercion is required. An ArrayTypeMismatchException is also thrown if either the source or the destination arrays are user-defined value types (i.e., non-intrinsic value types). If source and destination are both arrays of Objects, they are copied as described above for arrays of value types. If source is an array of Object and destination is an array of reference (or value) types, the values stored in each Object are retrieved, boxed, if needed, and copied to the destination array. A InvalidCastException is thrown if this assignment is not possible. If source is an array of reference or value types and destination is an array of type Object, an Object is created to hold each value (or reference) in source and is copied into destination.

See Also

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