Export (0) Print
Expand All

Buffer.BlockCopy Method

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)

'Declaration
Public Shared Sub BlockCopy ( _
	src As Array, _
	srcOffset As Integer, _
	dst As Array, _
	dstOffset As Integer, _
	count As Integer _
)
'Usage
Dim src As Array
Dim srcOffset As Integer
Dim dst As Array
Dim dstOffset As Integer
Dim count As Integer

Buffer.BlockCopy(src, srcOffset, dst, dstOffset, count)
public static void BlockCopy (
	Array src, 
	int srcOffset, 
	Array dst, 
	int dstOffset, 
	int count
)
public static function BlockCopy (
	src : Array, 
	srcOffset : int, 
	dst : Array, 
	dstOffset : int, 
	count : int
)

Parameters

src

The source buffer.

srcOffset

The byte offset into src.

dst

The destination buffer.

dstOffset

The byte offset into dst.

count

The number of bytes to copy.

Exception typeCondition

ArgumentNullException

src or dst is a null reference (Nothing in Visual Basic).

ArgumentException

src or dst is an object array, not a value type array.

-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.

Copies count bytes from src, beginning at srcOffset, to dst, beginning at dstOffset.

Developers should be careful to remember that the BlockCopy method accesses the src parameter array using offsets, not programming constructs such as indices 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, 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 endianess of the computer executing your application.

The following code example copies regions of arrays with the BlockCopy method.

' Example of the Buffer.BlockCopy method.
Imports System
Imports Microsoft.VisualBasic

Module BlockCopyDemo

    ' Display the array contents in hexadecimal.
    Sub DisplayArray( arr As Array, name As String )

        ' Get the array element width; format the formatting string.
        Dim loopX     As Integer
        Dim elemWidth As Integer = _
            Buffer.ByteLength( arr ) / arr.Length
        Dim format    As String = _
            String.Format( " {{0:X{0}}}", 2 * elemWidth )

        ' Display the array elements from right to left.
        Console.Write( "{0,5}:", name )
        For loopX = arr.Length - 1 to 0 Step -1
            Console.Write( format, arr( loopX ) )
        Next loopX
        Console.WriteLine( )
    End Sub

    Sub Main( )

        ' 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 }

        Console.WriteLine( "This example of the " & vbCrLf & _
            "Buffer.BlockCopy( Array, Integer, Array, " & _
            "Integer, Integer ) " & vbCrLf & "method generates " & _
            "the following output." & vbCrLf & "Note: The " & _
            "arrays are displayed from right to left." & vbCrLf )
        Console.WriteLine( "  Initial values of arrays:" & vbCrLf )

        ' Display the values of the arrays.
        DisplayArray( src, "src" )
        DisplayArray( dest, "dest" )

        ' Copy two regions of source array to destination array,
        ' and two overlapped copies from source to source.
        Console.WriteLine( vbCrLf & _
            "  Call these methods: " & vbCrLf & vbCrLf & _
            " Buffer.BlockCopy( src, 5, dest, 7, 6 )," & vbCrLf & _
            " Buffer.BlockCopy( src, 16, dest, 22, 5 )," & vbCrLf & _
            "  (these overlap source and destination)" & vbCrLf & _
            " Buffer.BlockCopy( src, 4, src, 5, 7 )," & vbCrLf & _
            " Buffer.BlockCopy( src, 16, src, 15, 7 )." & vbCrLf )
        Console.WriteLine( "  Final values of arrays:" & vbCrLf )

        Buffer.BlockCopy( src, 5, dest, 7, 6 )
        Buffer.BlockCopy( src, 16, dest, 22, 5 )
        Buffer.BlockCopy( src, 4, src, 5, 7 )
        Buffer.BlockCopy( src, 16, src, 15, 7 )

        ' Display the arrays again.
        DisplayArray( src, "src" )
        DisplayArray( 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

// Example of the Buffer.BlockCopy method.
import System.*;

class BlockCopyDemo
{
    // Display the array contents in hexadecimal.
    public static void DisplayArray(Array arr, String name)
    {
        // Get the array element width; format the formatting string.
        int elemWidth = Buffer.ByteLength(arr) / arr.get_Length();
        String format = String.Format(" {{0:X{0}}}", (Int32)(2 * elemWidth));

        // Display the array elements from right to left.
        Console.Write("{0,5}:", name);
        for (int loopX = arr.get_Length() - 1; loopX >= 0; loopX--) {
            Console.Write(format, arr.GetValue(loopX));
        }
        Console.WriteLine();
    } //DisplayArray

    public static void main(String[] args)
    {
        // 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 };

        Console.WriteLine(("This example of the \n"  
            + "Buffer.BlockCopy( Array, int, Array, int, int ) \n"
            + "method generates the following output.\n" 
            + "Note: The arrays are displayed from right to left.\n"));
        Console.WriteLine("  Initial values of arrays:\r\n");

        // Display the values of the arrays.
        DisplayArray(src, "src");
        DisplayArray(dest, "dest");

        // Copy two regions of source array to destination array,
        // and two overlapped copies from source to source.
        Console.WriteLine("\n  Call these methods: \n\n"  
            + " Buffer.BlockCopy( src, 5, dest, 7, 6 ),\n" 
            + " Buffer.BlockCopy( src, 16, dest, 22, 5 ),\n"  
            + "  (these overlap source and destination)\n"  
            + " Buffer.BlockCopy( src, 4, src, 5, 7 ),\n"  
            + " Buffer.BlockCopy( src, 16, src, 15, 7 ).\n");
        Console.WriteLine("  Final values of arrays:\n");
        Buffer.BlockCopy(src, 5, dest, 7, 6);
        Buffer.BlockCopy(src, 16, dest, 22, 5);
        Buffer.BlockCopy(src, 4, src, 5, 7);
        Buffer.BlockCopy(src, 16, src, 15, 7);

        // Display the arrays again.
        DisplayArray(src, "src");
        DisplayArray(dest, "dest");
    } //main
} //BlockCopyDemo

/*
This example of the
Buffer.BlockCopy( Array, int, Array, int, int )
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
*/

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

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

.NET Framework

Supported in: 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0, 1.0

Community Additions

ADD
Show:
© 2014 Microsoft