16 結構體

16.1 一般

結構與類別類似,因為它們代表可包含數據成員和函式成員的數據結構。 不過,不同於類別,結構是實值型別,不需要堆積配置。 型別為struct的變數直接包含struct的數據,而類別型別的變數則包含對數據的參考,後者稱為物件。

注意:結構對於具有值語意的小型資料結構特別有用。 複數、座標系統中的點或字典中的索引鍵/值組都是結構的良好範例。 這些資料結構的關鍵在於,它們通常只有很少的數據成員,不需要使用繼承或引用語意,而是可以方便地使用值語意,讓指派是複製值而不是引用。 結尾註記

如§8.3.5中所述,C#提供的簡單類型,例如int、double和bool,實際上都是結構類型。

16.2 結構宣告

16.2.1 一般

struct_declaration 是一種宣告新結構的 type_declaration(§14.8):

struct_declaration
    : non_record_struct_declaration
    | record_struct_declaration
    ;

non_record_struct_declaration
    : non_record_struct_without_positional_members
    | non_record_struct_with_positional_members
    ;

non_record_struct_without_positional_members
    : attributes? struct_modifier* 'ref'? 'partial'? 'struct'
      identifier type_parameter_list? struct_interfaces?
      type_parameter_constraints_clause* struct_body
    ;

non_record_struct_with_positional_members
    : attributes? struct_modifier* 'ref'? 'partial'? 'struct'
      identifier type_parameter_list? delimited_parameter_list struct_interfaces?
      type_parameter_constraints_clause* struct_body
    ;

結構由 non_record_struct_declaration 宣告,記錄結構由 record_struct_declaration 宣告。 記錄結構在 第16.5節中有討論。 這兩種差異詳見 第16.7節。

non_record_struct_declaration可以有兩種幾乎相同的形式:non_record_struct_without_positional_members和non_record_struct_with_positional_members。

non_record_struct_without_positional_members由一組可選屬性(§23)、一組可選的struct_modifiers(§16.2.2)、一個可選ref修飾符(§16.2.3)、一個可選的部分修飾符(§15.2.7)、關鍵字struct及一個命名結構體的識別碼,最後是可選的type_parameter_list規範(§15.2.3),接著是可選的 struct_interfaces 規範(§16.2.5),接著是可選的 type_parameter_constraints 子句規範(§15.2.5),接著是struct_body(§16.2.6),可選擇性地接著分號。

non_record_struct_with_positional_members語法相同,但需要delimited_parameter_list,如上文文法規則所示。 關於 delimited_parameter_list的討論,請參見 第15.11.6節。

一個結構體若直接擁有必要的成員(§15.7.1),即非透過繼承,應視為已裝飾屬性 System.Runtime.CompilerServices.RequiredMemberAttribute (§23.5.12.2)。 struct_declaration除非同時提供type_parameter_list,否則不得供應type_parameter_constraints_clause。

