src/libcore/ops/arith.rs

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