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

   1 # What `#[derive(Add)]` generates
   2
   3 The derived `Add` implementation will allow two structs from the same type to be
   4 added together. This done by adding their respective fields together and
   5 creating a new struct with those values.
   6 For enums each variant can be added in a similar way to another instance of that
   7 same variant. There's one big difference however, it returns a
   8 `Result<EnumType>`, because an error is returned when to different variants are
   9 added together.
  10
  11
  12
  13
  14 ## Tuple structs
  15
  16 When deriving `Add` for a tuple struct with two fields like this:
  17
  18 ```rust
  19 # use derive_more::Add;
  20 #
  21 #[derive(Add)]
  22 struct MyInts(i32, i32);
  23 ```
  24
  25 Code like this will be generated:
  26
  27 ```rust
  28 # struct MyInts(i32, i32);
  29 impl ::core::ops::Add for MyInts {
  30     type Output = MyInts;
  31     fn add(self, rhs: MyInts) -> MyInts {
  32         MyInts(self.0.add(rhs.0), self.1.add(rhs.1))
  33     }
  34 }
  35 ```
  36
  37 The behaviour is similar with more or less fields.
  38
  39
  40
  41
  42 ## Regular structs
  43
  44 When deriving `Add` for a regular struct with two fields like this:
  45
  46 ```rust
  47 # use derive_more::Add;
  48 #
  49 #[derive(Add)]
  50 struct Point2D {
  51     x: i32,
  52     y: i32,
  53 }
  54 ```
  55
  56 Code like this will be generated:
  57
  58 ```rust
  59 # struct Point2D {
  60 #     x: i32,
  61 #     y: i32,
  62 # }
  63 impl ::core::ops::Add for Point2D {
  64     type Output = Point2D;
  65     fn add(self, rhs: Point2D) -> Point2D {
  66         Point2D {
  67             x: self.x.add(rhs.x),
  68             y: self.y.add(rhs.y),
  69         }
  70     }
  71 }
  72 ```
  73
  74 The behaviour is similar for more or less fields.
  75
  76
  77
  78
  79 ## Enums
  80
  81 There's a big difference between the code that is generated for the two struct
  82 types and the one that is generated for enums. The code for enums returns
  83 `Result<EnumType>` instead of an `EnumType` itself. This is because adding an
  84 enum to another enum is only possible if both are the same variant. This makes
  85 the generated code much more complex as well, because this check needs to be
  86 done. For instance when deriving `Add` for an enum like this:
  87
  88 ```rust
  89 # use derive_more::Add;
  90 #
  91 #[derive(Add)]
  92 enum MixedInts {
  93     SmallInt(i32),
  94     BigInt(i64),
  95     TwoSmallInts(i32, i32),
  96     NamedSmallInts { x: i32, y: i32 },
  97     UnsignedOne(u32),
  98     UnsignedTwo(u32),
  99     Unit,
 100 }
 101 ```
 102
 103 Code like this will be generated:
 104
 105 ```rust
 106 # enum MixedInts {
 107 #     SmallInt(i32),
 108 #     BigInt(i64),
 109 #     TwoSmallInts(i32, i32),
 110 #     NamedSmallInts { x: i32, y: i32 },
 111 #     UnsignedOne(u32),
 112 #     UnsignedTwo(u32),
 113 #     Unit,
 114 # }
 115 impl ::core::ops::Add for MixedInts {
 116     type Output = Result<MixedInts, ::derive_more::ops::BinaryError>;
 117     fn add(self, rhs: MixedInts) -> Result<MixedInts, ::derive_more::ops::BinaryError> {
 118         match (self, rhs) {
 119             (MixedInts::SmallInt(__l_0), MixedInts::SmallInt(__r_0)) => {
 120                 Ok(MixedInts::SmallInt(__l_0.add(__r_0)))
 121             }
 122             (MixedInts::BigInt(__l_0), MixedInts::BigInt(__r_0)) => {
 123                 Ok(MixedInts::BigInt(__l_0.add(__r_0)))
 124             }
 125             (MixedInts::TwoSmallInts(__l_0, __l_1), MixedInts::TwoSmallInts(__r_0, __r_1)) => {
 126                 Ok(MixedInts::TwoSmallInts(__l_0.add(__r_0), __l_1.add(__r_1)))
 127             }
 128             (MixedInts::NamedSmallInts { x: __l_0, y: __l_1 },
 129              MixedInts::NamedSmallInts { x: __r_0, y: __r_1 }) => {
 130                 Ok(MixedInts::NamedSmallInts {
 131                     x: __l_0.add(__r_0),
 132                     y: __l_1.add(__r_1),
 133                 })
 134             }
 135             (MixedInts::UnsignedOne(__l_0), MixedInts::UnsignedOne(__r_0)) => {
 136                 Ok(MixedInts::UnsignedOne(__l_0.add(__r_0)))
 137             }
 138             (MixedInts::UnsignedTwo(__l_0), MixedInts::UnsignedTwo(__r_0)) => {
 139                 Ok(MixedInts::UnsignedTwo(__l_0.add(__r_0)))
 140             }
 141             (MixedInts::Unit, MixedInts::Unit) => Err(::derive_more::ops::BinaryError::Unit(
 142                 ::derive_more::ops::UnitError::new("add"),
 143             )),
 144             _ => Err(::derive_more::ops::BinaryError::Mismatch(
 145                 ::derive_more::ops::WrongVariantError::new("add"),
 146             )),
 147         }
 148     }
 149 }
 150 ```
 151
 152 Also note the Unit type that throws an error when adding it to itself.