src/doc/reference/src/items/constant-items.md

   1 # Constant items
   2
   3 > **<sup>Syntax</sup>**\
   4 > _ConstantItem_ :\
   5 > &nbsp;&nbsp; `const` ( [IDENTIFIER] | `_` ) `:` [_Type_] `=` [_Expression_] `;`
   6
   7 A *constant item* is an optionally named _[constant value]_ which is not associated
   8 with a specific memory location in the program. Constants are essentially inlined
   9 wherever they are used, meaning that they are copied directly into the relevant
  10 context when used. This includes usage of constants from external crates, and
  11 non-[`Copy`] types. References to the same constant are not necessarily
  12 guaranteed to refer to the same memory address.
  13
  14 Constants must be explicitly typed. The type must have a `'static` lifetime: any
  15 references in the initializer must have `'static` lifetimes.
  16
  17 Constants may refer to the address of other constants, in which case the
  18 address will have elided lifetimes where applicable, otherwise – in most cases
  19 – defaulting to the `static` lifetime. (See [static lifetime
  20 elision].) The compiler is, however, still at liberty to translate the constant
  21 many times, so the address referred to may not be stable.
  22
  23 ```rust
  24 const BIT1: u32 = 1 << 0;
  25 const BIT2: u32 = 1 << 1;
  26
  27 const BITS: [u32; 2] = [BIT1, BIT2];
  28 const STRING: &'static str = "bitstring";
  29
  30 struct BitsNStrings<'a> {
  31     mybits: [u32; 2],
  32     mystring: &'a str,
  33 }
  34
  35 const BITS_N_STRINGS: BitsNStrings<'static> = BitsNStrings {
  36     mybits: BITS,
  37     mystring: STRING,
  38 };
  39 ```
  40
  41 ## Constants with Destructors
  42
  43 Constants can contain destructors. Destructors are run when the value goes out
  44 of scope.
  45
  46 ```rust
  47 struct TypeWithDestructor(i32);
  48
  49 impl Drop for TypeWithDestructor {
  50     fn drop(&mut self) {
  51         println!("Dropped. Held {}.", self.0);
  52     }
  53 }
  54
  55 const ZERO_WITH_DESTRUCTOR: TypeWithDestructor = TypeWithDestructor(0);
  56
  57 fn create_and_drop_zero_with_destructor() {
  58     let x = ZERO_WITH_DESTRUCTOR;
  59     // x gets dropped at end of function, calling drop.
  60     // prints "Dropped. Held 0.".
  61 }
  62 ```
  63
  64 ## Unnamed constant
  65
  66 Unlike an [associated] constant, a [free] constant may be unnamed by using
  67 an underscore instead of the name. For example:
  68
  69 ```rust
  70 const _: () =  { struct _SameNameTwice; };
  71
  72 // OK although it is the same name as above:
  73 const _: () =  { struct _SameNameTwice; };
  74 ```
  75
  76 As with [underscore imports], macros may safely emit the same unnamed constant in
  77 the same scope more than once. For example, the following should not produce an error:
  78
  79 ```rust
  80 macro_rules! m {
  81     ($item: item) => { $item $item }
  82 }
  83
  84 m!(const _: () = (););
  85 // This expands to:
  86 // const _: () = ();
  87 // const _: () = ();
  88 ```
  89
  90 [associated]: ../glossary.md#associated-item
  91 [constant value]: ../const_eval.md#constant-expressions
  92 [free]: ../glossary.md#free-item
  93 [static lifetime elision]: ../lifetime-elision.md#static-lifetime-elision
  94 [IDENTIFIER]: ../identifiers.md
  95 [underscore imports]: use-declarations.md#underscore-imports
  96 [_Type_]: ../types.md#type-expressions
  97 [_Expression_]: ../expressions.md
  98 [`Copy`]: ../special-types-and-traits.md#copy