String Constructors

Reference

Definition

Namespace:: System

Assembly:: System.Runtime.dll

Assembly:: mscorlib.dll

Assembly:: netstandard.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Initializes a new instance of the String class.

Overloads

String(Char*)	Initializes a new instance of the String class to the value indicated by a specified pointer to an array of Unicode characters.
String(Char[])	Initializes a new instance of the String class to the Unicode characters indicated in the specified character array.
String(ReadOnlySpan<Char>)	Initializes a new instance of the String class to the Unicode characters indicated in the specified read-only span.
String(SByte*)	Initializes a new instance of the String class to the value indicated by a pointer to an array of 8-bit signed integers.
String(Char, Int32)	Initializes a new instance of the String class to the value indicated by a specified Unicode character repeated a specified number of times.
String(Char*, Int32, Int32)	Initializes a new instance of the String class to the value indicated by a specified pointer to an array of Unicode characters, a starting character position within that array, and a length.
String(Char[], Int32, Int32)	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.
String(SByte*, Int32, Int32)	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, and a length.
String(SByte*, Int32, Int32, Encoding)	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.

Remarks

In this section:

Overloaded constructor syntax
Parameters
Exceptions
Which method do I call?
Creating strings
Handle repetitive strings

Examples of instantiating strings:

Use string assignment
Use a character array
Use a portion of a character array and repeating a single character
Use a pointer to a character array
Use a pointer and a range of an array
Use a pointer to a signed byte array

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.

For additional guidance on choosing an overload, see Which method do I call?.

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.

Parameter	Type	Description
`value`	Char[]	An array of Unicode characters.
`c`	Char	A Unicode character.
`startIndex`	Int32	The starting position in `value` of the first character in the new string. Default value: 0
`length`	Int32	The number of characters in `value` to include in the new string. Default value: Array.Length
`count`	Int32	The number of times the character `c` is repeated in the new string. If `count` is zero, the value of the new object is String.Empty.

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

Parameter	Type	Description
`value`	Char* -or- SByte*	A pointer to a null-terminated array of Unicode characters or an array of 8-bit signed integers. If `value` is `null` or an empty array, the value of the new string is String.Empty.
`startIndex`	Int32	The index of the array element that defines the first character in the new string. Default value: 0
`length`	Int32	The number of array elements to use to create the new string. If length is zero, the constructor creates a string whose value is String.Empty. Default value: Array.Length
`enc`	Encoding	An object that specifies how the `value` array is encoded. Default value: Encoding.Default, or the system's current ANSI code page

Exceptions

Here's a list of exceptions thrown by constructors that don't include pointer parameters.

Exception	Condition	Thrown by
ArgumentNullException	`value` is `null`.	String(Char[], Int32, Int32)
ArgumentOutOfRangeException	`startIndex`,`length`, or `count` is less than zero. -or- The sum of `startIndex` and `length` is greater than the number of elements in `value`. -or- `count` is less than zero.	String(Char, Int32) String(Char[], Int32, Int32)

Here's a list of exceptions thrown by constructors that include pointer parameters.

Exception	Condition	Thrown by
ArgumentException	`value` specifies an array that contains an invalid Unicode character. -or- `value` or `value` + `startIndex` specifies an address that is less than 64K. -or- A new String instance could not be initialized from the `value` byte array because `value` does not use the default code page encoding.	All constructors with pointers.
ArgumentNullException	`value` is null.	String(SByte) String(SByte, Int32, Int32) String(SByte*, Int32, Int32, Encoding)
ArgumentOutOfRangeException	The current process does not have read access to all the addressed characters. -or- `startIndex` or `length` is less than zero, `value` + `startIndex` cause a pointer overflow, or the current process does not have read access to all the addressed characters. -or- The length of the new string is too large to allocate.	All constructors with pointers.
AccessViolationException	`value`, or `value` + `startIndex` + `length` - 1, specifies an invalid address.	String(SByte) String(SByte, Int32, Int32) String(SByte*, Int32, Int32, Encoding)

