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