Switch branches/tags
version-2.8.2 version-2.8.0 version-2.7.0-beta3 version-2.6.0-beta3 version-2.4.0 version-2.3.5 version-2.3.4 version-2.3.2 version-2.3.2-beta1 version-2.3.0-beta3 version-2.3.0-beta2 version-2.3.0-beta1 version-2.2.0 version-2.1.0 version-2.0.0 version-2.0.0-rc4 version-2.0.0-rc3 version-2.0.0-rc2 version-2.0.0-rc version-2.0.0-beta5 version-2.0.0-beta4 version-2.0.0-beta3 version-2.0.0-beta1 version-1.3.2 version-1.3.1 version-1.3.0 version-1.3.0-beta1-20160429-01 version-1.2.2 version-1.2.1 version-1.2.0 version-1.2.0-beta1-20160108-01 version-1.2.0-beta version-1.2.0-beta-20151211-01 version-1.1.1 version-1.1.0 version-1.1.0-rc1-20151109-01 version-1.0.0 version-1.0.0-beta1-20141031-01 toolset_5 toolset_3 toolset_2 toolset_1_1 toolset_1 Visual.Studio.2015.Update.1.RC Visual.Studio.2015.Update.1.CTP Visual-Studio-2017 Visual-Studio-2017-Version-15.7.2 Visual-Studio-2017-Version-15.7 Visual-Studio-2017-Version-15.6 Visual-Studio-2017-Version-15.5 Visual-Studio-2017-Version-15.4 Visual-Studio-2017-Version-15.3.5 Visual-Studio-2017-Version-15.3.4 Visual-Studio-2017-Version-15.3.2 Visual-Studio-2017-Version-15.3 Visual-Studio-2017-Version-15.2 Visual-Studio-2017-Version-15.1 Visual-Studio-2017-RC4 Visual-Studio-2017-RC3 Visual-Studio-2017-RC2 Visual-Studio-2017-RC Visual-Studio-2017-Preview-Version-15.3 Visual-Studio-2017-Preview-6-Version-15.7 Visual-Studio-2017-Preview-3-Version-15.4 Visual-Studio-2017-Preview-3-Version-15.3 Visual-Studio-2017-Preview-2-Version-15.4 Visual-Studio-2017-Preview-2-Version-15.3 Visual-Studio-2017-Preview-1-Version-15.4 Visual-Studio-2015 Visual-Studio-2015-Update-3 Visual-Studio-2015-Update-3-Micro-Update-1 Visual-Studio-2015-Update-2 Visual-Studio-2015-Update-2-RC Visual-Studio-2015-Update-2-Micro-Update-3 Visual-Studio-2015-Update-2-Micro-Update-1 Visual-Studio-2015-Update-1 Visual-Studio-2015-Update-1-RC Visual-Studio-2015-Update-1-CTP Visual-Studio-2015-RC Visual-Studio-2015-Preview Visual-Studio-2015-CTP-6 Visual-Studio-2015-CTP-5 Visual-Studio-15-Preview Visual-Studio-15-Preview-5 Visual-Studio-15-Preview-4 Visual-Studio-15-Preview-3 VS.Toolset.Roslyn.1.1.0-beta1-20150727-01 VS.Tools.X86.Managed.V45.1.0.150513.2 Oss.Scan.2015.03.13 Oss.Scan.2013.03.13 NetFx.Toolset.150729
Nothing to show
Find file Copy path
361 lines (265 sloc) 12.8 KB

