third_party/rust/derive_more-impl/doc/from.md

   1 # What `#[derive(From)]` generates
   2
   3 The point of deriving this type is that it makes it easy to create a new
   4 instance of the type by using the `.into()` method on the value(s) that it
   5 should contain. This is done by implementing the `From` trait for the type
   6 that is passed to the derive.
   7
   8
   9
  10
  11 ## Structs
  12
  13 For structs with a single field you can call `.into()` on the desired content
  14 itself after deriving `From`.
  15
  16 ```rust
  17 # use derive_more::From;
  18 #
  19 #[derive(Debug, From, PartialEq)]
  20 struct Int(i32);
  21
  22 assert_eq!(Int(2), 2.into());
  23 ```
  24
  25 For structs that have multiple fields `.into()` needs to be called on a tuple
  26 containing the desired content for each field.
  27
  28 ```rust
  29 # use derive_more::From;
  30 #
  31 #[derive(Debug, From, PartialEq)]
  32 struct Point(i32, i32);
  33
  34 assert_eq!(Point(1, 2), (1, 2).into());
  35 ```
  36
  37 To specify concrete types to derive convert from use `#[from(<types>)]`.
  38
  39 ```rust
  40 # use std::borrow::Cow;
  41 #
  42 # use derive_more::From;
  43 #
  44 #[derive(Debug, From, PartialEq)]
  45 #[from(Cow<'static, str>, String, &'static str)]
  46 struct Str(Cow<'static, str>);
  47
  48 assert_eq!(Str("&str".into()), "&str".into());
  49 assert_eq!(Str("String".into()), "String".to_owned().into());
  50 assert_eq!(Str("Cow".into()), Cow::Borrowed("Cow").to_owned().into());
  51
  52 #[derive(Debug, From, PartialEq)]
  53 #[from((i16, i16), (i32, i32))]
  54 struct Point {
  55     x: i32,
  56     y: i32,
  57 }
  58
  59 assert_eq!(Point { x: 1_i32, y: 2_i32 }, (1_i16, 2_i16).into());
  60 assert_eq!(Point { x: 3_i32, y: 4_i32 }, (3_i32, 4_i32).into());
  61 ```
  62
  63 Also, you can forward implementation to the inner type, which means deriving `From` for any type, that derives `From`
  64 inner type.
  65
  66 ```rust
  67 # use std::borrow::Cow;
  68 #
  69 # use derive_more::From;
  70 #
  71 #[derive(Debug, From, PartialEq)]
  72 #[from(forward)]
  73 struct Str {
  74     inner: Cow<'static, str>,
  75 }
  76
  77 assert_eq!(Str { inner: "&str".into() }, "&str".into());
  78 assert_eq!(Str { inner: "String".into() }, "String".to_owned().into());
  79 assert_eq!(Str { inner: "Cow".into() }, Cow::Borrowed("Cow").to_owned().into());
  80 ```
  81
  82
  83
  84
  85 ## Enums
  86
  87 For enums `.into()` works for each variant as if they were structs. This
  88 includes specifying concrete types via `#[from(<types>)]` or forwarding
  89 implementation with `#[from(forward)]`.
  90
  91 ```rust
  92 # use derive_more::From;
  93 #
  94 #[derive(Debug, From, PartialEq)]
  95 enum IntOrPoint {
  96     Int(i32),
  97     Point {
  98         x: i32,
  99         y: i32,
 100     },
 101 }
 102
 103 assert_eq!(IntOrPoint::Int(1), 1.into());
 104 assert_eq!(IntOrPoint::Point { x: 1, y: 2 }, (1, 2).into());
 105 ```
 106
 107 By default, `From` is generated for every enum variant, but you can skip some
 108 variants via `#[from(skip)]` or only concrete fields via `#[from]`.
 109
 110 ```rust
 111 # mod from {
 112 # use derive_more::From;
 113 #[derive(Debug, From, PartialEq)]
 114 enum Int {
 115     #[from]
 116     Derived(i32),
 117     NotDerived(i32),
 118 }
 119 # }
 120
 121 // Is equivalent to:
 122
 123 # mod skip {
 124 # use derive_more::From;
 125 #[derive(Debug, From, PartialEq)]
 126 enum Int {
 127     Derived(i32),
 128     #[from(skip)]
 129     NotDerived(i32),
 130 }
 131 # }
 132 ```
 133
 134
 135
 136
 137 ## Example usage
 138
 139 ```rust
 140 # use derive_more::From;
 141 #
 142 // Allow converting from i32
 143 #[derive(From, PartialEq)]
 144 struct MyInt(i32);
 145
 146 // Forward from call to the field, so allow converting
 147 // from anything that can be converted into an i64 (so most integers)
 148 #[derive(From, PartialEq)]
 149 #[from(forward)]
 150 struct MyInt64(i64);
 151
 152 // You can ignore a variant
 153 #[derive(From, PartialEq)]
 154 enum MyEnum {
 155     SmallInt(i32),
 156     NamedBigInt { int: i64 },
 157     #[from(ignore)]
 158     NoFromImpl(i64),
 159 }
 160
 161 // Or explicitly annotate the ones you need
 162 #[derive(From, PartialEq)]
 163 enum MyEnum2 {
 164     #[from]
 165     SmallInt(i32),
 166     #[from]
 167     NamedBigInt { int: i64 },
 168     NoFromImpl(i64),
 169 }
 170
 171 // And even specify additional conversions for them
 172 #[derive(From, PartialEq)]
 173 enum MyEnum3 {
 174     #[from(i8, i32)]
 175     SmallInt(i32),
 176     #[from(i16, i64)]
 177     NamedBigInt { int: i64 },
 178     NoFromImpl(i64),
 179 }
 180
 181 assert!(MyInt(2) == 2.into());
 182 assert!(MyInt64(6) == 6u8.into());
 183 assert!(MyEnum::SmallInt(123) == 123i32.into());
 184 assert!(MyEnum::SmallInt(123) != 123i64.into());
 185 assert!(MyEnum::NamedBigInt{int: 123} == 123i64.into());
 186 assert!(MyEnum3::SmallInt(123) == 123i8.into());
 187 assert!(MyEnum3::NamedBigInt{int: 123} == 123i16.into());
 188 ```