提供type_parameter_list的struct_declaration是一個通用的結構宣告。 此外,泛型類別宣告或泛型結構宣告內巢狀的任何結構本身都是泛型結構宣告,因為應該提供包含型別的型別自變數來建立建構型別 ({8.4)。

包含修飾符的ref不應有struct_interfaces部分。

16.2.2 結構修飾詞

struct_declaration可以選擇性地包含一連串struct_modifier。

struct_modifier
    : 'new'
    | 'public'
    | 'protected'
    | 'internal'
    | 'private'
    | 'readonly'
    | 'file'
    | unsafe_modifier   // unsafe code support
    ;

unsafe_modifier (§24.2)僅在非安全程式碼(§24)中提供。

同一個修飾詞在結構宣告中出現多次是編譯時期錯誤。

對於任何 public、 protected、 internal和 private 修飾符與修飾符合併 file 時,都是編譯時錯誤。

readonly除了 之外,結構宣告的修飾詞與類別宣告的修飾詞意義相同({15.2.2)。

readonly修飾詞表示struct_declaration宣告實例不可變的類型。

唯讀結構具有下列條件約束:

  • 每個實體欄位也應該宣告為readonly。
  • 它不得宣告任何類似欄位的事件(§15.8.2)。

當只讀結構實例傳遞至方法時,其 this 會被視為輸入參數,即不允許寫入任何實例欄位(除了建構函式除外)。

16.2.3 Ref 修飾詞

ref修飾符表示non_record_struct_declaration宣告一個實例被分配到執行堆疊上的型態。 這些類型稱為 ref 結構 類型。 ref修飾符宣告實例可包含類似參考的欄位,且不得從其安全上下文中複製(§16.8.15)。 判斷ref結構安全上下文的規則詳見 §16.8.15。

如果在下列任一內容中使用 ref 結構類型,則為編譯時期錯誤:

  • 作為陣列的元素類型。
  • 做為類別或結構中沒有 ref 修飾詞之欄位的宣告型別。
  • 作為 Tuple 元素的型別。
  • 採用非同步方法。
  • 在迭代器中。
  • 作為方法群組從實例方法轉換為代理型別的接收器類型。
  • 作為 lambda 表達式中的捕捉變數或局部函數。

此外,以下限制適用於類型 ref struct :

  • 類型 ref struct 不應被框定為 System.ValueType 或 System.Object。
  • 在 object 或 System.ValueType 中宣告但未在 ref struct 型別中覆寫的實例方法,不得以該 ref struct 型別的接收者呼叫。

注意:A ref struct 不得宣告 async 實例方法,也不得在實例方法中使用 yield return or yield break 陳述,因為隱含 this 參數在這些上下文中無法使用。 結尾註記

這些條件約束可確保 類型的 ref struct 變數不會參考不再有效的堆疊記憶體,或參考不再有效的變數。

雖然某個 ref struct 型別可以實作介面,但該 ref struct 型別必須實作該介面的所有實例成員,即使它們有預設實作。

16.2.4 部分修飾詞

修飾詞 partial 表示這個 struct_declaration 是部分類型宣告。 多個在封入命名空間或類型宣告內具有相同名稱的部分結構宣告會結合成一個結構宣告,並遵循在 \15.2.7 中指定的規則。

16.2.5 結構介面

結構宣告可能包含 struct_interfaces 規格,在此情況下,結構據說會直接實作指定的介面類型。 針對建構的結構類型,包括在泛型型別宣告中宣告的巢狀類型(§15.3.9.7),每個實作的介面類型都是通過在所指定的介面中用建構型別的對應type_argument 替代每個type_parameter 來取得。

struct_interfaces
    : ':' interface_type_list
    ;

在多個部分的部分結構宣告(§15.2.7)中介面的處理方式,會在§15.2.4.3中進一步討論。

第 19.6 節進一步討論介面實作。

16.2.6 結構主體

結構 struct_body 會定義結構的成員。

struct_body
    : '{' struct_member_declaration* '}' ';'?
    | ';'
    ;

struct_bodys{}、{};、、;等價,struct_bodys{…}和 {…}; 等價。

16.3 結構成員

16.3.1 一般

結構體的成員由其 struct_member_declarations 所引入的成員、繼承自型別「System.ValueType」的成員,以及實作(§16.5.3)隱含提供的成員組成。

struct_member_declaration
    : constant_declaration
    | struct_field_declaration
    | method_declaration
    | property_declaration
    | event_declaration
    | indexer_declaration
    | operator_declaration
    | constructor_declaration
    | static_constructor_declaration
    | type_declaration
    | fixed_size_buffer_declaration   // unsafe code support
    ;

fixed_size_buffer_declaration (§24.8.2)僅在非安全程式碼(§24)中提供。

注意:struct_member_declaration包含除finalizer_declaration外所有class_member_declaration選項,並新增支援參考欄位的 struct_field_declaration(§16.8.8.2)。 結尾註記

結構體中的欄位支援類別不支援的功能。 詳情請參見 第16.8.8.2節 。

除了第 16.8節所述的差異外, 第15.3 至 15.12 條中對類別成員的描述同樣適用於結構成員。

16.3.2 只讀會員

實例成員定義或包含該 readonly 修飾符的實例屬性、索引器或事件的存取器,有以下限制:

  • 參數 this 是一個 ref readonly 參考。
  • 成員不得重新指派接收者的值 this 或實例欄位。
  • 成員不得重新指派接收端類似實例欄位事件(§15.8.2)的值。
  • 若一個唯讀成員呼叫非唯讀成員,必須複製該 this 結構以使用可寫的參數參考 this 。

註: 實例欄位包含用於自動實作屬性的隱藏後盾欄位(§15.7.4)。 結尾註記

範例:唯讀成員可以修改實例欄位所指物件的狀態,儘管該只讀成員無法重新指派該實例成員。 以下程式碼示範重新指派與修改實例欄位:

public struct S
{
    private List<string> messages;

    public S(IEnumerable<string> messages) =>
        this.messages = new List<string>(messages);

    public void InitializeMessages() =>
        messages = new List<string>();

    public readonly void AddMessage(string message)
    {
        if (messages == null)
        {
            throw new InvalidOperationException("Messages not initialized.");
        }
        messages.Add(message);
    }
}

此 readonly 方法 AddMessage 可以改變訊息清單的狀態。 InitializeMessages成員可以清除並重新初始化訊息清單。 在 的情況下 AddMessage,修 readonly 飾符是有效的。 在 的情況下 InitializeMessages,加入 readonly 修飾符是無效的。 結束範例

16.4 主要製造商

與非記錄類別類似,帶有 delimited_parameter_list 的非記錄結構體由實作提供主要建構子(§15.11.6)。 非記錄類別版本的語意在此同樣適用,並由本子句的文本補充。

對於非記錄類別,實作應為每個參數提供一個私有且僅初始化的欄位。 然而,對於非記錄結構體,儲存是讀寫方式,且以未指定方式提供。

非記錄結構的實例欄位宣告允許包含變數初始化器。 若無主要建構子,實例初始化器將作為無參數建構子的一部分執行。 否則,執行時主要建構子會執行 struct_body中出現的實例初始化器。

16.5 記錄結構

16.5.1 一般

記錄結構是一種專門用於儲存資料而非行為的特殊值類型。 它內建的功能通常需要大量「樣板」結構體程式碼,例如基於值的等號與易於不變性。

record_struct_declaration
    : attributes? struct_modifier* 'partial'? 'record' 'struct'
      identifier type_parameter_list? delimited_parameter_list? struct_interfaces?
      type_parameter_constraints_clause* struct_body
    ;

一個 record_struct_declaration 由一組可選 屬性 (§23)、一組可選的 struct_modifiers(§16.2.2)、一個可選的部分修飾符(§15.2.7)、關鍵字 record、關鍵字 struct 及命名結構的 識別碼 、可選的 type_parameter_list 規範(§15.2.3)以及可選的 delimited_parameter_list組成 規範(§15.6.2.1),接著是可選的 struct_interfaces 規範(§16.2.5),接著是可選的 type_parameter_constraints條款 規範(§15.2.5),接著是 struct_body (§16.2.6)。

擁有 delimited_parameter_list 的record_struct_declaration宣告一個位置記錄結構。

最多只有一個 record_struct_declaration 能 partial 提供 一個delimited_parameter_list。

delimited_parameter_list 中的參數不得有 ref,out或this修飾符;然而,in且params允許修飾符。

16.5.2 結構成員

記錄結構體的成員被命名 Clone為 是錯誤。

記錄結構體的實例欄位出現不安全型態是錯誤。

16.5.3 隱含記錄結構成員

16.5.3.1 一般

對於記錄結構體而言,成員由實作提供,除非 struct_body 中宣告具有「匹配」簽章的成員,或繼承一個具有「匹配」簽章的可存取具體非虛擬成員。 匹配成員可防止實作僅提供該成員,而非其他成員。 若兩個成員有相同的簽名,則視為匹配,或在繼承情況下被視為「隱藏」。 (參見簽名與過載 §7.5。)

實作所提供的成員在以下子條款中描述。

16.5.3.2 平等成員

所提供的等號成員與記錄類別(§15.16.4.3)相似,但缺少方法 EqualityContract、空檢查或繼承。

記錄結構 R 實 System.IEquatable<R> 作並包含一個合成的強型別超載,該超載 Equals(R other)為公開,具體如下:

public readonly bool Equals(R other);

這個方法可以明確宣告。 然而,若明確宣告與預期的簽名或可存取性不符,則為錯誤。

若 Equals(R other) 是使用者定義但 GetHashCode 未定義,則會產生警告。

當Equals(R)true且僅當記錄結構中每個實例欄位fieldN的值 System.Collections.Generic.EqualityComparer<TN>.Default.Equals(fieldN, other.fieldN),TN其中 是欄位類型,為 true。

記錄結構包含 提供了 和 ==!= 運算子,等同於以下宣告的運算子:

public static bool operator==(R r1, R r2) => r1.Equals(r2);
public static bool operator!=(R r1, R r2) => !(r1 == r2);

Equals運算子==所呼叫的方法即上述Equals(R other)所述方法。 !=操作員將工作權委託給操作員==。 若運算子被明確宣告,則為錯誤。

記錄結構包含一個覆蓋方法,宣告如下:

public override readonly bool Equals(object? obj);

若覆蓋被明確宣告,則為錯誤。 所提供的覆寫將回傳 obj is R temp && Equals(temp) ,其中 R 為記錄結構。

記錄結構包含一個覆蓋方法,宣告如下:

public override readonly int GetHashCode();

此方法可明確宣告。

若明確宣告其中 Equals(R) 一種 和 GetHashCode() 但另一方未宣告,則應報告警告。

所提供的覆寫應回GetHashCode()傳將將每個實例欄位intSystem.Collections.Generic.EqualityComparer<TN>.Default.GetHashCode(fieldN)的值fieldN與為 的TN類型結合後的fieldN結果。

範例:考慮以下記錄結構:

record struct R1(T1 P1, T2 P2);

為此,所提供的等值成員大致如下:

struct R1 : IEquatable<R1>
{
    public T1 P1 { get; set; }
    public T2 P2 { get; set; }
    public override bool Equals(object? obj) => obj is R1 temp && Equals(temp);
    public bool Equals(R1 other)
    {
        return
            EqualityComparer<T1>.Default.Equals(P1, other.P1) &&
            EqualityComparer<T2>.Default.Equals(P2, other.P2);
    }
    public static bool operator==(R1 r1, R1 r2) => r1.Equals(r2);
    public static bool operator!=(R1 r1, R1 r2) => !(r1 == r2);
    public override int GetHashCode()
    {
        return HashCode.Combine(
            EqualityComparer<T1>.Default.GetHashCode(P1),
            EqualityComparer<T2>.Default.GetHashCode(P2));
    }
}

結束範例

16.5.3.3 印刷成員

記錄結構包含一個所提供的方法,宣告如下:

private bool PrintMembers(System.Text.StringBuilder builder);

此方法執行以下任務:

  1. 對於記錄結構中每個可列印的成員(非靜態的公共欄位及可讀屬性成員),會在該成員名稱後加上「=」,再以「, “分隔」分隔的成員值,
  2. 如果 record struct 有可列印的成員,則會回傳 true。

對於具有值型別的成員,其值應轉換為字串表示法。

若記錄的可列印成員未包含帶有非readonlyget accessor 的可讀屬性,則合成PrintMembersreadonly為 。 不要求記錄欄位必須為 readonly ,方法 PrintMembers 才 readonly為 。

PrintMembers此方法可明確宣告。 然而,若明確宣告與預期的簽名或可存取性不符,則為錯誤。

記錄結構包含一個方法,宣告如下:

public override string ToString();

若記錄結構 PrintMembers 的方法為 readonly,則所提供 ToString() 的方法為 readonly。

這個方法可以明確宣告。 若明確宣告與預期的簽章或可存取性不符,則為錯誤。

此方法執行以下任務:

  1. 建立一個 StringBuilder 實例,
  2. 將 record struct 名稱附加到建構者後面,接著是「{」,
  3. 呼叫記錄結構 PrintMembers 的方法,給出建構器,若返回為真,接著加上「 」,
  4. 附錄「}」,
  5. 返回建商的物品。builder.ToString()

範例:考慮以下記錄結構:

record struct R1(T1 P1, T2 P2);

對於此記錄結構,所提供的列印成員大致如下:

struct R1 : IEquatable<R1>
{
    public T1 P1 { get; set; }
    public T2 P2 { get; set; }

    private bool PrintMembers(StringBuilder builder)
    {
        builder.Append(nameof(P1));
        builder.Append(" = ");
        builder.Append(this.P1); // or builder.Append(this.P1.ToString());
                                 // if P1 has a value type
        builder.Append(", ");

        builder.Append(nameof(P2));
        builder.Append(" = ");
        builder.Append(this.P2); // or builder.Append(this.P2.ToString());
                                 // if P2 has a value type

        return true;
    }

    public override string ToString()
    {
        var builder = new StringBuilder();
        builder.Append(nameof(R1));
        builder.Append(" { ");

        if (PrintMembers(builder))
            builder.Append(" ");

        builder.Append("}");
        return builder.ToString();
    }
}

結束範例

16.5.3.4 位置記錄結構成員

16.5.3.4.1 一般

除了提供前述子條款中描述的成員外,位置記錄結構(§16.2.1)還使實作時,為其他成員提供與其他成員相同的條件,如後述子條款所述。

16.5.3.4.2 主要建構器

帶有 delimited_parameter_list 的記錄結構會有一個公開 的主要建構器 ,其簽名對應於該清單的參數。 宣告另一個具有相同簽章的建構器是編譯時錯誤。 若宣告無 delimited_parameter_list,則不提供主要建構子。 空 delimited_parameter_list 提供無參數的主要建構子。

若記錄結構有主要建構子,每個明確宣告的實例建構器都應有一個 this 建構器初始化器(§15.11.2),以呼叫主要建構子或其他明確宣告的實例建構子。 解析該初始化器的規則及循環建構子相依的規則,與其他結構建構子相同適用(§16.8.9)。

主要構造參數貫穿整個 struct_body。 在實例欄位、屬性或事件的初始化器中,一個主要建構參數會遮蔽同名成員,並可用作值。 在該主體的其他地方,成員會執行主要建構參數的影子,且除非在參數中 nameof ,否則不得引用主建構參數。 僅因為宣告了主要建構參數,並不會提供額外的儲存空間。 屬性及其支持欄位僅依 §16.5.3.4.3的規定提供。 若未讀取主要建構參數,可能會產生警告。

執行時,主建構子會將 §16.5.3.4.3 所提供的自動屬性的後盾欄位初始化為對應參數的值,然後依文字順序(§15.5.6.1)執行struct_body中的實例初始化器。 明確宣告的匹配欄位或屬性不會自動從對應參數初始化;儲存該值需要初始化器或建構子指派。

記錄結構中的實例欄位宣告可能包含變數初始化器。 在缺乏主要建構子的情況下,明確宣告的實例建構子會依據結構建構者規則(§16.8.9)執行實例初始化器。 隱含預設初始化(§16.8.5)不會執行實例初始化器。

範例:匹配屬性可以提供自身值,而非儲存主要建構子參數:

var r = new R<int>(42);
Console.WriteLine($"{r.Initial}/{r.X}");
Console.WriteLine($"{new S().X}/{new S(1).X}");

record struct R<T>(T X)
{
    public T Initial { get; set; } = X;
    public T X => default;
}

record struct S
{
    public int X = 42;
    public S(int ignored) { }
}

此處初始 Initial 化子讀取參數 X,而屬性 X 無後盾欄位。 隱含提供的無參數建構 S 不會執行其欄位初始化器,而其明確宣告的建構子則執行。 結束範例

結構體實例建構子的確定指派規則(§16.8.9、 §12.8.14)適用於記錄結構體的主要建構子。 與其他沒有 this() 初始化器的結構體實例建構器一樣,任何未被主建構器明確指派的實例欄位,會在主建構子主體之前的初始化階段,隱含初始化為其預設值。

16.5.3.4.3 屬性

對於每個與明確宣告的實例欄位名稱與型別相同的 delimited_parameter_list 參數,該子句的其餘部分不適用。

對於每個 delimited_parameter_list的記錄結構參數,都會提供一個對應的公共屬性成員,其名稱與型別取自值參數宣告,除非有匹配成員(§16.5.3.1)阻止其提供。

對於記錄結構:

  • 若 record 結構帶有get修飾符,則會建立 public init 與 readonly auto 屬性, getset否則則不然。 這兩種集合存取器(set 和 init)都被視為「匹配」的。 因此,使用者可以宣告僅初始化的屬性,取代提供的可變屬性。

  • 繼承 abstract 屬性與類型匹配的屬性會被覆寫。

  • 如果記錄結構體有一個包含預期名稱和類型的實例欄位,則不會產生自動屬性。

  • 若繼承的屬性沒有 publicget 和 set/init 存取者,則為錯誤。

  • 若繼承的屬性或欄位被隱藏,則為錯誤。

  • 每個提供的自動屬性都會初始化為對應的主要建構參數值。 如果 record struct 有 修readonly飾符,則其 backfield 為 readonly 。

  • 屬性可透過使用 property: 或 field: 目標,分別套用於相應的記錄結構參數的屬性,套用於所提供的自動屬性及其後盾欄位。

16.5.3.4.4 解構

一個至少包含一個參數的位置記錄結構,提供 void一個公開的 -returning 實例方法,該方法對主要建構子宣告的每個參數都有一個 Deconstruct out 參數宣告。 每個參數 Deconstruct 的型別與主建構子宣告的對應參數相同。 方法主體會將 Deconstruct 方法的每個參數指派給同名成員的實例成員存取值。 若在實體中存取的實例成員中沒有包含非readonlyget accessor 的屬性,則合成 Deconstruct 方法為 readonly。 此方法可明確宣告。 若明確宣告與預期的簽章或可存取性不符,或是靜態,則為錯誤。

16.6 直列陣列

以屬性 System.Runtime.CompilerServices.InlineArrayAttribute 裝飾的結構型別(§23.5.14)是一個內 列陣列型別,屬於受管理型態。 該類型的實例是 內嵌陣列,包含連續區塊的結構,包含相同類型元素的連續區塊,且不包含其他元素。 它是 safe-code 中 unsafe code 固定大小緩衝區(§24.8)的等價物。

雖然有一些限制(詳見下文),內嵌陣列也可以像陣列一樣使用(§17)。

請考慮下列事項:

var buffer = new Buffer();

for (int i = 0; i < 5; ++i)
{
    buffer[i] = i;
}

foreach (var i in buffer)
{
    Console.WriteLine(i);
}

Console.WriteLine($"buffer[^2]        = >{buffer[^2]}<");
Console.WriteLine($"buffer[1..^0][0]  = >{buffer[1..^0][0]}<");

[System.Runtime.CompilerServices.InlineArray(5)]
public struct Buffer
{
    private int _element0;
    // other, optional, non-instance-field members
}

產生以下輸出:

0
1
2
3
4
buffer[^2]        = >3<
buffer[1..^0][0]  = >1<

屬性建構子需要一個正值 int 參數,表示每個內嵌陣列中由此類型建立的元素數,在此例中為五個。 結構型應宣告一個實例欄位,其型別即為內嵌陣列元素的類型。 實例欄位的可存取性不會影響程式透過結構實例名稱(此例為 buffer)存取內嵌陣列的能力。

實例欄位宣告有多項限制:

  • 它不應包含field_modifiersreadonly、、refrequired、或volatile。
  • 不得宣告為 fixed_size_buffer_declaration (§24.8)。
  • 型別 應是作為型別參數有效型態的型別。

buffer 是 的 Buffer一個實例,包含一個包含五個 int 的陣列,元素 buffer[0] 佔據與 相同的記憶體 buffer._element0。 然而,與具有公共 Length 屬性的陣列類型不同, buffer 陣列類型並非由 System.Array衍生而來,且沒有此類成員。

注意:可以將公共 Length 屬性加入( Buffer 回傳 sizeof(Buffer)/sizeof(int),但該屬性必須是不安全成員)。 或者,也可以對 或 進行隱式轉換System.Span<int>System.ReadOnlySpan<int>,並使用其Length屬性。 結尾註記

內嵌陣列是一個集合;因此,它可以透過陳述 foreach 來迭代,如圖所示。

內嵌陣列的元素可透過下標(§12.8.12.3)存取以進行讀寫。

串列模式(§11.2.11)不得用於內嵌陣列的情境。

內嵌陣列類型是集合文字的有效可建構集合目標類型。

任何為內嵌陣列類型宣告且簽名與非內嵌陣列處理定義相符的索引器或 Slice 方法,不得在內線陣列元素存取時使用。

範例:請考慮以下情況:

var buffer = new Buffer();
int x = buffer[2];      // element access

[System.Runtime.CompilerServices.InlineArray(5)]
public struct Buffer
{
    private int _element0;
    public int this[int index] // NOT USED for element access
    {
        get
        {
            return 0;
        }
    }
}

即使結構體宣告索引器接收 int 參數,該索引器並未被元素存取 buffer[2]所使用。 結束範例

16.7 記錄結構與結構差異

記錄結構與結構體在幾個重要方面有所不同:

  • 它是用關鍵字 record struct 宣告的,而非僅用 struct。
  • 該委員會由實施時提供的若干成員。
  • 其宣告可能包含一個包含零或多個參數的 delimited_parameter_list ,這會導致提供包含這些參數的主要建構子(§16.5.3.4.2)。 依照匹配成員規則,每個參數都會提供一個屬性,包含 get 和 accessors,或initget是 and 用於只讀記錄結構(§16.5.3.4.3set)。 Deconstruct只有當至少有一個參數且沒有匹配成員抑制時,才會提供方法(§16.5.3.4.4)。
  • 其記錄結構體可省略。
  • 它不應有名為 Clone的成員。
  • 它不應有帶有不安全類型的實例欄位。

16.8 班級與結構差異

16.8.1 一般

結構與類別在幾個重要方面上有所不同:

  • 結構體是值型別(§16.8.2)。
  • 所有結構型別都隱含地繼承自類別 System.ValueType (§16.8.3)。
  • 將變數指派到結構型別的變數後,會產生被指派值的 副本 (§16.8.4)。
  • 結構體的預設值是將所有欄位設為預設值所產生的值(§16.8.5)。
  • 箱裝與開箱操作用於結構型態與某些參考型別之間的轉換(§16.8.6)。
  • 在結構成員中,其 this 意義不同(§16.8.7)。
  • 結構體不得宣告終結器。
  • 事件宣告、屬性宣告、屬性存取子、索引器宣告和方法宣告可以有修飾詞 readonly,而這些相同成員類型在類別中通常不允許這樣做。

16.8.2 值語意

結構是實值型別(~8.3),據說具有值語意。 另一方面,類別是參考型別(~8.2),據說具有參考語意。

結構類型的變數直接包含結構的數據,而類別類型的變數則包含包含數據的 對象參考。 當結構B包含類型A的實例字段,而A是結構類型時,如果A依賴於B或來自B建構的類型,則會產生編譯時期錯誤。 如果 X 包含類型為 的實例欄位,則結構 YX。 鑒於此定義,結構所依賴的完整結構集是「直接依賴於」關係的傳遞閉包。

Example:

struct Node
{
    int data;
    Node next; // error, Node directly depends on itself
}

是錯誤,因為 Node 包含其本身類型的實例欄位。 另一個範例

struct A { B b; }
struct B { C c; }
struct C { A a; }

是錯誤,因為每個類型 A、 B和 C 相依於彼此。

結束範例

使用類別時,兩個變數可以參考相同的物件,因此一個變數上的作業可能會影響另一個變數所參考的物件。 使用結構體時,變數各自擁有自己的數據副本(除了以引用參數的情況外),因此在一個變數上的操作不會影響到另一個變數。 此外,除非明確可為 Null (~8.3.12),否則結構類型的值不可能是 null。

注意:如果結構體包含參考型態的欄位,或是參考變數,則可被其他操作更改所參考物件的內容。 不過,欄位本身的值,也就是它所參考的物件,無法透過不同結構值的突變來變更。 結尾註記

範例:給定以下情況

struct Point
{
    public int x, y;

    public Point(int x, int y) 
    {
        this.x = x;
        this.y = y;
    }
}

class A
{
    static void Main()
    {
        Point a = new Point(10, 10);
        Point b = a;
        a.x = 100;
        Console.WriteLine(b.x);
    }
}

輸出為 10。 指派 a 給 b 時會建立值的複本,因此 b 不會受到指派給 a.x 的影響。 若 Point 被宣告為類別,輸出將為 100,因為 a 和 b 将參考相同的物件。

結束範例

16.8.3 繼承

所有結構型別會隱含地繼承自類別 System.ValueType,而類別 System.ValueType 則會繼承自類別 。 結構宣告可以指定實作介面的清單,但結構宣告不可能指定基類。

結構體永遠不是抽象的,並且總是隱含封閉的。 因此,abstract 和 sealed 修飾詞在結構宣告中不被允許。

由於結構體不支援繼承,結構成員宣告的可及性不能是 protected、 或 private protectedprotected internal。

結構中的函式成員不可以是抽象或虛擬的,而且 override 只允許修飾詞覆寫繼承自 System.ValueType的方法。

16.8.4 分配

結構類型的變數指派會 建立所指派值的複本 。 這與類別類型的變數指派不同,該變數會複製參考,但不會複製參考所識別的物件。

類似於指派,當結構當做值參數傳遞或當做函式成員的結果傳回時,就會建立結構的複本。 結構可以透過傳址參數,以參考方式傳遞至函式成員。

當結構的屬性或索引器是指派的目標時,與屬性或索引器存取相關聯的實例表達式應分類為變數。 如果實例表達式分類為值,就會發生編譯時期錯誤。 此點在 第12.24.2節有更詳細說明。

16.8.5 預設值

如 \9.3 中所述,在建立變數時,會自動初始化數種變數的預設值。 對於類別類型及其他參考類型,以及參考變數欄位,預設值為 null。 然而,由於結構體是無法被設定為 null的值型別,結構體的預設值是將所有值型別欄位設為預設值,並將所有參考變數欄位與參考型別欄位設 null為 所產生的值。

範例:參考 Point 上述宣告的結構體,範例

Point[] a = new Point[100];

將陣列中的每個Point初始化為將x和y欄位設定為零所產生的值。

結束範例

結構體的預設值是將所有欄位設為預設值所產生的值(§8.3.3)。 當結構體未宣告明確的無參數實例建構子時,其隱含的預設建構子會產生該值。 明確宣告的無參數實例建構器可能會產生不同的值。 該 default 表達式總是產生零初始化的預設值,且不會呼叫明確宣告的實例建構子(§16.8.9)。

注意:結構體應設計成將預設初始化狀態視為有效狀態。 在範例中

struct KeyValuePair
{
    string key;
    string value;

    public KeyValuePair(string key, string value)
    {
        if (key == null || value == null)
        {
            throw new ArgumentException();
        }

        this.key = key;
        this.value = value;
    }
}

用戶定義的實例建構函式只有在被明確呼叫時,才會防止 null 的值造成問題。 在變數受限於預設值初始化的情況下 KeyValuePair , key 和 value 欄位將會是 null,而結構應該準備好處理此狀態。

結尾註記

16.8.6 拳擊與解封

類別類型的值可以轉換成類型 object ,或轉換成類別所實作的介面類型,只要在編譯階段將參考視為另一種類型即可。 同樣地,類型 object 的值或介面類型的值可以轉換回類別類型,而不需變更參考(但在此案例中,需要執行時類型檢查)。

由於結構不是參考型別,因此這些作業會針對結構類型以不同的方式實作。 當結構類型的值轉換成特定參考型別時(如 §10.2.9 中所定義),就會進行裝箱作業。 同樣地,當特定參考型別的值(如第10.3.7節中所定義)轉換為結構類型時,就會進行拆箱操作。 與類別類型相同的作業相比,主要差異在於boxing和unboxing會將結構值複製至Boxed實例或從Boxed實例取出。

注意:因此,在進行打盒或開箱操作後,對開箱 struct 的變更不會反映在被打 struct框的 。 結尾註記

如需了解封箱和拆箱的更多詳情,請參閱 §10.2.9 和 §10.3.7。

16.8.7 此意義

結構中 的意義this與 類別中 的意義this不同,如 •12.8.14 中所述。 當結構類型覆寫繼承自 System.ValueType 的虛擬方法(例如 Equals、 GetHashCode或 ToString),透過結構類型的實例叫用虛擬方法時,不會造成 Boxing 發生。 即使結構當做類型參數使用,而且會透過類型參數類型的實例進行調用,也是如此。

Example:

struct Counter
{
    int value;
    public override string ToString() 
    {
        value++;
        return value.ToString();
    }
}

class Program
{
    static void Test<T>() where T : new()
    {
        T x = new T();
        Console.WriteLine(x.ToString());
        Console.WriteLine(x.ToString());
        Console.WriteLine(x.ToString());
    }

    static void Main() => Test<Counter>();
}

程式輸出為:

1
2
3

雖然ToString有副作用是不良的風格,但此範例顯示呼叫x.ToString()的三次操作中沒有發生封箱。

結束範例

同樣地,當成員實作於實作實值型別時,在限制型別參數上存取成員時,永遠不會隱含地發生Boxing。 例如,假設介面 ICounter 包含方法 Increment,可用來修改值。 如果使用 ICounter 作為限制條件,那麼會以Increment所呼叫的變數作為參考來呼叫Increment方法的實作,絕不會呼叫封裝的複本。

Example:

interface ICounter
{
    void Increment();
}

struct Counter : ICounter
{
    int value;

    public override string ToString() => value.ToString();

    void ICounter.Increment() => value++;
}

class Program
{
    static void Test<T>() where T : ICounter, new()
    {
        T x = new T();
        Console.WriteLine(x);
        x.Increment();              // Modify x
        Console.WriteLine(x);
        ((ICounter)x).Increment();  // Modify boxed copy of x
        Console.WriteLine(x);
    }

    static void Main() => Test<Counter>();
}

第一次呼叫 ,修改 Increment 變數 x中的值。 這與第二次呼叫 Increment 不相等,因為它修改了 x 的封裝複本中的值。 因此,程序的輸出為:

0
1
1

結束範例

16.8.8 田野

16.8.8.1 場初始化器

如 §16.8.5 所述,結構體的預設值由將所有值型別與參考變數欄位設為預設值,並將所有參考型態欄位設為 null後產生的值組成。 結構體的靜態與實例欄位允許包含變數初始化器;然而,若是實例欄位初始化器,至少還應宣告一個實例建構子,或對於記錄結構體,必須有 delimited_parameter_list 。

Example:

Console.WriteLine($"Point is {new Point()}");

struct Point
{
    public int x = 1;
    public int y = 1;

    public Point() { }

    public override string ToString()
    {
        return "(" + x + ", " + y + ")";
    }
}
Point is (1, 1)

結束範例

當結構體實例建構器沒有建構器初始化器時,該建構器會隱含執行由其結構中宣告的實例欄位 variable_initializers 所指定的初始化。 這對應於一連串在進入建構子時立即執行的指派序列。

當結構體實例建構子有一個 this() 代表預設無參數建構器的建構器初始化器時,該宣告建構子會隱含地清除所有實例欄位,並執行其結構中宣告的實例欄位 variable_initializers 所指定的初始化。 一旦進入建構子,所有值型別欄位即設為預設值,所有參考型別欄位皆設為 null。 緊接著執行一連串對應 於 variable_initializers 的指派。

直接在具有struct_modifier的struct_declaration內宣告的readonly應具有field_modifierreadonly。

16.8.8.2 參考欄位

struct_field_declaration
    : attributes? field_modifier* ('readonly'? 'ref' 'readonly'?)? type
      variable_declarators ';'
    ;

field_modifier 詳見 第15.5.1條。

不含 、 ref、 的readonly refref readonly如第15.5節所述。

A ref 或 readonly ref 欄位為參考變數,並受以下限制條件約束:

  • 它只能在 中 ref struct宣告。
  • 不得宣 static告為 、 volatile或 const。
  • 其類型本身不應是 ref struct 類型。
  • 在 中 readonly ref struct,每個 ref 欄位都應宣告 readonly ref (也可以宣告 readonly ref readonly)。

請考慮以下 ref struct 宣告:

ref struct RwS
{
    public static int rwField = 100;

    public ref int                   rwRefToRwData = ref rwField;
    public ref readonly int          rwRefToRoData = ref rwField;
    public readonly ref int          roRefToRwData = ref rwField;
    public readonly ref readonly int roRefToRoData = ref rwField;
    public RwS() { /*…*/ }
}

rwRefToRwData 是一個可寫的參考變數,其指稱被視為可 int寫的。 rwRefToRoData 是一個可寫的參考變數,其參照對象被視為唯讀 int。 roRefToRwData 是一個唯讀參考變數,其參照物被視為可 int寫的。 roRefToRoData 是一個唯讀參考變數,其指涉被視為唯讀 int。 讀寫欄位 rwField 可直接寫入,並透過參考變數 rwRefToRwData 和 roRefToRwData。

可讀參考變數可透過初始化器、建構子內的賦值或僅初始化的設定器取得值。

請考慮以下可讀的 ref struct 宣告:

readonly ref struct RoS
{
    public static int rwField = 200;

    public readonly ref int          roRefToRwData = ref rwField;
    public readonly ref readonly int roRefToRoData = ref rwField;
    public RoS() { /*...*/ }
}

roRefToRwData 是一個唯讀參考變數,其參照物被視為可 int寫的。 roRefToRoData 是一個唯讀參考變數,其指涉被視為唯讀 int。 讀寫欄位 rwField 可以直接寫入,並透過參考變數 roRefToRwData。

16.8.9 製造商

結構體可以宣告實例建構子,參數為零或多個。 若結構體沒有明確宣告的無參數實例建構子,則會合成並公開可及性,該構造體總是回傳將所有值型別欄位設為預設值、所有參考變數欄位為空參考、所有參考型別欄位設為 null (§8.3.3) 後產生的值。 在這種情況下,當建構子執行時,任何實例欄位初始化器都會被忽略。

明確宣告的無參數實例建構器應具備公開可存取性。

範例:給定以下情況:

using System;
struct Point
{
    int x = -1, y = -2;

    public Point(int x, int y) 
    {
        this.x = x;
        this.y = y;
    }

    public override string ToString()
    {
        return "(" + x + ", " + y + ")";
    }
}

class A
{
    static void Main()
    {
        Console.WriteLine($"Point is {new Point()}");
        Console.WriteLine($"Point is {new Point(0,0)}");
    }
}
Point is (0, 0)
Point is (0, 0)

這些陳述式同時建立 Point 且xy初始化為零,這在呼叫無參數實例建構子時可能會令人驚訝,因為兩個實例欄位都有初始化器,但它們並未被執行。

結束範例

不允許結構體實例建構子包含形式為base(argument_list)的建構子初始化,其中 argument_list 是可選的。 執行實例建構子時,不應執行結構基底型 System.ValueType態 的建構子。

this結構實例建構子的參數行為類似於結構型態的輸出參數,但當明確的指派要求(§9.4.1)thisthis未在本應滿足的位置時,則不會導致編譯時錯誤。 相反地,未指派變數會在初始化階段隱含初始化為預設值(§9.3),在建構子中其他程式碼執行前,如 §12.8.14 所述。

如果結構實例建構子指定了一個建構器初始化器,該初始化器就被視為在建構子主體之前的明確指派。this 因此,系統本身不需要初始化要求。

對於沒有this()初始化器的結構體實例建構子,任何未在建構子回傳的每個位置都明確指派,或尚未在讀取該欄位值的位置被明確指派this的實例欄位(除欄位外fixed),在§12.8.14所述初始化階段會隱含初始化為其預設值。

範例:請考慮以下實例建構子的實作:

struct Point
{
    int x, y;

    public int X
    {
        set { x = value; }
    }

    public int Y 
    {
        set { y = value; }
    }

    public Point(int x, int y) 
    {
        X = x; // ok; x is implicitly initialized to its default value
               // before the body runs, so calling the X setter is allowed
        Y = y; // ok, for the same reason
    }
}

由於實例欄位 x 和 y 在向屬性設定器呼叫前並未明確指派,因此在建構子主體執行前的初始化階段,它們會隱含地初始化為預設值。 因此,即使XY建構本體本身未先指派 x 和 y,也可以調用 和 的集合。

自動實作的屬性(§15.7.4)透過隱藏的背板欄位與這些規則互動。 定指派規則(§12.24.2)明確將在該結構型別的實例建構器中,對該結構型態的自動屬性指派視為對該自屬性隱藏支持欄位的確定指派。 因此,以下情況也被允許:

struct Point
{
    public int X { get; set; }
    public int Y { get; set; }

    public Point(int x, int y)
    {
        X = x; // allowed, definitely assigns backing field
        Y = y; // allowed, definitely assigns backing field
   }
}

範例結束]

16.8.10 靜態建構器

結構靜態建構函式會遵循與類別相同的大部分規則。 結構類型的靜態建構函式執行是由應用程式域內發生下列第一個事件所觸發:

  • 參考結構類型的靜態成員。
  • 結構型別的明確宣告的建構函式被呼叫。

注意:建立結構型別的預設值(§16.8.5)不會觸發靜態建構子。 (其中一個範例是陣列中元素的初始值。)end note

16.8.11 屬性

在struct_declaration中,實例屬性的property_declaration(§15.7.1)可能包含property_modifierreadonly。 不過,靜態屬性不得包含該修飾詞。

嘗試透過該結構中宣告的唯讀屬性修改實例結構變數的狀態,這是編譯時期錯誤。

自動實作屬性在編譯時期會出現錯誤,如果它同時具有 readonly 修飾詞和 set 存取子。

自動實作的屬性若在 readonly 結構中具有 set 存取子,則會導致編譯時錯誤。

在一個結構中宣告的自動實作屬性不需要有修飾詞 readonly,因為其存取子 readonly 被隱含地假設為只讀。

在屬性本身,以及它的readonly或get存取子上都有set修飾詞,是編譯時期的錯誤。

屬性若在其所有的存取子上都具有唯讀修飾詞,會導致編譯時錯誤。

注意:要修正錯誤,請將修飾符從 accesss 移到 屬性本身。 結尾註記

針對屬性存取子表示式, s.P:

  • 如果在 s.PM 中的進程會建立 的暫存複本T時叫用 型別的 set 存取子s,則為編譯時期錯誤。
  • 如果 s.P 叫用 類型的 Tget 存取子,則會遵循 \12.6.6.1 中的進程,包括視需要建立 的 s 暫存複本。

自動實作的屬性(§15.7.4)會使用隱藏的後備欄位,這些欄位只能由屬性存取子存取。

注意:由於結構型別自動屬性的後台欄位在未指派該建構器的初始化階段會隱含初始化為其預設值(§12.8.14),因此不需明確的建構器初始化器即可滿足該後盾欄位的確定指派規則。 結尾註記

16.8.12 方法

一個 struct_declaration 中實例方法的 method_declaration(§15.6.1)可能會包含 method_modifierreadonly。 不過,靜態方法不得包含該修飾詞。

嘗試透過該結構中宣告的唯讀方法修改實例結構變數的狀態,這是編譯時期錯誤。

雖然只讀方法可能會呼叫同層級的非唯讀方法、屬性或索引器的 get 存取子,但這樣做會促使建立 this 的隱含複本,以防止潛在的副作用。

readonly 方法可能會呼叫唯讀的同層級屬性或索引器 set 存取子。 如果同層級成員的存取子不是明確或隱含唯讀的,就會發生編譯錯誤。

所有部分方法的 method_declaration 都應該有 readonly 修飾詞,或者所有都不應該有。

16.8.13 索引員

在struct_declaration的實例索引器中,indexer_declaration(§15.9)可能包含indexer_modifierreadonly。

嘗試透過該結構中宣告的唯讀索引器修改實例結構變數的狀態,這是編譯時期錯誤。

在索引器本身以及其 readonly 或是 get 存取子上使用set修飾詞為編譯時錯誤。

索引器在所有存取子上都有只讀修飾詞,這是編譯時期錯誤。

注意:要修正錯誤,請將修飾符從存取器移到索引器本身。 結尾註記

2014年8月16日 活動

實例的 event_declaration (~15.8.1), struct_declaration 中的非字段式事件可能包含 event_modifierreadonly。 不過,靜態事件不得包含該修飾詞。

16.8.15 安全上下文約束

16.8.15.1 一般

在編譯階段,每個表達式都會與一個上下文相關聯,其中該實例及其所有欄位都可以安全地存取,這就是其安全環境。 安全環境是可以包容某個表達式的環境,在這個環境中,值可以安全地被傳遞。

編譯時期類型不是 ref 結構的任何運算式,都具有呼叫者內容的安全上下文。

任何類型的 default 表達式都取決於呼叫端內容的安全上下文。

UTF-8 字串字面值(§6.4.5.6)有一個呼叫者上下文的安全上下文。

對於任何編譯時間類型為 ref 結構的非預設表達式,其具有下列各節所定義的安全內容。

安全上下文記錄指出值可以被複製到哪些上下文中。 如果將具有安全內容E1的表達式S1指派給具有安全內容E2的表達式S2,而S2比S1具有更廣泛的內容,則這是錯誤的。

有四種不同的安全上下文值,與參考變數定義的 ref-safe-context 值相同(§9.7.2): 宣告區塊、 函式成員、 僅回傳及 呼叫者上下文。 表達式的安全內容會限制其用法,如下所示:

  • 對於返回語句 return e1,的安全 e1 上下文至少應是僅返回。
  • 指派 e1 = e2 的安全情境 e2 至少應與安全情境 e1一樣寬。
  • 對於參數的指派 out ,右側的安全上下文至少應是僅回傳的。

16.8.15.2 參數安全上下文

ref 結構類型的參數,包含實例方法中的 this 參數,會在呼叫方上下文中具有安全上下文。

out ref struct 類型的參數有一個安全上下文為僅回傳。

this結構建構子中的參數有一個安全上下文為僅回傳。

16.8.15.3 局部變數安全上下文

ref 結構類型的局部變數具有安全內容,如下所示:

  • 如果變數是迴圈的 foreach 反覆專案變數,則變數的安全內容與迴圈表達式的安全內容 foreach 相同。
  • 否則,如果變數的宣告具有初始化表達式,則變數的安全內容與該初始化表達式的安全內容相同。
  • 否則,變數在宣告點未初始化,且具有呼叫端內容的安全內容。

參見§9.7.2.1及§9.7.2.2。

16.8.15.4 現場安全上下文

欄位 e.F 的參考,其中類型 F 是 ref 結構型別,具有與 e 相同的安全內容。

16.8.15.5 使用者

使用者自訂運算子的應用被視為方法調用(§16.8.15.6)。

對於產生值,例如 e1 + e2 或 c ? e1 : e2的運算符,結果的安全內容是運算符之安全內容中最窄的內容。 因此,對於產生值的一元運算符,例如 +e,結果的安全內容是操作數的安全內容。

注意:條件運算子的第一個運算元是 bool,因此其安全上下文為呼叫者上下文。 因此,所得的安全上下文是第二和第三個運算元中最狹窄的安全上下文。 結尾註記

16.8.15.6 方法與屬性調用

由方法調用 e1.M(e2, ...) 或屬性調用 e.P所產生的值,若 M() 不回傳ref-to-ref-struct,其安全上下文為以下最小上下文之一:

  • 呼叫端內容。
  • 當回傳為 ref struct時,所有參數表達式(包括接收者)所貢獻的安全上下文,排除對應 scoped 參數的參數及 out 參數。
  • 當回傳為 ref struct時,則所有參數(排除參數ref及參數scoped ref)貢獻的 ref-safe-contextout。

如果 M() 回傳 ref-to-ref-struct,則安全上下文與所有 ref-to-ref-struct 參數的安全上下文相同。 若存在多個此類參數且安全上下文不同,則為錯誤。

為了這些規則的目的,給定的參數 expr 傳遞給參數 p:

  1. 若 p , scoped ref則 expr 不提供參考安全上下文。
  2. 若 p , scoped則 expr 不提供安全上下文。
  3. 若 p , out則 expr 不貢獻 ref-safe-context 或 safe-context。

上述規則會將屬性調用 (或 getset) 視為基礎方法的方法調用。

範例:以下 scoped 說明如何影響方法回傳值的安全上下文:

ref struct RS
{
    public ref int RefField;
    public RS(ref int i) { RefField = ref i; }
}

class C
{
    static RS CreateAndCapture(ref int value)
    {
        // OK: ref-safe-context of `ref value` is caller-context,
        // safe-context contributed is caller-context.
        return new RS(ref value);
    }

    static RS CreateWithoutCapture(scoped ref int value)
    {
        // Error: `value` is scoped ref so it does not contribute
        // ref-safe-context. The constructor needs ref-safe-context
        // of caller-context but `value` only has function-member.
        return new RS(ref value);
    }
}

結束範例

16.8.15.7 方法參數必須相符

對於任意方法調用 e.M(a1, a2, ... aN):

  1. 計算最窄的安全情境如下:

    • 呼叫者-語境。
    • 所有論點的安全脈絡。
    • 所有參數對應參數為呼叫者上下文的 ref-safe-context ref 的參數。
  2. 所有 ref 型別的 ref struct 參數都應由具有該安全上下文的值指派。 在此規則中, ref不 推廣包含 in 和 out。

對於任意方法調用 e.M(a1, a2, ... aN):

  1. 計算最窄的安全情境如下:

    • 呼叫者-語境。
    • 所有論點的安全脈絡。
    • 所有 ref 參數非 scoped的參數的 ref-safe-context 。
  2. 所有 out 型別的 ref struct 參數都應由具有該安全上下文的值指派。

scoped 的存在使開發人員能夠通過將未傳回的參數標記為 scoped,從而減少此規則所引起的摩擦。 這會將上述兩種情況中的參數從(1)中移除,並提供給呼叫者更大的靈活性。

範例:以下說明方法-參數必須匹配規則如何防止安全上下文較窄的值被儲存在 ref 安全上下文較寬的參數中:

ref struct R { }

class C
{
    static void F0(ref R a, scoped ref R b) { }

    static void F1(ref R x, scoped R y)
    {
        // Error: The narrowest safe-context is function-member (from `y`)
        // but `x` is a ref argument of a ref struct type whose
        // safe-context is caller-context. It must be assignable by
        // a value with that narrowest safe-context, which fails.
        F0(ref x, ref y);
    }
}

結束範例

16.8.15.8 推斷宣告表達式的安全上下文

從 out 參數(M(x, out var y))或解構(var x, var y) = M()()中宣告變數的安全上下文是以下中最狹窄的:

  • 呼叫者-語境。
  • 如果 out 變數被標記 scoped為 ,則宣告區塊(即函式成員或更窄的範圍)。
  • 若 out 變數的型別為 ref struct,請考慮包含 invocation 的所有參數,包括接收者:
    • 任何參數對應參數不 out 為且安全上下文為僅返回或更寬的參數的安全語境。
    • 任何參數對應參數僅為返回或更寬的 ref-safe context 的參數,其 ref-safe-context 是 ref-safe-context。

範例:以下說明如何從呼叫的其他參數推斷宣告變數的安全 out 上下文:

ref struct RS
{
    public RS(ref int x) { }

    static void M0(RS input, out RS output) => output = input;

    static RS M1()
    {
        var i = 0;
        var rs1 = new RS(ref i);  // safe-context of rs1 is function-member
        M0(rs1, out var rs2);     // safe-context of rs2 is function-member
        return rs2;               // Error: rs2 cannot escape function-member
    }

    static void M2(RS rs1)
    {
        M0(rs1, out scoped var rs2); // scoped forces safe-context to
                                     // declaration-block
    }
}

在 M1中,的安全rs2上下文是呼叫者上下文中最狹窄的,而 的安全上下文rs1則是函數成員(function-member)。 因此 rs2 無法退還。 在 M2中, scoped 修飾符強制將 的安全 rs2 上下文強制為 宣告區塊。

結束範例

16.8.15.9 物件初始化器安全上下文

物件初始化運算式的安全上下文是以下中最狹窄的一種:

  1. 建構者召喚的安全上下文。
  2. 對於成員初始化索引器的參數,可以逃逸到接收端,這些參數的安全上下文與ref安全上下文。
  3. 在成員初始化器中指派給非唯讀設定器的 RHS 安全上下文,或在 ref 指派的情況下使用 ref-safe-context。

注意:另一種建模方式是將任何可指派給接收端的成員初始化器的參數視為建構子的參數。 結尾註記

範例:以下說明物件初始化器如何縮小結果值的安全上下文:

using System;

ref struct S
{
    public Span<int> Field;
    public S(ref int i) { }
}

class C
{
    static S Example()
    {
        Span<int> stackSpan = stackalloc int[42];
        int i = 0;

        // safe-context is narrowest of:
        //   constructor safe-context (caller-context) and
        //   RHS of Field assignment (stackSpan: function-member)
        // = function-member
        var x = new S(ref i) { Field = stackSpan };
        return x; // Error: x has safe-context of function-member
    }
}

結束範例

16.8.15.10 stackalloc

stackalloc 運算式的結果具有 function-member 的安全內容。

16.8.15.11 建造者召喚

new 調用建構函式的表達式會遵守與被視為傳回所建構之型別的方法調用相同的規則。

此外,安全環境是所有物件初始化表達式中各自的參數和運算元的最小安全環境,若有任一初始化表達式存在,則遞迴計算之。 詳情請參見 第16.8.15.9節 。