ValueTuple ExamplesUse the ValueTuple type from System.ValueTuple. Call the ToTuple method.
This page was last reviewed on Mar 23, 2022.
ValueTuple. Consider the Tuple class: its syntax is hard to type and remember. We must specify its items types. What if we could remove this complexity for clearer C# programs?
And what if we could optimize tuples to avoid allocations? With ValueTuple, from the package System.ValueTuple, we can use optimized tuples.
System.ValueTuple. With a ValueTuple, we can use a simpler syntax form to create and handle tuples. Add the System.ValueTuple package to your program (it is a NuGet package).
Here We create a 3-item ValueTuple. It is the same as a Tuple of the specified items, except it has simpler syntax and a ToTuple method.
using System; class Program { static void Main() { // Make sure System.ValueTuple is referenced in the project. // ... Create 3-item ValueTuple. var data = (10, "bird", 1.5); // Test an item. if (data.Item1 == 10) { Console.WriteLine(data); } } }
(10, bird, 1.5)
ToTuple. Here we use the ToTuple method on the ValueTuple. Make sure you add the System.ValueTuple package. We can convert a ValueTuple to a Tuple.
using System; class Program { static void Main() { // Create a ValueTuple. var unit = (10, 20, 'X'); // Convert to a Tuple. Tuple<int, int, char> tuple = unit.ToTuple(); Console.WriteLine(unit.GetType()); Console.WriteLine(unit); Console.WriteLine(tuple.GetType()); Console.WriteLine(tuple); } }
System.ValueTuple`3[System.Int32,System.Int32,System.Char] (10, 20, X) System.Tuple`3[System.Int32,System.Int32,System.Char] (10, 20, X)
ValueTuple, names. With the ValueTuple syntax we can improve the readability of code that uses tuples. We do not need to use Item1, Item2 syntax—we can access items by a label or name.
using System; class Program { static void Main() { // Create a ValueTuple with names. var result = (count: 10, animal: "scorpion"); // Access items by their names. Console.WriteLine(result.count); Console.WriteLine(result.animal); } }
10 scorpion
ValueTuple, deconstruction. With a ValueTuple, we can "deconstruct" a return value from a method. Consider this example. CatInfo returns a 2-item ValueTuple.
And We then deconstruct the returned tuple in the Main method. We can access the cat's size and name directly.
using System; class Program { static (int, string) CatInfo() { // Return a ValueTuple with an int and string. return (10, "Mittens"); } static void Main() { // Deconstruct the ValueTuple. var (size, name) = CatInfo(); // Display the values. Console.WriteLine($"Cat size = {size}; name = {name}"); } }
Cat size = 10; name = Mittens
ValueTuple, type error. To use a ValueTuple, you may need to add a package from NuGet in Visual Studio. In Visual Studio, use "Manage NuGet Packages" and search for "ValueType."
class Program { static void Main() { // Make sure System.ValueTuple is imported. var unit = ("bird", "blue", 5); } }
Error CS8179 Predefined type 'System.ValueTuple`3' is not defined or imported
Benchmark, ValueTuple. With a Tuple, we must allocate a class instance. But with ValueTuple, the Framework uses dynamic types to reduce overhead.
Here Method1 and Method2 both return a 2-item result. Method1 uses Tuple, and Method2 use a value tuple.
Result The new ValueTuple is faster. With ValueTuple we have both simpler syntax and improved performance.
using System; using System.Diagnostics; class Program { static Tuple<int, string> Method1() { return new Tuple<int, string>(10, "bird"); } static (int, string) Method2() { return (10, "bird"); } static void Main() { const int _max = 1000000; // Version 1: use Tuple class. var s1 = Stopwatch.StartNew(); for (int i = 0; i < _max; i++) { var result = Method1(); if (result.Item1 != 10) { return; } } s1.Stop(); // Version 2: use ValueTuple. var s2 = Stopwatch.StartNew(); for (int i = 0; i < _max; i++) { var result = Method2(); if (result.Item1 != 10) { return; } } s2.Stop(); Console.WriteLine(s1.Elapsed.TotalMilliseconds); Console.WriteLine(s2.Elapsed.TotalMilliseconds); } }
4.8384 Return Tuple 0.2571 Return ValueTuple
A summary. The standard Tuple class is still a useful class. But ValueTuple has advantages that are clear. It can be used to optimize return statements from methods.
Dot Net Perls is a collection of tested code examples. Pages are continually updated to stay current, with code correctness a top priority.
Sam Allen is passionate about computer languages. In the past, his work has been recommended by Apple and Microsoft and he has studied computers at a selective university in the United States.
This page was last updated on Mar 23, 2022 (grammar).
© 2007-2023 Sam Allen.