Home
Map
Tuple ExamplesCreate tuples to store immutable data. A tuple has multiple fields of different types.
C#
This page was last reviewed on Apr 20, 2023.
Tuple. In a C# program, we store things (like strings or ints) together. A name might be associated with an index. Tuples help us keep our logic clear and simple.
Shows an array
Tuple details. In .NET we have 2 kinds of tuples—the regular tuple and the ValueTuple which uses a more modern syntax. Both tuple types work well.
3 items. Consider that the Tuple type is a class. Once we create the Tuple, we cannot change the values of its fields. This makes the Tuple more like a string.
Part 1 Here we create a 3-item tuple using the special Tuple constructor syntax.
Part 2 We read the Item1, Item2 and Item3 properties and test them in if-statements. We do not modify them.
Important When we create a Tuple, we specify the order and types of the fields. Try changing the types, and the number of types.
using System; // Part 1: create three-item tuple. Tuple<int, string, bool> tuple = new Tuple<int, string, bool>(1, "cat", true); // Part 2: access tuple properties. if (tuple.Item1 == 1) { Console.WriteLine(tuple.Item1); } if (tuple.Item2 == "dog") { Console.WriteLine(tuple.Item2); } if (tuple.Item3) { Console.WriteLine(tuple.Item3); }
1 True
4 items. Continuing on, a Tuple can have more complex items inside it, such as arrays. We can also pass the Tuple to other methods.
Here In this example, we create a four-item Tuple with two arrays—string and int arrays.
Array
Then We initialize those arrays inside the constructor invocation. Next we pass our Tuple variable to another method.
Detail Why does the example use the var keyword? The reason is pure syntactic sugar. Var shortens the lines in the code example.
var
Shows an array
using System; class Program { static void Main() { // Create four-item tuple. // ... Use var implicit type. var tuple = new Tuple<string, string[], int, int[]>("perl", new string[] { "java", "c#" }, 1, new int[] { 2, 3 }); // Pass tuple as argument. M(tuple); } static void M(Tuple<string, string[], int, int[]> tuple) { // Evaluate the tuple's items. Console.WriteLine(tuple.Item1); foreach (string value in tuple.Item2) { Console.WriteLine(value); } Console.WriteLine(tuple.Item3); foreach (int value in tuple.Item4) { Console.WriteLine(value); } } }
perl java c# 1 2 3
6 items. Tuples have different names. A sextuple has 6 items. To create a sextuple, use the Tuple constructor. You have to specify each type of the items in the type parameter list.
Warning This can lead to programs that have complex and hard-to-remember type names. But the compiler will check them.
using System; class Program { static void Main() { var sextuple = new Tuple<int, int, int, string, string, string>(1, 1, 2, "dot", "net", "perls"); Console.WriteLine(sextuple); } }
(1, 1, 2, dot, net, perls)
Tuple names. In Visual Studio, we can hover the mouse over the var keyword. This shows that the var "Represents a 6-tuple, or sextuple." We also see the tuple's individual types.
Note The naming of tuples is not important in many programs. But these terms can be useful when describing programs in a concise way.
Detail Beyond septuples, we only have n-tuples. These terms will make you sound really smart.
A 2-tuple is called a pair. A 3-tuple is called a triple. A 4-tuple is called a quadruple. A 5-tuple is called a quintuple. A 6-tuple is called a sextuple. A 7-tuple is called a septuple. Larger tuples are called n-tuples.
Tuple.Create. Next we invoke this method. We use Create() with three arguments: a string literal, an integer and a boolean value.
Result The Create() method returns a class instance of type Tuple that has 3 typed items.
Detail The code does a series of tests of the Tuple. It tests Item1, Item2 and Item3.
using System; class Program { static void Main() { // Use Tuple.Create static method. var tuple = Tuple.Create("cat", 2, true); // Test value of string. string value = tuple.Item1; if (value == "cat") { Console.WriteLine(true); } // Test Item2 and Item3. Console.WriteLine(tuple.Item2 == 10); Console.WriteLine(!tuple.Item3); // Write string representation. Console.WriteLine(tuple); } }
True False False (cat, 2, True)
Internals. There is no elaborate algorithm devoted to tuple creation. The Tuple.Create method calls a constructor and returns a reference.
Tip There is essentially no functional reason to ever call Tuple.Create. It might have more pleasing syntax.
public static Tuple<T1> Create<T1>(T1 item1) { return new Tuple<T1>(item1); }
Class, read-only. Tuple is not a struct—it is a class. It will be allocated upon the managed heap. Its items like Item1, Item2 are read-only properties.
class
Property
readonly
Detail All items must be initialized with the constructor. We cannot change a property (like Item1) after the constructor has run.
Note The properties Item1, Item2 and further do not have setters. We cannot assign them. A Tuple is immutable once created in memory.
Tip This limitation can lead to more maintainable code that does not rely on field changes through time.
using System; class Program { static void Main() { var tuple = new Tuple<int, string>(200, "Greece"); // This will not work. tuple.Item1 = 300; } }
Property or indexer 'System.Tuple...Item1' cannot be assigned to--it is read-only.
Sort. Tuples can be sorted. A Tuple is a great way to encapsulate units of data, but it can make sorting harder—a Comparison delegate is needed.
Comparison
Detail This program creates a List and adds 3 new Tuple instances to it. We invoke the Sort method on the List.
Sort List, Lambda
Here We use the lambda syntax and pass in 2 arguments (a, b) and return the result of CompareTo on the Item2 string property.
Tip To sort on the int, change the lambda to return a.Item1.CompareTo(b.Item1). A reverse sort would be b.Item2.CompareTo(a.Item2).
using System; using System.Collections.Generic; class Program { static void Main() { List<Tuple<int, string>> list = new List<Tuple<int, string>>(); list.Add(new Tuple<int, string>(1, "cat")); list.Add(new Tuple<int, string>(100, "apple")); list.Add(new Tuple<int, string>(2, "zebra")); // Use Sort method with Comparison delegate. // ... Has two parameters; return comparison of Item2 on each. list.Sort((a, b) => a.Item2.CompareTo(b.Item2)); foreach (var element in list) { Console.WriteLine(element); } } }
(100, apple) (1, cat) (2, zebra)
Return multiple values. This is a classic problem—a method may need to return many things, not just one. A tuple can return multiple values (with less code than a class would require).
Multiple Return Values
Note This causes an allocation. Using ref and out parameters would be faster for a method that is hot.
Parameter
Note 2 A Tuple has advantages. It is a reference and can be reused. Less copying is needed when passed to other methods.
using System; class Program { static Tuple<string, int> NameAndId() { // This method returns multiple values. return new Tuple<string, int>("Satya Nadella", 100); } static void Main() { var result = NameAndId(); string name = result.Item1; int id = result.Item2; // Display the multiple values returned. Console.WriteLine(name); Console.WriteLine(id); } }
Satya Nadella 100
ValueTuple. This type has clear advantages over Tuple. We can specify a ValueTuple by including values in an expression (with no type names).
Here We create a 3-item tuple literal, and display its 3 items with Console.WriteLine.
ValueTuple
Console.WriteLine
using System; class Program { static void Main() { // Go to NuGet, then search for and install System.ValueTuple. // ... This program will then compile correctly. var values = (10, "bird", "plane"); Console.WriteLine(values); Console.WriteLine(values.Item1); Console.WriteLine(values.Item2); Console.WriteLine(values.Item3); } }
(10, bird, plane) 10 bird plane
ToValueTuple. We can convert a Tuple into its equivalent ValueTuple form. The ValueTuple will have some performance advantages, and also simpler syntax.
using System; class Program { static void Main() { var tuple = new Tuple<int, string>(-20, "Bolivia"); // Convert tuple to a value tuple, and pass it to a method. Print(tuple.ToValueTuple()); } static void Print((int, string) items) { // Print value tuple. Console.WriteLine(items); } }
(-20, Bolivia)
Benchmark, tuple. Consider 4 possible performance tests: allocation, argument passing, returning, and loading a field. We test the performance of 3 types with these 4 tests.
Version 1 Here we benchmark Tuple in the 4 performance tests. We only use 2-item objects in this test.
Version 2 Here we use a KeyValuePair struct instead of a Tuple class instance as part of the benchmark.
struct
Version 3 This version is newest and most modern of the tests: it uses the ValueTuple literal syntax.
Result Tuples and ValueTuples tend to perform as well as anything in the tests. Tuples can be used as part of fast code.
using System; using System.Collections.Generic; using System.Diagnostics; using System.Runtime.CompilerServices; class Program { static void Main() { Allocation(); Argument(); Return(); Load(); } static void Allocation() { // Time allocating the object. const int max = 1000000; var a = new Tuple<string, string>("", ""); var b = new KeyValuePair<string, string>("", ""); var c = ("", ""); var s1 = Stopwatch.StartNew(); // Version 1: allocate Tuple. for (var i = 0; i < max; i++) { var tuple = new Tuple<string, string>("cat", "dog"); } s1.Stop(); var s2 = Stopwatch.StartNew(); // Version 2: allocate KeyValuePair. for (var i = 0; i < max; i++) { var pair = new KeyValuePair<string, string>("cat", "dog"); } s2.Stop(); var s3 = Stopwatch.StartNew(); // Version 3: allocate tuple literal. for (var i = 0; i < max; i++) { var pair = ("cat", "dog"); } s3.Stop(); Console.WriteLine(((double)(s1.Elapsed.TotalMilliseconds * 1000000) / max) + " allocation, Tuple"); Console.WriteLine(((double)(s2.Elapsed.TotalMilliseconds * 1000000) / max) + " allocation, KeyValuePair"); Console.WriteLine(((double)(s3.Elapsed.TotalMilliseconds * 1000000) / max) + " allocation, Tuple literal"); Console.WriteLine(); } static void Argument() { // Time passing the object as an argument to a function. const int max = 10000000; var a = new Tuple<string, string>("", ""); var b = new KeyValuePair<string, string>("", ""); var c = ("", ""); X(a); X(b); X(c); var s1 = Stopwatch.StartNew(); for (var i = 0; i < max; i++) { X(a); } s1.Stop(); var s2 = Stopwatch.StartNew(); for (var i = 0; i < max; i++) { X(b); } s2.Stop(); var s3 = Stopwatch.StartNew(); for (var i = 0; i < max; i++) { X(c); } s3.Stop(); Console.WriteLine(((double)(s1.Elapsed.TotalMilliseconds * 1000000) / max) + " argument, Tuple"); Console.WriteLine(((double)(s2.Elapsed.TotalMilliseconds * 1000000) / max) + " argument, KeyValuePair"); Console.WriteLine(((double)(s3.Elapsed.TotalMilliseconds * 1000000) / max) + " argument, Tuple literal"); Console.WriteLine(); } static void Return() { // Time returning the object itself. const int max = 10000000; var a = new Tuple<string, string>("", ""); var b = new KeyValuePair<string, string>("", ""); var c = ("", ""); Y(a); Y(b); Y(c); var s1 = Stopwatch.StartNew(); for (var i = 0; i < max; i++) { Y(a); } s1.Stop(); var s2 = Stopwatch.StartNew(); for (var i = 0; i < max; i++) { Y(b); } s2.Stop(); var s3 = Stopwatch.StartNew(); for (var i = 0; i < max; i++) { Y(c); } s3.Stop(); Console.WriteLine(((double)(s1.Elapsed.TotalMilliseconds * 1000000) / max) + " return, Tuple"); Console.WriteLine(((double)(s2.Elapsed.TotalMilliseconds * 1000000) / max) + " return, KeyValuePair"); Console.WriteLine(((double)(s3.Elapsed.TotalMilliseconds * 1000000) / max) + " return, Tuple literal"); Console.WriteLine(); } static void Load() { // Time accessing an element. const int max = 10000000; var a = new Tuple<string, string>("cat", "dog"); var b = new KeyValuePair<string, string>("cat", "dog"); var c = ("cat", "dog"); var list1 = new List<Tuple<string, string>>(); list1.Add(a); Z(list1); var list2 = new List<KeyValuePair<string, string>>(); list2.Add(b); Z(list2); var list3 = new List<(string, string)>(); list3.Add(c); Z(list3); var s1 = Stopwatch.StartNew(); for (var i = 0; i < max; i++) { Z(list1); } s1.Stop(); var s2 = Stopwatch.StartNew(); for (var i = 0; i < max; i++) { Z(list2); } s2.Stop(); var s3 = Stopwatch.StartNew(); for (var i = 0; i < max; i++) { Z(list3); } s3.Stop(); Console.WriteLine(((double)(s1.Elapsed.TotalMilliseconds * 1000000) / max) + " load, Tuple"); Console.WriteLine(((double)(s2.Elapsed.TotalMilliseconds * 1000000) / max) + " load, KeyValuePair"); Console.WriteLine(((double)(s3.Elapsed.TotalMilliseconds * 1000000) / max) + " load, Tuple literal"); Console.WriteLine(); } [MethodImpl(MethodImplOptions.NoInlining)] static void X(Tuple<string, string> a) { // This and following methods are used in the benchmarks. } [MethodImpl(MethodImplOptions.NoInlining)] static void X(KeyValuePair<string, string> a) { } [MethodImpl(MethodImplOptions.NoInlining)] static void X((string, string) a) { } [MethodImpl(MethodImplOptions.NoInlining)] static Tuple<string, string> Y(Tuple<string, string> a) { return a; } [MethodImpl(MethodImplOptions.NoInlining)] static KeyValuePair<string, string> Y(KeyValuePair<string, string> a) { return a; } [MethodImpl(MethodImplOptions.NoInlining)] static (string, string) Y((string, string) a) { return a; } static char Z(List<Tuple<string, string>> list) { return list[0].Item1[0]; } static char Z(List<KeyValuePair<string, string>> list) { return list[0].Key[0]; } static char Z(List<(string, string)> list) { return list[0].Item1[0]; } }
8.3944 allocation, Tuple 0.4949 allocation, KeyValuePair 0.3457 allocation, Tuple literal (FASTEST) 2.16168 argument, Tuple 2.17551 argument, KeyValuePair 2.17316 argument, Tuple literal 1.84421 return, Tuple (FASTEST) 5.42422 return, KeyValuePair 5.32932 return, Tuple literal 2.44545 load, Tuple 3.27982 load, KeyValuePair 2.56207 load, Tuple literal
Notes, above benchmark. We see 4 separate tests. The tests use different numbers of iterations to test the types. The average time in nanoseconds for each operation is computed.
Result The tuple literals (ValueTuple) are fastest when allocating. As arguments, the 3 types are all about the same speed.
And For returning from a method, Tuple is the fastest. For accessing an item from the object, Tuple and tuple literals are the fastest.
A summary. The Tuple is a typed, immutable, generic construct. Tuples are helpful—they can store related data. For important things, a simple class is easier to use and document.
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 Apr 20, 2023 (edit).
Home
Changes
© 2007-2024 Sam Allen.