Article
11/18/2011

String Constructor (array<Char[], Int32, Int32)

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Initializes a new instance of the String class to the value indicated by an array of Unicode characters, a starting character position within that array, and a length.

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

Syntax

'Declaration
<SecuritySafeCriticalAttribute> _
Public Sub New ( _
    value As Char(), _
    startIndex As Integer, _
    length As Integer _
)

[SecuritySafeCriticalAttribute]
public String(
    char[] value,
    int startIndex,
    int length
)

Parameters

value
Type: array<System.Char[]
An array of Unicode characters.

startIndex
Type: System.Int32
The starting position within value.

length
Type: System.Int32
The number of characters within value to use.

Exceptions

Exception	Condition
ArgumentNullException	value is nulla null reference (Nothing in Visual Basic).
ArgumentOutOfRangeException	startIndex or length is less than zero. -or- The sum of startIndex and length is greater than the number of elements in value.

ArgumentNullException

value is nulla null reference (Nothing in Visual Basic).

ArgumentOutOfRangeException

startIndex or length is less than zero.

-or-

The sum of startIndex and length is greater than the number of elements in value.

Remarks

If length is zero, an Empty instance is initialized.

This constructor copies Unicode characters from value, starting at startIndex and ending at (startIndex + length - 1).

Performance Considerations

Applications that parse or decode streams of text often use the String constructor or StringBuilder.Append(array<Char[], Int32, Int32) method to convert runs of characters into a string. If your application repeatedly encounters the same runs of characters, it will waste memory if it repeatedly creates new strings with the same value instead of creating and reusing one string.

If your application will repeatedly encounter the same runs of characters, but you cannot predict what those runs will be, you might consider using a lookup table instead of creating new String objects with the String constructor. For example, suppose your application reads and parses a stream of characters from a file that contains XML tags and attributes. When you parse the stream, you repeatedly encounter certain tokens (that is, runs of characters with symbolic meaning). Tokens equivalent to the strings "0", "1", "true", and "false" are likely to occur frequently in an XML stream.

Instead of converting each token your application encounters into a new string, you can create a NameTable object to hold commonly occurring strings. The NameTable object improves performance because it retrieves stored strings without allocating temporary memory.

When your application encounters a token, use the NameTable.Get(array<Char[], Int32, Int32) method to attempt to retrieve the token from the table. If the token exists, the method returns the corresponding string. If the token does not exist, use the NameTable.Add(array<Char[], Int32, Int32) method to insert the token into the table. After the token is inserted, the method returns the corresponding string. In either case, the appropriate string is returned to your application.

Examples

The following simple code example demonstrates how you can create an instance of the String class with this constructor.

' Create a Unicode String with 5 Greek Alpha characters
Dim szGreekAlpha As New String(ChrW(&H319), 5)
' Create a Unicode String with a Greek Omega character
Dim szGreekOmega As New String(New Char() {ChrW(&H3A9), ChrW(&H3A9), _
                                           ChrW(&H3A9)}, 2, 1)

Dim szGreekLetters As String = String.Concat(szGreekOmega, szGreekAlpha, _
                                             szGreekOmega)

' Examine the result
outputBlock.Text &= szGreekLetters & vbCrLf

' The first index of Alpha
Dim iAlpha As Integer = szGreekLetters.IndexOf(ChrW(&H319))
' The last index of Omega
Dim iomega As Integer = szGreekLetters.LastIndexOf(ChrW(&H3A9))

outputBlock.Text &= String.Format("The Greek letter Alpha first appears at index {0}.", _
                  iAlpha) & vbCrLf
outputBlock.Text &= String.Format("The Greek letter Omega last appears at index {0}.", _
                  iomega) & vbCrLf

// Create a Unicode String with 5 Greek Alpha characters
String szGreekAlpha = new String('\u0319', 5);
// Create a Unicode String with a Greek Omega character
String szGreekOmega = new String(new char[] { '\u03A9', '\u03A9', '\u03A9' }, 2, 1);

String szGreekLetters = String.Concat(szGreekOmega, szGreekAlpha, szGreekOmega);

// Examine the result
outputBlock.Text += szGreekLetters + "\n";

// The first index of Alpha
int ialpha = szGreekLetters.IndexOf('\u0319');
// The last index of Omega
int iomega = szGreekLetters.LastIndexOf('\u03A9');

outputBlock.Text += "The Greek letter Alpha first appears at index " + ialpha +
    " and Omega last appears at index " + iomega + " in this String." + "\n";

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.

Partager via