This documentation is archived and is not being maintained.

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 Sub CopyTo ( _
	sourceIndex As Integer, _
	destination As Char(), _
	destinationIndex As Integer, _
	count As Integer _


Type: System.Int32
The starting position in this instance where characters will be copied from. The index is zero-based.
Type: System.Char()
The array where characters will be copied.
Type: System.Int32
The starting position in destination where characters will be copied. The index is zero-based.
Type: System.Int32
The number of characters to be copied.


destination is Nothing.


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


sourceIndex is greater than the length of this instance.


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


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 example demonstrates the CopyTo 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.

Imports System.Text

Class Sample
   Protected Shared dest(5) As Char

   Public Shared Sub Main()
      Dim src As New StringBuilder("abcdefghijklmnopqrstuvwxyz!")
      dest(1) = ")"c
      dest(2) = " "c

      ' Copy the source to the destination in 9 pieces, 3 characters per piece.
      Console.WriteLine(vbCrLf & "Piece) Data:")
      Dim ix As Integer
      For ix = 0 To 8
         dest(0) = ix.ToString()(0)
         src.CopyTo(ix * 3, dest, 3, 3)
         Console.Write("    ")
      Next ix
   End Sub 'Main
End Class '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!

.NET Framework

Supported in: 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

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