Which method do I call?

To	Call or use
Create a string.	Assignment from a string literal or an existing string (example)
Create a string from an entire character array.	String(Char[]) (example)
Create a string from a portion of a character array.	String(Char[], Int32, Int32) (example)
Create a string that repeats the same character multiple times.	String(Char, Int32) (example)
Create a string from a pointer to a Unicode or wide character array.	String(Char*)
Create a string from a portion of a Unicode or wide character array by using its pointer.	String(Char*, Int32, Int32)
Create a string from a C++ `char` array.	String(SByte), String(SByte, Int32, Int32) -or- String(SByte*, Int32, Int32, Encoding)
Create a string from ASCII characters.	ASCIIEncoding.GetString

Create 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.
```
using namespace System;

void main()
{
   wchar_t chars[] = { L'a', L'b', L'c', L'd', L'\0', L'A', L'B', 
                       L'C', L'D', L'\0' };
   Char* chPtr = chars;
   String^ s = gcnew String(chPtr, 0, 
                            sizeof(chars) / sizeof (wchar_t));            
   for each (Char ch in s)
      Console::Write("{0:X4} ", Convert::ToUInt16(ch));
   Console::WriteLine();
   
   s = gcnew String(chPtr);         
   
   for each (Char ch in s)
      Console::Write("{0:X4} ", Convert::ToUInt16(ch));
   Console::WriteLine();    
}
// The example displays the following output:
//       0061 0062 0063 0064 0000 0041 0042 0043 0044 0000
//       0061 0062 0063 0064
```
```
using System;

public class Example
{
   public unsafe static void Main()
   {
      char[] chars = { 'a', 'b', 'c', 'd', '\0', 'A', 'B', 'C', 'D', '\0' };
      string s = null;
      
      fixed(char* chPtr = chars) {
         s = new string(chPtr, 0, chars.Length);            
      } 

      foreach (var ch in s)
         Console.Write($"{(ushort)ch:X4} ");
      Console.WriteLine();
      
      fixed(char* chPtr = chars) {
         s = new string(chPtr);         
      }
      
      foreach (var ch in s)
         Console.Write($"{(ushort)ch:X4} ");
      Console.WriteLine();    
   }
}
// The example displays the following output:
//       0061 0062 0063 0064 0000 0041 0042 0043 0044 0000
//       0061 0062 0063 0064
```
```
#nowarn "9"
open System

let chars = [| 'a'; 'b'; 'c'; 'd'; '\000'; 'A'; 'B'; 'C'; 'D'; '\000' |]
let s =
    use chPtr = fixed chars
    String(chPtr, 0, chars.Length)

for ch in s do
    printf $"{uint16 ch:X4} "
printfn ""

let s2 = 
    use chPtr = fixed chars
    String chPtr    

for ch in s2 do
    printf $"{uint16 ch:X4} "
printfn ""  
// The example displays the following output:
//       0061 0062 0063 0064 0000 0041 0042 0043 0044 0000
//       0061 0062 0063 0064
```
The array must contain Unicode characters. In C++, this means that the character array must be defined either as the managed Char[] type or the unmanagedwchar_t[] type.

If the String(Char*) overload is called and the array is not null-terminated, or if the String(Char*, Int32, Int32) overload is called and startIndex + length-1 includes a range that is outside the memory allocated for the sequence of characters, the behavior of the constructor is system-dependent, and an access violation may occur.

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:

using namespace System;

void main()
{
      char chars[] = { 'a', 'b', 'c', 'd', '\x00' };
      
      char* charPtr = chars;
      String^ value = gcnew String(charPtr);

      Console::WriteLine(value);
}
// The example displays the following output:
//      abcd

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.

using namespace System;

