C# 參考 (元組類型)

Tuple 功能提供簡潔的語法,將輕量型資料結構中的多個資料元素分組。 下列範例示範如何宣告 Tuple 變數、初始化它,以及存取其資料成員:

(double, int) t1 = (4.5, 3);
Console.WriteLine($"Tuple with elements {t1.Item1} and {t1.Item2}.");
// Output:
// Tuple with elements 4.5 and 3.

(double Sum, int Count) t2 = (4.5, 3);
Console.WriteLine($"Sum of {t2.Count} elements is {t2.Sum}.");
// Output:
// Sum of 3 elements is 4.5.

如上述範例所示,若要定義 Tuple 類型,您可以指定其所有資料成員的類型,以及選擇性地指定 功能變數名稱。 您無法在元組類型中定義方法,但您可以使用 .NET 所提供的方法,如下列範例所示:

(double, int) t = (4.5, 3);
Console.WriteLine(t.ToString());
Console.WriteLine($"Hash code of {t} is {t.GetHashCode()}.");
// Output:
// (4.5, 3)
// Hash code of (4.5, 3) is 718460086.

Tuple 類型支援相等運算子==!= 。 如需詳細資訊,請參閱 Tuple 相等一 節。

Tuple 類型為 實值型別;Tuple 元素是公用欄位。 這可讓 Tuple 成為可變 實值型別。

注意

Tuple 功能需要 System.ValueTuple 型別和相關泛型型別 (例如, System.ValueTuple<T1,T2>) ,這些類型適用于 .NET Core 和 .NET Framework 4.7 和更新版本。 若要在以 .NET Framework 4.6.2 或更早版本為目標的專案中使用 Tuple,請將 NuGet 套件 System.ValueTuple 新增至專案。

您可以使用任意大量元素來定義 Tuple:

var t = 
(1, 2, 3, 4, 5, 6, 7, 8, 9, 10,
11, 12, 13, 14, 15, 16, 17, 18,
19, 20, 21, 22, 23, 24, 25, 26);
Console.WriteLine(t.Item26);  // output: 26

元組的使用案例

元組最常見的其中一個使用案例是做為方法傳回型別。 也就是說,您可以分組方法產生 Tuple 傳回型別,而不是定義out 方法參數,如下列範例所示:

var xs = new[] { 4, 7, 9 };
var limits = FindMinMax(xs);
Console.WriteLine($"Limits of [{string.Join(" ", xs)}] are {limits.min} and {limits.max}");
// Output:
// Limits of [4 7 9] are 4 and 9

var ys = new[] { -9, 0, 67, 100 };
var (minimum, maximum) = FindMinMax(ys);
Console.WriteLine($"Limits of [{string.Join(" ", ys)}] are {minimum} and {maximum}");
// Output:
// Limits of [-9 0 67 100] are -9 and 100

(int min, int max) FindMinMax(int[] input)
{
    if (input is null || input.Length == 0)
    {
        throw new ArgumentException("Cannot find minimum and maximum of a null or empty array.");
    }

    var min = int.MaxValue;
    var max = int.MinValue;
    foreach (var i in input)
    {
        if (i < min)
        {
            min = i;
        }
        if (i > max)
        {
            max = i;
        }
    }
    return (min, max);
}

如上述範例所示,您可以直接使用傳回的 Tuple 實例,或在個別變數中 解構 它。

您也可以使用 Tuple 類型,而不是 匿名型別;例如,在 LINQ 查詢中。 如需詳細資訊,請參閱 選擇匿名和 Tuple 類型

一般而言,您會使用 Tuple 來分組鬆散相關的資料元素。 這通常適用于私人和內部公用程式方法。 在公用 API 的情況下,請考慮定義 類別結構 類型。

Tuple 功能變數名稱

您可以在 Tuple 初始化運算式或 Tuple 類型的定義中明確指定 Tuple 欄位的名稱,如下列範例所示:

var t = (Sum: 4.5, Count: 3);
Console.WriteLine($"Sum of {t.Count} elements is {t.Sum}.");

(double Sum, int Count) d = (4.5, 3);
Console.WriteLine($"Sum of {d.Count} elements is {d.Sum}.");

如果您未指定功能變數名稱,可能會從 Tuple 初始化運算式中對應的變數名稱推斷,如下列範例所示:

var sum = 4.5;
var count = 3;
var t = (sum, count);
Console.WriteLine($"Sum of {t.count} elements is {t.sum}.");

這稱為元組投影初始化運算式。 在下列情況下,變數的名稱不會投影到 Tuple 功能變數名稱上:

  • 候選名稱是元組類型的成員名稱,例如 、 Item3ToStringRest
  • 候選名稱是另一個元組功能變數名稱的重複專案,可以是明確或隱含的。

在這些情況下,您可以明確指定功能變數名稱,或依預設名稱存取欄位。

元組欄位的預設名稱為 Item1Item2Item3 等等。 您一律可以使用欄位的預設名稱,即使明確或推斷功能變數名稱,如下列範例所示:

var a = 1;
var t = (a, b: 2, 3);
Console.WriteLine($"The 1st element is {t.Item1} (same as {t.a}).");
Console.WriteLine($"The 2nd element is {t.Item2} (same as {t.b}).");
Console.WriteLine($"The 3rd element is {t.Item3}.");
// Output:
// The 1st element is 1 (same as 1).
// The 2nd element is 2 (same as 2).
// The 3rd element is 3.