Quickstart guide for tuples (C# 7.0 and Visual Basic 15)

  1. Install VS2017
  2. Start a C# or VB project
  3. Add a reference to the System.ValueTuple package from NuGet Install the ValueTuple package
  4. Use tuples in C#:
public class C
        public static (int code, string message) Method((int, string) x) 
                return x;

        public static void Main()
                var pair1 = (42, "hello");
                var pair2 = (code: 43, message: "world");
  1. Or use tuples in VB:
Public Class C
        Public Shared Function Method(x As (Integer, String)) As (code As Integer, message As String)
                Return x
        End Function

        Public Shared Sub Main()
                Dim x = (42, "hello")
                Dim pair2 = (code:=43, message:="world")
        End Sub
End Class
  1. Use deconstructions (C# only): see the deconstruction page

Without the System.ValueTuple package from NuGet, the compiler will produce an error: error CS8179: Predefined type 'System.ValueTuple`2' is not defined or imported


The goal of this document is capture what is being implemented. As design evolves, the document will undergo adjustments. Changes in design will be applied to this document as the changes are implemented.

Tuple types

Tuple types would be introduced with syntax very similar to a parameter list:

public (int sum, int count) Tally(IEnumerable<int> values) { ... }
var t = Tally(myValues);
Console.WriteLine($"Sum: {t.sum}, count: {t.count}");   

The syntax (int sum, int count) indicates an anonymous data structure with public fields of the given names and types, also referred to as tuple.

With no further syntax additions to C#, tuple values could be created as

var t1 = new (int sum, int count) (0, 1);
var t2 = new (int sum, int count) { sum = 0, count = 0 };
var t3 = new (int, int) (0, 1);     // field names are optional    

Note that specifying field names is optional, however when names are provided, all fields must be named. Duplicate names are disallowed.

Tuple literals

var t1 = (0, 2);				// infer tuple type from values
var t2 = (sum: 0, count: 1);	// infer tuple type from names and values

Creating a tuple value of a known target type:

public (int sum, int count) Tally(IEnumerable<int> values) 
    var s = 0; var c = 0;
    foreach (var value in values) { s += value; c++; }
    return (s, c); // target typed to (int sum, int count)

Note that specifying field names is optional, however when names are provided, all fields must be named. Duplicate names are disallowed.

var t1 = (sum: 0, 1);		// error! some fields are named some are not.
var t2 = (sum: 0, sum: 1);	// error! duplicate names.

Duality with underlying type

Tuples map to underlying types of particular names -

System.ValueTuple<T1, T2>
System.ValueTuple<T1, T2, T3>
System.ValueTuple<T1, T2, T3,..., T7, TRest>

In all scenarios tuple types behave exactly like underlying types with only additional optional enhancement of the more expressive field names given by the programmer.

var t = (sum: 0, count: 1);	
t.sum   = 1;				// sum   is the name for the field #1 
t.Item1 = 1;				// Item1 is the name of underlying field #1 and is also available

var t1 = (0, 1);			// tuple omits the field names.
t.Item1 = 1;				// underlying field name is still available 

t.ToString()				// ToString on the underlying tuple type is called.

System.ValueTuple<int, int> vt = t;	// identity conversion 
(int moo, int boo) t2 = vt;			// identity conversion

Because of the dual nature of tuples, it is not allowed to assign field names that overlap with preexisting member names of the underlying type. The only exception is the use of predefined "Item1", "Item2",..."ItemN" at corresponding position N, since that would not be ambiguous.

var t =  (ToString: 0, ObjectEquals: 1);		// error: names match underlying member names
var t1 = (Item1: 0, Item2: 1);					// valid
var t2 = (misc: 0, Item1: 1);					// error: "Item1" was used in a wrong position

Example of underlying tuple type implementation: To be replaced by the actual tuple implementation in FX Core.

Identity conversion

Element names are immaterial to tuple conversions. Tuples with the same types in the same order are identity convertible to each other or to and from corresponding underlying ValueTuple types, regardless of the names.

var t = (sum: 0, count: 1);	

System.ValueTuple<int, int> vt = t;  // identity conversion 
(int moo, int boo) t2 = vt;  		 // identity conversion

t2.moo = 1;

That said, if you have an element name at one position on one side of a conversion, and the same name at another position on the other side. That would be indication that the code almost certainly contains a bug:

(int sum, int count) moo ()
	return (count: 1, sum: 3); // warning!! 

Overloading, Overriding, Hiding

For the purpose of Overloading Overriding Hiding, tuples of the same types and lengths as well as their underlying ValueTuple types are considered equivalent. All other differences are immaterial.

When overriding a member it is permitted to use tuple types with same or different field names than in the base member.

A situation where same field names are used for non-matching fields between base and derived member signatures, a warning is reported by the compiler.

class Base 
	virtual void M1(ValueTuple<int, int> arg){...}
class Derived : Base
	override void M1((int c, int d) arg){...} // valid override, signatures are equivalent
class Derived2 : Derived 
	override void M1((int c1, int c) arg){...} // also valid, warning on possible misuse of name 'c' 

class InvalidOverloading 
	virtual void M1((int c, int d) arg){...}
	virtual void M1((int x, int y) arg){...}			// invalid overload, signatures are eqivalent
	virtual void M1(ValueTuple<int, int> arg){...}		// also invalid

Name erasure at runtime

Importantly, the tuple field names aren't part of the runtime representation of tuples, but are tracked only by the compiler.

As a result, the field names will not be available to a 3rd party observer of a tuple instance - such as reflection or dynamic code.

In alignment with the identity conversions, a boxed tuple does not retain the names of the fields and will unbox to any tuple type that has the same element types in the same order.

object o = (a: 1, b: 2);    		 // boxing conversion 
var t = ((int moo, int boo))o;		 // unboxing conversion

Target typing

A tuple literal is "target typed" when used in a context specifying a tuple type. What that means is that the tuple literal has a "conversion from expression" to any tuple type, as long as the element expressions of the tuple literal have an implicit conversion to the element types of the tuple type.

(string name, byte age) t = (null, 5); // Ok: the expressions null and 5 convert to string and byte

In cases where the tuple literal is not part of a conversion, a tuple is used by its "natural type", which means a tuple type where the element types are the types of the constituent expressions. Since not all expressions have types, not all tuple literals have a natural type either:

var t = ("John", 5);  						//   Ok: the type of t is (string, int)
var t = (null, 5);    						//   Error: tuple expression doesn't have a type because null does not have a type
((1,2, null), 5).ToString();    	    	//   Error: tuple expression doesn't have a type

ImmutableArray.Create((()=>1, 1));        	//   Error: tuple expression doesn't have a type because lambda does not have a type
ImmutableArray.Create(((Func<int>)(()=>1), 1)); //   ok

A tuple literal may include names, in which case they become part of the natural type:

var t = (name: "John", age: 5); // The type of t is (string name, int age)
t.age++;						// t has field named age.

A successful conversion from tuple expression to tuple type is classified as ImplictTuple conversion, unless tuple's natural type matches the target type exactly, in such case it is an Identity conversion.

void M1((int x, int y) arg){...};
void M1((object x, object y) arg){...};

M1((1, 2));   			// first overload is used. Identity conversion is better than implicit conversion. 
M1(("hi", "hello"));   // second overload is used. Implicit tuple conversion is better than no conversion. 

Target typing will "see through" nullable target types. A successfull conversion from tuple expression to a nullable tuple type is classified as ImplicitNullable conversion.

((int x, int y, int z)?, int t)? SpaceTime()
	return ((1,2,3), 7); 	// valid, implicit nullable conversion

Overload resolution and tuples with no natural types.

A situation may arise during overload resolution where multiple equally qualified candidates could be available due to a tuple argument without natural type being implicitly convertible to the corresponding parameters.

In such situations overload resolution employs exact match rule where arguments without natural types are recursively matched to the types of the corresponding parameters in terms of constituent structural elements.

Tuple expressions are no exception from this rule and the exact match rule is based on the natural types of the constituent tuple arguments.

The rule is mutually recursive with respect to other containing or contained expressions not in a possession of a natural type.

void M1((int x, Func<(int, int)>) arg){...};
void M1((int x, Func<(int, byte)>) arg){...};

M1((1, ()=>(2, 3)));         // the first overload is used due to "exact match" rule


Tuple types and expressions support a variety of conversions by "lifting" conversions of the elements into overal tuple conversion. For the classification purpose, all element conversions are considered recursively. For example: To have an implicit conversion, all element expressions/types must have implicit conversions to the corresponding element types.

Typele conversions are Standard Conversions and therefore can stack with user-defined operators to form user-defined conversions.

A tuple conversion can be classified as a valid instance conversion for an extension method invocation as long as all element conversions are applicable as instance conversions.

Language grammar changes

This is based on the ANTLR grammar from Lucian.

For tuple type declarations:

    : type_name
    | simple_type
    | nullable_type
    | tuple_type // new
    : '(' tuple_type_element_list ')'
    : tuple_type_element ',' tuple_type_element
    | tuple_type_element_list ',' tuple_type_element
    : type identifier?

For tuple literals:

    : boolean_literal
    | integer_literal
    | real_literal
    | character_literal
    | string_literal
    | null_literal
    | tuple_literal // new

    : '(' tuple_literal_element_list ')'

    : tuple_literal_element ',' tuple_literal_element
    | tuple_literal_element_list ',' tuple_literal_element

    : ( identifier ':' )? expression

Note that because it is not a constant expression, a tuple literal cannot be used as default value for an optional parameter.

Open issues:

  • Provide more details on semantics of tuple type declarations, both static (Type rules, constraints, all-or-none names, can't be used on right-hand-side of a 'is', ...) and dynamic (what does it do at runtime?).
  • Provide more details on semantics of tuple literals, both static (new kind of conversion from expression, new kind of conversion from type, all-or-none, scrambled names, underlying types, underlying names, listing the members of this type, what it means to access, ) and dynamic (what happens when you do this conversion?).
  • Exactly matching expression


A lot of details and motivation for the feature is given in Proposal: Language support for Tuples

C# Design Notes for Apr 6, 2016