使用 集合表達式 來建立共同的集合值。
集合式是一種簡潔的語法,你可以指派給許多不同的集合類型。 集合運算式包含 [ 和 ] 方括弧之間的元素序列。
C# 語言參考資料記錄了 C# 語言最新版本。 同時也包含即將推出語言版本公開預覽功能的初步文件。
文件中標示了語言最近三個版本或目前公開預覽版中首次引入的任何功能。
小提示
欲查詢某功能何時首次在 C# 中引入,請參閱 C# 語言版本歷史的條目。
下列範例會宣告 System.Span<T> 元素的 string,並將其初始化為一週的日子:
Span<string> weekDays = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
foreach (var day in weekDays)
{
Console.WriteLine(day);
}
你可以將 集合表達 式轉換成多種不同的集合類型。 第一個範例展示了如何使用集合表達式來初始化變數。 下列程式碼顯示您可以使用集合運算式的其他許多位置:
// Initialize private field:
private static readonly ImmutableArray<string> _months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
// property with expression body:
public IEnumerable<int> MaxDays =>
[31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
public int Sum(IEnumerable<int> values) =>
values.Sum();
public void Example()
{
// As a parameter:
int sum = Sum([1, 2, 3, 4, 5]);
}
你不能使用預期編譯時常數的集合表達式,例如初始化常數時,或作為方法參數的預設值。
上述兩個範例都使用常數作為集合運算式的元素。 你也可以用變數來表示元素,如下範例所示:
string hydrogen = "H";
string helium = "He";
string lithium = "Li";
string beryllium = "Be";
string boron = "B";
string carbon = "C";
string nitrogen = "N";
string oxygen = "O";
string fluorine = "F";
string neon = "Ne";
string[] elements = [hydrogen, helium, lithium, beryllium, boron, carbon, nitrogen, oxygen, fluorine, neon];
foreach (var element in elements)
{
Console.WriteLine(element);
}
Spread 元素
使用 擴散元素.. 將集合數值內嵌在集合表達式中。 以下範例透過組合母音集合、子音集合和字母 "y" 來建立完整字母表的集合,而字母 "y" 可以是:
string[] vowels = ["a", "e", "i", "o", "u"];
string[] consonants = ["b", "c", "d", "f", "g", "h", "j", "k", "l", "m",
"n", "p", "q", "r", "s", "t", "v", "w", "x", "z"];
string[] alphabet = [.. vowels, .. consonants, "y"];
評估時,spread 元素 ..vowels 會產生五個元素:"a"、"e"、"i"、"o" 和 "u"。 spread 元素 ..consonants 會產生 20 個元素,也就是 consonants 陣列中的數字。 展開元素中的表達式必須透過陳述 foreach 來枚舉。 如上一個範例所示,您可以將 spread 元素與集合運算式中的個別元素結合。
轉換
你可以將 集合表達 式轉換成不同的集合類型,包括:
- System.Span<T> 和 System.ReadOnlySpan<T>。
-
陣列,例如
int[]或string[]。 - 具有參數型別為 的
ReadOnlySpan<T>方法的任何型別,其中存在從集合運算式型別到T的隱含轉換。 - 支援集合初始設定式的任何型別,例如 System.Collections.Generic.List<T>。 此需求通常表示型別支援 System.Collections.Generic.IEnumerable<T>,而且有一個可存取的
Add方法可將項目新增至集合。 必須有一個從集合運算式元素型別到集合元素型別的隱含轉換。 對於 spread 元素,必須有一個從 spread 元素型別轉換成集合元素型別的隱含轉換。 - 下列任何介面:
備註
你不能用集合式來初始化 內嵌陣列。 內嵌陣列需要不同的初始化語法。
重要
集合運算式一律會建立包含集合運算式中所有元素的集合,不論轉換的目標類型為何。 例如,當轉換的目標為 System.Collections.Generic.IEnumerable<T> 時,產生的程式碼會評估集合運算式,並將結果儲存在記憶體內部集合中。
此行為與 LINQ 不同,在列舉序列之前,可能不會具現化序列。 您無法使用集合運算式來產生不會列舉的無限序列。
編譯器會使用靜態分析以確定最佳效能方法,以使用集合運算式建立宣告的集合。 例如,如果初始化後不修改目標,則空集合運算式 [] 可以實現為 Array.Empty<T>()。 當目標為 System.Span<T> 或 System.ReadOnlySpan<T> 時,儲存體可能會配置堆疊。 C# 標準中的 §12.8.25 集合表達式 條款規定編譯器必須遵循的規則。
許多 API 會以多個集合型別作為參數來多載。 因為集合運算式可以轉換成許多不同的運算式類型,因此這些 API 可能需要在集合運算式上轉換,以指定正確的轉換。 下列轉換規則可解決一些模棱兩可的情況:
- 較佳的項目轉換優先於較佳的集合類型轉換。 換句話說,集合表達式中的項目類型比集合類型更重要。 這些規則在 C# 語言規範中較 佳的從表達式子 句轉換中描述。
- 轉換為 Span<T>、ReadOnlySpan<T> 或其他
ref struct型別優於轉換為非 ref 結構型別。 - 轉換為非介面型別優於轉換為介面型別。
當你將集合表達式轉換成 Span 或 ReadOnlySpan時,span 物件的安全 上下文 來自於該 span 中所有元素的安全 上下文 。 詳細規則請參閱 C# 標準中的第 9.7.2 節 Ref 安全上下文 。
集合建立器
集合表達式適用於任何行為 良好的集合類型。 表現良好的關聯具有下列特性:
- 在可數集合上的 或
CountLength值與你列舉集合時的元素數值相同。 - 命名空間中的 System.Collections.Generic 型別是無副作用的。 編譯器會優化這些類型可能作為中介值的情境,但不會以其他方式暴露它們。
- 呼叫集合上的適用
.AddRange(x)成員,最終值與使用x反覆迭代並逐個加入所有列舉值到集合.Add中時,得到相同的最終值。
.NET 執行階段中的所有集合類型都表現良好。
警告
如果自訂的集合類型行為不佳,當你使用該集合類型搭配集合表達式時,行為是未定義的。
你的類型選擇支援集合表達式,方法是寫一個 Create() 方法,並在集合類型上套用 System.Runtime.CompilerServices.CollectionBuilderAttribute 屬性來指示建構方法。 例如,請考慮使用 80 個字元的固定長度緩衝區的應用程式。 該類別看起來類似下列程式碼:
public class LineBuffer : IEnumerable<char>
{
private readonly char[] _buffer;
private readonly int _count;
public LineBuffer(ReadOnlySpan<char> buffer)
{
_buffer = new char[buffer.Length];
_count = buffer.Length;
for (int i = 0; i < _count; i++)
{
_buffer[i] = buffer[i];
}
}
public int Count => _count;
public char this[int index]
{
get
{
if (index >= _count)
throw new IndexOutOfRangeException();
return _buffer[index];
}
}
public IEnumerator<char> GetEnumerator()
{
for (int i = 0; i < _count; i++)
{
yield return _buffer[i];
}
}
IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
// etc
}
你想用它搭配集合式,如以下範例所示:
LineBuffer line = ['H', 'e', 'l', 'l', 'o', ' ', 'W', 'o', 'r', 'l', 'd', '!'];
LineBuffer 型別會實作 IEnumerable<char>,因此編譯器會將它辨識為 char 項目的集合。 實作的 System.Collections.Generic.IEnumerable<T> 介面的型別參數表示元素型別。 您必須將兩個新增項目新增至應用程式,才能將集合運算式指派給 LineBuffer 物件。 首先,您必須建立包含 Create 方法的類別:
internal static class LineBufferBuilder
{
internal static LineBuffer Create(ReadOnlySpan<char> values) => new LineBuffer(values);
}
該 Create 方法必須回傳一個 LineBuffer 物件,並且必須取一個型別 ReadOnlySpan<char>為 的最後參數。
ReadOnlySpan 的型別參數必須符合集合的元素類型。 回傳泛型集合的建構方法參數為泛型集合 ReadOnlySpan<T> 。 方法必須可存取與static。
從 C# 15 開始, Create 方法可以在參數前 ReadOnlySpan<T> 加上額外參數。 你可以透過集合表達式中的元素 with(...) ,將值傳遞給這些參數。 詳情請參閱 收藏建構器論點 。
最後,您必須將 CollectionBuilderAttribute 新增至 LineBuffer 類別宣告:
[CollectionBuilder(typeof(LineBufferBuilder), "Create")]
第一個參數會提供 Builder 類別的名稱。 第二個屬性會提供建立器方法的名稱。
集合式參數
從 C# 15 開始,你可以將參數傳給底層集合的建構子或工廠方法,方法是將 with(...) 元素作為集合表達式的第一個元素。 此功能允許您直接在集合表達式語法中指定容量、比較器或其他建構參數。 欲了解更多資訊,請參閱 集合式參數功能規範。
元素 with(...) 必須是集合表達式的第一個元素。 元素中 with(...) 宣告的參數會根據目標型別,導向適當的建構子或建立方法。 你可以使用元素中 with 參數的任何有效表達式。
參數表達式與元素表達式依左至右順序評估一次,參數 with(...) 在集合元素之前評估。 對於像 .. GetItems()這樣的擴散,評估呼叫 GetItems() 以獲得擴散的集合。 列舉是獨立步驟,讀取該集合中的項目並將其加入結果。 編譯器在從左到右的位置進行 GetItems() 列舉,但可以延遲列舉,直到評估後續元素表達式後再進行。 不要依賴列舉的副作用會先於那些後續表達式發生。
建構子參數
當目標型別是實 System.Collections.IEnumerable作 的類別或結構體時,會評估 中的 with(...) 參數,結果會送達建構子。 編譯器會利用超載解析來選擇最匹配的建構子:
public void CollectionArgumentsExamples()
{
string[] values = ["one", "two", "three"];
// Pass capacity argument to List<T> constructor
List<string> names = [with(capacity: values.Length * 2), .. values];
// Pass comparer argument to HashSet<T> constructor
HashSet<string> set = [with(StringComparer.OrdinalIgnoreCase), "Hello", "HELLO", "hello"];
// set contains only one element because all strings are equal with OrdinalIgnoreCase
// Pass capacity to IList<T> (uses List<T> constructor)
IList<int> numbers = [with(capacity: 100), 1, 2, 3];
}
在前述範例中:
-
List<string>參數為capacity的建構子會被呼叫為values.Length * 2。 - 帶有參數的
HashSet<string>構造子會被呼叫為StringComparer.OrdinalIgnoreCase。System.Collections.Generic.IEqualityComparer<T> - 對於像 System.Collections.Generic.IList<T>這樣的介面目標類型,編譯器會建立具有指定容量的 。
List<T>
對於以此方式構造的目標型別, with(...) 若該型別沒有可達的無參數建構子,則 是必須的。 用它來提供可存取的建構子參數。 例如,需要 NamedValues 一個名稱,並繼承了 的 List<int>集合行為:
public class NamedValues(string name) : List<int>
{
public string Name { get; } = name;
}
此集合表達式提供所需的名稱,然後加入以下元素:
NamedValues readings = [with("temperature"), 18, 21, 24];
Console.WriteLine($"{readings.Name}: {string.Join(", ", readings)}");
// output: temperature: 18, 21, 24
集合建構者論元
對於具有 的System.Runtime.CompilerServices.CollectionBuilderAttribute型別,元素with(...)會評估宣告的參數,並將結果先傳送到參數前ReadOnlySpan<T>的 create 方法。 此功能允許建立方法接受組態參數:
internal static class MySetBuilder
{
internal static MySet<T> Create<T>(ReadOnlySpan<T> items) => new MySet<T>(items);
internal static MySet<T> Create<T>(IEqualityComparer<T> comparer, ReadOnlySpan<T> items) =>
new MySet<T>(items, comparer);
}
使用該 with(...) 元素傳遞比較器:
public void CollectionBuilderArgumentsExample()
{
// Pass comparer to a type with CollectionBuilder attribute
// The comparer argument is passed before the ReadOnlySpan<T> parameter
MySet<string> mySet = [with(StringComparer.OrdinalIgnoreCase), "A", "a", "B"];
// mySet contains only two elements: "A" and "B"
}
超載解析會根據你提供的參數選擇建立方法。 包含集合元素的 總是 ReadOnlySpan<T> 最後一個參數。
介面目標類型
多種介面目標類型支援集合表達式參數。 下表顯示支援的介面及其適用的建構函式簽名:
| 介面 | 支援 with 元素 |
|---|---|
| IEnumerable<T>、IReadOnlyCollection<T>、IReadOnlyList<T> |
() (僅空) |
| ICollection<T>、IList<T> |
()、(int capacity) |
對於 IList<T> 和 ICollection<T>,編譯器使用 System.Collections.Generic.List<T> a 並使用指定的構造子。
限制
該 with(...) 元素有以下限制:
- 它必須是集合式的第一個元素。
- 論點不能有
dynamic類型。 - 不支援陣列或區間類型(
Span<T>,ReadOnlySpan<T>)。 - 這些
with(...)參數不會影響集合表達式是否存在從集合表達式轉換到候選目標型別的轉換。 對於封函呼叫的超載解析與型別推論,則忽略這些參數。 只有元素的with(...)存在,而非其論元,才會影響該轉換的存在。 一旦目標型別確定,參數會參與其建構子或集合建構方法的超載解析。
例如,比較器參數不會告訴編譯器在超載上List<string>選擇HashSet<string>過載:
class Examples
{
static void Print(List<string> values) { }
static void Print(HashSet<string> values) { }
static void Example()
{
Print([with(StringComparer.OrdinalIgnoreCase), "one", "ONE"]);
}
}
呼叫產生 CS0121:「呼叫在以下方法或性質間存在歧義。」雖然只有HashSet<string>一個構造子接受此比較器,編譯器在選擇Print超載時會忽略這些with(...)參數。 先將集合運算式指派給變 HashSet<string> 數以選擇該超載。
同樣地, with(...) 參數不會提供一般類型推論的元素類型:
class Examples
{
static void Use<T>(List<T> values) { }
static void Example()
{
Use([with(10)]);
}
}
此呼叫產生 CS0411:「型別參數無法從使用中推斷。 試著明確指定型別參數。」容量論證無法決定 T,且集合中沒有可推斷的元素。 指定型別參數,例如 Use<int>([with(10)])。