元組類型 (c # 參考)

在 c # 7.0 和更新版本中提供, 元組 功能提供簡潔的語法,以將輕量資料結構中的多個資料元素群組在一起。 下列範例會示範如何宣告元組變數、將它初始化,以及存取其資料成員:

(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.

如先前的範例所示,若要定義元組類型,請指定其所有資料成員的類型,並選擇性地指定 功能變數名稱。 您無法在元組類型中定義方法,但您可以使用 .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.

從 c # 7.3 開始,元組類型支援 等號比較運算子 ==!= 。 如需詳細資訊,請參閱 元組相等 區段。

元組類型為實 數值型別;元組元素為公用欄位。 這會讓元組 可變 的實值型別。

注意

元組功能需要 System.ValueTuple 類型和相關的泛型型別 (例如, System.ValueTuple<T1,T2>) ,可在 .net Core 和 .NET Framework 4.7 和更新版本中使用。 若要在以 .NET Framework 4.6.2 或更早版本為目標的專案中使用元組,請將 NuGet 封裝加入 System.ValueTuple 至專案。

您可以定義具有任意大量元素的元組:

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

元組的使用案例

元組最常見的其中一個使用案例是做為方法傳回型別。 也就是說,您可以將方法結果分組為元組傳回型別,而不是定義 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);
}

如先前的範例所示,您可以直接使用傳回的元組實例,或在不同的變數中 解構 它。

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

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

元組功能變數名稱

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

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}.");

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

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

這就是所謂的元組投影初始化運算式。 在下列情況中,不會將變數的名稱投射到元組功能變數名稱:

  • 候選名稱是元組類型的成員名稱,例如、 Item3 ToStringRest
  • 候選名稱是另一個元組功能變數名稱(明確或隱含)的複本。

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

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

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.

元組指派元組相等比較 不會將欄位名稱列入考慮。

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

元組指派和解構

C # 支援在符合下列兩個條件的元組類型之間進行指派:

  • 這兩個元組類型都有相同數目的元素
  • 針對每個元組位置,右邊元組專案的型別會與或隱含轉換成對應的左邊元組元素類型。

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

(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

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

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

    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.
    

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

元組相等

從 C# 7.3 開始,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

如先前的範例所示, ==!= 作業不會考慮元組功能變數名稱。

當滿足下列兩個條件時,可以比較兩個元組:

  • 這兩個元組都有相同數目的元素。 例如, t1 != t2 如果 t1t2 具有不同數目的元素,則不會編譯。
  • 針對每個元組位置,左側和右邊元組運算元中的對應元素可與 ==!= 運算子比較。 例如,不會進行 (1, (2, 3)) == ((1, 2), 3) 編譯,因為 1 無法比較 (1, 2)

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

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

元組作為 out 參數

通常,您會將具有 out 參數的方法重構為傳回元組的方法。 不過,在某些情況下, out 參數可以是元組類型。 下列範例顯示如何使用元組作為 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

元組與 System.Tuple

由型別所支援的 c # 元組, System.ValueTuple 與以類型表示的元組不同 System.Tuple 。 主要的差異如下:

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

C# 語言規格

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

另請參閱