void main()
{
   char bytes[] = { 0x61, 0x62, 0x063, 0x064, 0x00, 0x41, 0x42,0x43, 
                    0x44, 0x00 };
   
   char* bytePtr = bytes;
   String^ s = gcnew String(bytePtr, 0, sizeof(bytes) / sizeof (char));
   
   for each (Char ch in s)
      Console::Write("{0:X4} ", Convert::ToUInt16(ch));
   
   Console::WriteLine();
   
   s = gcnew String(bytePtr);

   for each (Char ch in s)
      Console::Write("{0:X4} ", Convert::ToUInt16(ch));
   Console::WriteLine();       
}
// The example displays the following output:
//      0061 0062 0063 0064 0000 0041 0042 0043 0044 0000
//      0061 0062 0063 0064

using System;

public class Example
{
   public unsafe static void Main()
   {
      sbyte[] bytes = { 0x61, 0x62, 0x063, 0x064, 0x00, 0x41, 0x42, 0x43, 0x44, 0x00 };
      
      string s = null;
      fixed (sbyte* bytePtr = bytes) {
         s = new string(bytePtr, 0, bytes.Length);
      }
      
      foreach (var ch in s)
         Console.Write($"{(ushort)ch:X4} ");
      
      Console.WriteLine();    

      fixed(sbyte* bytePtr = bytes) {
         s = new string(bytePtr);         
      }
      
      foreach (var ch in s)
         Console.Write($"{(ushort)ch:X4} ");
      Console.WriteLine();    
   }
}
// The example displays the following output:
//       0061 0062 0063 0064 0000 0041 0042 0043 0044 0000
//       0061 0062 0063 0064

#nowarn "9"
open System

let bytes = 
    [| 0x61y; 0x62y; 0x063y; 0x064y; 0x00y; 0x41y; 0x42y; 0x43y; 0x44y; 0x00y |]

let s =
    use bytePtr = fixed bytes
    String(bytePtr, 0, bytes.Length)

for ch in s do
    printf $"{uint16 ch:X4} "
printfn ""

let s2 =
    use bytePtr = fixed bytes
    String bytePtr         

for ch in s do
    printf $"{uint16 ch:X4} "
printfn ""
// The example displays the following output:
//       0061 0062 0063 0064 0000 0041 0042 0043 0044 0000
//       0061 0062 0063 0064

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.

Handle 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: Use 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.

let value1 = "This is a string."
let value2 = value1
printfn "%s" value1
printfn "%s" 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: Use a character array

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

// Unicode Mathematical operators
wchar_t charArray1[4] = {L'\x2200',L'\x2202',L'\x200F',L'\x2205'};
wchar_t * lptstr1 =  &charArray1[ 0 ];
String^ wszMathSymbols = gcnew String( lptstr1 );

// Unicode Letterlike Symbols
wchar_t charArray2[4] = {L'\x2111',L'\x2118',L'\x2122',L'\x2126'};
wchar_t * lptstr2 =  &charArray2[ 0 ];
String^ wszLetterLike = gcnew String( lptstr2 );

// Compare Strings - the result is false
Console::WriteLine( String::Concat( L"The Strings are equal? ", (0 == String::Compare( wszLetterLike, wszMathSymbols ) ? (String^)"TRUE" : "FALSE") ) );

// Unicode Mathematical operators
char [] charArr1 = {'\u2200','\u2202','\u200F','\u2205'};
String szMathSymbols = new String(charArr1);

// Unicode Letterlike Symbols
char [] charArr2 = {'\u2111','\u2118','\u2122','\u2126'};
String szLetterLike = new String (charArr2);

// Compare Strings - the result is false
Console.WriteLine("The Strings are equal? " +
    (String.Compare(szMathSymbols, szLetterLike)==0?"true":"false") );

// Unicode Mathematical operators
let charArr1 = [| '\u2200'; '\u2202'; '\u200F'; '\u2205' |]
let szMathSymbols = String charArr1

// Unicode Letterlike Symbols
let charArr2 = [| '\u2111'; '\u2118'; '\u2122'; '\u2126' |]
let szLetterLike = String charArr2

// Compare Strings - the result is false
printfn $"The Strings are equal? %b{String.Compare(szMathSymbols, szLetterLike) = 0}"

