> ## Documentation Index > Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt > Use this file to discover all available pages before exploring further. # C# Tuple A tuple in C# is a lightweight data structure that groups multiple, potentially heterogeneous, data elements into a single composite value. Modern C# primarily utilizes `System.ValueTuple`, a mutable value type introduced in C# 7.0, which provides concise language-level syntax for grouping variables without the overhead of defining a custom `class` or `struct`. ## `System.ValueTuple` vs. `System.Tuple` C# contains two distinct tuple implementations: * **`System.ValueTuple` (Modern C# 7.0+):** A `struct` (value type) that is allocated *inline*. It is allocated on the stack when used as a local variable, but on the heap when embedded as a field within a `class` or as an element in an array. It is mutable, exposes its elements as public fields, and supports language-level syntax for named elements. * **`System.Tuple` (Legacy C# 4.0):** A `class` (reference type) allocated on the heap. It is immutable, exposes its elements as read-only properties, and requires verbose instantiation via `Tuple.Create()`. Modern C# development almost exclusively uses `System.ValueTuple`. ## Syntax and Initialization The C# compiler provides built-in syntax for declaring and initializing `ValueTuple` instances using parentheses. ```csharp theme={"dark"} // 1. Unnamed Tuple: Elements are accessed via default field names (Item1, Item2) (int, string, bool) unnamed = (42, "System", true); int number = unnamed.Item1; // 2. Named Tuple: Elements are assigned explicit semantic names (int Id, string Status) named = (100, "Active"); string status = named.Status; // 3. Implicit Typing (var) with Named Elements var inferred = (X: 15.5, Y: 20.0); // 4. Projection Initializers: Names are inferred from existing variables int count = 5; string label = "Items"; var projected = (count, label); // Fields are automatically named 'count' and 'label' ``` ## Method Signatures Tuples can be declared as parameter types or return types in method signatures, utilizing the same parenthetical syntax. ```csharp theme={"dark"} public (int Code, string Message) ProcessData((string input, int retries) config) { return (200, "Success"); } ``` ## Deconstruction Tuple deconstruction extracts the elements of a tuple into distinct local variables in a single operation. This is handled by the compiler mapping the tuple fields to the declared variables based on their ordinal position. ```csharp theme={"dark"} var data = (Id: 1, Name: "Entity", IsValid: true); // Deconstructing into explicitly typed variables (int id, string name, bool isValid) = data; // Deconstructing into implicitly typed variables var (x, y, z) = data; // Discards (_): Ignoring specific elements during deconstruction var (identifier, _, _) = data; ``` ## Underlying Mechanics and Metadata The named elements in a `ValueTuple` are syntactic sugar. At the Common Language Runtime (CLR) level, a `ValueTuple` only possesses `Item1`, `Item2`, `Item3`, etc., fields. During the current compilation, the C# compiler tracks custom element names using its internal syntax tree and symbol table. For local variables, these names are entirely erased at runtime. However, when tuples are used in members (such as fields, properties, or method signatures), the compiler emits a `TupleElementNamesAttribute` into the Intermediate Language (IL) metadata. This attribute persists the names across assembly boundaries, allowing consuming code to read the custom names from the compiled assembly. Because names are not part of the underlying CLR type, tuples with identical arity and types but different element names are structurally compatible and can be assigned to one another. ```csharp theme={"dark"} (int A, int B) tuple1 = (1, 2); (int X, int Y) tuple2 = tuple1; // Valid: The CLR only sees (int, int) ``` ## Tuple Equality Starting with C# 7.3, tuples support the `==` and `!=` operators. The compiler evaluates tuple equality by performing a pairwise, short-circuiting comparison of each element in ordinal order. ```csharp theme={"dark"} var t1 = (A: 1, B: "Test"); var t2 = (X: 1, Y: "Test"); // Evaluates to true. Element names are ignored; underlying values and types are compared. bool isEqual = t1 == t2; ``` For equality to compile, both tuples must have the same number of elements (arity), and an applicable `==` operator must be defined between the two corresponding types of each element pair. ## Hashing and Composite Keys A critical architectural benefit of `System.ValueTuple` is its built-in, value-based implementation of `IEquatable` and `GetHashCode()`. The `GetHashCode()` method computes a combined hash code from all underlying elements. This deterministic, value-based hashing makes tuples ideal for use as composite keys in hash-based collections like `Dictionary` or `HashSet`, eliminating the need to define custom structures solely for key grouping. ```csharp theme={"dark"} var regionData = new Dictionary<(string Country, int Zone), string>(); regionData.Add(("US", 1), "North America - East"); // Successfully retrieves the value because the hash code and element values match string region = regionData[("US", 1)]; ```
Tired of Poor C# Skills? Fix That With Deep Grasping! Learn More