src/doc/book/src/appendix-02-operators.md

   1 ## Appendix B: Operators and Symbols
   2
   3 This appendix contains a glossary of Rust’s syntax, including operators and
   4 other symbols that appear by themselves or in the context of paths, generics,
   5 trait bounds, macros, attributes, comments, tuples, and brackets.
   6
   7 ### Operators
   8
   9 Table B-1 contains the operators in Rust, an example of how the operator would
  10 appear in context, a short explanation, and whether that operator is
  11 overloadable. If an operator is overloadable, the relevant trait to use to
  12 overload that operator is listed.
  13
  14 <span class="caption">Table B-1: Operators</span>
  15
  16 | Operator | Example | Explanation | Overloadable? |
  17 |----------|---------|-------------|---------------|
  18 | `!` | `ident!(...)`, `ident!{...}`, `ident![...]` | Macro expansion | |
  19 | `!` | `!expr` | Bitwise or logical complement | `Not` |
  20 | `!=` | `var != expr` | Nonequality comparison | `PartialEq` |
  21 | `%` | `expr % expr` | Arithmetic remainder | `Rem` |
  22 | `%=` | `var %= expr` | Arithmetic remainder and assignment | `RemAssign` |
  23 | `&` | `&expr`, `&mut expr` | Borrow | |
  24 | `&` | `&type`, `&mut type`, `&'a type`, `&'a mut type` | Borrowed pointer type | |
  25 | `&` | `expr & expr` | Bitwise AND | `BitAnd` |
  26 | `&=` | `var &= expr` | Bitwise AND and assignment | `BitAndAssign` |
  27 | `&&` | `expr && expr` | Logical AND | |
  28 | `*` | `expr * expr` | Arithmetic multiplication | `Mul` |
  29 | `*=` | `var *= expr` | Arithmetic multiplication and assignment | `MulAssign` |
  30 | `*` | `*expr` | Dereference | |
  31 | `*` | `*const type`, `*mut type` | Raw pointer | |
  32 | `+` | `trait + trait`, `'a + trait` | Compound type constraint | |
  33 | `+` | `expr + expr` | Arithmetic addition | `Add` |
  34 | `+=` | `var += expr` | Arithmetic addition and assignment | `AddAssign` |
  35 | `,` | `expr, expr` | Argument and element separator | |
  36 | `-` | `- expr` | Arithmetic negation | `Neg` |
  37 | `-` | `expr - expr` | Arithmetic subtraction | `Sub` |
  38 | `-=` | `var -= expr` | Arithmetic subtraction and assignment | `SubAssign` |
  39 | `->` | `fn(...) -> type`, <code>&vert;...&vert; -> type</code> | Function and closure return type | |
  40 | `.` | `expr.ident` | Member access | |
  41 | `..` | `..`, `expr..`, `..expr`, `expr..expr` | Right-exclusive range literal | |
  42 | `..=` | `..=expr`, `expr..=expr` | Right-inclusive range literal | |
  43 | `..` | `..expr` | Struct literal update syntax | |
  44 | `..` | `variant(x, ..)`, `struct_type { x, .. }` | “And the rest” pattern binding | |
  45 | `...` | `expr...expr` | In a pattern: inclusive range pattern | |
  46 | `/` | `expr / expr` | Arithmetic division | `Div` |
  47 | `/=` | `var /= expr` | Arithmetic division and assignment | `DivAssign` |
  48 | `:` | `pat: type`, `ident: type` | Constraints | |
  49 | `:` | `ident: expr` | Struct field initializer | |
  50 | `:` | `'a: loop {...}` | Loop label | |
  51 | `;` | `expr;` | Statement and item terminator | |
  52 | `;` | `[...; len]` | Part of fixed-size array syntax | |
  53 | `<<` | `expr << expr` | Left-shift | `Shl` |
  54 | `<<=` | `var <<= expr` | Left-shift and assignment | `ShlAssign` |
  55 | `<` | `expr < expr` | Less than comparison | `PartialOrd` |
  56 | `<=` | `expr <= expr` | Less than or equal to comparison | `PartialOrd` |
  57 | `=` | `var = expr`, `ident = type` | Assignment/equivalence | |
  58 | `==` | `expr == expr` | Equality comparison | `PartialEq` |
  59 | `=>` | `pat => expr` | Part of match arm syntax | |
  60 | `>` | `expr > expr` | Greater than comparison | `PartialOrd` |
  61 | `>=` | `expr >= expr` | Greater than or equal to comparison | `PartialOrd` |
  62 | `>>` | `expr >> expr` | Right-shift | `Shr` |
  63 | `>>=` | `var >>= expr` | Right-shift and assignment | `ShrAssign` |
  64 | `@` | `ident @ pat` | Pattern binding | |
  65 | `^` | `expr ^ expr` | Bitwise exclusive OR | `BitXor` |
  66 | `^=` | `var ^= expr` | Bitwise exclusive OR and assignment | `BitXorAssign` |
  67 | <code>&vert;</code> | <code>pat &vert; pat</code> | Pattern alternatives | |
  68 | <code>&vert;</code> | <code>expr &vert; expr</code> | Bitwise OR | `BitOr` |
  69 | <code>&vert;=</code> | <code>var &vert;= expr</code> | Bitwise OR and assignment | `BitOrAssign` |
  70 | <code>&vert;&vert;</code> | <code>expr &vert;&vert; expr</code> | Logical OR | |
  71 | `?` | `expr?` | Error propagation | |
  72
  73 ### Non-operator Symbols
  74
  75 The following list contains all non-letters that don’t function as operators;
  76 that is, they don’t behave like a function or method call.
  77
  78 Table B-2 shows symbols that appear on their own and are valid in a variety of
  79 locations.
  80
  81 <span class="caption">Table B-2: Stand-Alone Syntax</span>
  82
  83 | Symbol | Explanation |
  84 |--------|-------------|
  85 | `'ident` | Named lifetime or loop label |
  86 | `...u8`, `...i32`, `...f64`, `...usize`, etc. | Numeric literal of specific type |
  87 | `"..."` | String literal |
  88 | `r"..."`, `r#"..."#`, `r##"..."##`, etc. | Raw string literal, escape characters not processed |
  89 | `b"..."` | Byte string literal; constructs a `[u8]` instead of a string |
  90 | `br"..."`, `br#"..."#`, `br##"..."##`, etc. | Raw byte string literal, combination of raw and byte string literal |
  91 | `'...'` | Character literal |
  92 | `b'...'` | ASCII byte literal |
  93 | <code>&vert;...&vert; expr</code> | Closure |
  94 | `!` | Always empty bottom type for diverging functions |
  95 | `_` | “Ignored” pattern binding; also used to make integer literals readable |
  96
  97 Table B-3 shows symbols that appear in the context of a path through the module
  98 hierarchy to an item.
  99
 100 <span class="caption">Table B-3: Path-Related Syntax</span>
 101
 102 | Symbol | Explanation |
 103 |--------|-------------|
 104 | `ident::ident` | Namespace path |
 105 | `::path` | Path relative to the crate root (i.e., an explicitly absolute path) |
 106 | `self::path` | Path relative to the current module (i.e., an explicitly relative path).
 107 | `super::path` | Path relative to the parent of the current module |
 108 | `type::ident`, `<type as trait>::ident` | Associated constants, functions, and types |
 109 | `<type>::...` | Associated item for a type that cannot be directly named (e.g., `<&T>::...`, `<[T]>::...`, etc.) |
 110 | `trait::method(...)` | Disambiguating a method call by naming the trait that defines it |
 111 | `type::method(...)` | Disambiguating a method call by naming the type for which it’s defined |
 112 | `<type as trait>::method(...)` | Disambiguating a method call by naming the trait and type |
 113
 114 Table B-4 shows symbols that appear in the context of using generic type
 115 parameters.
 116
 117 <span class="caption">Table B-4: Generics</span>
 118
 119 | Symbol | Explanation |
 120 |--------|-------------|
 121 | `path<...>` | Specifies parameters to generic type in a type (e.g., `Vec<u8>`) |
 122 | `path::<...>`, `method::<...>` | Specifies parameters to generic type, function, or method in an expression; often referred to as turbofish (e.g., `"42".parse::<i32>()`) |
 123 | `fn ident<...> ...` | Define generic function |
 124 | `struct ident<...> ...` | Define generic structure |
 125 | `enum ident<...> ...` | Define generic enumeration |
 126 | `impl<...> ...` | Define generic implementation |
 127 | `for<...> type` | Higher-ranked lifetime bounds |
 128 | `type<ident=type>` | A generic type where one or more associated types have specific assignments (e.g., `Iterator<Item=T>`) |
 129
 130 Table B-5 shows symbols that appear in the context of constraining generic type
 131 parameters with trait bounds.
 132
 133 <span class="caption">Table B-5: Trait Bound Constraints</span>
 134
 135 | Symbol | Explanation |
 136 |--------|-------------|
 137 | `T: U` | Generic parameter `T` constrained to types that implement `U` |
 138 | `T: 'a` | Generic type `T` must outlive lifetime `'a` (meaning the type cannot transitively contain any references with lifetimes shorter than `'a`) |
 139 | `T : 'static` | Generic type `T` contains no borrowed references other than `'static` ones |
 140 | `'b: 'a` | Generic lifetime `'b` must outlive lifetime `'a` |
 141 | `T: ?Sized` | Allow generic type parameter to be a dynamically sized type |
 142 | `'a + trait`, `trait + trait` | Compound type constraint |
 143
 144 Table B-6 shows symbols that appear in the context of calling or defining
 145 macros and specifying attributes on an item.
 146
 147 <span class="caption">Table B-6: Macros and Attributes</span>
 148
 149 | Symbol | Explanation |
 150 |--------|-------------|
 151 | `#[meta]` | Outer attribute |
 152 | `#![meta]` | Inner attribute |
 153 | `$ident` | Macro substitution |
 154 | `$ident:kind` | Macro capture |
 155 | `$(…)…` | Macro repetition |
 156 | `ident!(...)`, `ident!{...}`, `ident![...]` | Macro invocation |
 157
 158 Table B-7 shows symbols that create comments.
 159
 160 <span class="caption">Table B-7: Comments</span>
 161
 162 | Symbol | Explanation |
 163 |--------|-------------|
 164 | `//` | Line comment |
 165 | `//!` | Inner line doc comment |
 166 | `///` | Outer line doc comment |
 167 | `/*...*/` | Block comment |
 168 | `/*!...*/` | Inner block doc comment |
 169 | `/**...*/` | Outer block doc comment |
 170
 171 Table B-8 shows symbols that appear in the context of using tuples.
 172
 173 <span class="caption">Table B-8: Tuples</span>
 174
 175 | Symbol | Explanation |
 176 |--------|-------------|
 177 | `()` | Empty tuple (aka unit), both literal and type |
 178 | `(expr)` | Parenthesized expression |
 179 | `(expr,)` | Single-element tuple expression |
 180 | `(type,)` | Single-element tuple type |
 181 | `(expr, ...)` | Tuple expression |
 182 | `(type, ...)` | Tuple type |
 183 | `expr(expr, ...)` | Function call expression; also used to initialize tuple `struct`s and tuple `enum` variants |
 184 | `expr.0`, `expr.1`, etc. | Tuple indexing |
 185
 186 Table B-9 shows the contexts in which curly braces are used.
 187
 188 <span class="caption">Table B-9: Curly Brackets</span>
 189
 190 | Context | Explanation |
 191 |---------|-------------|
 192 | `{...}` | Block expression |
 193 | `Type {...}` | `struct` literal |
 194
 195 Table B-10 shows the contexts in which square brackets are used.
 196
 197 <span class="caption">Table B-10: Square Brackets</span>
 198
 199 | Context | Explanation |
 200 |---------|-------------|
 201 | `[...]` | Array literal |
 202 | `[expr; len]` | Array literal containing `len` copies of `expr` |
 203 | `[type; len]` | Array type containing `len` instances of `type` |
 204 | `expr[expr]` | Collection indexing. Overloadable (`Index`, `IndexMut`) |
 205 | `expr[..]`, `expr[a..]`, `expr[..b]`, `expr[a..b]` | Collection indexing pretending to be collection slicing, using `Range`, `RangeFrom`, `RangeTo`, or `RangeFull` as the “index” |