' Unicode Mathematical operators
Dim charArr1() As Char = {ChrW(&H2200), ChrW(&H2202), _
                          ChrW(&H200F), ChrW(&H2205)}
Dim szMathSymbols As New String(charArr1)

' Unicode Letterlike Symbols
Dim charArr2() As Char = {ChrW(&H2111), ChrW(&H2118), _
                          ChrW(&H2122), ChrW(&H2126)}
Dim szLetterLike As New String(charArr2)

' Compare Strings - the result is false
Console.WriteLine("The strings are equal? " & _
        CStr(szMathSymbols.Equals(szLetterLike)))

Example 3: Use 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.

// Create a Unicode String with 5 Greek Alpha characters
String^ szGreekAlpha = gcnew String( L'\x0391',5 );

// Create a Unicode String with a Greek Omega character
wchar_t charArray5[3] = {L'\x03A9',L'\x03A9',L'\x03A9'};
String^ szGreekOmega = gcnew String( charArray5,2,1 );
String^ szGreekLetters = String::Concat( szGreekOmega, szGreekAlpha, szGreekOmega->Clone() );

// Examine the result
Console::WriteLine( szGreekLetters );

// The first index of Alpha
int ialpha = szGreekLetters->IndexOf( L'\x0391' );

// The last index of Omega
int iomega = szGreekLetters->LastIndexOf( L'\x03A9' );
Console::WriteLine( String::Concat(  "The Greek letter Alpha first appears at index ", Convert::ToString( ialpha ) ) );
Console::WriteLine( String::Concat(  " and Omega last appears at index ", Convert::ToString( iomega ),  " in this String." ) );

// Create a Unicode String with 5 Greek Alpha characters
String szGreekAlpha = new String('\u0391',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.Clone());

// Examine the result
Console.WriteLine(szGreekLetters);

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

Console.WriteLine("The Greek letter Alpha first appears at index " + ialpha +
    " and Omega last appears at index " + iomega + " in this String.");

// Create a Unicode String with 5 Greek Alpha characters
let szGreekAlpha = String('\u0391',5)
// Create a Unicode String with a Greek Omega character
let szGreekOmega = String([| '\u03A9'; '\u03A9'; '\u03A9' |],2,1)

let szGreekLetters = String.Concat(szGreekOmega, szGreekAlpha, szGreekOmega.Clone())

// Examine the result
printfn $"{szGreekLetters}"

// The first index of Alpha
let ialpha = szGreekLetters.IndexOf '\u0391'
// The last index of Omega
let iomega = szGreekLetters.LastIndexOf '\u03A9'

printfn $"The Greek letter Alpha first appears at index {ialpha} and Omega last appears at index {iomega} in this String."

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

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

' Examine the result
Console.WriteLine(szGreekLetters)

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

Console.WriteLine("The Greek letter Alpha first appears at index {0}.", _ 
                  ialpha)
Console.WriteLIne("The Greek letter Omega last appears at index {0}.", _
                  iomega)

Example 4: Use a pointer to a character array

The following example demonstrates how to create a new String object from a pointer to an array of characters. The C# example must be compiled by using the /unsafe compiler switch.

using namespace System;

void main()
{
   wchar_t characters[] = {L'H',L'e',L'l',L'l',L'o',L' ', 
                           L'W',L'o',L'r',L'l',L'd',L'!',L'\x0000'};

   Char* charPtr = characters;
   String^ value = gcnew String(charPtr);
   Console::WriteLine(value);
}
// The example displays the following output:
//        Hello world!

using System;

public class Example
{
   public static unsafe void Main()
   {
      char[] characters = { 'H', 'e', 'l', 'l', 'o', ' ', 
                            'w', 'o', 'r', 'l', 'd', '!', '\u0000' };
      string value;
      
      fixed (char* charPtr = characters) {
         value = new String(charPtr);
      }                            
      Console.WriteLine(value);
   }
}
// The example displays the following output:
//        Hello world!

