src/doc/reference/src/expressions/tuple-expr.md

   1 # Tuple and tuple indexing expressions
   2
   3 ## Tuple expressions
   4
   5 > **<sup>Syntax</sup>**\
   6 > _TupleExpression_ :\
   7 > &nbsp;&nbsp; `(` [_InnerAttribute_]<sup>\*</sup> _TupleElements_<sup>?</sup> `)`
   8 >
   9 > _TupleElements_ :\
  10 > &nbsp;&nbsp; ( [_Expression_] `,` )<sup>+</sup> [_Expression_]<sup>?</sup>
  11
  12 Tuple expressions evaluate into [tuple values][tuple type] with the operands initializing the elements of the tuple.
  13
  14 Tuple expressions are written by listing the [operands] in a parenthesized, comma-separated list. 1-ary tuple expressions require a comma after their operand to be disambiguated with a [parenthetical expression].
  15
  16 The number of operands is the arity of the constructed tuple.
  17 Tuple expressions without operands produce the unit tuple.
  18 For other tuple expressions, the first written operand initializes the 0th element and subsequent operands initializes the next highest element.
  19 For example, in the tuple expression `('a', 'b', 'c')`, `'a'` initializes the value of the 0th element, `'b'` the 1st, and `'c'` the 2nd.
  20
  21 Examples of tuple expressions:
  22
  23 | Expression           | Type         |
  24 | -------------------- | ------------ |
  25 | `()`                 | `()` (unit)  |
  26 | `(0.0, 4.5)`         | `(f64, f64)` |
  27 | `("x".to_string(), )` | `(String, )`  |
  28 | `("a", 4usize, true)`| `(&'static str, usize, bool)` |
  29
  30 ### Tuple expression attributes
  31
  32 [Inner attributes] are allowed directly after the opening parenthesis of a tuple expression in the same expression contexts as [attributes on block expressions].
  33
  34 ## Tuple indexing expressions
  35
  36 > **<sup>Syntax</sup>**\
  37 > _TupleIndexingExpression_ :\
  38 > &nbsp;&nbsp; [_Expression_] `.` [TUPLE_INDEX]
  39
  40 Tuple indexing expressions evaluate like [field access expressions], but access elements of [tuples][tuple type] or [tuple structs].
  41
  42 Tuple index expressions are written as an operand, `.`, and a tuple index.
  43 The index must be written as a [decimal literal] with no leading zeros, underscores, or suffix.
  44 The operand must have the type of a tuple or tuple struct.
  45 If the tuple index is not an element of the tuple or tuple struct, it is a compiler error.
  46
  47 Examples of tuple indexing expressions:
  48
  49 ```rust
  50 let pair = ("a string", 2);
  51 assert_eq!(pair.1, 2);
  52
  53 # struct Point(f32, f32);
  54 let point = Point(1.0, 0.0);
  55 assert_eq!(point.0, 1.0);
  56 assert_eq!(point.1, 0.0);
  57 ```
  58
  59 > **Note**: Unlike field access expressions, tuple index expressions can be the function operand of a [call expression] as it cannot be confused with a method call since method names cannot be numbers.
  60
  61 [_Expression_]: ../expressions.md
  62 [_InnerAttribute_]: ../attributes.md
  63 [attributes on block expressions]: block-expr.md#attributes-on-block-expressions
  64 [call expression]: ./call-expr.md
  65 [decimal literal]: ../tokens.md#integer-literals
  66 [field access expressions]: ./field-expr.html#field-access-expressions
  67 [Inner attributes]: ../attributes.md
  68 [operands]: ../expressions.md
  69 [parenthetical expression]: grouped-expr.md
  70 [tuple type]: ../types/tuple.md
  71 [tuple structs]: ../types/struct.md
  72 [TUPLE_INDEX]: ../tokens.md#tuple-index