Tuple 指派Tuple 相等比較 不會考慮功能變數名稱。

在編譯時期,編譯器會以對應的預設名稱取代非預設功能變數名稱。 因此,在執行時間無法使用明確指定或推斷的功能變數名稱。

提示

啟用 .NET 程式碼樣式規則 IDE0037 ,以設定推斷或明確 Tuple 功能變數名稱的喜好設定。

Tuple 指派和解構

C# 支援在滿足下列兩個條件的元組類型之間指派:

  • 這兩個 Tuple 類型都有相同的元素數目
  • 針對每個 Tuple 位置,右側 Tuple 元素的類型與對應左側 Tuple 元素的類型相同或隱含可轉換成對應的左元組元素類型

Tuple 元素值會依 Tuple 元素的順序指派。 元組欄位的名稱會被忽略且未指派,如下列範例所示:

(int, double) t1 = (17, 3.14);
(double First, double Second) t2 = (0.0, 1.0);
t2 = t1;
Console.WriteLine($"{nameof(t2)}: {t2.First} and {t2.Second}");
// Output:
// t2: 17 and 3.14

(double A, double B) t3 = (2.0, 3.0);
t3 = t2;
Console.WriteLine($"{nameof(t3)}: {t3.A} and {t3.B}");
// Output:
// t3: 17 and 3.14

您也可以使用指派運算子 = ,在不同的變數中 解構 Tuple 實例。 您可以透過下列其中一種方式來執行此動作:

  • 在括弧內明確宣告每個變數的類型:

    var t = ("post office", 3.6);
    (string destination, double distance) = t;
    Console.WriteLine($"Distance to {destination} is {distance} kilometers.");
    // Output:
    // Distance to post office is 3.6 kilometers.
    
  • var使用括弧外的 關鍵字來宣告隱含類型變數,並讓編譯器推斷其類型:

    var t = ("post office", 3.6);
    var (destination, distance) = t;
    Console.WriteLine($"Distance to {destination} is {distance} kilometers.");
    // Output:
    // Distance to post office is 3.6 kilometers.
    
  • 使用現有的變數:

    var destination = string.Empty;
    var distance = 0.0;
    
    var t = ("post office", 3.6);
    (destination, distance) = t;
    Console.WriteLine($"Distance to {destination} is {distance} kilometers.");
    // Output:
    // Distance to post office is 3.6 kilometers.
    

如需解構 Tuple 和其他類型的詳細資訊,請參閱 解構 Tuple 和其他類型

Tuple 相等

Tuple 類型支援 ==!= 運算子。 這些運算子會比較左側運算元的成員與右運算元的對應成員,並遵循 Tuple 元素的順序。

(int a, byte b) left = (5, 10);
(long a, int b) right = (5, 10);
Console.WriteLine(left == right);  // output: True
Console.WriteLine(left != right);  // output: False

var t1 = (A: 5, B: 10);
var t2 = (B: 5, A: 10);
Console.WriteLine(t1 == t2);  // output: True
Console.WriteLine(t1 != t2);  // output: False

如上述範例所示, ==!= 作業不會考慮 Tuple 功能變數名稱。

滿足下列兩個條件時,兩個 Tuple 會比較:

  • 這兩個元組都有相同的元素數目。 例如,如果 t1t2 具有不同的專案數目, t1 != t2 則不會進行編譯。
  • 對於每個 Tuple 位置,來自左側和右手 Tuple 運算元的對應元素會與 ==!= 運算子相比較。 例如,不會編譯, (1, (2, 3)) == ((1, 2), 3) 因為 1 與 不相等 (1, 2)

!= 運算子會 == 以簡短方式比較 Tuple。 也就是說,一旦作業符合一對不相等的專案或到達 Tuple 的結尾,作業就會停止。 不過,在進行任何比較之前, 會評估所有 Tuple 元素,如下列範例所示:

Console.WriteLine((Display(1), Display(2)) == (Display(3), Display(4)));

int Display(int s)
{
    Console.WriteLine(s);
    return s;
}
// Output:
// 1
// 2
// 3
// 4
// False

Tuple 作為 out 參數

一般而言,您會將具有out 參數的方法重構為傳回 Tuple 的方法。 不過,在某些情況下, out 參數可以是 Tuple 類型。 下列範例示範如何使用 Tuple 作為 out 參數:

var limitsLookup = new Dictionary<int, (int Min, int Max)>()
{
    [2] = (4, 10),
    [4] = (10, 20),
    [6] = (0, 23)
};

if (limitsLookup.TryGetValue(4, out (int Min, int Max) limits))
{
    Console.WriteLine($"Found limits: min is {limits.Min}, max is {limits.Max}");
}
// Output:
// Found limits: min is 10, max is 20

Tuple 與 System.Tuple

由型別支援的 System.ValueTuple C# Tuple 與型別所 System.Tuple 代表的 Tuple 不同。 主要差異如下:

  • System.ValueTuple 類型是 實值型別System.Tuple 類型是 參考型別
  • System.ValueTuple 類型是可變的。 System.Tuple 類型不可變。
  • 類型的資料成員 System.ValueTuple 是欄位。 類型的資料成員 System.Tuple 是屬性。

C# 語言規格

如需詳細資訊,請參閱下列功能提案附注:

另請參閱