#nowarn "9"
open System

let characters = 
    [| 'H'; 'e'; 'l'; 'l'; 'o'; ' ' 
       'w'; 'o'; 'r'; 'l'; 'd'; '!'; '\u0000' |]

let value =
    use charPtr = fixed characters
    String charPtr

printfn $"{value}"
// The example displays the following output:
//        Hello world!

Example 5: Instantiate 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.

using namespace System;


void main()
{
   wchar_t characters[] = {L'H',L'e',L'l',L'l',L'o',L' ', 
                           L'W',L'o',L'r',L'l',L'd',L'!',L'\x0000'};

   Char* charPtr = characters;
   int length = 0;
   Char* iterator = charPtr;

   while (*iterator != '\x0000')
   {
      if (*iterator == L'!' || *iterator == L'.')
         break;
      *iterator++;
      length++;
   }
   String^ value = gcnew String(charPtr, 0, length);
   Console::WriteLine(value);
}
// The example displays the following output:
//      Hello World

using System;

public class Example
{
   public static unsafe void Main()
   {
      char[] characters = { 'H', 'e', 'l', 'l', 'o', ' ', 
                            'w', 'o', 'r', 'l', 'd', '!', '\u0000' };
      String value;
      
      fixed (char* charPtr = characters) {
         int length = 0;
         Char* iterator = charPtr;
   
         while (*iterator != '\x0000')
         {
            if (*iterator == '!' || *iterator == '.')
               break;
            iterator++;
            length++;
         }
         value = new String(charPtr, 0, length);
      }
      Console.WriteLine(value);
   }
}
// The example displays the following output:
//      Hello World

#nowarn "9"
open System
open FSharp.NativeInterop

let characters = 
    [| 'H'; 'e'; 'l'; 'l'; 'o'; ' '
       'w'; 'o'; 'r'; 'l'; 'd'; '!'; '\u0000' |]

[<EntryPoint>]
let main _ =
    use charPtr = fixed characters
    let mutable length = 0
    let mutable iterator = charPtr
    let mutable broken = false
    while not broken && NativePtr.read iterator <> '\u0000' do
        if NativePtr.read iterator = '!' || NativePtr.read iterator = '.' then
            broken <- true
        else
            iterator <- NativePtr.add iterator 1
            length <- length + 1
    String(charPtr, 0, length)
    |> printfn "%s"
    0
// The example displays the following output:
//      Hello World

Example 6: Instantiate a string from a pointer to a signed byte array

The following example demonstrates how you can create an instance of the String class with the String(SByte*) constructor.

// Null terminated ASCII characters in a simple char array
char charArray3[4] = {0x41,0x42,0x43,0x00};
char * pstr3 =  &charArray3[ 0 ];
String^ szAsciiUpper = gcnew String( pstr3 );
char charArray4[4] = {0x61,0x62,0x63,0x00};
char * pstr4 =  &charArray4[ 0 ];
String^ szAsciiLower = gcnew String( pstr4,0,sizeof(charArray4) );

// Prints "ABC abc"
Console::WriteLine( String::Concat( szAsciiUpper,  " ", szAsciiLower ) );

// Compare Strings - the result is true
Console::WriteLine( String::Concat(  "The Strings are equal when capitalized ? ", (0 == String::Compare( szAsciiUpper->ToUpper(), szAsciiLower->ToUpper() ) ? (String^)"TRUE" :  "FALSE") ) );

// This is the effective equivalent of another Compare method, which ignores case
Console::WriteLine( String::Concat(  "The Strings are equal when capitalized ? ", (0 == String::Compare( szAsciiUpper, szAsciiLower, true ) ? (String^)"TRUE" :  "FALSE") ) );

