library/core/src/ops/arith.rs

   1 /// The addition operator `+`.
   2 ///
   3 /// Note that `Rhs` is `Self` by default, but this is not mandatory. For
   4 /// example, [`std::time::SystemTime`] implements `Add<Duration>`, which permits
   5 /// operations of the form `SystemTime = SystemTime + Duration`.
   6 ///
   7 /// [`std::time::SystemTime`]: ../../std/time/struct.SystemTime.html
   8 ///
   9 /// # Examples
  10 ///
  11 /// ## `Add`able points
  12 ///
  13 /// ```
  14 /// use std::ops::Add;
  15 ///
  16 /// #[derive(Debug, Copy, Clone, PartialEq)]
  17 /// struct Point {
  18 ///     x: i32,
  19 ///     y: i32,
  20 /// }
  21 ///
  22 /// impl Add for Point {
  23 ///     type Output = Self;
  24 ///
  25 ///     fn add(self, other: Self) -> Self {
  26 ///         Self {
  27 ///             x: self.x + other.x,
  28 ///             y: self.y + other.y,
  29 ///         }
  30 ///     }
  31 /// }
  32 ///
  33 /// assert_eq!(Point { x: 1, y: 0 } + Point { x: 2, y: 3 },
  34 ///            Point { x: 3, y: 3 });
  35 /// ```
  36 ///
  37 /// ## Implementing `Add` with generics
  38 ///
  39 /// Here is an example of the same `Point` struct implementing the `Add` trait
  40 /// using generics.
  41 ///
  42 /// ```
  43 /// use std::ops::Add;
  44 ///
  45 /// #[derive(Debug, Copy, Clone, PartialEq)]
  46 /// struct Point<T> {
  47 ///     x: T,
  48 ///     y: T,
  49 /// }
  50 ///
  51 /// // Notice that the implementation uses the associated type `Output`.
  52 /// impl<T: Add<Output = T>> Add for Point<T> {
  53 ///     type Output = Self;
  54 ///
  55 ///     fn add(self, other: Self) -> Self::Output {
  56 ///         Self {
  57 ///             x: self.x + other.x,
  58 ///             y: self.y + other.y,
  59 ///         }
  60 ///     }
  61 /// }
  62 ///
  63 /// assert_eq!(Point { x: 1, y: 0 } + Point { x: 2, y: 3 },
  64 ///            Point { x: 3, y: 3 });
  65 /// ```
  66 #[lang = "add"]
  67 #[stable(feature = "rust1", since = "1.0.0")]
  68 #[rustc_on_unimplemented(
  69     on(all(_Self = "{integer}", Rhs = "{float}"), message = "cannot add a float to an integer",),
  70     on(all(_Self = "{float}", Rhs = "{integer}"), message = "cannot add an integer to a float",),
  71     message = "cannot add `{Rhs}` to `{Self}`",
  72     label = "no implementation for `{Self} + {Rhs}`"
  73 )]
  74 #[doc(alias = "+")]
  75 pub trait Add<Rhs = Self> {
  76     /// The resulting type after applying the `+` operator.
  77     #[stable(feature = "rust1", since = "1.0.0")]
  78     type Output;
  79
  80     /// Performs the `+` operation.
  81     ///
  82     /// # Example
  83     ///
  84     /// ```
  85     /// assert_eq!(12 + 1, 13);
  86     /// ```
  87     #[must_use]
  88     #[stable(feature = "rust1", since = "1.0.0")]
  89     fn add(self, rhs: Rhs) -> Self::Output;
  90 }
  91
  92 macro_rules! add_impl {
  93     ($($t:ty)*) => ($(
  94         #[stable(feature = "rust1", since = "1.0.0")]
  95         impl Add for $t {
  96             type Output = $t;
  97
  98             #[inline]
  99             #[rustc_inherit_overflow_checks]
 100             fn add(self, other: $t) -> $t { self + other }
 101         }
 102
 103         forward_ref_binop! { impl Add, add for $t, $t }
 104     )*)
 105 }
 106
 107 add_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 }
 108
 109 /// The subtraction operator `-`.
 110 ///
 111 /// Note that `Rhs` is `Self` by default, but this is not mandatory. For
 112 /// example, [`std::time::SystemTime`] implements `Sub<Duration>`, which permits
 113 /// operations of the form `SystemTime = SystemTime - Duration`.
 114 ///
 115 /// [`std::time::SystemTime`]: ../../std/time/struct.SystemTime.html
 116 ///
 117 /// # Examples
 118 ///
 119 /// ## `Sub`tractable points
 120 ///
 121 /// ```
 122 /// use std::ops::Sub;
 123 ///
 124 /// #[derive(Debug, Copy, Clone, PartialEq)]
 125 /// struct Point {
 126 ///     x: i32,
 127 ///     y: i32,
 128 /// }
 129 ///
 130 /// impl Sub for Point {
 131 ///     type Output = Self;
 132 ///
 133 ///     fn sub(self, other: Self) -> Self::Output {
 134 ///         Self {
 135 ///             x: self.x - other.x,
 136 ///             y: self.y - other.y,
 137 ///         }
 138 ///     }
 139 /// }
 140 ///
 141 /// assert_eq!(Point { x: 3, y: 3 } - Point { x: 2, y: 3 },
 142 ///            Point { x: 1, y: 0 });
 143 /// ```
 144 ///
 145 /// ## Implementing `Sub` with generics
 146 ///
 147 /// Here is an example of the same `Point` struct implementing the `Sub` trait
 148 /// using generics.
 149 ///
 150 /// ```
 151 /// use std::ops::Sub;
 152 ///
 153 /// #[derive(Debug, PartialEq)]
 154 /// struct Point<T> {
 155 ///     x: T,
 156 ///     y: T,
 157 /// }
 158 ///
 159 /// // Notice that the implementation uses the associated type `Output`.
 160 /// impl<T: Sub<Output = T>> Sub for Point<T> {
 161 ///     type Output = Self;
 162 ///
 163 ///     fn sub(self, other: Self) -> Self::Output {
 164 ///         Point {
 165 ///             x: self.x - other.x,
 166 ///             y: self.y - other.y,
 167 ///         }
 168 ///     }
 169 /// }
 170 ///
 171 /// assert_eq!(Point { x: 2, y: 3 } - Point { x: 1, y: 0 },
 172 ///            Point { x: 1, y: 3 });
 173 /// ```
 174 #[lang = "sub"]
 175 #[stable(feature = "rust1", since = "1.0.0")]
 176 #[rustc_on_unimplemented(
 177     message = "cannot subtract `{Rhs}` from `{Self}`",
 178     label = "no implementation for `{Self} - {Rhs}`"
 179 )]
 180 #[doc(alias = "-")]
 181 pub trait Sub<Rhs = Self> {
 182     /// The resulting type after applying the `-` operator.
 183     #[stable(feature = "rust1", since = "1.0.0")]
 184     type Output;
 185
 186     /// Performs the `-` operation.
 187     ///
 188     /// # Example
 189     ///
 190     /// ```
 191     /// assert_eq!(12 - 1, 11);
 192     /// ```
 193     #[must_use]
 194     #[stable(feature = "rust1", since = "1.0.0")]
 195     fn sub(self, rhs: Rhs) -> Self::Output;
 196 }
 197
 198 macro_rules! sub_impl {
 199     ($($t:ty)*) => ($(
 200         #[stable(feature = "rust1", since = "1.0.0")]
 201         impl Sub for $t {
 202             type Output = $t;
 203
 204             #[inline]
 205             #[rustc_inherit_overflow_checks]
 206             fn sub(self, other: $t) -> $t { self - other }
 207         }
 208
 209         forward_ref_binop! { impl Sub, sub for $t, $t }
 210     )*)
 211 }
 212
 213 sub_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 }
 214
 215 /// The multiplication operator `*`.
 216 ///
 217 /// Note that `Rhs` is `Self` by default, but this is not mandatory.
 218 ///
 219 /// # Examples
 220 ///
 221 /// ## `Mul`tipliable rational numbers
 222 ///
 223 /// ```
 224 /// use std::ops::Mul;
 225 ///
 226 /// // By the fundamental theorem of arithmetic, rational numbers in lowest
 227 /// // terms are unique. So, by keeping `Rational`s in reduced form, we can
 228 /// // derive `Eq` and `PartialEq`.
 229 /// #[derive(Debug, Eq, PartialEq)]
 230 /// struct Rational {
 231 ///     numerator: usize,
 232 ///     denominator: usize,
 233 /// }
 234 ///
 235 /// impl Rational {
 236 ///     fn new(numerator: usize, denominator: usize) -> Self {
 237 ///         if denominator == 0 {
 238 ///             panic!("Zero is an invalid denominator!");
 239 ///         }
 240 ///
 241 ///         // Reduce to lowest terms by dividing by the greatest common
 242 ///         // divisor.
 243 ///         let gcd = gcd(numerator, denominator);
 244 ///         Self {
 245 ///             numerator: numerator / gcd,
 246 ///             denominator: denominator / gcd,
 247 ///         }
 248 ///     }
 249 /// }
 250 ///
 251 /// impl Mul for Rational {
 252 ///     // The multiplication of rational numbers is a closed operation.
 253 ///     type Output = Self;
 254 ///
 255 ///     fn mul(self, rhs: Self) -> Self {
 256 ///         let numerator = self.numerator * rhs.numerator;
 257 ///         let denominator = self.denominator * rhs.denominator;
 258 ///         Self::new(numerator, denominator)
 259 ///     }
 260 /// }
 261 ///
 262 /// // Euclid's two-thousand-year-old algorithm for finding the greatest common
 263 /// // divisor.
 264 /// fn gcd(x: usize, y: usize) -> usize {
 265 ///     let mut x = x;
 266 ///     let mut y = y;
 267 ///     while y != 0 {
 268 ///         let t = y;
 269 ///         y = x % y;
 270 ///         x = t;
 271 ///     }
 272 ///     x
 273 /// }
 274 ///
 275 /// assert_eq!(Rational::new(1, 2), Rational::new(2, 4));
 276 /// assert_eq!(Rational::new(2, 3) * Rational::new(3, 4),
 277 ///            Rational::new(1, 2));
 278 /// ```
 279 ///
 280 /// ## Multiplying vectors by scalars as in linear algebra
 281 ///
 282 /// ```
 283 /// use std::ops::Mul;
 284 ///
 285 /// struct Scalar { value: usize }
 286 ///
 287 /// #[derive(Debug, PartialEq)]
 288 /// struct Vector { value: Vec<usize> }
 289 ///
 290 /// impl Mul<Scalar> for Vector {
 291 ///     type Output = Self;
 292 ///
 293 ///     fn mul(self, rhs: Scalar) -> Self::Output {
 294 ///         Self { value: self.value.iter().map(|v| v * rhs.value).collect() }
 295 ///     }
 296 /// }
 297 ///
 298 /// let vector = Vector { value: vec![2, 4, 6] };
 299 /// let scalar = Scalar { value: 3 };
 300 /// assert_eq!(vector * scalar, Vector { value: vec![6, 12, 18] });
 301 /// ```
 302 #[lang = "mul"]
 303 #[stable(feature = "rust1", since = "1.0.0")]
 304 #[rustc_on_unimplemented(
 305     message = "cannot multiply `{Self}` by `{Rhs}`",
 306     label = "no implementation for `{Self} * {Rhs}`"
 307 )]
 308 #[doc(alias = "*")]
 309 pub trait Mul<Rhs = Self> {
 310     /// The resulting type after applying the `*` operator.
 311     #[stable(feature = "rust1", since = "1.0.0")]
 312     type Output;
 313
 314     /// Performs the `*` operation.
 315     ///
 316     /// # Example
 317     ///
 318     /// ```
 319     /// assert_eq!(12 * 2, 24);
 320     /// ```
 321     #[must_use]
 322     #[stable(feature = "rust1", since = "1.0.0")]
 323     fn mul(self, rhs: Rhs) -> Self::Output;
 324 }
 325
 326 macro_rules! mul_impl {
 327     ($($t:ty)*) => ($(
 328         #[stable(feature = "rust1", since = "1.0.0")]
 329         impl Mul for $t {
 330             type Output = $t;
 331
 332             #[inline]
 333             #[rustc_inherit_overflow_checks]
 334             fn mul(self, other: $t) -> $t { self * other }
 335         }
 336
 337         forward_ref_binop! { impl Mul, mul for $t, $t }
 338     )*)
 339 }
 340
 341 mul_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 }
 342
 343 /// The division operator `/`.
 344 ///
 345 /// Note that `Rhs` is `Self` by default, but this is not mandatory.
 346 ///
 347 /// # Examples
 348 ///
 349 /// ## `Div`idable rational numbers
 350 ///
 351 /// ```
 352 /// use std::ops::Div;
 353 ///
 354 /// // By the fundamental theorem of arithmetic, rational numbers in lowest
 355 /// // terms are unique. So, by keeping `Rational`s in reduced form, we can
 356 /// // derive `Eq` and `PartialEq`.
 357 /// #[derive(Debug, Eq, PartialEq)]
 358 /// struct Rational {
 359 ///     numerator: usize,
 360 ///     denominator: usize,
 361 /// }
 362 ///
 363 /// impl Rational {
 364 ///     fn new(numerator: usize, denominator: usize) -> Self {
 365 ///         if denominator == 0 {
 366 ///             panic!("Zero is an invalid denominator!");
 367 ///         }
 368 ///
 369 ///         // Reduce to lowest terms by dividing by the greatest common
 370 ///         // divisor.
 371 ///         let gcd = gcd(numerator, denominator);
 372 ///         Self {
 373 ///             numerator: numerator / gcd,
 374 ///             denominator: denominator / gcd,
 375 ///         }
 376 ///     }
 377 /// }
 378 ///
 379 /// impl Div for Rational {
 380 ///     // The division of rational numbers is a closed operation.
 381 ///     type Output = Self;
 382 ///
 383 ///     fn div(self, rhs: Self) -> Self::Output {
 384 ///         if rhs.numerator == 0 {
 385 ///             panic!("Cannot divide by zero-valued `Rational`!");
 386 ///         }
 387 ///
 388 ///         let numerator = self.numerator * rhs.denominator;
 389 ///         let denominator = self.denominator * rhs.numerator;
 390 ///         Self::new(numerator, denominator)
 391 ///     }
 392 /// }
 393 ///
 394 /// // Euclid's two-thousand-year-old algorithm for finding the greatest common
 395 /// // divisor.
 396 /// fn gcd(x: usize, y: usize) -> usize {
 397 ///     let mut x = x;
 398 ///     let mut y = y;
 399 ///     while y != 0 {
 400 ///         let t = y;
 401 ///         y = x % y;
 402 ///         x = t;
 403 ///     }
 404 ///     x
 405 /// }
 406 ///
 407 /// assert_eq!(Rational::new(1, 2), Rational::new(2, 4));
 408 /// assert_eq!(Rational::new(1, 2) / Rational::new(3, 4),
 409 ///            Rational::new(2, 3));
 410 /// ```
 411 ///
 412 /// ## Dividing vectors by scalars as in linear algebra
 413 ///
 414 /// ```
 415 /// use std::ops::Div;
 416 ///
 417 /// struct Scalar { value: f32 }
 418 ///
 419 /// #[derive(Debug, PartialEq)]
 420 /// struct Vector { value: Vec<f32> }
 421 ///
 422 /// impl Div<Scalar> for Vector {
 423 ///     type Output = Self;
 424 ///
 425 ///     fn div(self, rhs: Scalar) -> Self::Output {
 426 ///         Self { value: self.value.iter().map(|v| v / rhs.value).collect() }
 427 ///     }
 428 /// }
 429 ///
 430 /// let scalar = Scalar { value: 2f32 };
 431 /// let vector = Vector { value: vec![2f32, 4f32, 6f32] };
 432 /// assert_eq!(vector / scalar, Vector { value: vec![1f32, 2f32, 3f32] });
 433 /// ```
 434 #[lang = "div"]
 435 #[stable(feature = "rust1", since = "1.0.0")]
 436 #[rustc_on_unimplemented(
 437     message = "cannot divide `{Self}` by `{Rhs}`",
 438     label = "no implementation for `{Self} / {Rhs}`"
 439 )]
 440 #[doc(alias = "/")]
 441 pub trait Div<Rhs = Self> {
 442     /// The resulting type after applying the `/` operator.
 443     #[stable(feature = "rust1", since = "1.0.0")]
 444     type Output;
 445
 446     /// Performs the `/` operation.
 447     ///
 448     /// # Example
 449     ///
 450     /// ```
 451     /// assert_eq!(12 / 2, 6);
 452     /// ```
 453     #[must_use]
 454     #[stable(feature = "rust1", since = "1.0.0")]
 455     fn div(self, rhs: Rhs) -> Self::Output;
 456 }
 457
 458 macro_rules! div_impl_integer {
 459     ($(($($t:ty)*) => $panic:expr),*) => ($($(
 460         /// This operation rounds towards zero, truncating any
 461         /// fractional part of the exact result.
 462         ///
 463         /// # Panics
 464         ///
 465         #[doc = $panic]
 466         #[stable(feature = "rust1", since = "1.0.0")]
 467         impl Div for $t {
 468             type Output = $t;
 469
 470             #[inline]
 471             fn div(self, other: $t) -> $t { self / other }
 472         }
 473
 474         forward_ref_binop! { impl Div, div for $t, $t }
 475     )*)*)
 476 }
 477
 478 div_impl_integer! {
 479     (usize u8 u16 u32 u64 u128) => "This operation will panic if `other == 0`.",
 480     (isize i8 i16 i32 i64 i128) => "This operation will panic if `other == 0` or the division results in overflow."
 481 }
 482
 483 macro_rules! div_impl_float {
 484     ($($t:ty)*) => ($(
 485         #[stable(feature = "rust1", since = "1.0.0")]
 486         impl Div for $t {
 487             type Output = $t;
 488
 489             #[inline]
 490             fn div(self, other: $t) -> $t { self / other }
 491         }
 492
 493         forward_ref_binop! { impl Div, div for $t, $t }
 494     )*)
 495 }
 496
 497 div_impl_float! { f32 f64 }
 498
 499 /// The remainder operator `%`.
 500 ///
 501 /// Note that `Rhs` is `Self` by default, but this is not mandatory.
 502 ///
 503 /// # Examples
 504 ///
 505 /// This example implements `Rem` on a `SplitSlice` object. After `Rem` is
 506 /// implemented, one can use the `%` operator to find out what the remaining
 507 /// elements of the slice would be after splitting it into equal slices of a
 508 /// given length.
 509 ///
 510 /// ```
 511 /// use std::ops::Rem;
 512 ///
 513 /// #[derive(PartialEq, Debug)]
 514 /// struct SplitSlice<'a, T: 'a> {
 515 ///     slice: &'a [T],
 516 /// }
 517 ///
 518 /// impl<'a, T> Rem<usize> for SplitSlice<'a, T> {
 519 ///     type Output = Self;
 520 ///
 521 ///     fn rem(self, modulus: usize) -> Self::Output {
 522 ///         let len = self.slice.len();
 523 ///         let rem = len % modulus;
 524 ///         let start = len - rem;
 525 ///         Self {slice: &self.slice[start..]}
 526 ///     }
 527 /// }
 528 ///
 529 /// // If we were to divide &[0, 1, 2, 3, 4, 5, 6, 7] into slices of size 3,
 530 /// // the remainder would be &[6, 7].
 531 /// assert_eq!(SplitSlice { slice: &[0, 1, 2, 3, 4, 5, 6, 7] } % 3,
 532 ///            SplitSlice { slice: &[6, 7] });
 533 /// ```
 534 #[lang = "rem"]
 535 #[stable(feature = "rust1", since = "1.0.0")]
 536 #[rustc_on_unimplemented(
 537     message = "cannot mod `{Self}` by `{Rhs}`",
 538     label = "no implementation for `{Self} % {Rhs}`"
 539 )]
 540 #[doc(alias = "%")]
 541 pub trait Rem<Rhs = Self> {
 542     /// The resulting type after applying the `%` operator.
 543     #[stable(feature = "rust1", since = "1.0.0")]
 544     type Output;
 545
 546     /// Performs the `%` operation.
 547     ///
 548     /// # Example
 549     ///
 550     /// ```
 551     /// assert_eq!(12 % 10, 2);
 552     /// ```
 553     #[must_use]
 554     #[stable(feature = "rust1", since = "1.0.0")]
 555     fn rem(self, rhs: Rhs) -> Self::Output;
 556 }
 557
 558 macro_rules! rem_impl_integer {
 559     ($(($($t:ty)*) => $panic:expr),*) => ($($(
 560         /// This operation satisfies `n % d == n - (n / d) * d`. The
 561         /// result has the same sign as the left operand.
 562         ///
 563         /// # Panics
 564         ///
 565         #[doc = $panic]
 566         #[stable(feature = "rust1", since = "1.0.0")]
 567         impl Rem for $t {
 568             type Output = $t;
 569
 570             #[inline]
 571             fn rem(self, other: $t) -> $t { self % other }
 572         }
 573
 574         forward_ref_binop! { impl Rem, rem for $t, $t }
 575     )*)*)
 576 }
 577
 578 rem_impl_integer! {
 579     (usize u8 u16 u32 u64 u128) => "This operation will panic if `other == 0`.",
 580     (isize i8 i16 i32 i64 i128) => "This operation will panic if `other == 0` or if `self / other` results in overflow."
 581 }
 582
 583 macro_rules! rem_impl_float {
 584     ($($t:ty)*) => ($(
 585
 586         /// The remainder from the division of two floats.
 587         ///
 588         /// The remainder has the same sign as the dividend and is computed as:
 589         /// `x - (x / y).trunc() * y`.
 590         ///
 591         /// # Examples
 592         /// ```
 593         /// let x: f32 = 50.50;
 594         /// let y: f32 = 8.125;
 595         /// let remainder = x - (x / y).trunc() * y;
 596         ///
 597         /// // The answer to both operations is 1.75
 598         /// assert_eq!(x % y, remainder);
 599         /// ```
 600         #[stable(feature = "rust1", since = "1.0.0")]
 601         impl Rem for $t {
 602             type Output = $t;
 603
 604             #[inline]
 605             fn rem(self, other: $t) -> $t { self % other }
 606         }
 607
 608         forward_ref_binop! { impl Rem, rem for $t, $t }
 609     )*)
 610 }
 611
 612 rem_impl_float! { f32 f64 }
 613
 614 /// The unary negation operator `-`.
 615 ///
 616 /// # Examples
 617 ///
 618 /// An implementation of `Neg` for `Sign`, which allows the use of `-` to
 619 /// negate its value.
 620 ///
 621 /// ```
 622 /// use std::ops::Neg;
 623 ///
 624 /// #[derive(Debug, PartialEq)]
 625 /// enum Sign {
 626 ///     Negative,
 627 ///     Zero,
 628 ///     Positive,
 629 /// }
 630 ///
 631 /// impl Neg for Sign {
 632 ///     type Output = Self;
 633 ///
 634 ///     fn neg(self) -> Self::Output {
 635 ///         match self {
 636 ///             Sign::Negative => Sign::Positive,
 637 ///             Sign::Zero => Sign::Zero,
 638 ///             Sign::Positive => Sign::Negative,
 639 ///         }
 640 ///     }
 641 /// }
 642 ///
 643 /// // A negative positive is a negative.
 644 /// assert_eq!(-Sign::Positive, Sign::Negative);
 645 /// // A double negative is a positive.
 646 /// assert_eq!(-Sign::Negative, Sign::Positive);
 647 /// // Zero is its own negation.
 648 /// assert_eq!(-Sign::Zero, Sign::Zero);
 649 /// ```
 650 #[lang = "neg"]
 651 #[stable(feature = "rust1", since = "1.0.0")]
 652 #[doc(alias = "-")]
 653 pub trait Neg {
 654     /// The resulting type after applying the `-` operator.
 655     #[stable(feature = "rust1", since = "1.0.0")]
 656     type Output;
 657
 658     /// Performs the unary `-` operation.
 659     ///
 660     /// # Example
 661     ///
 662     /// ```
 663     /// let x: i32 = 12;
 664     /// assert_eq!(-x, -12);
 665     /// ```
 666     #[must_use]
 667     #[stable(feature = "rust1", since = "1.0.0")]
 668     fn neg(self) -> Self::Output;
 669 }
 670
 671 macro_rules! neg_impl {
 672     ($($t:ty)*) => ($(
 673         #[stable(feature = "rust1", since = "1.0.0")]
 674         impl Neg for $t {
 675             type Output = $t;
 676
 677             #[inline]
 678             #[rustc_inherit_overflow_checks]
 679             fn neg(self) -> $t { -self }
 680         }
 681
 682         forward_ref_unop! { impl Neg, neg for $t }
 683     )*)
 684 }
 685
 686 neg_impl! { isize i8 i16 i32 i64 i128 f32 f64 }
 687
 688 /// The addition assignment operator `+=`.
 689 ///
 690 /// # Examples
 691 ///
 692 /// This example creates a `Point` struct that implements the `AddAssign`
 693 /// trait, and then demonstrates add-assigning to a mutable `Point`.
 694 ///
 695 /// ```
 696 /// use std::ops::AddAssign;
 697 ///
 698 /// #[derive(Debug, Copy, Clone, PartialEq)]
 699 /// struct Point {
 700 ///     x: i32,
 701 ///     y: i32,
 702 /// }
 703 ///
 704 /// impl AddAssign for Point {
 705 ///     fn add_assign(&mut self, other: Self) {
 706 ///         *self = Self {
 707 ///             x: self.x + other.x,
 708 ///             y: self.y + other.y,
 709 ///         };
 710 ///     }
 711 /// }
 712 ///
 713 /// let mut point = Point { x: 1, y: 0 };
 714 /// point += Point { x: 2, y: 3 };
 715 /// assert_eq!(point, Point { x: 3, y: 3 });
 716 /// ```
 717 #[lang = "add_assign"]
 718 #[stable(feature = "op_assign_traits", since = "1.8.0")]
 719 #[rustc_on_unimplemented(
 720     message = "cannot add-assign `{Rhs}` to `{Self}`",
 721     label = "no implementation for `{Self} += {Rhs}`"
 722 )]
 723 #[doc(alias = "+")]
 724 #[doc(alias = "+=")]
 725 pub trait AddAssign<Rhs = Self> {
 726     /// Performs the `+=` operation.
 727     ///
 728     /// # Example
 729     ///
 730     /// ```
 731     /// let mut x: u32 = 12;
 732     /// x += 1;
 733     /// assert_eq!(x, 13);
 734     /// ```
 735     #[stable(feature = "op_assign_traits", since = "1.8.0")]
 736     fn add_assign(&mut self, rhs: Rhs);
 737 }
 738
 739 macro_rules! add_assign_impl {
 740     ($($t:ty)+) => ($(
 741         #[stable(feature = "op_assign_traits", since = "1.8.0")]
 742         impl AddAssign for $t {
 743             #[inline]
 744             #[rustc_inherit_overflow_checks]
 745             fn add_assign(&mut self, other: $t) { *self += other }
 746         }
 747
 748         forward_ref_op_assign! { impl AddAssign, add_assign for $t, $t }
 749     )+)
 750 }
 751
 752 add_assign_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 }
 753
 754 /// The subtraction assignment operator `-=`.
 755 ///
 756 /// # Examples
 757 ///
 758 /// This example creates a `Point` struct that implements the `SubAssign`
 759 /// trait, and then demonstrates sub-assigning to a mutable `Point`.
 760 ///
 761 /// ```
 762 /// use std::ops::SubAssign;
 763 ///
 764 /// #[derive(Debug, Copy, Clone, PartialEq)]
 765 /// struct Point {
 766 ///     x: i32,
 767 ///     y: i32,
 768 /// }
 769 ///
 770 /// impl SubAssign for Point {
 771 ///     fn sub_assign(&mut self, other: Self) {
 772 ///         *self = Self {
 773 ///             x: self.x - other.x,
 774 ///             y: self.y - other.y,
 775 ///         };
 776 ///     }
 777 /// }
 778 ///
 779 /// let mut point = Point { x: 3, y: 3 };
 780 /// point -= Point { x: 2, y: 3 };
 781 /// assert_eq!(point, Point {x: 1, y: 0});
 782 /// ```
 783 #[lang = "sub_assign"]
 784 #[stable(feature = "op_assign_traits", since = "1.8.0")]
 785 #[rustc_on_unimplemented(
 786     message = "cannot subtract-assign `{Rhs}` from `{Self}`",
 787     label = "no implementation for `{Self} -= {Rhs}`"
 788 )]
 789 #[doc(alias = "-")]
 790 #[doc(alias = "-=")]
 791 pub trait SubAssign<Rhs = Self> {
 792     /// Performs the `-=` operation.
 793     ///
 794     /// # Example
 795     ///
 796     /// ```
 797     /// let mut x: u32 = 12;
 798     /// x -= 1;
 799     /// assert_eq!(x, 11);
 800     /// ```
 801     #[stable(feature = "op_assign_traits", since = "1.8.0")]
 802     fn sub_assign(&mut self, rhs: Rhs);
 803 }
 804
 805 macro_rules! sub_assign_impl {
 806     ($($t:ty)+) => ($(
 807         #[stable(feature = "op_assign_traits", since = "1.8.0")]
 808         impl SubAssign for $t {
 809             #[inline]
 810             #[rustc_inherit_overflow_checks]
 811             fn sub_assign(&mut self, other: $t) { *self -= other }
 812         }
 813
 814         forward_ref_op_assign! { impl SubAssign, sub_assign for $t, $t }
 815     )+)
 816 }
 817
 818 sub_assign_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 }
 819
 820 /// The multiplication assignment operator `*=`.
 821 ///
 822 /// # Examples
 823 ///
 824 /// ```
 825 /// use std::ops::MulAssign;
 826 ///
 827 /// #[derive(Debug, PartialEq)]
 828 /// struct Frequency { hertz: f64 }
 829 ///
 830 /// impl MulAssign<f64> for Frequency {
 831 ///     fn mul_assign(&mut self, rhs: f64) {
 832 ///         self.hertz *= rhs;
 833 ///     }
 834 /// }
 835 ///
 836 /// let mut frequency = Frequency { hertz: 50.0 };
 837 /// frequency *= 4.0;
 838 /// assert_eq!(Frequency { hertz: 200.0 }, frequency);
 839 /// ```
 840 #[lang = "mul_assign"]
 841 #[stable(feature = "op_assign_traits", since = "1.8.0")]
 842 #[rustc_on_unimplemented(
 843     message = "cannot multiply-assign `{Self}` by `{Rhs}`",
 844     label = "no implementation for `{Self} *= {Rhs}`"
 845 )]
 846 #[doc(alias = "*")]
 847 #[doc(alias = "*=")]
 848 pub trait MulAssign<Rhs = Self> {
 849     /// Performs the `*=` operation.
 850     ///
 851     /// # Example
 852     ///
 853     /// ```
 854     /// let mut x: u32 = 12;
 855     /// x *= 2;
 856     /// assert_eq!(x, 24);
 857     /// ```
 858     #[stable(feature = "op_assign_traits", since = "1.8.0")]
 859     fn mul_assign(&mut self, rhs: Rhs);
 860 }
 861
 862 macro_rules! mul_assign_impl {
 863     ($($t:ty)+) => ($(
 864         #[stable(feature = "op_assign_traits", since = "1.8.0")]
 865         impl MulAssign for $t {
 866             #[inline]
 867             #[rustc_inherit_overflow_checks]
 868             fn mul_assign(&mut self, other: $t) { *self *= other }
 869         }
 870
 871         forward_ref_op_assign! { impl MulAssign, mul_assign for $t, $t }
 872     )+)
 873 }
 874
 875 mul_assign_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 }
 876
 877 /// The division assignment operator `/=`.
 878 ///
 879 /// # Examples
 880 ///
 881 /// ```
 882 /// use std::ops::DivAssign;
 883 ///
 884 /// #[derive(Debug, PartialEq)]
 885 /// struct Frequency { hertz: f64 }
 886 ///
 887 /// impl DivAssign<f64> for Frequency {
 888 ///     fn div_assign(&mut self, rhs: f64) {
 889 ///         self.hertz /= rhs;
 890 ///     }
 891 /// }
 892 ///
 893 /// let mut frequency = Frequency { hertz: 200.0 };
 894 /// frequency /= 4.0;
 895 /// assert_eq!(Frequency { hertz: 50.0 }, frequency);
 896 /// ```
 897 #[lang = "div_assign"]
 898 #[stable(feature = "op_assign_traits", since = "1.8.0")]
 899 #[rustc_on_unimplemented(
 900     message = "cannot divide-assign `{Self}` by `{Rhs}`",
 901     label = "no implementation for `{Self} /= {Rhs}`"
 902 )]
 903 #[doc(alias = "/")]
 904 #[doc(alias = "/=")]
 905 pub trait DivAssign<Rhs = Self> {
 906     /// Performs the `/=` operation.
 907     ///
 908     /// # Example
 909     ///
 910     /// ```
 911     /// let mut x: u32 = 12;
 912     /// x /= 2;
 913     /// assert_eq!(x, 6);
 914     /// ```
 915     #[stable(feature = "op_assign_traits", since = "1.8.0")]
 916     fn div_assign(&mut self, rhs: Rhs);
 917 }
 918
 919 macro_rules! div_assign_impl {
 920     ($($t:ty)+) => ($(
 921         #[stable(feature = "op_assign_traits", since = "1.8.0")]
 922         impl DivAssign for $t {
 923             #[inline]
 924             fn div_assign(&mut self, other: $t) { *self /= other }
 925         }
 926
 927         forward_ref_op_assign! { impl DivAssign, div_assign for $t, $t }
 928     )+)
 929 }
 930
 931 div_assign_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 }
 932
 933 /// The remainder assignment operator `%=`.
 934 ///
 935 /// # Examples
 936 ///
 937 /// ```
 938 /// use std::ops::RemAssign;
 939 ///
 940 /// struct CookieJar { cookies: u32 }
 941 ///
 942 /// impl RemAssign<u32> for CookieJar {
 943 ///     fn rem_assign(&mut self, piles: u32) {
 944 ///         self.cookies %= piles;
 945 ///     }
 946 /// }
 947 ///
 948 /// let mut jar = CookieJar { cookies: 31 };
 949 /// let piles = 4;
 950 ///
 951 /// println!("Splitting up {} cookies into {} even piles!", jar.cookies, piles);
 952 ///
 953 /// jar %= piles;
 954 ///
 955 /// println!("{} cookies remain in the cookie jar!", jar.cookies);
 956 /// ```
 957 #[lang = "rem_assign"]
 958 #[stable(feature = "op_assign_traits", since = "1.8.0")]
 959 #[rustc_on_unimplemented(
 960     message = "cannot mod-assign `{Self}` by `{Rhs}``",
 961     label = "no implementation for `{Self} %= {Rhs}`"
 962 )]
 963 #[doc(alias = "%")]
 964 #[doc(alias = "%=")]
 965 pub trait RemAssign<Rhs = Self> {
 966     /// Performs the `%=` operation.
 967     ///
 968     /// # Example
 969     ///
 970     /// ```
 971     /// let mut x: u32 = 12;
 972     /// x %= 10;
 973     /// assert_eq!(x, 2);
 974     /// ```
 975     #[stable(feature = "op_assign_traits", since = "1.8.0")]
 976     fn rem_assign(&mut self, rhs: Rhs);
 977 }
 978
 979 macro_rules! rem_assign_impl {
 980     ($($t:ty)+) => ($(
 981         #[stable(feature = "op_assign_traits", since = "1.8.0")]
 982         impl RemAssign for $t {
 983             #[inline]
 984             fn rem_assign(&mut self, other: $t) { *self %= other }
 985         }
 986
 987         forward_ref_op_assign! { impl RemAssign, rem_assign for $t, $t }
 988     )+)
 989 }
 990
 991 rem_assign_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 }