System.String 建構函式

本文提供此 API 參考文件的補充備註。

多載建構函式語法

字串建構函 式分為兩個類別：不含指標參數，以及具有指標參數的類別。 使用指標的建構函式不符合CLS標準。 此外，Visual Basic 不支援使用指標，而 C# 需要使用指標在不安全的內容中執行的程式代碼。 如需詳細資訊，請參閱 unsafe。

如需選擇多載的其他指引，請參閱 我呼叫哪一種方法？。

String(Char[] value)
將新的 實例初始化為 Unicode 字元陣列所指示的值。 此建構函式會複製 Unicode 字元（範例 2：使用字元陣列）。

String(Char[] value, Int32 startIndex, Int32 length)
將新實例初始化為 Unicode 字元陣列、該陣列內的起始字元位置，以及長度的值（範例 3：使用字元陣列的一部分並重複單一字元）。

String(Char c, Int32 count)
將新實例初始化為指定的 Unicode 字元重複指定次數的值（範例 3：使用字元陣列的一部分並重複單一字元）。

String(char* value)
（不符合 CLS 規範） 將新實例初始化為以 Null 字元結尾的 Unicode 字元陣列指標所表示的值（U+0000 或 '\0'）。 （範例 4：使用字元陣列的指標）。

許可權： SecurityCriticalAttribute，需要立即呼叫端的完整信任。 部分信任或透明程式代碼無法使用這個成員。

String(char* value, Int32 startIndex, Int32 length)
（不符合 CLS 規範） 將新實例初始化為 Unicode 字元陣列的指標、該陣列內的起始字元位置，以及長度所指示的值。 建構函式會從value索引開始複製 Unicode 字元，並以索引lengthstartIndexstartIndex + 結尾 - 1 （範例 5：從指標和數位範圍具現化字串）。

許可權： SecurityCriticalAttribute，需要立即呼叫端的完整信任。 部分信任或透明程式代碼無法使用這個成員。

String(SByte* value)
（不符合 CLS 規範） 將新實例初始化為8位帶正負號整數數位指標所表示的值。 數位假設代表使用目前系統代碼頁編碼的字串（也就是 所 Encoding.Default指定的編碼方式）。 建構函式會從 value 指標指定的位置開始處理字元，直到到達 null 字元（0x00）為止（範例 6：從指標具現化到帶正負號位元組陣列的字串）。

許可權： SecurityCriticalAttribute，需要立即呼叫端的完整信任。 部分信任或透明程式代碼無法使用這個成員。

String(SByte* value, Int32 startIndex, Int32 length)
（不符合 CLS 規範） 將新實例初始化為8位帶正負號整數數位的指標、該陣列內的起始位置，以及長度所表示的值。 數位假設代表使用目前系統代碼頁編碼的字串（也就是 所 Encoding.Default指定的編碼方式）。 建構函式會處理從值開始startIndex到結尾startIndexlength + 的字元 - 1 （範例 6：從指標具現化字串到帶正負號位元組數位元組）。

許可權： SecurityCriticalAttribute，需要立即呼叫端的完整信任。 部分信任或透明程式代碼無法使用這個成員。

String(SByte* value, Int32 startIndex, Int32 length, Encoding enc)
（不符合 CLS 規範） 將新實例初始化為8位帶正負號整數數位的指標、該陣列內的起始位置、長度和 Encoding 物件所指示的值。

許可權： SecurityCriticalAttribute，需要立即呼叫端的完整信任。 部分信任或透明程式代碼無法使用這個成員。

參數

以下是不包含指標參數之建構函式所使用的 String 參數完整清單。 如需每個多載所使用的參數，請參閱上述多載語法。

以下是包含 String 指標參數之建構函式所使用的參數完整清單。 如需每個多載所使用的參數，請參閱上述多載語法。

例外狀況

以下是不包含指標參數的建構函式所擲回的例外狀況清單。

以下是包含指標參數的建構函式擲回的例外狀況清單。

我呼叫哪一種方法？

建立字串

以程序設計方式建立字串最常使用的技巧是簡單的指派，如範例 1 所示。 類別 String 也包含四種類型的建構函式多載，可讓您從下列值建立字串：

• 從字元陣列（UTF-16 編碼字元的陣列）。 您可以從整個陣列或部分的字元建立新的 String 物件。 建 String(Char[]) 構函式會將陣列中的所有字元複製到新的字串。 建String(Char[], Int32, Int32)構函式會將字元從索引複製到索引 startIndexstartIndex + length - 1 複製到新的字串。 如果 length 為零，新字串的值會是 String.Empty。

  如果您的程式代碼重複具現化具有相同值的字串，您可以使用建立字串的替代方式來改善應用程式效能。 如需詳細資訊，請參閱 處理重複字串。

• 使用 建構函式，從重複零、一或多次 String(Char, Int32) 的單一字元。 如果 count 為零，新字串的值會是 String.Empty。

