Tuple<T1, T2> Class

 
System_CAPS_noteNote

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Represents a 2-tuple, or pair.

Namespace:   System
Assembly:  mscorlib (in mscorlib.dll)

System.Object
  System.Tuple<T1, T2>

[SerializableAttribute]
public class Tuple<T1, T2> : IStructuralEquatable, IStructuralComparable, 
	IComparable, ITuple

Type Parameters

T1

The type of the tuple's first component.

T2

The type of the tuple's second component.

NameDescription
System_CAPS_pubmethodTuple<T1, T2>(T1, T2)

Initializes a new instance of the Tuple<T1, T2> class.

NameDescription
System_CAPS_pubpropertyItem1

Gets the value of the current Tuple<T1, T2> object's first component.

System_CAPS_pubpropertyItem2

Gets the value of the current Tuple<T1, T2> object's second component.

NameDescription
System_CAPS_pubmethodEquals(Object)

Returns a value that indicates whether the current Tuple<T1, T2> object is equal to a specified object.(Overrides Object.Equals(Object).)

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethodGetHashCode()

Returns the hash code for the current Tuple<T1, T2> object.(Overrides Object.GetHashCode().)

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_pubmethodToString()

Returns a string that represents the value of this Tuple<T1, T2> instance.(Overrides Object.ToString().)

NameDescription
System_CAPS_pubinterfaceSystem_CAPS_privmethodIStructuralComparable.CompareTo(Object, IComparer)

Compares the current Tuple<T1, T2> object to a specified object by using a specified comparer, and returns an integer that indicates whether the current object is before, after, or in the same position as the specified object in the sort order.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIStructuralEquatable.Equals(Object, IEqualityComparer)

Returns a value that indicates whether the current Tuple<T1, T2> object is equal to a specified object based on a specified comparison method.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIStructuralEquatable.GetHashCode(IEqualityComparer)

Calculates the hash code for the current Tuple<T1, T2> object by using a specified computation method.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIComparable.CompareTo(Object)

Compares the current Tuple<T1, T2> object to a specified object and returns an integer that indicates whether the current object is before, after, or in the same position as the specified object in the sort order.

System_CAPS_pubinterfaceSystem_CAPS_privpropertyITuple.Item[Int32]

Gets the value of the specified Tuple element.

System_CAPS_pubinterfaceSystem_CAPS_privpropertyITuple.Length

Gets the number of elements in the Tuple.

A tuple is a data structure that has a specific number and sequence of values. The Tuple<T1, T2> class represents a 2-tuple, or pair, which is a tuple that has two components. A 2-tuple is similar to a KeyValuePair<TKey, TValue> structure.

You can instantiate a Tuple<T1, T2> object by calling either the Tuple<T1, T2> constructor or the static Tuple.Create<T1, T2>(T1, T2) method. You can retrieve the values of the tuple's components by using the read-only Item1 and Item2 instance properties.

Tuples are commonly used in four different ways:

  • To represent a single set of data. For example, a tuple can represent a record in a database, and its components can represent that record's fields.

  • To provide easy access to, and manipulation of, a data set. The following example defines an array of Tuple<T1, T2> objects that contain the names of students and their corresponding test scores. It then iterates the array to calculate the mean test score.

    using System;
    
    public class Example
    {
       public static void Main()
       {
          Tuple<string, Nullable<int>>[] scores = 
                        { new Tuple<string, Nullable<int>>("Jack", 78),
                          new Tuple<string, Nullable<int>>("Abbey", 92), 
                          new Tuple<string, Nullable<int>>("Dave", 88),
                          new Tuple<string, Nullable<int>>("Sam", 91), 
                          new Tuple<string, Nullable<int>>("Ed", null),
                          new Tuple<string, Nullable<int>>("Penelope", 82),
                          new Tuple<string, Nullable<int>>("Linda", 99),
                          new Tuple<string, Nullable<int>>("Judith", 84) };
          int number;
          double mean = ComputeMean(scores, out number);
          Console.WriteLine("Average test score: {0:N2} (n={1})", mean, number);
       }
    
       private static double ComputeMean(Tuple<string, Nullable<int>>[] scores, out int n) 
       {
          n = 0;      
          int sum = 0;
          foreach (var score in scores)
          {
             if (score.Item2.HasValue)
             { 
                n += 1;
                sum += score.Item2.Value;
             }
          }     
          if (n > 0)
             return sum / (double) n;
          else
             return 0;
       }
    }
    // The example displays the following output:
    //       Average test score: 88 (n=7)
    
  • To return multiple values from a method without the use of out parameters (in C#) or ByRef parameters (in Visual Basic). For example, the following example uses a Tuple<T1, T2> object to return the quotient and the remainder that result from integer division.

    using System;
    
    public class Class1
    {
       public static void Main()
       {
          int dividend, divisor;
          Tuple<int, int> result;
    
          dividend = 136945; divisor = 178;
          result = IntegerDivide(dividend, divisor);
          if (result != null)
             Console.WriteLine(@"{0} \ {1} = {2}, remainder {3}", 
                               dividend, divisor, result.Item1, result.Item2);
          else
             Console.WriteLine(@"{0} \ {1} = <Error>", dividend, divisor);
    
          dividend = Int32.MaxValue; divisor = -2073;
          result = IntegerDivide(dividend, divisor);
          if (result != null)
             Console.WriteLine(@"{0} \ {1} = {2}, remainder {3}", 
                               dividend, divisor, result.Item1, result.Item2);
          else
             Console.WriteLine(@"{0} \ {1} = <Error>", dividend, divisor);
       }
    
       private static Tuple<int, int> IntegerDivide(int dividend, int divisor)
       {
          try {
             int remainder;
             int quotient = Math.DivRem(dividend, divisor, out remainder);
             return new Tuple<int, int>(quotient, remainder);
          }   
          catch (DivideByZeroException) {
             return null;
          }      
       }
    }
    // The example displays the following output:
    //       136945 \ 178 = 769, remainder 63
    //       2147483647 \ -2073 = -1035930, remainder 757
    
  • To pass multiple values to a method through a single parameter. For example, the Thread.Start(Object) method has a single parameter that lets you supply one value to the method that the thread executes at startup. If you supply a Tuple<T1, T2> object as the method argument, you can supply the thread’s startup routine with two items of data.

Universal Windows Platform
Available since 8
.NET Framework
Available since 4.0
Portable Class Library
Supported in: portable .NET platforms
Silverlight
Available since 4.0
Windows Phone Silverlight
Available since 8.0
Windows Phone
Available since 8.1

Any public static ( Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top
Show: