src/doc/reference/src/types/tuple.md

   1 # Tuple types
   2
   3 > **<sup>Syntax</sup>**\
   4 > _TupleType_ :\
   5 > &nbsp;&nbsp; &nbsp;&nbsp; `(` `)`\
   6 > &nbsp;&nbsp; | `(` ( [_Type_] `,` )<sup>+</sup> [_Type_]<sup>?</sup> `)`
   7
   8 *Tuple types* are a family of structural types[^1] for heterogeneous lists of other types.
   9
  10 The syntax for a tuple type is a parenthesized, comma-separated list of types.
  11 1-ary tuples require a comma after their element type to be disambiguated with a [parenthesized type].
  12
  13 A tuple type has a number of fields equal to the length of the list of types.
  14 This number of fields determines the *arity* of the tuple.
  15 A tuple with `n` fields is called an *n-ary tuple*.
  16 For example, a tuple with 2 fields is a 2-ary tuple.
  17
  18 Fields of tuples are named using increasing numeric names matching their position in the list of types.
  19 The first field is `0`.
  20 The second field is `1`.
  21 And so on.
  22 The type of each field is the type of the same position in the tuple's list of types.
  23
  24 For convenience and historical reasons, the tuple type with no fields (`()`) is often called *unit* or *the unit type*.
  25 Its one value is also called *unit* or *the unit value*.
  26
  27 Some examples of tuple types:
  28
  29 * `()` (unit)
  30 * `(f64, f64)`
  31 * `(String, i32)`
  32 * `(i32, String)` (different type from the previous example)
  33 * `(i32, f64, Vec<String>, Option<bool>)`
  34
  35 Values of this type are constructed using a [tuple expression].
  36 Furthermore, various expressions will produce the unit value if there is no other meaningful value for it to evaluate to.
  37 Tuple fields can be accessed by either a [tuple index expression] or [pattern matching].
  38
  39 [^1]: Structural types are always equivalent if their internal types are equivalent.
  40       For a nominal version of tuples, see [tuple structs].
  41
  42 [_Type_]: ../types.md#type-expressions
  43 [parenthesized type]: ../types.md#parenthesized-types
  44 [pattern matching]: ../patterns.md#tuple-patterns
  45 [tuple expression]: ../expressions/tuple-expr.md#tuple-expressions
  46 [tuple index expression]: ../expressions/tuple-expr.md#tuple-indexing-expressions
  47 [tuple structs]: ./struct.md