• 使用 String(Char*) 或 String(Char*, Int32, Int32) 建構函式，從 Null 終止字元陣列的指標。 整個陣列或指定的範圍都可以用來初始化字串。 建構函式會複製 Unicode 字元序列，從指定的指標或指定的指標加上 startIndex ，然後繼續到陣列結尾或 length 字元。 如果 value 是 Null 指標或 length 零，建構函式會建立值為 String.Empty的字串。 如果複製作業繼續到陣列的結尾，而且陣列不是以 Null 終止，則建構函式行為會與系統相依。 這類狀況可能會導致存取違規。

  如果陣列包含任何內嵌的 Null 字元（U+0000 或 '\0'），而且 String(Char*, Int32, Int32) 會呼叫 多載，則字串實例會 length 包含包含任何內嵌 Null 的字元。 下列範例顯示當包含兩個 Null 字元的 10 個元素陣列指標傳遞至 String(Char*, Int32, Int32) 方法時，會發生什麼事。 因為位址是數位的開頭，而且數位中的所有元素都會新增至字串，因此建構函式會具現化具有十個字元的字串，包括兩個內嵌 Null。 另一方面，如果相同的陣列傳遞至 String(Char*) 建構函式，則結果是不包含第一個Null字元的四個字元字串。

  using System;
  
  public class Example2
  {
     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
  

  數位必須包含 Unicode 字元。 在 C++ 中，這表示字元數位必須定義為 managed Char[] 類型或 Unmanagedwchar_t[] 類型。

  String(Char*)如果呼叫多載且陣列不是以 Null 終止，或String(Char*, Int32, Int32)呼叫多載且 startIndex + length-1 包含配置給字元序列記憶體以外的範圍，則建構函式的行為與系統相依，而且可能會發生存取違規。

• 從帶正負號位元組陣組的指標。 整個陣列或指定的範圍都可以用來初始化字串。 您可以使用預設代碼頁編碼來解譯位元組序列，也可以在建構函式呼叫中指定編碼。 如果建構函式嘗試從不是 Null 終止的整個數位具現化字串，或如果數位的範圍從 value + startIndex 到startIndex + value + length -1 超出為數位配置的記憶體，則此建構函式的行為與系統相依，而且可能會發生存取違規。

  包含帶正負號位元組陣組做為參數的三個建構函式主要設計成將C++ char 陣列轉換成字串，如下列範例所示：

  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
  

  如果陣列包含任何 Null 字元 （'\0'） 或其值為 0 且 String(SByte*, Int32, Int32) 呼叫多載的位元組，則字串實例會 length 包含包含任何內嵌 Null 的字元。 下列範例顯示當包含兩個 Null 字元的 10 個元素陣列指標傳遞至 String(SByte*, Int32, Int32) 方法時，會發生什麼事。 因為位址是數位的開頭，而且數位中的所有元素都會新增至字串，因此建構函式會具現化具有十個字元的字串，包括兩個內嵌 Null。 另一方面，如果相同的陣列傳遞至 String(SByte*) 建構函式，則結果是不包含第一個Null字元的四個字元字串。

  using System;
  
  public class Example5
  {
     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
  

  由於和 String(SByte*, Int32, Int32) 建String(SByte*)構函式會使用預設 ANSI 代碼頁來解譯value，因此呼叫具有相同位元組數位的建構函式可能會建立在不同系統上具有不同值的字串。

處理重複字串

剖析或譯碼文字數據流的應用程式通常會使用建 String(Char[], Int32, Int32) 構函式或 StringBuilder.Append(Char[], Int32, Int32) 方法，將字元序列轉換成字串。 重複建立具有相同值的新字串，而不是建立和重複使用一個字串會浪費記憶體。 如果您可能藉由呼叫 String(Char[], Int32, Int32) 建構函式重複建立相同的字串值，即使您事先不知道這些相同的字串值可能是什麼，您也可以改用查閱表格。

例如，假設您從包含 XML 標籤和屬性的檔案讀取和剖析字元數據流。 當您剖析數據流時，會重複遇到某些標記（也就是具有符號意義的字元序列）。 相當於字串 「0」、“1”、“true” 和 “false” 的令牌可能會經常出現在 XML 數據流中。

您可以建立 System.Xml.NameTable 物件來保存常見的字串，而不是將每個令牌轉換成新的字串。 物件 NameTable 會改善效能，因為它會擷取儲存的字串，而不會配置暫存記憶體。 當您遇到令牌時，請使用 NameTable.Get(Char[], Int32, Int32) 方法從數據表擷取令牌。 如果令牌存在，方法會傳回對應的字串。 如果令牌不存在，請使用 NameTable.Add(Char[], Int32, Int32) 方法將令牌插入數據表中，並取得對應的字串。

範例 1：使用字串指派

下列範例會藉由指派字串常值來建立新的字串。 它會將第一個字串的值指派給它，藉以建立第二個字元串。 這些是具現化新 String 物件的兩種最常見方式。

using System;

public class Example3
{
   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.

範例 2：使用字元陣列

下列範例示範如何從字元陣列建立新的 String 物件。

// 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)))

範例 3：使用字元陣列的一部分並重複單一字元

下列範例示範如何從字元數位的一部分建立新的 String 物件，以及如何建立包含單一字元多次出現的新 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)

範例 4：使用字元陣列的指標

下列範例示範如何從字元數位的指標建立新的 String 物件。 C# 範例必須使用編譯程式參數進行 /unsafe 編譯。

using System;

public class Example4
{
   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!

範例 5：從指標和數位範圍具現化字串

下列範例會檢查字元陣列的項目期間或驚嘆號。 如果找到其中一個，它會從在標點符號前面之陣列中的字元具現化字串。 如果沒有，它會使用數位的整個內容來具現化字串。 C# 範例必須使用編譯程式參數進行 /unsafe 編譯。

using System;

public class Example1
{
   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

範例 6：將字串從指標具現化為帶正負號的位元組陣列

下列範例示範如何使用 建構函式建立 類別String(SByte*)的String實例。

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}"