unsafe
{
    // Null terminated ASCII characters in an sbyte array
    String szAsciiUpper = null;
    sbyte[] sbArr1 = new sbyte[] { 0x41, 0x42, 0x43, 0x00 };
    // Instruct the Garbage Collector not to move the memory
    fixed(sbyte* pAsciiUpper = sbArr1)
    {
        szAsciiUpper = new String(pAsciiUpper);
    }
    String szAsciiLower = null;
    sbyte[] sbArr2 = { 0x61, 0x62, 0x63, 0x00 };
    // Instruct the Garbage Collector not to move the memory
    fixed(sbyte* pAsciiLower = sbArr2)
    {
        szAsciiLower = new String(pAsciiLower, 0, sbArr2.Length);
    }
    // Prints "ABC abc"
    Console.WriteLine(szAsciiUpper + " " + szAsciiLower);

    // Compare Strings - the result is true
    Console.WriteLine("The Strings are equal when capitalized ? " +
        (String.Compare(szAsciiUpper.ToUpper(), szAsciiLower.ToUpper())==0?"true":"false") );

    // This is the effective equivalent of another Compare method, which ignores case
    Console.WriteLine("The Strings are equal when capitalized ? " +
        (String.Compare(szAsciiUpper, szAsciiLower, true)==0?"true":"false") );
}

// Null terminated ASCII characters in an sbyte array
let szAsciiUpper =
    let sbArr1 = [| 0x41y; 0x42y; 0x43y; 0x00y |]
    // Instruct the Garbage Collector not to move the memory
    use pAsciiUpper = fixed sbArr1
    String pAsciiUpper

let szAsciiLower =
    let sbArr2 = [| 0x61y; 0x62y; 0x63y; 0x00y |]
    // Instruct the Garbage Collector not to move the memory
    use pAsciiLower = fixed sbArr2 
    String(pAsciiLower, 0, sbArr2.Length)

// Prints "ABC abc"
printfn $"{szAsciiUpper} {szAsciiLower}"

// Compare Strings - the result is true
printfn $"The Strings are equal when capitalized ? %b{String.Compare(szAsciiUpper.ToUpper(), szAsciiLower.ToUpper()) = 0}"

// This is the effective equivalent of another Compare method, which ignores case
printfn $"The Strings are equal when capitalized ? %b{String.Compare(szAsciiUpper, szAsciiLower, true) = 0}"

String(Char*)

Important

This API is not CLS-compliant.

Initializes a new instance of the String class to the value indicated by a specified pointer to an array of Unicode characters.

public:
 String(char* value);

[System.CLSCompliant(false)]
[System.Security.SecurityCritical]
public String (char* value);

[System.CLSCompliant(false)]
public String (char* value);

[<System.CLSCompliant(false)>]
[<System.Security.SecurityCritical>]
new string : nativeptr<char> -> string

[<System.CLSCompliant(false)>]
new string : nativeptr<char> -> string

Parameters

value: Char*

A pointer to a null-terminated array of Unicode characters.

Attributes: CLSCompliantAttribute SecurityCriticalAttribute

Exceptions

ArgumentOutOfRangeException

The current process does not have read access to all the addressed characters.

ArgumentException

value specifies an array that contains an invalid Unicode character, or value specifies an address less than 64000.

Remarks

Note

For examples and comprehensive usage information about this and other String constructor overloads, see the String constructor summary.

Applies to

String(Char[])

Initializes a new instance of the String class to the Unicode characters indicated in the specified character array.

public:
 String(cli::array <char> ^ value);

public String (char[] value);

public String (char[]? value);

new string : char[] -> string

Public Sub New (value As Char())

Parameters

value: Char[]

An array of Unicode characters.

Remarks

Note

For examples and comprehensive usage information about this and other String constructor overloads, see the String constructor summary.

Applies to

String(ReadOnlySpan<Char>)

Initializes a new instance of the String class to the Unicode characters indicated in the specified read-only span.

public:
 String(ReadOnlySpan<char> value);

public String (ReadOnlySpan<char> value);

new string : ReadOnlySpan<char> -> string

Public Sub New (value As ReadOnlySpan(Of Char))

Parameters

value: ReadOnlySpan<Char>

