Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

Array.ConstrainedCopy Method

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. Guarantees that all changes are undone if the copy does not succeed completely.

Namespace:  System
Assembly:  mscorlib (in mscorlib.dll)
public static void ConstrainedCopy(
	Array sourceArray,
	int sourceIndex,
	Array destinationArray,
	int destinationIndex,
	int length
)

Parameters

sourceArray
Type: System.Array

The Array that contains the data to copy.

sourceIndex
Type: System.Int32

A 32-bit integer that represents the index in the sourceArray at which copying begins.

destinationArray
Type: System.Array

The Array that receives the data.

destinationIndex
Type: System.Int32

A 32-bit integer that represents the index in the destinationArray at which storing begins.

length
Type: System.Int32

A 32-bit integer that represents the number of elements to copy.

ExceptionCondition
ArgumentNullException

sourceArray is null.

-or-

destinationArray is null.

RankException

sourceArray and destinationArray have different ranks.

ArrayTypeMismatchException

The sourceArray type is neither the same as nor derived from the destinationArray type.

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.

The sourceArray and destinationArray parameters must have the same number of dimensions. The sourceArray type must be the same as or derived from the destinationArray type; otherwise, an ArrayTypeMismatchException is thrown. Unlike Copy, ConstrainedCopy verifies the compatibility of the array types before performing any operation.

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), sourceIndex 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. 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.

If this method throws an exception while copying, the destinationArray remains unchanged; therefore, ConstrainedCopy can be used within a constrained execution region (Cer).

This method is an O(n) operation, where n is length.

.NET Framework

Supported in: 4.5.1, 4.5, 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

.NET for Windows Store apps

Supported in: Windows 8

.NET for Windows Phone apps

Supported in: Windows Phone 8.1, Windows Phone 8, Silverlight 8.1

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.