src/doc/reference/src/identifiers.md

   1 # Identifiers
   2
   3 > **<sup>Lexer:<sup>**\
   4 > IDENTIFIER_OR_KEYWORD :\
   5 > &nbsp;&nbsp; &nbsp;&nbsp; XID_Start XID_Continue<sup>\*</sup>\
   6 > &nbsp;&nbsp; | `_` XID_Continue<sup>+</sup>
   7 >
   8 > RAW_IDENTIFIER : `r#` IDENTIFIER_OR_KEYWORD <sub>*Except `crate`, `self`, `super`, `Self`*</sub>
   9 >
  10 > NON_KEYWORD_IDENTIFIER : IDENTIFIER_OR_KEYWORD <sub>*Except a [strict] or [reserved] keyword*</sub>
  11 >
  12 > IDENTIFIER :\
  13 > NON_KEYWORD_IDENTIFIER | RAW_IDENTIFIER
  14
  15 <!-- When updating the version, update the UAX links, too. -->
  16 Identifiers follow the specification in [Unicode Standard Annex #31][UAX31] for Unicode version 15.0, with the additions described below. Some examples of identifiers:
  17
  18 * `foo`
  19 * `_identifier`
  20 * `r#true`
  21 * `Москва`
  22 * `東京`
  23
  24 The profile used from UAX #31 is:
  25
  26 * Start := [`XID_Start`], plus the underscore character (U+005F)
  27 * Continue := [`XID_Continue`]
  28 * Medial := empty
  29
  30 with the additional constraint that a single underscore character is not an identifier.
  31
  32 > **Note**: Identifiers starting with an underscore are typically used to indicate an identifier that is intentionally unused, and will silence the unused warning in `rustc`.
  33
  34 Identifiers may not be a [strict] or [reserved] keyword without the `r#` prefix described below in [raw identifiers](#raw-identifiers).
  35
  36 Zero width non-joiner (ZWNJ U+200C) and zero width joiner (ZWJ U+200D) characters are not allowed in identifiers.
  37
  38 Identifiers are restricted to the ASCII subset of [`XID_Start`] and [`XID_Continue`] in the following situations:
  39
  40 * [`extern crate`] declarations
  41 * External crate names referenced in a [path]
  42 * [Module] names loaded from the filesystem without a [`path` attribute]
  43 * [`no_mangle`] attributed items
  44 * Item names in [external blocks]
  45
  46 ## Normalization
  47
  48 Identifiers are normalized using Normalization Form C (NFC) as defined in [Unicode Standard Annex #15][UAX15]. Two identifiers are equal if their NFC forms are equal.
  49
  50 [Procedural][proc-macro] and [declarative][mbe] macros receive normalized identifiers in their input.
  51
  52 ## Raw identifiers
  53
  54 A raw identifier is like a normal identifier, but prefixed by `r#`. (Note that
  55 the `r#` prefix is not included as part of the actual identifier.)
  56 Unlike a normal identifier, a raw identifier may be any strict or reserved
  57 keyword except the ones listed above for `RAW_IDENTIFIER`.
  58
  59 [`extern crate`]: items/extern-crates.md
  60 [`no_mangle`]: abi.md#the-no_mangle-attribute
  61 [`path` attribute]: items/modules.md#the-path-attribute
  62 [`XID_Continue`]: http://unicode.org/cldr/utility/list-unicodeset.jsp?a=%5B%3AXID_Continue%3A%5D&abb=on&g=&i=
  63 [`XID_Start`]:  http://unicode.org/cldr/utility/list-unicodeset.jsp?a=%5B%3AXID_Start%3A%5D&abb=on&g=&i=
  64 [external blocks]: items/external-blocks.md
  65 [mbe]: macros-by-example.md
  66 [module]: items/modules.md
  67 [path]: paths.md
  68 [proc-macro]: procedural-macros.md
  69 [reserved]: keywords.md#reserved-keywords
  70 [strict]: keywords.md#strict-keywords
  71 [UAX15]: https://www.unicode.org/reports/tr15/tr15-53.html
  72 [UAX31]: https://www.unicode.org/reports/tr31/tr31-37.html