A read-only span of Unicode characters.

Applies to

String(SByte*)

Important

This API is not CLS-compliant.

Initializes a new instance of the String class to the value indicated by a pointer to an array of 8-bit signed integers.

public:
 String(System::SByte* value);

[System.CLSCompliant(false)]
public String (sbyte* value);

[System.CLSCompliant(false)]
[System.Security.SecurityCritical]
public String (sbyte* value);

[<System.CLSCompliant(false)>]
new string : nativeptr<sbyte> -> string

[<System.CLSCompliant(false)>]
[<System.Security.SecurityCritical>]
new string : nativeptr<sbyte> -> string

Parameters

value: SByte*

A pointer to a null-terminated array of 8-bit signed integers. The integers are interpreted using the current system code page encoding (that is, the encoding specified by Default).

Attributes: CLSCompliantAttribute SecurityCriticalAttribute

Exceptions

ArgumentNullException

value is null.

ArgumentException

A new instance of String could not be initialized using value, assuming value is encoded in ANSI.

ArgumentOutOfRangeException

The length of the new string to initialize, which is determined by the null termination character of value, is too large to allocate.

AccessViolationException

value specifies an invalid address.

Remarks

Note

For examples and comprehensive usage information about this and other String constructor overloads, see the String constructor summary.

Applies to

String(Char, Int32)

Initializes a new instance of the String class to the value indicated by a specified Unicode character repeated a specified number of times.

public:
 String(char c, int count);

public String (char c, int count);

new string : char * int -> string

Public Sub New (c As Char, count As Integer)

Parameters

c: Char

A Unicode character.

count: Int32

The number of times c occurs.

Exceptions

ArgumentOutOfRangeException

count is less than zero.

Remarks

Note

For examples and comprehensive usage information about this and other String constructor overloads, see the String constructor summary.

Applies to

String(Char*, Int32, Int32)

Important

This API is not CLS-compliant.

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

public:
 String(char* value, int startIndex, int length);

[System.CLSCompliant(false)]
[System.Security.SecurityCritical]
public String (char* value, int startIndex, int length);

[System.CLSCompliant(false)]
public String (char* value, int startIndex, int length);

[<System.CLSCompliant(false)>]
[<System.Security.SecurityCritical>]
new string : nativeptr<char> * int * int -> string

[<System.CLSCompliant(false)>]
new string : nativeptr<char> * int * int -> string

Parameters

value: Char*

A pointer to an array of Unicode characters.

startIndex: Int32

The starting position within value.

length: Int32

The number of characters within value to use.

Attributes: CLSCompliantAttribute SecurityCriticalAttribute

Exceptions

ArgumentOutOfRangeException

startIndex or length is less than zero, value + startIndex cause a pointer overflow, or the current process does not have read access to all the addressed characters.

ArgumentException

value specifies an array that contains an invalid Unicode character, or value + startIndex specifies an address less than 64000.

Remarks

Note

For examples and comprehensive usage information about this and other String constructor overloads, see the String constructor summary.

Applies to

String(Char[], Int32, Int32)

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.

public:
 String(cli::array <char> ^ value, int startIndex, int length);

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

new string : char[] * int * int -> string

Public Sub New (value As Char(), startIndex As Integer, length As Integer)

Parameters

value: Char[]

An array of Unicode characters.

startIndex: Int32

The starting position within value.

length: Int32

The number of characters within value to use.

Exceptions

ArgumentNullException

value is null.

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

Note

For examples and comprehensive usage information about this and other String constructor overloads, see the String constructor summary.

Applies to

String(SByte*, Int32, Int32)

Important

This API is not CLS-compliant.

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, and a length.

public:
 String(System::SByte* value, int startIndex, int length);

[System.CLSCompliant(false)]
public String (sbyte* value, int startIndex, int length);

[System.CLSCompliant(false)]
[System.Security.SecurityCritical]
public String (sbyte* value, int startIndex, int length);

