Buffer.BlockCopy Method
Microsoft Silverlight will reach end of support after October 2021. Learn more.
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)
Syntax
'Declaration
<SecuritySafeCriticalAttribute> _
Public Shared Sub BlockCopy ( _
src As Array, _
srcOffset As Integer, _
dst As Array, _
dstOffset As Integer, _
count As Integer _
)
[SecuritySafeCriticalAttribute]
public static void BlockCopy(
Array src,
int srcOffset,
Array dst,
int dstOffset,
int count
)
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.
Exceptions
| Exception | Condition |
|---|---|
| ArgumentNullException | src or dst is nulla null reference (Nothing in Visual Basic). |
| ArgumentException | src or dst is not an array of primitives. -or- The length of src is less than srcOffset plus count. -or- The length of dst is less than dstOffset plus count. |
| ArgumentOutOfRangeException | srcOffset, dstOffset, or count is less than 0. |
Remarks
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.
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.
Examples
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 the system on which this example was run is little-endian, the lower-order bytes of a primitive data type's value precede the higher-order bytes.
Module Example
Private outBlock As System.Windows.Controls.TextBlock
' Display the individual bytes in the array in hexadecimal.
Sub DisplayArray(arr As Array, name As String)
outBlock.Text += String.Format("{0,11}:", name)
For ctr As Integer = 0 to arr.Length - 1
Dim bytes() As Byte = BitConverter.GetBytes(arr(ctr))
For Each byteValue As Byte In bytes
outBlock.Text += String.Format(" {0:X2}", byteValue)
Next
Next
outBlock.Text += vbCrLf
End Sub
' Display the individual array element values in hexadecimal.
Sub DisplayArrayValues(arr As Array, name As String)
' Get the length of one element in the array.
Dim elementLength As Integer = Buffer.ByteLength(arr) / arr.Length
Dim formatString As String = String.Format(" {{0:X{0}}}", 2 * elementLength)
outBlock.Text += String.Format("{0,11}:", name)
For ctr As Integer = 0 to arr.Length - 1
outBlock.Text += String.Format(formatString, arr(ctr))
Next
outBlock.Text += vbCrLf
End Sub
Public Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
outBlock = outputBlock
outBlock.FontFamily = New System.Windows.Media.FontFamily("Courier New")
' These are source and destination arrays for BlockCopy.
Dim src() As Short = {258, 259, 260, 261, 262, 263, 264, _
265, 266, 267, 268, 269, 270}
Dim dest() As Long = {17, 18, 19, 20}
' Display the initial value of the arrays in memory.
outBlock.Text += "Initial values of arrays:" + vbCrLf
outBlock.Text += " Array values as Bytes:" + vbCrLf
DisplayArray(src, "src" )
DisplayArray(dest, "dest" )
outBlock.Text += " Array values:" + vbCrLf
DisplayArrayValues(src, "src")
DisplayArrayValues(dest, "dest")
outBlock.Text += vbCrLf
' Copy bytes 5-10 from source to index 7 in destination and display the result.
Buffer.BlockCopy( src, 5, dest, 7, 6 )
outBlock.Text += "Buffer.BlockCopy(src, 5, dest, 7, 6 )" + vbCrLf
outBlock.Text += " Array values as Bytes:" + vbCrLf
DisplayArray(src, "src")
DisplayArray(dest, "dest")
outBlock.Text += " Array values:" + vbCrLf
DisplayArrayValues(src, "src")
DisplayArrayValues(dest, "dest")
outBlock.Text += vbCrLf
' Copy bytes 16-20 from source to index 22 in destination and display the result.
Buffer.BlockCopy( src, 16, dest, 22, 5 )
outBlock.Text += "Buffer.BlockCopy(src, 16, dest, 22, 5)" + vbCrLf
outBlock.Text += " Array values as Bytes:" + vbCrLf
DisplayArray(src, "src")
DisplayArray(dest, "dest")
outBlock.Text += " Array values:" + vbCrLf
DisplayArrayValues(src, "src")
DisplayArrayValues(dest, "dest")
outBlock.Text += vbCrLf
' Copy overlapping range of bytes 4-10 to index 5 in source.
Buffer.BlockCopy( src, 4, src, 5, 7 )
outBlock.Text += "Buffer.BlockCopy( src, 4, src, 5, 7)" + vbCrLf
outBlock.Text += " Array values as Bytes:" + vbCrLf
DisplayArray(src, "src")
DisplayArray(dest, "dest")
outBlock.Text += " Array values:" + vbCrLf
DisplayArrayValues(src, "src")
DisplayArrayValues(dest, "dest")
outBlock.Text += vbCrLf
' Copy overlapping range of bytes 16-22 to index 15 in source.
Buffer.BlockCopy(src, 16, src, 15, 7)
outBlock.Text += "Buffer.BlockCopy( src, 16, src, 15, 7)" + vbCrLf
outBlock.Text += " Array values as Bytes:" + vbCrLf
DisplayArray(src, "src")
DisplayArray(dest, "dest")
outBlock.Text += " Array values:" + vbCrLf
DisplayArrayValues(src, "src")
DisplayArrayValues(dest, "dest")
End Sub
End Module
' This example of the
' Buffer.BlockCopy( Array, Integer, Array, Integer, Integer )
' method generates the following output.
' Note: The arrays are displayed from right to left.
'
' Initial values of arrays:
'
' src: 010E 010D 010C 010B 010A 0109 0108 0107 0106 0105 0104 0103 0102
' dest: 0000000000000014 0000000000000013 0000000000000012 0000000000000011
'
' Call these methods:
'
' Buffer.BlockCopy( src, 5, dest, 7, 6 ),
' Buffer.BlockCopy( src, 16, dest, 22, 5 ),
' (these overlap source and destination)
' Buffer.BlockCopy( src, 4, src, 5, 7 ),
' Buffer.BlockCopy( src, 16, src, 15, 7 ).
'
' Final values of arrays:
'
' src: 010E 010D 0D01 0C01 0B01 0A09 0108 0701 0601 0501 0404 0103 0102
' dest: 00000000000C010B 010A000000000013 0000000701060105 0100000000000011
using System;
class Example
{
private static System.Windows.Controls.TextBlock outBlock;
// Display the individual bytes in the array in hexadecimal.
public static void DisplayArray(Array arr, string name)
{
outBlock.Text += String.Format("{0,11}:", name);
for (int ctr = 0; ctr < arr.Length; ctr++)
{
byte[] bytes;
if (arr is long[])
bytes = BitConverter.GetBytes((long) arr.GetValue(ctr));
else
bytes = BitConverter.GetBytes((short) arr.GetValue(ctr));
foreach (byte byteValue in bytes)
outBlock.Text += String.Format(" {0:X2}", byteValue);
}
outBlock.Text += "\n";
}
// Display the individual array element values in hexadecimal.
public static void DisplayArrayValues(Array arr, string name)
{
// Get the length of one element in the array.
int elementLength = Buffer.ByteLength(arr) / arr.Length;
string formatString = String.Format(" {{0:X{0}}}", 2 * elementLength);
outBlock.Text += String.Format( "{0,11}:", name);
for (int ctr = 0; ctr < arr.Length; ctr++)
outBlock.Text += String.Format(formatString, arr.GetValue(ctr));
outBlock.Text += "\n";
}
public static void Demo(System.Windows.Controls.TextBlock outputBlock)
{
outBlock = outputBlock;
outBlock.FontFamily = new System.Windows.Media.FontFamily("Courier New");
// These are source and destination arrays for BlockCopy.
short[] src = { 258, 259, 260, 261, 262, 263, 264,
265, 266, 267, 268, 269, 270 };
long[] dest = { 17, 18, 19, 20 };
// Display the initial value of the arrays in memory.
outBlock.Text += "Initial values of arrays:\n";
outBlock.Text += " Array values as Bytes:\n";
DisplayArray(src, "src");
DisplayArray(dest, "dest");
outBlock.Text += " Array values:\n";
DisplayArrayValues(src, "src");
DisplayArrayValues(dest, "dest");
outBlock.Text += "\n";
// Copy bytes 5-10 from source to index 7 in destination and display the result.
Buffer.BlockCopy(src, 5, dest, 7, 6);
outBlock.Text += "Buffer.BlockCopy(src, 5, dest, 7, 6 )\n";
outBlock.Text += " Array values as Bytes:\n";
DisplayArray(src, "src");
DisplayArray(dest, "dest");
outBlock.Text += " Array values:\n";
DisplayArrayValues(src, "src");
DisplayArrayValues(dest, "dest");
outBlock.Text += "\n";
// Copy bytes 16-20 from source to index 22 in destination and display the result.
Buffer.BlockCopy(src, 16, dest, 22, 5);
outBlock.Text += "Buffer.BlockCopy(src, 16, dest, 22, 5)\n";
outBlock.Text += " Array values as Bytes:\n";
DisplayArray(src, "src");
DisplayArray(dest, "dest");
outBlock.Text += " Array values:\n";
DisplayArrayValues(src, "src");
DisplayArrayValues(dest, "dest");
outBlock.Text += "\n";
// Copy overlapping range of bytes 4-10 to index 5 in source.
Buffer.BlockCopy(src, 4, src, 5, 7 );
outBlock.Text += "Buffer.BlockCopy( src, 4, src, 5, 7)\n";
outBlock.Text += " Array values as Bytes:\n";
DisplayArray(src, "src");
DisplayArray(dest, "dest");
outBlock.Text += " Array values:\n";
DisplayArrayValues(src, "src");
DisplayArrayValues(dest, "dest");
outBlock.Text += "\n";
// Copy overlapping range of bytes 16-22 to index 15 in source.
Buffer.BlockCopy(src, 16, src, 15, 7);
outBlock.Text += "Buffer.BlockCopy( src, 16, src, 15, 7)\n";
outBlock.Text += " Array values as Bytes:\n";
DisplayArray(src, "src");
DisplayArray(dest, "dest");
outBlock.Text += " Array values:\n";
DisplayArrayValues(src, "src");
DisplayArrayValues(dest, "dest");
}
}
// This example displays the following output:
// Initial values of arrays:
// Array values as Bytes:
// src: 02 01 03 01 04 01 05 01 06 01 07 01 08 01 09 01 0A 01 0B 01 0C 01 0D 01 0E 01
// dest: 11 00 00 00 00 00 00 00 12 00 00 00 00 00 00 00 13 00 00 00 00 00 00 00 14 00 00 00 00 00 00 00
// Array values:
// src: 0102 0103 0104 0105 0106 0107 0108 0109 010A 010B 010C 010D 010E
// dest: 0000000000000011 0000000000000012 0000000000000013 0000000000000014
//
// Buffer.BlockCopy(src, 5, dest, 7, 6 )
// Array values as Bytes:
// src: 02 01 03 01 04 01 05 01 06 01 07 01 08 01 09 01 0A 01 0B 01 0C 01 0D 01 0E 01
// dest: 11 00 00 00 00 00 00 01 05 01 06 01 07 00 00 00 13 00 00 00 00 00 00 00 14 00 00 00 00 00 00 00
// Array values:
// src: 0102 0103 0104 0105 0106 0107 0108 0109 010A 010B 010C 010D 010E
// dest: 0100000000000011 0000000701060105 0000000000000013 0000000000000014
//
// Buffer.BlockCopy(src, 16, dest, 22, 5)
// Array values as Bytes:
// src: 02 01 03 01 04 01 05 01 06 01 07 01 08 01 09 01 0A 01 0B 01 0C 01 0D 01 0E 01
// dest: 11 00 00 00 00 00 00 01 05 01 06 01 07 00 00 00 13 00 00 00 00 00 0A 01 0B 01 0C 00 00 00 00 00
// Array values:
// src: 0102 0103 0104 0105 0106 0107 0108 0109 010A 010B 010C 010D 010E
// dest: 0100000000000011 0000000701060105 010A000000000013 00000000000C010B
//
// Buffer.BlockCopy( src, 4, src, 5, 7)
// Array values as Bytes:
// src: 02 01 03 01 04 04 01 05 01 06 01 07 08 01 09 01 0A 01 0B 01 0C 01 0D 01 0E 01
// dest: 11 00 00 00 00 00 00 01 05 01 06 01 07 00 00 00 13 00 00 00 00 00 0A 01 0B 01 0C 00 00 00 00 00
// Array values:
// src: 0102 0103 0404 0501 0601 0701 0108 0109 010A 010B 010C 010D 010E
// dest: 0100000000000011 0000000701060105 010A000000000013 00000000000C010B
//
// Buffer.BlockCopy( src, 16, src, 15, 7)
// Array values as Bytes:
// src: 02 01 03 01 04 04 01 05 01 06 01 07 08 01 09 0A 01 0B 01 0C 01 0D 0D 01 0E 01
// dest: 11 00 00 00 00 00 00 01 05 01 06 01 07 00 00 00 13 00 00 00 00 00 0A 01 0B 01 0C 00 00 00 00 00
// Array values:
// src: 0102 0103 0404 0501 0601 0701 0108 0A09 0B01 0C01 0D01 010D 010E
// dest: 0100000000000011 0000000701060105 010A000000000013 00000000000C010B
Version Information
Silverlight
Supported in: 5, 4, 3
Silverlight for Windows Phone
Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0
XNA Framework
Supported in: Xbox 360, Windows Phone OS 7.0
Platforms
For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.