src/doc/book/src/appendix-03-derivable-traits.md

   1 ## Appendix C: Derivable Traits
   2
   3 In various places in the book, we’ve discussed the `derive` attribute, which
   4 you can apply to a struct or enum definition. The `derive` attribute generates
   5 code that will implement a trait with its own default implementation on the
   6 type you’ve annotated with the `derive` syntax.
   7
   8 In this appendix, we provide a reference of all the traits in the standard
   9 library that you can use with `derive`. Each section covers:
  10
  11 * What operators and methods deriving this trait will enable
  12 * What the implementation of the trait provided by `derive` does
  13 * What implementing the trait signifies about the type
  14 * The conditions in which you’re allowed or not allowed to implement the trait
  15 * Examples of operations that require the trait
  16
  17 If you want different behavior from that provided by the `derive` attribute,
  18 consult the [standard library documentation](../std/index.html)<!-- ignore -->
  19 for each trait for details of how to manually implement them.
  20
  21 The rest of the traits defined in the standard library can’t be implemented on
  22 your types using `derive`. These traits don’t have sensible default behavior,
  23 so it’s up to you to implement them in the way that makes sense for what you’re
  24 trying to accomplish.
  25
  26 An example of a trait that can’t be derived is `Display`, which handles
  27 formatting for end users. You should always consider the appropriate way to
  28 display a type to an end user. What parts of the type should an end user be
  29 allowed to see? What parts would they find relevant? What format of the data
  30 would be most relevant to them? The Rust compiler doesn’t have this insight, so
  31 it can’t provide appropriate default behavior for you.
  32
  33 The list of derivable traits provided in this appendix is not comprehensive:
  34 libraries can implement `derive` for their own traits, making the list of
  35 traits you can use `derive` with truly open-ended. Implementing `derive`
  36 involves using a procedural macro, which is covered in the
  37 [“Macros”][macros]<!-- ignore --> section of Chapter 19.
  38
  39 ### `Debug` for Programmer Output
  40
  41 The `Debug` trait enables debug formatting in format strings, which you
  42 indicate by adding `:?` within `{}` placeholders.
  43
  44 The `Debug` trait allows you to print instances of a type for debugging
  45 purposes, so you and other programmers using your type can inspect an instance
  46 at a particular point in a program’s execution.
  47
  48 The `Debug` trait is required, for example, in use of the `assert_eq!` macro.
  49 This macro prints the values of instances given as arguments if the equality
  50 assertion fails so programmers can see why the two instances weren’t equal.
  51
  52 ### `PartialEq` and `Eq` for Equality Comparisons
  53
  54 The `PartialEq` trait allows you to compare instances of a type to check for
  55 equality and enables use of the `==` and `!=` operators.
  56
  57 Deriving `PartialEq` implements the `eq` method. When `PartialEq` is derived on
  58 structs, two instances are equal only if *all* fields are equal, and the
  59 instances are not equal if any fields are not equal. When derived on enums,
  60 each variant is equal to itself and not equal to the other variants.
  61
  62 The `PartialEq` trait is required, for example, with the use of the
  63 `assert_eq!` macro, which needs to be able to compare two instances of a type
  64 for equality.
  65
  66 The `Eq` trait has no methods. Its purpose is to signal that for every value of
  67 the annotated type, the value is equal to itself. The `Eq` trait can only be
  68 applied to types that also implement `PartialEq`, although not all types that
  69 implement `PartialEq` can implement `Eq`. One example of this is floating point
  70 number types: the implementation of floating point numbers states that two
  71 instances of the not-a-number (`NaN`) value are not equal to each other.
  72
  73 An example of when `Eq` is required is for keys in a `HashMap<K, V>` so the
  74 `HashMap<K, V>` can tell whether two keys are the same.
  75
  76 ### `PartialOrd` and `Ord` for Ordering Comparisons
  77
  78 The `PartialOrd` trait allows you to compare instances of a type for sorting
  79 purposes. A type that implements `PartialOrd` can be used with the `<`, `>`,
  80 `<=`, and `>=` operators. You can only apply the `PartialOrd` trait to types
  81 that also implement `PartialEq`.
  82
  83 Deriving `PartialOrd` implements the `partial_cmp` method, which returns an
  84 `Option<Ordering>` that will be `None` when the values given don’t produce an
  85 ordering. An example of a value that doesn’t produce an ordering, even though
  86 most values of that type can be compared, is the not-a-number (`NaN`) floating
  87 point value. Calling `partial_cmp` with any floating point number and the `NaN`
  88 floating point value will return `None`.
  89
  90 When derived on structs, `PartialOrd` compares two instances by comparing the
  91 value in each field in the order in which the fields appear in the struct
  92 definition. When derived on enums, variants of the enum declared earlier in the
  93 enum definition are considered less than the variants listed later.
  94
  95 The `PartialOrd` trait is required, for example, for the `gen_range` method
  96 from the `rand` crate that generates a random value in the range specified by a
  97 low value and a high value.
  98
  99 The `Ord` trait allows you to know that for any two values of the annotated
 100 type, a valid ordering will exist. The `Ord` trait implements the `cmp` method,
 101 which returns an `Ordering` rather than an `Option<Ordering>` because a valid
 102 ordering will always be possible. You can only apply the `Ord` trait to types
 103 that also implement `PartialOrd` and `Eq` (and `Eq` requires `PartialEq`). When
 104 derived on structs and enums, `cmp` behaves the same way as the derived
 105 implementation for `partial_cmp` does with `PartialOrd`.
 106
 107 An example of when `Ord` is required is when storing values in a `BTreeSet<T>`,
 108 a data structure that stores data based on the sort order of the values.
 109
 110 ### `Clone` and `Copy` for Duplicating Values
 111
 112 The `Clone` trait allows you to explicitly create a deep copy of a value, and
 113 the duplication process might involve running arbitrary code and copying heap
 114 data. See the [“Ways Variables and Data Interact:
 115 Clone”][ways-variables-and-data-interact-clone]<!-- ignore --> section in
 116 Chapter 4 for more information on `Clone`.
 117
 118 Deriving `Clone` implements the `clone` method, which when implemented for the
 119 whole type, calls `clone` on each of the parts of the type. This means all the
 120 fields or values in the type must also implement `Clone` to derive `Clone`.
 121
 122 An example of when `Clone` is required is when calling the `to_vec` method on a
 123 slice. The slice doesn’t own the type instances it contains, but the vector
 124 returned from `to_vec` will need to own its instances, so `to_vec` calls
 125 `clone` on each item. Thus, the type stored in the slice must implement `Clone`.
 126
 127 The `Copy` trait allows you to duplicate a value by only copying bits stored on
 128 the stack; no arbitrary code is necessary. See the [“Stack-Only Data:
 129 Copy”][stack-only-data-copy]<!-- ignore --> section in Chapter 4 for more
 130 information on `Copy`.
 131
 132 The `Copy` trait doesn’t define any methods to prevent programmers from
 133 overloading those methods and violating the assumption that no arbitrary code
 134 is being run. That way, all programmers can assume that copying a value will be
 135 very fast.
 136
 137 You can derive `Copy` on any type whose parts all implement `Copy`. You can
 138 only apply the `Copy` trait to types that also implement `Clone`, because a
 139 type that implements `Copy` has a trivial implementation of `Clone` that
 140 performs the same task as `Copy`.
 141
 142 The `Copy` trait is rarely required; types that implement `Copy` have
 143 optimizations available, meaning you don’t have to call `clone`, which makes
 144 the code more concise.
 145
 146 Everything possible with `Copy` you can also accomplish with `Clone`, but the
 147 code might be slower or have to use `clone` in places.
 148
 149 ### `Hash` for Mapping a Value to a Value of Fixed Size
 150
 151 The `Hash` trait allows you to take an instance of a type of arbitrary size and
 152 map that instance to a value of fixed size using a hash function. Deriving
 153 `Hash` implements the `hash` method. The derived implementation of the `hash`
 154 method combines the result of calling `hash` on each of the parts of the type,
 155 meaning all fields or values must also implement `Hash` to derive `Hash`.
 156
 157 An example of when `Hash` is required is in storing keys in a `HashMap<K, V>`
 158 to store data efficiently.
 159
 160 ### `Default` for Default Values
 161
 162 The `Default` trait allows you to create a default value for a type. Deriving
 163 `Default` implements the `default` function. The derived implementation of the
 164 `default` function calls the `default` function on each part of the type,
 165 meaning all fields or values in the type must also implement `Default` to
 166 derive `Default`.
 167
 168 The `Default::default` function is commonly used in combination with the struct
 169 update syntax discussed in the [“Creating Instances From Other Instances With
 170 Struct Update
 171 Syntax”][creating-instances-from-other-instances-with-struct-update-syntax]<!-- ignore -->
 172 section in Chapter 5. You can customize a few fields of a struct and then
 173 set and use a default value for the rest of the fields by using
 174 `..Default::default()`.
 175
 176 The `Default` trait is required when you use the method `unwrap_or_default` on
 177 `Option<T>` instances, for example. If the `Option<T>` is `None`, the method
 178 `unwrap_or_default` will return the result of `Default::default` for the type
 179 `T` stored in the `Option<T>`.
 180
 181 [creating-instances-from-other-instances-with-struct-update-syntax]:
 182 ch05-01-defining-structs.html#creating-instances-from-other-instances-with-struct-update-syntax
 183 [stack-only-data-copy]:
 184 ch04-01-what-is-ownership.html#stack-only-data-copy
 185 [ways-variables-and-data-interact-clone]:
 186 ch04-01-what-is-ownership.html#ways-variables-and-data-interact-clone
 187 [macros]: ch19-06-macros.html#macros