[<System.CLSCompliant(false)>]
new string : nativeptr<sbyte> * int * int -> string

[<System.CLSCompliant(false)>]
[<System.Security.SecurityCritical>]
new string : nativeptr<sbyte> * int * int -> string

Parameters

value: SByte*

A pointer to an array of 8-bit signed integers. The integers are interpreted using the current system code page encoding (that is, the encoding specified by Default).

startIndex: Int32

The starting position within value.

length: Int32

The number of characters within value to use.

Attributes: CLSCompliantAttribute SecurityCriticalAttribute

Exceptions

ArgumentNullException

value is null.

ArgumentOutOfRangeException

startIndex or length is less than zero.

-or-

The address specified by value + startIndex is too large for the current platform; that is, the address calculation overflowed.

-or-

The length of the new string to initialize is too large to allocate.

ArgumentException

The address specified by value + startIndex is less than 64K.

-or-

A new instance of String could not be initialized using value, assuming value is encoded in ANSI.

AccessViolationException

value, startIndex, and length collectively specify an invalid address.

Remarks

Note

For examples and comprehensive usage information about this and other String constructor overloads, see the String constructor summary.

Applies to

String(SByte*, Int32, Int32, Encoding)

Important

This API is not CLS-compliant.

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.

public:
 String(System::SByte* value, int startIndex, int length, System::Text::Encoding ^ enc);

[System.CLSCompliant(false)]
public String (sbyte* value, int startIndex, int length, System.Text.Encoding enc);

[System.CLSCompliant(false)]
[System.Security.SecurityCritical]
public String (sbyte* value, int startIndex, int length, System.Text.Encoding enc);

[<System.CLSCompliant(false)>]
new string : nativeptr<sbyte> * int * int * System.Text.Encoding -> string

[<System.CLSCompliant(false)>]
[<System.Security.SecurityCritical>]
new string : nativeptr<sbyte> * int * int * System.Text.Encoding -> string

Parameters

value: SByte*

A pointer to an array of 8-bit signed integers.

startIndex: Int32

The starting position within value.

length: Int32

The number of characters within value to use.

enc: Encoding

An object that specifies how the array referenced by value is encoded. If enc is null, ANSI encoding is assumed.

Attributes: CLSCompliantAttribute SecurityCriticalAttribute

Exceptions

ArgumentNullException

value is null.

ArgumentOutOfRangeException

startIndex or length is less than zero.

-or-

The address specified by value + startIndex is too large for the current platform; that is, the address calculation overflowed.

-or-

The length of the new string to initialize is too large to allocate.

ArgumentException

The address specified by value + startIndex is less than 64K.

-or-

A new instance of String could not be initialized using value, assuming value is encoded as specified by enc.

AccessViolationException

value, startIndex, and length collectively specify an invalid address.

Remarks

Note

For examples and comprehensive usage information about this and other String constructor overloads, see the String constructor summary.

Applies to

String Constructors

Definition

Overloads

Remarks

Overloaded constructor syntax

Parameters

Exceptions

Which method do I call?

Create strings

Handle repetitive strings

Example 1: Use string assignment

Example 2: Use a character array

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

Example 4: Use a pointer to a character array

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

Example 6: Instantiate a string from a pointer to a signed byte array

String(Char*)

Parameters

Exceptions

Remarks

Applies to

String(Char[])

Parameters

Remarks

Applies to

String(ReadOnlySpan<Char>)

Parameters

Applies to

String(SByte*)

Parameters

Exceptions

Remarks

Applies to

String(Char, Int32)

Parameters

Exceptions

Remarks

Applies to

String(Char*, Int32, Int32)

Parameters

Exceptions

Remarks

Applies to

String(Char[], Int32, Int32)

Parameters

Exceptions

Remarks

Applies to

String(SByte*, Int32, Int32)

Parameters

Exceptions

Remarks

Applies to

String(SByte*, Int32, Int32, Encoding)

Parameters

Exceptions

Remarks

Applies to

Feedback

Feedback

Additional resources