Buffer.BlockCopy Method (Array, Int32, Array, Int32, Int32)

 
System_CAPS_noteNote

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Copies a specified number of bytes from a source array starting at a particular offset to a destination array starting at a particular offset.

Namespace:   System
Assembly:  mscorlib (in mscorlib.dll)

static member BlockCopy : 
        src:Array *
        srcOffset:int *
        dst:Array *
        dstOffset:int *
        count:int -> unit

Parameters

src
Type: System.Array

The source buffer.

srcOffset
Type: System.Int32

The zero-based byte offset into src.

dst
Type: System.Array

The destination buffer.

dstOffset
Type: System.Int32

The zero-based byte offset into dst.

count
Type: System.Int32

The number of bytes to copy.

Exception Condition
ArgumentNullException

src or dst is null.

ArgumentException

src or dst is not an array of primitives.

-or-

The number of bytes in src is less than srcOffset plus count.

-or-

The number of bytes in dst is less than dstOffset plus count.

ArgumentOutOfRangeException

srcOffset, dstOffset, or count is less than 0.

This method copies count bytes from src, beginning at srcOffset, to dst, beginning at dstOffset. Both srcOffset and dstOffset are zero-based; that is, the first byte in each buffer is at position 0, not position 1.

The BlockCopy method accesses the bytes in the src parameter array using offsets into memory, not programming constructs such as indexes or upper and lower array bounds. For example, if in the programming language of your application you declare an Int32 array with a zero-based lower bound of -50, and then pass the array and an offset of 5 to the BlockCopy method, the first array element the method will access is the second element of the array, which is at index -49. Furthermore, which byte of array element -49 is accessed first depends on the endianness of the computer that is executing your application.

As its name suggests, the BlockCopy method copies a block of bytes as a whole, rather than copying one byte at a time. Therefore, if src and dst reference the same array, and the range from srcOffset + count -1 overlaps the range from dstOffset + count - 1, the values of the overlapping bytes are not overwritten before they are copied to the destination. In the following example, the values of bytes 0-16 in an array named arr are copied to bytes 12-28. Despite the overlapping range, the values of the source bytes are successfully copied.

No code example is currently available or this language may not be supported.

In the following example, the values of bytes 12-28 in an array named arr are copied to bytes 0-16. Again, despite the overlapping range, the values of the source bytes are successfully copied.

No code example is currently available or this language may not be supported.

The following example copies regions of arrays by using the BlockCopy method. For each BlockCopy operation, it lists the source and destination arrays as both an array of values and as a sequence of bytes. The example illustrates the importance of considering a system's endianness when working with the BlockCopy method: Because Windows systems are little-endian, the lower-order bytes of a primitive data type's value precede the higher-order bytes.

No code example is currently available or this language may not be supported.

Universal Windows Platform
Available since 8
.NET Framework
Available since 1.1
Portable Class Library
Supported in: portable .NET platforms
Silverlight
Available since 2.0
Windows Phone Silverlight
Available since 7.0
Windows Phone
Available since 8.1
Return to top
Show: