Initializes a new instance of the String class to the value indicated by a specified pointer to an array of 8-bit signed integers, a starting position within that array, a length, and an Encoding object.

Overloaded constructor syntax

String constructors fall into two categories: those without pointer parameters, and those with pointer parameters. The constructors that use pointers are not CLS-compliant. In addition, Visual Basic does not support the use of pointers, and C# requires code that uses pointers to run in an unsafe context. For more information, see unsafe.

String(Char[] value) Initializes the new instance to the value indicated by an array of Unicode characters. This constructor copies Unicode characters(example).

String(Char[] value, Int32 startIndex, Int32 length) Initializes the new instance to the value indicated by an array of Unicode characters, a starting character position within that array, and a length (example).

String(Char c, Int32 count) Initializes the new instance to the value indicated by a specified Unicode character repeated a specified number of times (example).

String(char* value)(Not CLS-compliant) Initializes the new instance to the value indicated by a pointer to an array of Unicode characters that is terminated by a null character (U+0000 or '\0'). (example).

Permission: SecurityCriticalAttribute, requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.

String(char* value, Int32 startIndex, Int32 length)(Not CLS-compliant) Initializes the new instance to the value indicated by a pointer to an array of Unicode characters, a starting character position within that array, and a length. The constructor copies the Unicode characters from value starting at index startIndex and ending at index startIndex + length – 1 (example).

Permission: SecurityCriticalAttribute, requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.

String(SByte* value)(Not CLS-compliant) Initializes the new instance to the value indicated by a pointer to an array of 8-bit signed integers. The array is assumed to represent a string encoded using the current system code page (that is, the encoding specified by Encoding.Default). The constructor processes characters from value starting from the location specified by the pointer until a null character (0x00) is reached (example).

Permission: SecurityCriticalAttribute, requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.

String(SByte* value, Int32 startIndex, Int32 length)(Not CLS-compliant) Initializes the new instance to the value indicated by a pointer to an array of 8-bit signed integers, a starting position within that array, and a length. The array is assumed to represent a string encoded using the current system code page (that is, the encoding specified by Encoding.Default). The constructor processes characters from value starting at startIndex and ending at startIndex + length – 1 (example).

Permission: SecurityCriticalAttribute, requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.

String(SByte* value, Int32 startIndex, Int32 length, Encoding enc)(Not CLS-compliant) Initializes the new instance to the value indicated by a pointer to an array of 8-bit signed integers, a starting position within that array, a length, and an Encoding object.

Permission: SecurityCriticalAttribute, requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.

Parameters

Here is a complete list of parameters used by String constructors that don't include a pointer parameter. For the parameters used by each overload, see the overload syntax above.

Creating strings

The most commonly used technique for creating strings programmatically is simple assignment, as illustrated in this example. The String class also includes four types of constructor overloads that let you create strings from the following values:

From a character array (an array of UTF-16-encoded characters). You can create a new String object from the characters in the entire array or a portion of it. The String(Char[]) constructor copies all the characters in the array to the new string. The String(Char[], Int32, Int32) constructor copies the characters from index startIndex to index startIndex + length – 1 to the new string. If length is zero, the value of the new string is String.Empty.

If your code repeatedly instantiates strings that have the same value, you can improve application performance by using an alternate means of creating strings. For more information, see Handling repetitive strings.

From a single character that is duplicated zero, one, or more times, by using the String(Char, Int32) constructor. If count is zero, the value of the new string is String.Empty.

From a pointer to a null-terminated character array, by using the String(Char*) or String(Char*, Int32, Int32) constructor. Either the entire array or a specified range can be used to initialize the string. The constructor copies a sequence of Unicode characters starting from the specified pointer or from the specified pointer plus startIndex and continuing to the end of the array or for length characters. If value is a null pointer or length is zero, the constructor creates a string whose value is String.Empty. If the copy operation proceeds to the end of the array and the array is not null-terminated, the constructor behavior is system-dependent. Such a condition might cause an access violation.

