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