I decompiled some C# 7 libraries and saw ValueTuple
generics being used. What are ValueTuples
and why not Tuple
instead?
-
I think its referring to Dot NEt Tuple class. Could you please share a sample code. So that it would be easy to understand.– Ranadip DuttaCommented Dec 11, 2016 at 8:54
-
21@Ranadip Dutta: If you know what a tuple is, you don't need sample code to understand the question. The question itself is straightforward: what is ValueTuple and how does it differ from Tuple?– BoltClockCommented Dec 11, 2016 at 9:35
-
1@BoltClock: That is the reason I did not answer anything on that context. I know in c# , there is a Tuple class which I use pretty frequently and same class some times I call it in powershell also. Its a reference type. Now seeing the other answers I understood that there is a value type also which is known as Valuetuple. If there is a sample I would like to know the usage for the same.– Ranadip DuttaCommented Dec 11, 2016 at 9:56
-
2Why do you decompile these when the source code for Roslyn is available on github ?– Zein MakkiCommented Dec 11, 2016 at 11:35
-
1@user3185569 probably because F12 auto-decompiles things and its easier than jumping to GitHub– John ZabroskiCommented Oct 27, 2017 at 16:49
6 Answers
What are
ValueTuples
and why notTuple
instead?
A ValueTuple
is a struct which reflects a tuple, same as the original System.Tuple
class.
The main difference between Tuple
and ValueTuple
are:
System.ValueTuple
is a value type (struct), whileSystem.Tuple
is a reference type (class
). This is meaningful when talking about allocations and GC pressure.System.ValueTuple
isn't only astruct
, it's a mutable one, and one has to be careful when using them as such. Think what happens when a class holds aSystem.ValueTuple
as a field.System.ValueTuple
exposes its items via fields instead of properties.
Until C# 7, using tuples wasn't very convenient. Their field names are Item1
, Item2
, etc, and the language hadn't supplied syntax sugar for them like most other languages do (Python, Scala).
When the .NET language design team decided to incorporate tuples and add syntax sugar to them at the language level an important factor was performance. With ValueTuple
being a value type, you can avoid GC pressure when using them because (as an implementation detail) they'll be allocated on the stack.
Additionally, a struct
gets automatic (shallow) equality semantics by the runtime, where a class
doesn't. Although the design team made sure there will be an even more optimized equality for tuples, hence implemented a custom equality for it.
Here is a paragraph from the design notes of Tuples
:
Struct or Class:
As mentioned, I propose to make tuple types
structs
rather thanclasses
, so that no allocation penalty is associated with them. They should be as lightweight as possible.Arguably,
structs
can end up being more costly, because assignment copies a bigger value. So if they are assigned a lot more than they are created, thenstructs
would be a bad choice.In their very motivation, though, tuples are ephemeral. You would use them when the parts are more important than the whole. So the common pattern would be to construct, return and immediately deconstruct them. In this situation structs are clearly preferable.
Structs also have a number of other benefits, which will become obvious in the following.
Examples:
You can easily see that working with System.Tuple
becomes ambiguous very quickly. For example, say we have a method which calculates a sum and a count of a List<Int>
:
public Tuple<int, int> DoStuff(IEnumerable<int> values)
{
var sum = 0;
var count = 0;
foreach (var value in values) { sum += value; count++; }
return new Tuple(sum, count);
}
On the receiving end, we end up with:
Tuple<int, int> result = DoStuff(Enumerable.Range(0, 10));
// What is Item1 and what is Item2?
// Which one is the sum and which is the count?
Console.WriteLine(result.Item1);
Console.WriteLine(result.Item2);
The way you can deconstruct value tuples into named arguments is the real power of the feature:
public (int sum, int count) DoStuff(IEnumerable<int> values)
{
var res = (sum: 0, count: 0);
foreach (var value in values) { res.sum += value; res.count++; }
return res;
}
And on the receiving end:
var result = DoStuff(Enumerable.Range(0, 10));
Console.WriteLine($"Sum: {result.sum}, Count: {result.count}");
Or:
var (sum, count) = DoStuff(Enumerable.Range(0, 10));
Console.WriteLine($"Sum: {sum}, Count: {count}");
Compiler goodies:
If we look under the cover of our previous example, we can see exactly how the compiler is interpreting ValueTuple
when we ask it to deconstruct:
[return: TupleElementNames(new string[] {
"sum",
"count"
})]
public ValueTuple<int, int> DoStuff(IEnumerable<int> values)
{
ValueTuple<int, int> result;
result..ctor(0, 0);
foreach (int current in values)
{
result.Item1 += current;
result.Item2++;
}
return result;
}
public void Foo()
{
ValueTuple<int, int> expr_0E = this.DoStuff(Enumerable.Range(0, 10));
int item = expr_0E.Item1;
int arg_1A_0 = expr_0E.Item2;
}
Internally, the compiled code utilizes Item1
and Item2
, but all of this is abstracted away from us since we work with a decomposed tuple. A tuple with named arguments gets annotated with the TupleElementNamesAttribute
. If we use a single fresh variable instead of decomposing, we get:
public void Foo()
{
ValueTuple<int, int> valueTuple = this.DoStuff(Enumerable.Range(0, 10));
Console.WriteLine(string.Format("Sum: {0}, Count: {1})", valueTuple.Item1, valueTuple.Item2));
}
Note that the compiler still has to make some magic happen (via the attribute) when we debug our application, as it would be odd to see Item1
, Item2
.
-
3Note that you can also use the simpler (and in my opinion, preferable) syntax
var (sum, count) = DoStuff(Enumerable.Range(0, 10));
– Abion47Commented Dec 11, 2016 at 11:50 -
-
Also how do your points "it's a mutable struct" and "it exposes readonly fields" agree? Commented Dec 11, 2016 at 12:41
-
1@YuvalItzchakov Nothing happens. That syntax is merely shorthand for the syntax you provided. It makes no assumptions or limitations of the types of the tuple fields.– Abion47Commented Dec 11, 2016 at 22:10
-
3Some nits: "they'll be allocated on the stack" -- true only for local variables. No doubt you know this, but unfortunately, the way you've phrased this is likely to perpetuate the myth that value types always live in the stack. Commented Apr 23, 2017 at 22:13
The difference between Tuple
and ValueTuple
is that Tuple
is a reference type and ValueTuple
is a value type. The latter is desirable because changes to the language in C# 7 have tuples being used much more frequently, but allocating a new object on the heap for every tuple is a performance concern, particularly when it's unnecessary.
However, in C# 7, the idea is that you never have to explicitly use either type because of the syntax sugar being added for tuple use. For example, in C# 6, if you wanted to use a tuple to return a value, you would have to do the following:
public Tuple<string, int> GetValues()
{
// ...
return new Tuple(stringVal, intVal);
}
var value = GetValues();
string s = value.Item1;
However, in C# 7, you can use this:
public (string, int) GetValues()
{
// ...
return (stringVal, intVal);
}
var value = GetValues();
string s = value.Item1;
You can even go a step further and give the values names:
public (string S, int I) GetValues()
{
// ...
return (stringVal, intVal);
}
var value = GetValues();
string s = value.S;
... Or deconstruct the tuple entirely:
public (string S, int I) GetValues()
{
// ...
return (stringVal, intVal);
}
var (S, I) = GetValues();
string s = S;
Tuples weren't often used in C# pre-7 because they were cumbersome and verbose, and only really used in cases where building a data class/struct for just a single instance of work would be more trouble than it was worth. But in C# 7, tuples have language-level support now, so using them is much cleaner and more useful.
-
if you return
(string S, int I)
then it's no longerTuple
but instead aValueTuple
, which is a different thing. Say if you return a private field of a class, then Tuple(reference type) could be better from a performance perspective?– joeCommented Jan 13, 2021 at 1:36 -
@joe In the strictest sense, maybe, but you could use the same logic to never use a value type for anything and it's a micro-optimization at best. You lose out on the language support and helpful tools offered for
ValueTuple
in exchange for a handful of nanoseconds on the return time. On the other hand, you also lose at least that much time whenever you need to dereference (i.e. unbox) the values. And finally, if you are storing tuples as private class values, that's code smell to me. If you're storing bundles of data as class data, use a class/struct, not a tuple.– Abion47Commented Jan 13, 2021 at 7:39 -
I just feel the code smell when you return, say a "steady" ValueTuple<structA, structB> (might be a field of a class on heap), but you have to copy it every time it's assigned(see the accepted answer). You are probably right in terms of "handful" and the trade-offs.– joeCommented Jan 14, 2021 at 3:09
-
@joe If we're talking primitive value types like
int
,bool
, and even to a certain extentstring
, copying the value for the return is faster than wrapping it in a reference type and subsequently unwrapping it later. That's what you do anyway when you have a getter function or property that returns a class field of a primitive type. Returning aValueType
falls under the same category of performance, especially if the fields of the tuple are themselves primitive types.– Abion47Commented Jan 14, 2021 at 7:23
I looked at the source for both Tuple
and ValueTuple
. The difference is that Tuple
is a class
and ValueTuple
is a struct
that implements IEquatable
.
That means that Tuple == Tuple
will return false
if they are not the same instance, but ValueTuple == ValueTuple
will return true
if they are of the same type and Equals
returns true
for each of the values they contain.
-
-
5@BoltClock Your comment would be constructive if you were to elaborate Commented Dec 11, 2016 at 13:58
-
3Also, value types don't necessarily go on the stack. The difference is that the semantically represent the value, rather than a reference, whenever that variable is stored, which may or may not be the stack.– ServyCommented Dec 13, 2016 at 15:53
In addition to the comments above, one unfortunate gotcha of ValueTuple is that, as a value type, the named arguments get erased when compiled to IL, so they're not available for serialisation at runtime.
i.e. Your sweet named arguments will still end up as "Item1", "Item2", etc. when serialised via e.g. Json.NET.
-
6
Other answers forgot to mention important points.Instead of rephrasing, I'm gonna reference the XML documentation from source code:
The ValueTuple types (from arity 0 to 8) comprise the runtime implementation that underlies tuples in C# and struct tuples in F#.
Aside from created via language syntax, they are most easily created via the
ValueTuple.Create
factory methods.
The System.ValueTuple
types differ from the System.Tuple
types in that:
- they are structs rather than classes,
- they are mutable rather than readonly, and
- their members (such as Item1, Item2, etc) are fields rather than properties.
With introduction of this type and C# 7.0 compiler, you can easily write
(int, string) idAndName = (1, "John");
And return two values from a method:
private (int, string) GetIdAndName()
{
//.....
return (id, name);
}
Contrary to System.Tuple
you can update its members (Mutable) because they are public read-write Fields that can be given meaningful names:
(int id, string name) idAndName = (1, "John");
idAndName.name = "New Name";
-
1"Arity 0 to 8". Ah, I like the fact that they include a 0-tuple. It could be used as a kind of empty type, and will be allowed in generics when some type parameter is not needed, like in
class MyNonGenericType : MyGenericType<string, ValueTuple, int>
etc. Commented Dec 13, 2016 at 16:28
Late-joining to add a quick clarification on these two factoids:
- they are structs rather than classes
- they are mutable rather than readonly
One would think that changing value-tuples en-masse would be straightforward:
foreach (var x in listOfValueTuples) { x.Foo = 103; } // wont even compile because x is a value (struct) not a variable
var d = listOfValueTuples[0].Foo;
Someone might try to workaround this like so:
// initially *.Foo = 10 for all items
listOfValueTuples.Select(x => x.Foo = 103);
var d = listOfValueTuples[0].Foo; // 'd' should be 103 right? wrong! it is '10'
The reason for this quirky behavior is that the value-tuples are exactly value-based (structs) and thus the .Select(...) call works on cloned-structs rather than on the originals. To resolve this we must resort to:
// initially *.Foo = 10 for all items
listOfValueTuples = listOfValueTuples
.Select(x => {
x.Foo = 103;
return x;
})
.ToList();
var d = listOfValueTuples[0].Foo; // 'd' is now 103 indeed
Alternatively of course one might try the straightforward approach:
for (var i = 0; i < listOfValueTuples.Length; i++) {
listOfValueTuples[i].Foo = 103; //this works just fine
// another alternative approach:
//
// var x = listOfValueTuples[i];
// x.Foo = 103;
// listOfValueTuples[i] = x; //<-- vital for this alternative approach to work if you omit this changes wont be saved to the original list
}
var d = listOfValueTuples[0].Foo; // 'd' is now 103 indeed
Hope this helps someone struggling to make heads of tails out of list-hosted value-tuples.