If the array contains any embedded null characters (U+0000 or '\0') and the String(Char*, Int32, Int32) overload is called, the string instance contains length characters including any embedded nulls. The following example shows what happens when a pointer to an array of 10 elements that includes two null characters is passed to the String(Char*, Int32, Int32) method. Because the address is the beginning of the array and all elements in the array are to be added to the string, the constructor instantiates a string with ten characters, including two embedded nulls. On the other hand, if the same array is passed to the String(Char*) constructor, the result is a four-character string that does not include the first null character.

From a pointer to a signed byte array. Either the entire array or a specified range can be used to initialize the string. The sequence of bytes can be interpreted by using the default code page encoding, or an encoding can be specified in the constructor call. If the constructor tries to instantiate a string from an entire array that is not null-terminated, or if the range of the array from value + startIndex to value + startIndex + length -1 is outside of the memory allocated for the array, the behavior of this constructor is system-dependent, and an access violation may occur.

The three constructors that include a signed byte array as a parameter are designed primarily to convert a C++ char array to a string, as shown in this example:

If the array contains any null characters ('\0') or bytes whose value is 0 and the String(SByte*, Int32, Int32) overload is called, the string instance contains length characters including any embedded nulls. The following example shows what happens when a pointer to an array of 10 elements that includes two null characters is passed to the String(SByte*, Int32, Int32) method. Because the address is the beginning of the array and all elements in the array are to be added to the string, the constructor instantiates a string with ten characters, including two embedded nulls. On the other hand, if the same array is passed to the String(SByte*) constructor, the result is a four-character string that does not include the first null character.

Because the String(SByte*) and String(SByte*, Int32, Int32) constructors interpret value by using the default ANSI code page, calling these constructors with identical byte arrays may create strings that have different values on different systems.

Handling repetitive strings

Apps that parse or decode streams of text often use the String(Char[], Int32, Int32) constructor or the StringBuilder.Append(Char[], Int32, Int32) method to convert sequences of characters into a string. Repeatedly creating new strings with the same value instead of creating and reusing one string wastes memory. If you are likely to create the same string value repeatedly by calling the String(Char[], Int32, Int32) constructor, even if you don't know in advance what those identical string values may be, you can use a lookup table instead.

For example, suppose you read and parse 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, sequences of characters that have a 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 into a new string, you can create a System.Xml.NameTable object to hold commonly occurring strings. The NameTable object improves performance, because it retrieves stored strings without allocating temporary memory. When you encounter a token, use the NameTable.Get(Char[], Int32, Int32) method 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(Char[], Int32, Int32) method to insert the token into the table and to get the corresponding string.

Example 1: Using string assignment

The following example creates a new string by assigning it a string literal. It creates a second string by assigning the value of the first string to it. These are the two most common ways to instantiate a new String object.

using namespace System;
void main()
{
String^ value1 = L"This is a string.";
String^ value2 = value1;
Console::WriteLine(value1);
Console::WriteLine(value2);
}
// The example displays the following output:
// This is a string.
// This is a string.

using System;
public class Example
{
public static void Main()
{
String value1 = "This is a string.";
String value2 = value1;
Console.WriteLine(value1);
Console.WriteLine(value2);
}
}
// The example displays the following output:
// This is a string.
// This is a string.

Module Example
Public Sub Main()
Dim value1 As String = "This is a string."
Dim value2 As String = value1
Console.WriteLine(value1)
Console.WriteLine(value2)
End Sub
End Module
' The example displays the following output:
' This is a string.
' This is a string.

Example 2: Using a character array

The following example demonstrates how to create a new String object from a character array.

Example 3: Using a portion of a character array and repeating a single character

The following example demonstrates how to create a new String object from a portion of a character array, and how to create a new String object that contains multiple occurrences of a single character.

Example 5: Instantiating a string from a pointer and a range of an array

The following example examines the elements of a character array for either a period or an exclamation point. If one is found, it instantiates a string from the characters in the array that precede the punctuation symbol. If not, it instantiates a string with the entire contents of the array. The C# example must be compiled using the /unsafe compiler switch.

Initializes a new instance of the String class to the value indicated by a specified pointer to an array of 8-bit signed integers, a starting position within that array, a length, and an Encoding object.