Visual Basic (Declaration)

<SerializableAttribute> _
Public Class Tuple(Of T1, T2) _
    Implements IStructuralEquatable, IStructuralComparable, IComparable

Visual Basic (Usage)

Dim instance As Tuple(Of T1, T2)

C#

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

Visual C++

[SerializableAttribute]
generic<typename T1, typename T2>
public ref class Tuple : IStructuralEquatable, IStructuralComparable, 
    IComparable

F#

[<SerializableAttribute>]
type Tuple<'T1, 'T2> =  
    class
        interface IStructuralEquatable
        interface IStructuralComparable
        interface IComparable
    end

A tuple is a data structure that has a specific number and sequence of values. The Tuple<(Of <(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<(Of <(TKey, TValue>)>) structure.

You can instantiate a Tuple<(Of <(T1, T2>)>) object by calling either the Tuple<(Of <(T1, T2>)>) constructor or the static Tuple..::.Create<(Of <(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<(Of <(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.

  Visual Basic

  Module Example
     Public Sub Main()
        Dim scores() As Tuple(Of String, Nullable(Of Integer)) = 
                        { New Tuple(Of String, Nullable(Of Integer))("Jack", 78),
                          New Tuple(Of String, Nullable(Of Integer))("Abbey", 92), 
                          New Tuple(Of String, Nullable(Of Integer))("Dave", 88),
                          New Tuple(Of String, Nullable(Of Integer))("Sam", 91), 
                          New Tuple(Of String, Nullable(Of Integer))("Ed", Nothing),
                          New Tuple(Of String, Nullable(Of Integer))("Penelope", 82),
                          New Tuple(Of String, Nullable(Of Integer))("Linda", 99),
                          New Tuple(Of String, Nullable(Of Integer))("Judith", 84) }
        Dim number As Integer
        Dim mean As Double = ComputeMean(scores, number)
        Console.WriteLine("Average test score: {0:N2} (n={1})", mean, number)
     End Sub
  
     Private Function ComputeMean(scores() As Tuple(Of String, Nullable(Of Integer)), 
                                  ByRef n As Integer) As Double
        n = 0      
        Dim sum As Integer
        For Each score In scores
           If score.Item2.HasValue Then 
              n += 1
              sum += score.Item2.Value
           End If
        Next     
        If n > 0 Then
           Return sum / n
        Else
           Return 0
        End If             
     End Function
  End Module
  ' The example displays the following output:
  '       Average test score: 88 (n=7)
  

  C#

  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<(Of <(T1, T2>)>) object to return the quotient and the remainder that result from integer division.

  Visual Basic

  Module modMain
     Public Sub Main()
        Dim dividend, divisor As Integer
        Dim result As Tuple(Of Integer, Integer)
  
        dividend = 136945 : divisor = 178
        result = IntegerDivide(dividend, divisor)
        If result IsNot Nothing Then
           Console.WriteLine("{0} \ {1} = {2}, remainder {3}", 
                             dividend, divisor, result.Item1, result.Item2)
        Else
           Console.WriteLine("{0} \ {1} = <Error>", dividend, divisor)
        End If
  
        dividend = Int32.MaxValue : divisor = -2073
        result = IntegerDivide(dividend, divisor)
        If result IsNot Nothing Then
           Console.WriteLine("{0} \ {1} = {2}, remainder {3}", 
                             dividend, divisor, result.Item1, result.Item2)
        Else
           Console.WriteLine("{0} \ {1} = <Error>", dividend, divisor)
        End If
     End Sub
  
     Private Function IntegerDivide(dividend As Integer, divisor As Integer) As Tuple(Of Integer, Integer)
        Try
           Dim remainder As Integer
           Dim quotient As Integer = Math.DivRem(dividend, divisor, remainder)
           Return New Tuple(Of Integer, Integer)(quotient, remainder)
        Catch e As DivideByZeroException
           Return Nothing
        End Try      
     End Function
  End Module
  ' The example displays the following output:
  '       136945 \ 178 = 769, remainder 63
  '       2147483647 \ -2073 = -1035930, remainder 757
  

  C#

  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<(Of <(T1, T2>)>) object as the method argument, you can supply the thread’s startup routine with two items of data.

System..::.Object
  System..::.Tuple<(Of <(T1, T2>)>)

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

Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008, Windows Server 2003

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 4

.NET Framework Client Profile

Supported in: 4

Reference