CopyTo Method

StringBuilder.CopyTo Method

Copies the characters from a specified segment of this instance to a specified segment of a destination Char array.

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

[ComVisibleAttribute(false)] 
public void CopyTo (
	int sourceIndex,
	char[] destination,
	int destinationIndex,
	int count
)
/** @attribute ComVisibleAttribute(false) */ 
public void CopyTo (
	int sourceIndex, 
	char[] destination, 
	int destinationIndex, 
	int count
)
ComVisibleAttribute(false) 
public function CopyTo (
	sourceIndex : int, 
	destination : char[], 
	destinationIndex : int, 
	count : int
)
Not applicable.

Parameters

sourceIndex

The starting position in this instance where characters will be copied from. The index is zero-based.

destination

The Char array where characters will be copied to.

destinationIndex

The starting position in destination where characters will be copied to. The index is zero-based.

count

The number of characters to be copied.

Exception typeCondition

ArgumentNullException

destination is a null reference (Nothing in Visual Basic).

ArgumentOutOfRangeException

sourceIndex, destinationIndex, or count, is less than zero.

-or-

sourceIndex is greater than the length of this instance.

ArgumentException

sourceIndex + count is greater than the length of this instance.

-or-

destinationIndex + count is greater than the length of destination.

The CopyTo method is intended to be used in the rare situation when you need to efficiently copy successive sections of a StringBuilder object to an array. The array should be a fixed size, preallocated, reusable, and possibly globally accessible.

For example, your application could populate a StringBuilder object with a large number of characters then use the CopyTo method to copy small, successive pieces of the StringBuilder object to an array where the pieces are processed. When all the data in the StringBuilder object is processed, the size of the StringBuilder object is set to zero and the cycle is repeated.

The following code example demonstrates the CopyTo method.

// This example demonstrates the CopyTo(Int32, Char[], Int32, Int32) method.

// Typically the destination array is small, preallocated, and global while 
// the StringBuilder is large with programmatically defined data. 
// However, for this example both the array and StringBuilder are small 
// and the StringBuilder has predefined data.

using System;
using System.Text;

class Sample 
{
    protected static char[] dest = new char[6];
    public static void Main() 
    {
    StringBuilder src = new StringBuilder("abcdefghijklmnopqrstuvwxyz!");
    dest[1] = ')';
    dest[2] = ' ';

// Copy the source to the destination in 9 pieces, 3 characters per piece.

    Console.WriteLine("\nPiece) Data:");
    for(int ix = 0; ix < 9; ix++)
        {
        dest[0] = ix.ToString()[0];
        src.CopyTo(ix * 3, dest, 3, 3);
        Console.Write("    ");
        Console.WriteLine(dest);
        }
    }
}
/*
This example produces the following results:

Piece) Data:
    0) abc
    1) def
    2) ghi
    3) jkl
    4) mno
    5) pqr
    6) stu
    7) vwx
    8) yz!
*/

// This example demonstrates the CopyTo(Int32, Char[], Int32, Int32) method.
// Typically the destination array is small, preallocated, and global while 
// the StringBuilder is large with programmatically defined data. 
// However, for this example both the array and StringBuilder are small 
// and the StringBuilder has predefined data.
import System.*;
import System.Text.*;

class Sample
{
    protected static char dest[] = new char[6];

    public static void main(String[] args)
    {
        StringBuilder src = new StringBuilder("abcdefghijklmnopqrstuvwxyz!");
        dest.set_Item(1, (System.Char)')');
        dest.set_Item(2, (System.Char)' ');
        // Copy the source to the destination in 9 pieces, 3 characters per 
        // piece.
        Console.WriteLine("\nPiece) Data:");
        for (int ix = 0; ix < 9; ix++) {
            dest[0] = ((Int32)ix).ToString().get_Chars(0);
            src.CopyTo(ix * 3, dest, 3, 3);
            Console.Write("    ");
            Console.WriteLine(dest);
        }
    } //main
} //Sample
/*
This example produces the following results:

Piece) Data:
    0) abc
    1) def
    2) ghi
    3) jkl
    4) mno
    5) pqr
    6) stu
    7) vwx
    8) yz!
*/

Windows 98, Windows Server 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0

Community Additions

ADD
Show:
© 2016 Microsoft