src/doc/book/src/appendix-01-keywords.md

   1 ## Appendix A: Keywords
   2
   3 The following list contains keywords that are reserved for current or future
   4 use by the Rust language. As such, they cannot be used as identifiers (except
   5 as raw identifiers as we’ll discuss in the “[Raw
   6 Identifiers][raw-identifiers]<!-- ignore -->” section), including names of
   7 functions, variables, parameters, struct fields, modules, crates, constants,
   8 macros, static values, attributes, types, traits, or lifetimes.
   9
  10 [raw-identifiers]: #raw-identifiers
  11
  12 ### Keywords Currently in Use
  13
  14 The following keywords currently have the functionality described.
  15
  16 * `as` - perform primitive casting, disambiguate the specific trait containing
  17   an item, or rename items in `use` and `extern crate` statements
  18 * `async` -  return a `Future` instead of blocking the current thread
  19 * `await` - suspend execution until the result of a `Future` is ready
  20 * `break` - exit a loop immediately
  21 * `const` - define constant items or constant raw pointers
  22 * `continue` - continue to the next loop iteration
  23 * `crate` - link an external crate or a macro variable representing the crate in
  24   which the macro is defined
  25 * `dyn` - dynamic dispatch to a trait object
  26 * `else` - fallback for `if` and `if let` control flow constructs
  27 * `enum` - define an enumeration
  28 * `extern` - link an external crate, function, or variable
  29 * `false` - Boolean false literal
  30 * `fn` - define a function or the function pointer type
  31 * `for` - loop over items from an iterator, implement a trait, or specify a
  32   higher-ranked lifetime
  33 * `if` - branch based on the result of a conditional expression
  34 * `impl` - implement inherent or trait functionality
  35 * `in` - part of `for` loop syntax
  36 * `let` - bind a variable
  37 * `loop` - loop unconditionally
  38 * `match` - match a value to patterns
  39 * `mod` - define a module
  40 * `move` - make a closure take ownership of all its captures
  41 * `mut` - denote mutability in references, raw pointers, or pattern bindings
  42 * `pub` - denote public visibility in struct fields, `impl` blocks, or modules
  43 * `ref` - bind by reference
  44 * `return` - return from function
  45 * `Self` - a type alias for the type we are defining or implementing
  46 * `self` - method subject or current module
  47 * `static` - global variable or lifetime lasting the entire program execution
  48 * `struct` - define a structure
  49 * `super` - parent module of the current module
  50 * `trait` - define a trait
  51 * `true` - Boolean true literal
  52 * `type` - define a type alias or associated type
  53 * `union` - define a [union] and is only a keyword when used in a union declaration
  54 * `unsafe` - denote unsafe code, functions, traits, or implementations
  55 * `use` - bring symbols into scope
  56 * `where` - denote clauses that constrain a type
  57 * `while` - loop conditionally based on the result of an expression
  58
  59 [union]: ../reference/items/unions.html
  60
  61 ### Keywords Reserved for Future Use
  62
  63 The following keywords do not have any functionality but are reserved by Rust
  64 for potential future use.
  65
  66 * `abstract`
  67 * `become`
  68 * `box`
  69 * `do`
  70 * `final`
  71 * `macro`
  72 * `override`
  73 * `priv`
  74 * `try`
  75 * `typeof`
  76 * `unsized`
  77 * `virtual`
  78 * `yield`
  79
  80 ### Raw Identifiers
  81
  82 *Raw identifiers* are the syntax that lets you use keywords where they wouldn’t
  83 normally be allowed. You use a raw identifier by prefixing a keyword with `r#`.
  84
  85 For example, `match` is a keyword. If you try to compile the following function
  86 that uses `match` as its name:
  87
  88 <span class="filename">Filename: src/main.rs</span>
  89
  90 ```rust,ignore,does_not_compile
  91 fn match(needle: &str, haystack: &str) -> bool {
  92     haystack.contains(needle)
  93 }
  94 ```
  95
  96 you’ll get this error:
  97
  98 ```text
  99 error: expected identifier, found keyword `match`
 100  --> src/main.rs:4:4
 101   |
 102 4 | fn match(needle: &str, haystack: &str) -> bool {
 103   |    ^^^^^ expected identifier, found keyword
 104 ```
 105
 106 The error shows that you can’t use the keyword `match` as the function
 107 identifier. To use `match` as a function name, you need to use the raw
 108 identifier syntax, like this:
 109
 110 <span class="filename">Filename: src/main.rs</span>
 111
 112 ```rust
 113 fn r#match(needle: &str, haystack: &str) -> bool {
 114     haystack.contains(needle)
 115 }
 116
 117 fn main() {
 118     assert!(r#match("foo", "foobar"));
 119 }
 120 ```
 121
 122 This code will compile without any errors. Note the `r#` prefix on the function
 123 name in its definition as well as where the function is called in `main`.
 124
 125 Raw identifiers allow you to use any word you choose as an identifier, even if
 126 that word happens to be a reserved keyword. In addition, raw identifiers allow
 127 you to use libraries written in a different Rust edition than your crate uses.
 128 For example, `try` isn’t a keyword in the 2015 edition but is in the 2018
 129 edition. If you depend on a library that’s written using the 2015 edition and
 130 has a `try` function, you’ll need to use the raw identifier syntax, `r#try` in
 131 this case, to call that function from your 2018 edition code. See [Appendix
 132 E][appendix-e]<!-- ignore --> for more information on editions.
 133
 134 [appendix-e]: appendix-05-editions.html