src/libcore/ops.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 //! Overloadable operators
  12 //!
  13 //! Implementing these traits allows you to get an effect similar to
  14 //! overloading operators.
  15 //!
  16 //! Some of these traits are imported by the prelude, so they are available in
  17 //! every Rust program.
  18 //!
  19 //! Many of the operators take their operands by value. In non-generic
  20 //! contexts involving built-in types, this is usually not a problem.
  21 //! However, using these operators in generic code, requires some
  22 //! attention if values have to be reused as opposed to letting the operators
  23 //! consume them. One option is to occasionally use `clone()`.
  24 //! Another option is to rely on the types involved providing additional
  25 //! operator implementations for references. For example, for a user-defined
  26 //! type `T` which is supposed to support addition, it is probably a good
  27 //! idea to have both `T` and `&T` implement the traits `Add<T>` and `Add<&T>`
  28 //! so that generic code can be written without unnecessary cloning.
  29 //!
  30 //! # Examples
  31 //!
  32 //! This example creates a `Point` struct that implements `Add` and `Sub`, and
  33 //! then demonstrates adding and subtracting two `Point`s.
  34 //!
  35 //! ```rust
  36 //! use std::ops::{Add, Sub};
  37 //!
  38 //! #[derive(Debug)]
  39 //! struct Point {
  40 //!     x: i32,
  41 //!     y: i32
  42 //! }
  43 //!
  44 //! impl Add for Point {
  45 //!     type Output = Point;
  46 //!
  47 //!     fn add(self, other: Point) -> Point {
  48 //!         Point {x: self.x + other.x, y: self.y + other.y}
  49 //!     }
  50 //! }
  51 //!
  52 //! impl Sub for Point {
  53 //!     type Output = Point;
  54 //!
  55 //!     fn sub(self, other: Point) -> Point {
  56 //!         Point {x: self.x - other.x, y: self.y - other.y}
  57 //!     }
  58 //! }
  59 //! fn main() {
  60 //!     println!("{:?}", Point {x: 1, y: 0} + Point {x: 2, y: 3});
  61 //!     println!("{:?}", Point {x: 1, y: 0} - Point {x: 2, y: 3});
  62 //! }
  63 //! ```
  64 //!
  65 //! See the documentation for each trait for a minimum implementation that
  66 //! prints something to the screen.
  67
  68 #![stable(feature = "rust1", since = "1.0.0")]
  69
  70 use marker::{Sized, Unsize};
  71 use fmt;
  72
  73 /// The `Drop` trait is used to run some code when a value goes out of scope.
  74 /// This is sometimes called a 'destructor'.
  75 ///
  76 /// # Examples
  77 ///
  78 /// A trivial implementation of `Drop`. The `drop` method is called when `_x`
  79 /// goes out of scope, and therefore `main` prints `Dropping!`.
  80 ///
  81 /// ```
  82 /// struct HasDrop;
  83 ///
  84 /// impl Drop for HasDrop {
  85 ///     fn drop(&mut self) {
  86 ///         println!("Dropping!");
  87 ///     }
  88 /// }
  89 ///
  90 /// fn main() {
  91 ///     let _x = HasDrop;
  92 /// }
  93 /// ```
  94 #[lang = "drop"]
  95 #[stable(feature = "rust1", since = "1.0.0")]
  96 pub trait Drop {
  97     /// A method called when the value goes out of scope.
  98     #[stable(feature = "rust1", since = "1.0.0")]
  99     fn drop(&mut self);
 100 }
 101
 102 // implements the unary operator "op &T"
 103 // based on "op T" where T is expected to be `Copy`able
 104 macro_rules! forward_ref_unop {
 105     (impl $imp:ident, $method:ident for $t:ty) => {
 106         #[stable(feature = "rust1", since = "1.0.0")]
 107         impl<'a> $imp for &'a $t {
 108             type Output = <$t as $imp>::Output;
 109
 110             #[inline]
 111             fn $method(self) -> <$t as $imp>::Output {
 112                 $imp::$method(*self)
 113             }
 114         }
 115     }
 116 }
 117
 118 // implements binary operators "&T op U", "T op &U", "&T op &U"
 119 // based on "T op U" where T and U are expected to be `Copy`able
 120 macro_rules! forward_ref_binop {
 121     (impl $imp:ident, $method:ident for $t:ty, $u:ty) => {
 122         #[stable(feature = "rust1", since = "1.0.0")]
 123         impl<'a> $imp<$u> for &'a $t {
 124             type Output = <$t as $imp<$u>>::Output;
 125
 126             #[inline]
 127             fn $method(self, other: $u) -> <$t as $imp<$u>>::Output {
 128                 $imp::$method(*self, other)
 129             }
 130         }
 131
 132         #[stable(feature = "rust1", since = "1.0.0")]
 133         impl<'a> $imp<&'a $u> for $t {
 134             type Output = <$t as $imp<$u>>::Output;
 135
 136             #[inline]
 137             fn $method(self, other: &'a $u) -> <$t as $imp<$u>>::Output {
 138                 $imp::$method(self, *other)
 139             }
 140         }
 141
 142         #[stable(feature = "rust1", since = "1.0.0")]
 143         impl<'a, 'b> $imp<&'a $u> for &'b $t {
 144             type Output = <$t as $imp<$u>>::Output;
 145
 146             #[inline]
 147             fn $method(self, other: &'a $u) -> <$t as $imp<$u>>::Output {
 148                 $imp::$method(*self, *other)
 149             }
 150         }
 151     }
 152 }
 153
 154 /// The `Add` trait is used to specify the functionality of `+`.
 155 ///
 156 /// # Examples
 157 ///
 158 /// A trivial implementation of `Add`. When `Foo + Foo` happens, it ends up
 159 /// calling `add`, and therefore, `main` prints `Adding!`.
 160 ///
 161 /// ```
 162 /// use std::ops::Add;
 163 ///
 164 /// #[derive(Copy, Clone)]
 165 /// struct Foo;
 166 ///
 167 /// impl Add for Foo {
 168 ///     type Output = Foo;
 169 ///
 170 ///     fn add(self, _rhs: Foo) -> Foo {
 171 ///         println!("Adding!");
 172 ///         self
 173 ///     }
 174 /// }
 175 ///
 176 /// fn main() {
 177 ///     Foo + Foo;
 178 /// }
 179 /// ```
 180 #[lang = "add"]
 181 #[stable(feature = "rust1", since = "1.0.0")]
 182 pub trait Add<RHS=Self> {
 183     /// The resulting type after applying the `+` operator
 184     #[stable(feature = "rust1", since = "1.0.0")]
 185     type Output;
 186
 187     /// The method for the `+` operator
 188     #[stable(feature = "rust1", since = "1.0.0")]
 189     fn add(self, rhs: RHS) -> Self::Output;
 190 }
 191
 192 macro_rules! add_impl {
 193     ($($t:ty)*) => ($(
 194         #[stable(feature = "rust1", since = "1.0.0")]
 195         impl Add for $t {
 196             type Output = $t;
 197
 198             #[inline]
 199             fn add(self, other: $t) -> $t { self + other }
 200         }
 201
 202         forward_ref_binop! { impl Add, add for $t, $t }
 203     )*)
 204 }
 205
 206 add_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 207
 208 /// The `Sub` trait is used to specify the functionality of `-`.
 209 ///
 210 /// # Examples
 211 ///
 212 /// A trivial implementation of `Sub`. When `Foo - Foo` happens, it ends up
 213 /// calling `sub`, and therefore, `main` prints `Subtracting!`.
 214 ///
 215 /// ```
 216 /// use std::ops::Sub;
 217 ///
 218 /// #[derive(Copy, Clone)]
 219 /// struct Foo;
 220 ///
 221 /// impl Sub for Foo {
 222 ///     type Output = Foo;
 223 ///
 224 ///     fn sub(self, _rhs: Foo) -> Foo {
 225 ///         println!("Subtracting!");
 226 ///         self
 227 ///     }
 228 /// }
 229 ///
 230 /// fn main() {
 231 ///     Foo - Foo;
 232 /// }
 233 /// ```
 234 #[lang = "sub"]
 235 #[stable(feature = "rust1", since = "1.0.0")]
 236 pub trait Sub<RHS=Self> {
 237     /// The resulting type after applying the `-` operator
 238     #[stable(feature = "rust1", since = "1.0.0")]
 239     type Output;
 240
 241     /// The method for the `-` operator
 242     #[stable(feature = "rust1", since = "1.0.0")]
 243     fn sub(self, rhs: RHS) -> Self::Output;
 244 }
 245
 246 macro_rules! sub_impl {
 247     ($($t:ty)*) => ($(
 248         #[stable(feature = "rust1", since = "1.0.0")]
 249         impl Sub for $t {
 250             type Output = $t;
 251
 252             #[inline]
 253             fn sub(self, other: $t) -> $t { self - other }
 254         }
 255
 256         forward_ref_binop! { impl Sub, sub for $t, $t }
 257     )*)
 258 }
 259
 260 sub_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 261
 262 /// The `Mul` trait is used to specify the functionality of `*`.
 263 ///
 264 /// # Examples
 265 ///
 266 /// A trivial implementation of `Mul`. When `Foo * Foo` happens, it ends up
 267 /// calling `mul`, and therefore, `main` prints `Multiplying!`.
 268 ///
 269 /// ```
 270 /// use std::ops::Mul;
 271 ///
 272 /// #[derive(Copy, Clone)]
 273 /// struct Foo;
 274 ///
 275 /// impl Mul for Foo {
 276 ///     type Output = Foo;
 277 ///
 278 ///     fn mul(self, _rhs: Foo) -> Foo {
 279 ///         println!("Multiplying!");
 280 ///         self
 281 ///     }
 282 /// }
 283 ///
 284 /// fn main() {
 285 ///     Foo * Foo;
 286 /// }
 287 /// ```
 288 #[lang = "mul"]
 289 #[stable(feature = "rust1", since = "1.0.0")]
 290 pub trait Mul<RHS=Self> {
 291     /// The resulting type after applying the `*` operator
 292     #[stable(feature = "rust1", since = "1.0.0")]
 293     type Output;
 294
 295     /// The method for the `*` operator
 296     #[stable(feature = "rust1", since = "1.0.0")]
 297     fn mul(self, rhs: RHS) -> Self::Output;
 298 }
 299
 300 macro_rules! mul_impl {
 301     ($($t:ty)*) => ($(
 302         #[stable(feature = "rust1", since = "1.0.0")]
 303         impl Mul for $t {
 304             type Output = $t;
 305
 306             #[inline]
 307             fn mul(self, other: $t) -> $t { self * other }
 308         }
 309
 310         forward_ref_binop! { impl Mul, mul for $t, $t }
 311     )*)
 312 }
 313
 314 mul_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 315
 316 /// The `Div` trait is used to specify the functionality of `/`.
 317 ///
 318 /// # Examples
 319 ///
 320 /// A trivial implementation of `Div`. When `Foo / Foo` happens, it ends up
 321 /// calling `div`, and therefore, `main` prints `Dividing!`.
 322 ///
 323 /// ```
 324 /// use std::ops::Div;
 325 ///
 326 /// #[derive(Copy, Clone)]
 327 /// struct Foo;
 328 ///
 329 /// impl Div for Foo {
 330 ///     type Output = Foo;
 331 ///
 332 ///     fn div(self, _rhs: Foo) -> Foo {
 333 ///         println!("Dividing!");
 334 ///         self
 335 ///     }
 336 /// }
 337 ///
 338 /// fn main() {
 339 ///     Foo / Foo;
 340 /// }
 341 /// ```
 342 #[lang = "div"]
 343 #[stable(feature = "rust1", since = "1.0.0")]
 344 pub trait Div<RHS=Self> {
 345     /// The resulting type after applying the `/` operator
 346     #[stable(feature = "rust1", since = "1.0.0")]
 347     type Output;
 348
 349     /// The method for the `/` operator
 350     #[stable(feature = "rust1", since = "1.0.0")]
 351     fn div(self, rhs: RHS) -> Self::Output;
 352 }
 353
 354 macro_rules! div_impl_integer {
 355     ($($t:ty)*) => ($(
 356         /// This operation rounds towards zero, truncating any
 357         /// fractional part of the exact result.
 358         #[stable(feature = "rust1", since = "1.0.0")]
 359         impl Div for $t {
 360             type Output = $t;
 361
 362             #[inline]
 363             fn div(self, other: $t) -> $t { self / other }
 364         }
 365
 366         forward_ref_binop! { impl Div, div for $t, $t }
 367     )*)
 368 }
 369
 370 div_impl_integer! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 371
 372 macro_rules! div_impl_float {
 373     ($($t:ty)*) => ($(
 374         #[stable(feature = "rust1", since = "1.0.0")]
 375         impl Div for $t {
 376             type Output = $t;
 377
 378             #[inline]
 379             fn div(self, other: $t) -> $t { self / other }
 380         }
 381
 382         forward_ref_binop! { impl Div, div for $t, $t }
 383     )*)
 384 }
 385
 386 div_impl_float! { f32 f64 }
 387
 388 /// The `Rem` trait is used to specify the functionality of `%`.
 389 ///
 390 /// # Examples
 391 ///
 392 /// A trivial implementation of `Rem`. When `Foo % Foo` happens, it ends up
 393 /// calling `rem`, and therefore, `main` prints `Remainder-ing!`.
 394 ///
 395 /// ```
 396 /// use std::ops::Rem;
 397 ///
 398 /// #[derive(Copy, Clone)]
 399 /// struct Foo;
 400 ///
 401 /// impl Rem for Foo {
 402 ///     type Output = Foo;
 403 ///
 404 ///     fn rem(self, _rhs: Foo) -> Foo {
 405 ///         println!("Remainder-ing!");
 406 ///         self
 407 ///     }
 408 /// }
 409 ///
 410 /// fn main() {
 411 ///     Foo % Foo;
 412 /// }
 413 /// ```
 414 #[lang = "rem"]
 415 #[stable(feature = "rust1", since = "1.0.0")]
 416 pub trait Rem<RHS=Self> {
 417     /// The resulting type after applying the `%` operator
 418     #[stable(feature = "rust1", since = "1.0.0")]
 419     type Output = Self;
 420
 421     /// The method for the `%` operator
 422     #[stable(feature = "rust1", since = "1.0.0")]
 423     fn rem(self, rhs: RHS) -> Self::Output;
 424 }
 425
 426 macro_rules! rem_impl_integer {
 427     ($($t:ty)*) => ($(
 428         /// This operation satisfies `n % d == n - (n / d) * d`.  The
 429         /// result has the same sign as the left operand.
 430         #[stable(feature = "rust1", since = "1.0.0")]
 431         impl Rem for $t {
 432             type Output = $t;
 433
 434             #[inline]
 435             fn rem(self, other: $t) -> $t { self % other }
 436         }
 437
 438         forward_ref_binop! { impl Rem, rem for $t, $t }
 439     )*)
 440 }
 441
 442 rem_impl_integer! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 443
 444 #[cfg(not(stage0))]
 445 macro_rules! rem_impl_float {
 446     ($($t:ty)*) => ($(
 447         #[stable(feature = "rust1", since = "1.0.0")]
 448         impl Rem for $t {
 449             type Output = $t;
 450
 451             #[inline]
 452             fn rem(self, other: $t) -> $t { self % other }
 453         }
 454
 455         forward_ref_binop! { impl Rem, rem for $t, $t }
 456     )*)
 457 }
 458
 459 #[cfg(not(stage0))]
 460 rem_impl_float! { f32 f64 }
 461
 462 #[stable(feature = "rust1", since = "1.0.0")]
 463 #[cfg(stage0)]
 464 impl Rem for f32 {
 465     type Output = f32;
 466
 467     // The builtin f32 rem operator is broken when targeting
 468     // MSVC; see comment in std::f32::floor.
 469     // FIXME: See also #27859.
 470     #[inline]
 471     #[cfg(target_env = "msvc")]
 472     fn rem(self, other: f32) -> f32 {
 473         (self as f64).rem(other as f64) as f32
 474     }
 475
 476     #[inline]
 477     #[cfg(not(target_env = "msvc"))]
 478     fn rem(self, other: f32) -> f32 {
 479         extern { fn fmodf(a: f32, b: f32) -> f32; }
 480         unsafe { fmodf(self, other) }
 481     }
 482 }
 483
 484 #[stable(feature = "rust1", since = "1.0.0")]
 485 #[cfg(stage0)]
 486 impl Rem for f64 {
 487     type Output = f64;
 488
 489     #[inline]
 490     fn rem(self, other: f64) -> f64 {
 491         extern { fn fmod(a: f64, b: f64) -> f64; }
 492         unsafe { fmod(self, other) }
 493     }
 494 }
 495
 496 #[cfg(stage0)]
 497 forward_ref_binop! { impl Rem, rem for f64, f64 }
 498 #[cfg(stage0)]
 499 forward_ref_binop! { impl Rem, rem for f32, f32 }
 500
 501 /// The `Neg` trait is used to specify the functionality of unary `-`.
 502 ///
 503 /// # Examples
 504 ///
 505 /// A trivial implementation of `Neg`. When `-Foo` happens, it ends up calling
 506 /// `neg`, and therefore, `main` prints `Negating!`.
 507 ///
 508 /// ```
 509 /// use std::ops::Neg;
 510 ///
 511 /// #[derive(Copy, Clone)]
 512 /// struct Foo;
 513 ///
 514 /// impl Neg for Foo {
 515 ///     type Output = Foo;
 516 ///
 517 ///     fn neg(self) -> Foo {
 518 ///         println!("Negating!");
 519 ///         self
 520 ///     }
 521 /// }
 522 ///
 523 /// fn main() {
 524 ///     -Foo;
 525 /// }
 526 /// ```
 527 #[lang = "neg"]
 528 #[stable(feature = "rust1", since = "1.0.0")]
 529 pub trait Neg {
 530     /// The resulting type after applying the `-` operator
 531     #[stable(feature = "rust1", since = "1.0.0")]
 532     type Output;
 533
 534     /// The method for the unary `-` operator
 535     #[stable(feature = "rust1", since = "1.0.0")]
 536     fn neg(self) -> Self::Output;
 537 }
 538
 539
 540
 541 macro_rules! neg_impl_core {
 542     ($id:ident => $body:expr, $($t:ty)*) => ($(
 543         #[stable(feature = "rust1", since = "1.0.0")]
 544         impl Neg for $t {
 545             type Output = $t;
 546
 547             #[inline]
 548             fn neg(self) -> $t { let $id = self; $body }
 549         }
 550
 551         forward_ref_unop! { impl Neg, neg for $t }
 552     )*)
 553 }
 554
 555 macro_rules! neg_impl_numeric {
 556     ($($t:ty)*) => { neg_impl_core!{ x => -x, $($t)*} }
 557 }
 558
 559 macro_rules! neg_impl_unsigned {
 560     ($($t:ty)*) => {
 561         neg_impl_core!{ x => {
 562             !x.wrapping_add(1)
 563         }, $($t)*} }
 564 }
 565
 566 // neg_impl_unsigned! { usize u8 u16 u32 u64 }
 567 neg_impl_numeric! { isize i8 i16 i32 i64 f32 f64 }
 568
 569 /// The `Not` trait is used to specify the functionality of unary `!`.
 570 ///
 571 /// # Examples
 572 ///
 573 /// A trivial implementation of `Not`. When `!Foo` happens, it ends up calling
 574 /// `not`, and therefore, `main` prints `Not-ing!`.
 575 ///
 576 /// ```
 577 /// use std::ops::Not;
 578 ///
 579 /// #[derive(Copy, Clone)]
 580 /// struct Foo;
 581 ///
 582 /// impl Not for Foo {
 583 ///     type Output = Foo;
 584 ///
 585 ///     fn not(self) -> Foo {
 586 ///         println!("Not-ing!");
 587 ///         self
 588 ///     }
 589 /// }
 590 ///
 591 /// fn main() {
 592 ///     !Foo;
 593 /// }
 594 /// ```
 595 #[lang = "not"]
 596 #[stable(feature = "rust1", since = "1.0.0")]
 597 pub trait Not {
 598     /// The resulting type after applying the `!` operator
 599     #[stable(feature = "rust1", since = "1.0.0")]
 600     type Output;
 601
 602     /// The method for the unary `!` operator
 603     #[stable(feature = "rust1", since = "1.0.0")]
 604     fn not(self) -> Self::Output;
 605 }
 606
 607 macro_rules! not_impl {
 608     ($($t:ty)*) => ($(
 609         #[stable(feature = "rust1", since = "1.0.0")]
 610         impl Not for $t {
 611             type Output = $t;
 612
 613             #[inline]
 614             fn not(self) -> $t { !self }
 615         }
 616
 617         forward_ref_unop! { impl Not, not for $t }
 618     )*)
 619 }
 620
 621 not_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 622
 623 /// The `BitAnd` trait is used to specify the functionality of `&`.
 624 ///
 625 /// # Examples
 626 ///
 627 /// A trivial implementation of `BitAnd`. When `Foo & Foo` happens, it ends up
 628 /// calling `bitand`, and therefore, `main` prints `Bitwise And-ing!`.
 629 ///
 630 /// ```
 631 /// use std::ops::BitAnd;
 632 ///
 633 /// #[derive(Copy, Clone)]
 634 /// struct Foo;
 635 ///
 636 /// impl BitAnd for Foo {
 637 ///     type Output = Foo;
 638 ///
 639 ///     fn bitand(self, _rhs: Foo) -> Foo {
 640 ///         println!("Bitwise And-ing!");
 641 ///         self
 642 ///     }
 643 /// }
 644 ///
 645 /// fn main() {
 646 ///     Foo & Foo;
 647 /// }
 648 /// ```
 649 #[lang = "bitand"]
 650 #[stable(feature = "rust1", since = "1.0.0")]
 651 pub trait BitAnd<RHS=Self> {
 652     /// The resulting type after applying the `&` operator
 653     #[stable(feature = "rust1", since = "1.0.0")]
 654     type Output;
 655
 656     /// The method for the `&` operator
 657     #[stable(feature = "rust1", since = "1.0.0")]
 658     fn bitand(self, rhs: RHS) -> Self::Output;
 659 }
 660
 661 macro_rules! bitand_impl {
 662     ($($t:ty)*) => ($(
 663         #[stable(feature = "rust1", since = "1.0.0")]
 664         impl BitAnd for $t {
 665             type Output = $t;
 666
 667             #[inline]
 668             fn bitand(self, rhs: $t) -> $t { self & rhs }
 669         }
 670
 671         forward_ref_binop! { impl BitAnd, bitand for $t, $t }
 672     )*)
 673 }
 674
 675 bitand_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 676
 677 /// The `BitOr` trait is used to specify the functionality of `|`.
 678 ///
 679 /// # Examples
 680 ///
 681 /// A trivial implementation of `BitOr`. When `Foo | Foo` happens, it ends up
 682 /// calling `bitor`, and therefore, `main` prints `Bitwise Or-ing!`.
 683 ///
 684 /// ```
 685 /// use std::ops::BitOr;
 686 ///
 687 /// #[derive(Copy, Clone)]
 688 /// struct Foo;
 689 ///
 690 /// impl BitOr for Foo {
 691 ///     type Output = Foo;
 692 ///
 693 ///     fn bitor(self, _rhs: Foo) -> Foo {
 694 ///         println!("Bitwise Or-ing!");
 695 ///         self
 696 ///     }
 697 /// }
 698 ///
 699 /// fn main() {
 700 ///     Foo | Foo;
 701 /// }
 702 /// ```
 703 #[lang = "bitor"]
 704 #[stable(feature = "rust1", since = "1.0.0")]
 705 pub trait BitOr<RHS=Self> {
 706     /// The resulting type after applying the `|` operator
 707     #[stable(feature = "rust1", since = "1.0.0")]
 708     type Output;
 709
 710     /// The method for the `|` operator
 711     #[stable(feature = "rust1", since = "1.0.0")]
 712     fn bitor(self, rhs: RHS) -> Self::Output;
 713 }
 714
 715 macro_rules! bitor_impl {
 716     ($($t:ty)*) => ($(
 717         #[stable(feature = "rust1", since = "1.0.0")]
 718         impl BitOr for $t {
 719             type Output = $t;
 720
 721             #[inline]
 722             fn bitor(self, rhs: $t) -> $t { self | rhs }
 723         }
 724
 725         forward_ref_binop! { impl BitOr, bitor for $t, $t }
 726     )*)
 727 }
 728
 729 bitor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 730
 731 /// The `BitXor` trait is used to specify the functionality of `^`.
 732 ///
 733 /// # Examples
 734 ///
 735 /// A trivial implementation of `BitXor`. When `Foo ^ Foo` happens, it ends up
 736 /// calling `bitxor`, and therefore, `main` prints `Bitwise Xor-ing!`.
 737 ///
 738 /// ```
 739 /// use std::ops::BitXor;
 740 ///
 741 /// #[derive(Copy, Clone)]
 742 /// struct Foo;
 743 ///
 744 /// impl BitXor for Foo {
 745 ///     type Output = Foo;
 746 ///
 747 ///     fn bitxor(self, _rhs: Foo) -> Foo {
 748 ///         println!("Bitwise Xor-ing!");
 749 ///         self
 750 ///     }
 751 /// }
 752 ///
 753 /// fn main() {
 754 ///     Foo ^ Foo;
 755 /// }
 756 /// ```
 757 #[lang = "bitxor"]
 758 #[stable(feature = "rust1", since = "1.0.0")]
 759 pub trait BitXor<RHS=Self> {
 760     /// The resulting type after applying the `^` operator
 761     #[stable(feature = "rust1", since = "1.0.0")]
 762     type Output;
 763
 764     /// The method for the `^` operator
 765     #[stable(feature = "rust1", since = "1.0.0")]
 766     fn bitxor(self, rhs: RHS) -> Self::Output;
 767 }
 768
 769 macro_rules! bitxor_impl {
 770     ($($t:ty)*) => ($(
 771         #[stable(feature = "rust1", since = "1.0.0")]
 772         impl BitXor for $t {
 773             type Output = $t;
 774
 775             #[inline]
 776             fn bitxor(self, other: $t) -> $t { self ^ other }
 777         }
 778
 779         forward_ref_binop! { impl BitXor, bitxor for $t, $t }
 780     )*)
 781 }
 782
 783 bitxor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 784
 785 /// The `Shl` trait is used to specify the functionality of `<<`.
 786 ///
 787 /// # Examples
 788 ///
 789 /// A trivial implementation of `Shl`. When `Foo << Foo` happens, it ends up
 790 /// calling `shl`, and therefore, `main` prints `Shifting left!`.
 791 ///
 792 /// ```
 793 /// use std::ops::Shl;
 794 ///
 795 /// #[derive(Copy, Clone)]
 796 /// struct Foo;
 797 ///
 798 /// impl Shl<Foo> for Foo {
 799 ///     type Output = Foo;
 800 ///
 801 ///     fn shl(self, _rhs: Foo) -> Foo {
 802 ///         println!("Shifting left!");
 803 ///         self
 804 ///     }
 805 /// }
 806 ///
 807 /// fn main() {
 808 ///     Foo << Foo;
 809 /// }
 810 /// ```
 811 #[lang = "shl"]
 812 #[stable(feature = "rust1", since = "1.0.0")]
 813 pub trait Shl<RHS> {
 814     /// The resulting type after applying the `<<` operator
 815     #[stable(feature = "rust1", since = "1.0.0")]
 816     type Output;
 817
 818     /// The method for the `<<` operator
 819     #[stable(feature = "rust1", since = "1.0.0")]
 820     fn shl(self, rhs: RHS) -> Self::Output;
 821 }
 822
 823 macro_rules! shl_impl {
 824     ($t:ty, $f:ty) => (
 825         #[stable(feature = "rust1", since = "1.0.0")]
 826         impl Shl<$f> for $t {
 827             type Output = $t;
 828
 829             #[inline]
 830             fn shl(self, other: $f) -> $t {
 831                 self << other
 832             }
 833         }
 834
 835         forward_ref_binop! { impl Shl, shl for $t, $f }
 836     )
 837 }
 838
 839 macro_rules! shl_impl_all {
 840     ($($t:ty)*) => ($(
 841         shl_impl! { $t, u8 }
 842         shl_impl! { $t, u16 }
 843         shl_impl! { $t, u32 }
 844         shl_impl! { $t, u64 }
 845         shl_impl! { $t, usize }
 846
 847         shl_impl! { $t, i8 }
 848         shl_impl! { $t, i16 }
 849         shl_impl! { $t, i32 }
 850         shl_impl! { $t, i64 }
 851         shl_impl! { $t, isize }
 852     )*)
 853 }
 854
 855 shl_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 856
 857 /// The `Shr` trait is used to specify the functionality of `>>`.
 858 ///
 859 /// # Examples
 860 ///
 861 /// A trivial implementation of `Shr`. When `Foo >> Foo` happens, it ends up
 862 /// calling `shr`, and therefore, `main` prints `Shifting right!`.
 863 ///
 864 /// ```
 865 /// use std::ops::Shr;
 866 ///
 867 /// #[derive(Copy, Clone)]
 868 /// struct Foo;
 869 ///
 870 /// impl Shr<Foo> for Foo {
 871 ///     type Output = Foo;
 872 ///
 873 ///     fn shr(self, _rhs: Foo) -> Foo {
 874 ///         println!("Shifting right!");
 875 ///         self
 876 ///     }
 877 /// }
 878 ///
 879 /// fn main() {
 880 ///     Foo >> Foo;
 881 /// }
 882 /// ```
 883 #[lang = "shr"]
 884 #[stable(feature = "rust1", since = "1.0.0")]
 885 pub trait Shr<RHS> {
 886     /// The resulting type after applying the `>>` operator
 887     #[stable(feature = "rust1", since = "1.0.0")]
 888     type Output;
 889
 890     /// The method for the `>>` operator
 891     #[stable(feature = "rust1", since = "1.0.0")]
 892     fn shr(self, rhs: RHS) -> Self::Output;
 893 }
 894
 895 macro_rules! shr_impl {
 896     ($t:ty, $f:ty) => (
 897         impl Shr<$f> for $t {
 898             type Output = $t;
 899
 900             #[inline]
 901             fn shr(self, other: $f) -> $t {
 902                 self >> other
 903             }
 904         }
 905
 906         forward_ref_binop! { impl Shr, shr for $t, $f }
 907     )
 908 }
 909
 910 macro_rules! shr_impl_all {
 911     ($($t:ty)*) => ($(
 912         shr_impl! { $t, u8 }
 913         shr_impl! { $t, u16 }
 914         shr_impl! { $t, u32 }
 915         shr_impl! { $t, u64 }
 916         shr_impl! { $t, usize }
 917
 918         shr_impl! { $t, i8 }
 919         shr_impl! { $t, i16 }
 920         shr_impl! { $t, i32 }
 921         shr_impl! { $t, i64 }
 922         shr_impl! { $t, isize }
 923     )*)
 924 }
 925
 926 shr_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 927
 928 /// The `AddAssign` trait is used to specify the functionality of `+=`.
 929 ///
 930 /// # Examples
 931 ///
 932 /// A trivial implementation of `AddAssign`. When `Foo += Foo` happens, it ends up
 933 /// calling `add_assign`, and therefore, `main` prints `Adding!`.
 934 ///
 935 /// ```
 936 /// #![feature(augmented_assignments)]
 937 /// #![feature(op_assign_traits)]
 938 ///
 939 /// use std::ops::AddAssign;
 940 ///
 941 /// #[derive(Copy, Clone)]
 942 /// struct Foo;
 943 ///
 944 /// impl AddAssign for Foo {
 945 ///     fn add_assign(&mut self, _rhs: Foo) {
 946 ///         println!("Adding!");
 947 ///     }
 948 /// }
 949 ///
 950 /// # #[allow(unused_assignments)]
 951 /// fn main() {
 952 ///     let mut foo = Foo;
 953 ///     foo += Foo;
 954 /// }
 955 /// ```
 956 #[cfg(not(stage0))]
 957 #[lang = "add_assign"]
 958 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
 959 pub trait AddAssign<Rhs=Self> {
 960     /// The method for the `+=` operator
 961     fn add_assign(&mut self, Rhs);
 962 }
 963
 964 #[cfg(not(stage0))]
 965 macro_rules! add_assign_impl {
 966     ($($t:ty)+) => ($(
 967         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
 968         impl AddAssign for $t {
 969             #[inline]
 970             fn add_assign(&mut self, other: $t) { *self += other }
 971         }
 972     )+)
 973 }
 974
 975 #[cfg(not(stage0))]
 976 add_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 977
 978 /// The `SubAssign` trait is used to specify the functionality of `-=`.
 979 ///
 980 /// # Examples
 981 ///
 982 /// A trivial implementation of `SubAssign`. When `Foo -= Foo` happens, it ends up
 983 /// calling `sub_assign`, and therefore, `main` prints `Subtracting!`.
 984 ///
 985 /// ```
 986 /// #![feature(augmented_assignments)]
 987 /// #![feature(op_assign_traits)]
 988 ///
 989 /// use std::ops::SubAssign;
 990 ///
 991 /// #[derive(Copy, Clone)]
 992 /// struct Foo;
 993 ///
 994 /// impl SubAssign for Foo {
 995 ///     fn sub_assign(&mut self, _rhs: Foo) {
 996 ///         println!("Subtracting!");
 997 ///     }
 998 /// }
 999 ///
1000 /// # #[allow(unused_assignments)]
1001 /// fn main() {
1002 ///     let mut foo = Foo;
1003 ///     foo -= Foo;
1004 /// }
1005 /// ```
1006 #[cfg(not(stage0))]
1007 #[lang = "sub_assign"]
1008 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1009 pub trait SubAssign<Rhs=Self> {
1010     /// The method for the `-=` operator
1011     fn sub_assign(&mut self, Rhs);
1012 }
1013
1014 #[cfg(not(stage0))]
1015 macro_rules! sub_assign_impl {
1016     ($($t:ty)+) => ($(
1017         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1018         impl SubAssign for $t {
1019             #[inline]
1020             fn sub_assign(&mut self, other: $t) { *self -= other }
1021         }
1022     )+)
1023 }
1024
1025 #[cfg(not(stage0))]
1026 sub_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
1027
1028 /// The `MulAssign` trait is used to specify the functionality of `*=`.
1029 ///
1030 /// # Examples
1031 ///
1032 /// A trivial implementation of `MulAssign`. When `Foo *= Foo` happens, it ends up
1033 /// calling `mul_assign`, and therefore, `main` prints `Multiplying!`.
1034 ///
1035 /// ```
1036 /// #![feature(augmented_assignments)]
1037 /// #![feature(op_assign_traits)]
1038 ///
1039 /// use std::ops::MulAssign;
1040 ///
1041 /// #[derive(Copy, Clone)]
1042 /// struct Foo;
1043 ///
1044 /// impl MulAssign for Foo {
1045 ///     fn mul_assign(&mut self, _rhs: Foo) {
1046 ///         println!("Multiplying!");
1047 ///     }
1048 /// }
1049 ///
1050 /// # #[allow(unused_assignments)]
1051 /// fn main() {
1052 ///     let mut foo = Foo;
1053 ///     foo *= Foo;
1054 /// }
1055 /// ```
1056 #[cfg(not(stage0))]
1057 #[lang = "mul_assign"]
1058 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1059 pub trait MulAssign<Rhs=Self> {
1060     /// The method for the `*=` operator
1061     fn mul_assign(&mut self, Rhs);
1062 }
1063
1064 #[cfg(not(stage0))]
1065 macro_rules! mul_assign_impl {
1066     ($($t:ty)+) => ($(
1067         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1068         impl MulAssign for $t {
1069             #[inline]
1070             fn mul_assign(&mut self, other: $t) { *self *= other }
1071         }
1072     )+)
1073 }
1074
1075 #[cfg(not(stage0))]
1076 mul_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
1077
1078 /// The `DivAssign` trait is used to specify the functionality of `/=`.
1079 ///
1080 /// # Examples
1081 ///
1082 /// A trivial implementation of `DivAssign`. When `Foo /= Foo` happens, it ends up
1083 /// calling `div_assign`, and therefore, `main` prints `Dividing!`.
1084 ///
1085 /// ```
1086 /// #![feature(augmented_assignments)]
1087 /// #![feature(op_assign_traits)]
1088 ///
1089 /// use std::ops::DivAssign;
1090 ///
1091 /// #[derive(Copy, Clone)]
1092 /// struct Foo;
1093 ///
1094 /// impl DivAssign for Foo {
1095 ///     fn div_assign(&mut self, _rhs: Foo) {
1096 ///         println!("Dividing!");
1097 ///     }
1098 /// }
1099 ///
1100 /// # #[allow(unused_assignments)]
1101 /// fn main() {
1102 ///     let mut foo = Foo;
1103 ///     foo /= Foo;
1104 /// }
1105 /// ```
1106 #[cfg(not(stage0))]
1107 #[lang = "div_assign"]
1108 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1109 pub trait DivAssign<Rhs=Self> {
1110     /// The method for the `/=` operator
1111     fn div_assign(&mut self, Rhs);
1112 }
1113
1114 #[cfg(not(stage0))]
1115 macro_rules! div_assign_impl {
1116     ($($t:ty)+) => ($(
1117         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1118         impl DivAssign for $t {
1119             #[inline]
1120             fn div_assign(&mut self, other: $t) { *self /= other }
1121         }
1122     )+)
1123 }
1124
1125 #[cfg(not(stage0))]
1126 div_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
1127
1128 /// The `RemAssign` trait is used to specify the functionality of `%=`.
1129 ///
1130 /// # Examples
1131 ///
1132 /// A trivial implementation of `RemAssign`. When `Foo %= Foo` happens, it ends up
1133 /// calling `rem_assign`, and therefore, `main` prints `Remainder-ing!`.
1134 ///
1135 /// ```
1136 /// #![feature(augmented_assignments)]
1137 /// #![feature(op_assign_traits)]
1138 ///
1139 /// use std::ops::RemAssign;
1140 ///
1141 /// #[derive(Copy, Clone)]
1142 /// struct Foo;
1143 ///
1144 /// impl RemAssign for Foo {
1145 ///     fn rem_assign(&mut self, _rhs: Foo) {
1146 ///         println!("Remainder-ing!");
1147 ///     }
1148 /// }
1149 ///
1150 /// # #[allow(unused_assignments)]
1151 /// fn main() {
1152 ///     let mut foo = Foo;
1153 ///     foo %= Foo;
1154 /// }
1155 /// ```
1156 #[cfg(not(stage0))]
1157 #[lang = "rem_assign"]
1158 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1159 pub trait RemAssign<Rhs=Self> {
1160     /// The method for the `%=` operator
1161     fn rem_assign(&mut self, Rhs);
1162 }
1163
1164 #[cfg(not(stage0))]
1165 macro_rules! rem_assign_impl {
1166     ($($t:ty)+) => ($(
1167         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1168         impl RemAssign for $t {
1169             #[inline]
1170             fn rem_assign(&mut self, other: $t) { *self %= other }
1171         }
1172     )+)
1173 }
1174
1175 #[cfg(not(stage0))]
1176 rem_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
1177
1178 /// The `BitAndAssign` trait is used to specify the functionality of `&=`.
1179 ///
1180 /// # Examples
1181 ///
1182 /// A trivial implementation of `BitAndAssign`. When `Foo &= Foo` happens, it ends up
1183 /// calling `bitand_assign`, and therefore, `main` prints `Bitwise And-ing!`.
1184 ///
1185 /// ```
1186 /// #![feature(augmented_assignments)]
1187 /// #![feature(op_assign_traits)]
1188 ///
1189 /// use std::ops::BitAndAssign;
1190 ///
1191 /// #[derive(Copy, Clone)]
1192 /// struct Foo;
1193 ///
1194 /// impl BitAndAssign for Foo {
1195 ///     fn bitand_assign(&mut self, _rhs: Foo) {
1196 ///         println!("Bitwise And-ing!");
1197 ///     }
1198 /// }
1199 ///
1200 /// # #[allow(unused_assignments)]
1201 /// fn main() {
1202 ///     let mut foo = Foo;
1203 ///     foo &= Foo;
1204 /// }
1205 /// ```
1206 #[cfg(not(stage0))]
1207 #[lang = "bitand_assign"]
1208 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1209 pub trait BitAndAssign<Rhs=Self> {
1210     /// The method for the `&` operator
1211     fn bitand_assign(&mut self, Rhs);
1212 }
1213
1214 #[cfg(not(stage0))]
1215 macro_rules! bitand_assign_impl {
1216     ($($t:ty)+) => ($(
1217         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1218         impl BitAndAssign for $t {
1219             #[inline]
1220             fn bitand_assign(&mut self, other: $t) { *self &= other }
1221         }
1222     )+)
1223 }
1224
1225 #[cfg(not(stage0))]
1226 bitand_assign_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
1227
1228 /// The `BitOrAssign` trait is used to specify the functionality of `|=`.
1229 ///
1230 /// # Examples
1231 ///
1232 /// A trivial implementation of `BitOrAssign`. When `Foo |= Foo` happens, it ends up
1233 /// calling `bitor_assign`, and therefore, `main` prints `Bitwise Or-ing!`.
1234 ///
1235 /// ```
1236 /// #![feature(augmented_assignments)]
1237 /// #![feature(op_assign_traits)]
1238 ///
1239 /// use std::ops::BitOrAssign;
1240 ///
1241 /// #[derive(Copy, Clone)]
1242 /// struct Foo;
1243 ///
1244 /// impl BitOrAssign for Foo {
1245 ///     fn bitor_assign(&mut self, _rhs: Foo) {
1246 ///         println!("Bitwise Or-ing!");
1247 ///     }
1248 /// }
1249 ///
1250 /// # #[allow(unused_assignments)]
1251 /// fn main() {
1252 ///     let mut foo = Foo;
1253 ///     foo |= Foo;
1254 /// }
1255 /// ```
1256 #[cfg(not(stage0))]
1257 #[lang = "bitor_assign"]
1258 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1259 pub trait BitOrAssign<Rhs=Self> {
1260     /// The method for the `|=` operator
1261     fn bitor_assign(&mut self, Rhs);
1262 }
1263
1264 #[cfg(not(stage0))]
1265 macro_rules! bitor_assign_impl {
1266     ($($t:ty)+) => ($(
1267         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1268         impl BitOrAssign for $t {
1269             #[inline]
1270             fn bitor_assign(&mut self, other: $t) { *self |= other }
1271         }
1272     )+)
1273 }
1274
1275 #[cfg(not(stage0))]
1276 bitor_assign_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
1277
1278 /// The `BitXorAssign` trait is used to specify the functionality of `^=`.
1279 ///
1280 /// # Examples
1281 ///
1282 /// A trivial implementation of `BitXorAssign`. When `Foo ^= Foo` happens, it ends up
1283 /// calling `bitxor_assign`, and therefore, `main` prints `Bitwise Xor-ing!`.
1284 ///
1285 /// ```
1286 /// #![feature(augmented_assignments)]
1287 /// #![feature(op_assign_traits)]
1288 ///
1289 /// use std::ops::BitXorAssign;
1290 ///
1291 /// #[derive(Copy, Clone)]
1292 /// struct Foo;
1293 ///
1294 /// impl BitXorAssign for Foo {
1295 ///     fn bitxor_assign(&mut self, _rhs: Foo) {
1296 ///         println!("Bitwise Xor-ing!");
1297 ///     }
1298 /// }
1299 ///
1300 /// # #[allow(unused_assignments)]
1301 /// fn main() {
1302 ///     let mut foo = Foo;
1303 ///     foo ^= Foo;
1304 /// }
1305 /// ```
1306 #[cfg(not(stage0))]
1307 #[lang = "bitxor_assign"]
1308 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1309 pub trait BitXorAssign<Rhs=Self> {
1310     /// The method for the `^=` operator
1311     fn bitxor_assign(&mut self, Rhs);
1312 }
1313
1314 #[cfg(not(stage0))]
1315 macro_rules! bitxor_assign_impl {
1316     ($($t:ty)+) => ($(
1317         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1318         impl BitXorAssign for $t {
1319             #[inline]
1320             fn bitxor_assign(&mut self, other: $t) { *self ^= other }
1321         }
1322     )+)
1323 }
1324
1325 #[cfg(not(stage0))]
1326 bitxor_assign_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
1327
1328 /// The `ShlAssign` trait is used to specify the functionality of `<<=`.
1329 ///
1330 /// # Examples
1331 ///
1332 /// A trivial implementation of `ShlAssign`. When `Foo <<= Foo` happens, it ends up
1333 /// calling `shl_assign`, and therefore, `main` prints `Shifting left!`.
1334 ///
1335 /// ```
1336 /// #![feature(augmented_assignments)]
1337 /// #![feature(op_assign_traits)]
1338 ///
1339 /// use std::ops::ShlAssign;
1340 ///
1341 /// #[derive(Copy, Clone)]
1342 /// struct Foo;
1343 ///
1344 /// impl ShlAssign<Foo> for Foo {
1345 ///     fn shl_assign(&mut self, _rhs: Foo) {
1346 ///         println!("Shifting left!");
1347 ///     }
1348 /// }
1349 ///
1350 /// # #[allow(unused_assignments)]
1351 /// fn main() {
1352 ///     let mut foo = Foo;
1353 ///     foo <<= Foo;
1354 /// }
1355 /// ```
1356 #[cfg(not(stage0))]
1357 #[lang = "shl_assign"]
1358 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1359 pub trait ShlAssign<Rhs> {
1360     /// The method for the `<<=` operator
1361     fn shl_assign(&mut self, Rhs);
1362 }
1363
1364 #[cfg(not(stage0))]
1365 macro_rules! shl_assign_impl {
1366     ($t:ty, $f:ty) => (
1367         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1368         impl ShlAssign<$f> for $t {
1369             #[inline]
1370             fn shl_assign(&mut self, other: $f) {
1371                 *self <<= other
1372             }
1373         }
1374     )
1375 }
1376
1377 #[cfg(not(stage0))]
1378 macro_rules! shl_assign_impl_all {
1379     ($($t:ty)*) => ($(
1380         shl_assign_impl! { $t, u8 }
1381         shl_assign_impl! { $t, u16 }
1382         shl_assign_impl! { $t, u32 }
1383         shl_assign_impl! { $t, u64 }
1384         shl_assign_impl! { $t, usize }
1385
1386         shl_assign_impl! { $t, i8 }
1387         shl_assign_impl! { $t, i16 }
1388         shl_assign_impl! { $t, i32 }
1389         shl_assign_impl! { $t, i64 }
1390         shl_assign_impl! { $t, isize }
1391     )*)
1392 }
1393
1394 #[cfg(not(stage0))]
1395 shl_assign_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
1396
1397 /// The `ShrAssign` trait is used to specify the functionality of `>>=`.
1398 ///
1399 /// # Examples
1400 ///
1401 /// A trivial implementation of `ShrAssign`. When `Foo >>= Foo` happens, it ends up
1402 /// calling `shr_assign`, and therefore, `main` prints `Shifting right!`.
1403 ///
1404 /// ```
1405 /// #![feature(augmented_assignments)]
1406 /// #![feature(op_assign_traits)]
1407 ///
1408 /// use std::ops::ShrAssign;
1409 ///
1410 /// #[derive(Copy, Clone)]
1411 /// struct Foo;
1412 ///
1413 /// impl ShrAssign<Foo> for Foo {
1414 ///     fn shr_assign(&mut self, _rhs: Foo) {
1415 ///         println!("Shifting right!");
1416 ///     }
1417 /// }
1418 ///
1419 /// # #[allow(unused_assignments)]
1420 /// fn main() {
1421 ///     let mut foo = Foo;
1422 ///     foo >>= Foo;
1423 /// }
1424 /// ```
1425 #[cfg(not(stage0))]
1426 #[lang = "shr_assign"]
1427 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1428 pub trait ShrAssign<Rhs=Self> {
1429     /// The method for the `>>=` operator
1430     fn shr_assign(&mut self, Rhs);
1431 }
1432
1433 #[cfg(not(stage0))]
1434 macro_rules! shr_assign_impl {
1435     ($t:ty, $f:ty) => (
1436         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1437         impl ShrAssign<$f> for $t {
1438             #[inline]
1439             fn shr_assign(&mut self, other: $f) {
1440                 *self >>= other
1441             }
1442         }
1443     )
1444 }
1445
1446 #[cfg(not(stage0))]
1447 macro_rules! shr_assign_impl_all {
1448     ($($t:ty)*) => ($(
1449         shr_assign_impl! { $t, u8 }
1450         shr_assign_impl! { $t, u16 }
1451         shr_assign_impl! { $t, u32 }
1452         shr_assign_impl! { $t, u64 }
1453         shr_assign_impl! { $t, usize }
1454
1455         shr_assign_impl! { $t, i8 }
1456         shr_assign_impl! { $t, i16 }
1457         shr_assign_impl! { $t, i32 }
1458         shr_assign_impl! { $t, i64 }
1459         shr_assign_impl! { $t, isize }
1460     )*)
1461 }
1462
1463 #[cfg(not(stage0))]
1464 shr_assign_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
1465
1466 /// The `Index` trait is used to specify the functionality of indexing operations
1467 /// like `arr[idx]` when used in an immutable context.
1468 ///
1469 /// # Examples
1470 ///
1471 /// A trivial implementation of `Index`. When `Foo[Bar]` happens, it ends up
1472 /// calling `index`, and therefore, `main` prints `Indexing!`.
1473 ///
1474 /// ```
1475 /// use std::ops::Index;
1476 ///
1477 /// #[derive(Copy, Clone)]
1478 /// struct Foo;
1479 /// struct Bar;
1480 ///
1481 /// impl Index<Bar> for Foo {
1482 ///     type Output = Foo;
1483 ///
1484 ///     fn index<'a>(&'a self, _index: Bar) -> &'a Foo {
1485 ///         println!("Indexing!");
1486 ///         self
1487 ///     }
1488 /// }
1489 ///
1490 /// fn main() {
1491 ///     Foo[Bar];
1492 /// }
1493 /// ```
1494 #[lang = "index"]
1495 #[rustc_on_unimplemented = "the type `{Self}` cannot be indexed by `{Idx}`"]
1496 #[stable(feature = "rust1", since = "1.0.0")]
1497 pub trait Index<Idx: ?Sized> {
1498     /// The returned type after indexing
1499     #[stable(feature = "rust1", since = "1.0.0")]
1500     type Output: ?Sized;
1501
1502     /// The method for the indexing (`Foo[Bar]`) operation
1503     #[stable(feature = "rust1", since = "1.0.0")]
1504     fn index(&self, index: Idx) -> &Self::Output;
1505 }
1506
1507 /// The `IndexMut` trait is used to specify the functionality of indexing
1508 /// operations like `arr[idx]`, when used in a mutable context.
1509 ///
1510 /// # Examples
1511 ///
1512 /// A trivial implementation of `IndexMut`. When `Foo[Bar]` happens, it ends up
1513 /// calling `index_mut`, and therefore, `main` prints `Indexing!`.
1514 ///
1515 /// ```
1516 /// use std::ops::{Index, IndexMut};
1517 ///
1518 /// #[derive(Copy, Clone)]
1519 /// struct Foo;
1520 /// struct Bar;
1521 ///
1522 /// impl Index<Bar> for Foo {
1523 ///     type Output = Foo;
1524 ///
1525 ///     fn index<'a>(&'a self, _index: Bar) -> &'a Foo {
1526 ///         self
1527 ///     }
1528 /// }
1529 ///
1530 /// impl IndexMut<Bar> for Foo {
1531 ///     fn index_mut<'a>(&'a mut self, _index: Bar) -> &'a mut Foo {
1532 ///         println!("Indexing!");
1533 ///         self
1534 ///     }
1535 /// }
1536 ///
1537 /// fn main() {
1538 ///     &mut Foo[Bar];
1539 /// }
1540 /// ```
1541 #[lang = "index_mut"]
1542 #[rustc_on_unimplemented = "the type `{Self}` cannot be mutably indexed by `{Idx}`"]
1543 #[stable(feature = "rust1", since = "1.0.0")]
1544 pub trait IndexMut<Idx: ?Sized>: Index<Idx> {
1545     /// The method for the indexing (`Foo[Bar]`) operation
1546     #[stable(feature = "rust1", since = "1.0.0")]
1547     fn index_mut(&mut self, index: Idx) -> &mut Self::Output;
1548 }
1549
1550 /// An unbounded range.
1551 #[derive(Copy, Clone, PartialEq, Eq)]
1552 #[lang = "range_full"]
1553 #[stable(feature = "rust1", since = "1.0.0")]
1554 pub struct RangeFull;
1555
1556 #[stable(feature = "rust1", since = "1.0.0")]
1557 impl fmt::Debug for RangeFull {
1558     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1559         write!(fmt, "..")
1560     }
1561 }
1562
1563 /// A (half-open) range which is bounded at both ends.
1564 #[derive(Clone, PartialEq, Eq)]
1565 #[lang = "range"]
1566 #[stable(feature = "rust1", since = "1.0.0")]
1567 pub struct Range<Idx> {
1568     /// The lower bound of the range (inclusive).
1569     #[stable(feature = "rust1", since = "1.0.0")]
1570     pub start: Idx,
1571     /// The upper bound of the range (exclusive).
1572     #[stable(feature = "rust1", since = "1.0.0")]
1573     pub end: Idx,
1574 }
1575
1576 #[stable(feature = "rust1", since = "1.0.0")]
1577 impl<Idx: fmt::Debug> fmt::Debug for Range<Idx> {
1578     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1579         write!(fmt, "{:?}..{:?}", self.start, self.end)
1580     }
1581 }
1582
1583 /// A range which is only bounded below.
1584 #[derive(Clone, PartialEq, Eq)]
1585 #[lang = "range_from"]
1586 #[stable(feature = "rust1", since = "1.0.0")]
1587 pub struct RangeFrom<Idx> {
1588     /// The lower bound of the range (inclusive).
1589     #[stable(feature = "rust1", since = "1.0.0")]
1590     pub start: Idx,
1591 }
1592
1593 #[stable(feature = "rust1", since = "1.0.0")]
1594 impl<Idx: fmt::Debug> fmt::Debug for RangeFrom<Idx> {
1595     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1596         write!(fmt, "{:?}..", self.start)
1597     }
1598 }
1599
1600 /// A range which is only bounded above.
1601 #[derive(Copy, Clone, PartialEq, Eq)]
1602 #[lang = "range_to"]
1603 #[stable(feature = "rust1", since = "1.0.0")]
1604 pub struct RangeTo<Idx> {
1605     /// The upper bound of the range (exclusive).
1606     #[stable(feature = "rust1", since = "1.0.0")]
1607     pub end: Idx,
1608 }
1609
1610 #[stable(feature = "rust1", since = "1.0.0")]
1611 impl<Idx: fmt::Debug> fmt::Debug for RangeTo<Idx> {
1612     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1613         write!(fmt, "..{:?}", self.end)
1614     }
1615 }
1616
1617 /// The `Deref` trait is used to specify the functionality of dereferencing
1618 /// operations like `*v`.
1619 ///
1620 /// `Deref` also enables ['`Deref` coercions'][coercions].
1621 ///
1622 /// [coercions]: ../../book/deref-coercions.html
1623 ///
1624 /// # Examples
1625 ///
1626 /// A struct with a single field which is accessible via dereferencing the
1627 /// struct.
1628 ///
1629 /// ```
1630 /// use std::ops::Deref;
1631 ///
1632 /// struct DerefExample<T> {
1633 ///     value: T
1634 /// }
1635 ///
1636 /// impl<T> Deref for DerefExample<T> {
1637 ///     type Target = T;
1638 ///
1639 ///     fn deref(&self) -> &T {
1640 ///         &self.value
1641 ///     }
1642 /// }
1643 ///
1644 /// fn main() {
1645 ///     let x = DerefExample { value: 'a' };
1646 ///     assert_eq!('a', *x);
1647 /// }
1648 /// ```
1649 #[lang = "deref"]
1650 #[stable(feature = "rust1", since = "1.0.0")]
1651 pub trait Deref {
1652     /// The resulting type after dereferencing
1653     #[stable(feature = "rust1", since = "1.0.0")]
1654     type Target: ?Sized;
1655
1656     /// The method called to dereference a value
1657     #[stable(feature = "rust1", since = "1.0.0")]
1658     fn deref(&self) -> &Self::Target;
1659 }
1660
1661 #[stable(feature = "rust1", since = "1.0.0")]
1662 impl<'a, T: ?Sized> Deref for &'a T {
1663     type Target = T;
1664
1665     fn deref(&self) -> &T { *self }
1666 }
1667
1668 #[stable(feature = "rust1", since = "1.0.0")]
1669 impl<'a, T: ?Sized> Deref for &'a mut T {
1670     type Target = T;
1671
1672     fn deref(&self) -> &T { *self }
1673 }
1674
1675 /// The `DerefMut` trait is used to specify the functionality of dereferencing
1676 /// mutably like `*v = 1;`
1677 ///
1678 /// `DerefMut` also enables ['`Deref` coercions'][coercions].
1679 ///
1680 /// [coercions]: ../../book/deref-coercions.html
1681 ///
1682 /// # Examples
1683 ///
1684 /// A struct with a single field which is modifiable via dereferencing the
1685 /// struct.
1686 ///
1687 /// ```
1688 /// use std::ops::{Deref, DerefMut};
1689 ///
1690 /// struct DerefMutExample<T> {
1691 ///     value: T
1692 /// }
1693 ///
1694 /// impl<T> Deref for DerefMutExample<T> {
1695 ///     type Target = T;
1696 ///
1697 ///     fn deref<'a>(&'a self) -> &'a T {
1698 ///         &self.value
1699 ///     }
1700 /// }
1701 ///
1702 /// impl<T> DerefMut for DerefMutExample<T> {
1703 ///     fn deref_mut<'a>(&'a mut self) -> &'a mut T {
1704 ///         &mut self.value
1705 ///     }
1706 /// }
1707 ///
1708 /// fn main() {
1709 ///     let mut x = DerefMutExample { value: 'a' };
1710 ///     *x = 'b';
1711 ///     assert_eq!('b', *x);
1712 /// }
1713 /// ```
1714 #[lang = "deref_mut"]
1715 #[stable(feature = "rust1", since = "1.0.0")]
1716 pub trait DerefMut: Deref {
1717     /// The method called to mutably dereference a value
1718     #[stable(feature = "rust1", since = "1.0.0")]
1719     fn deref_mut(&mut self) -> &mut Self::Target;
1720 }
1721
1722 #[stable(feature = "rust1", since = "1.0.0")]
1723 impl<'a, T: ?Sized> DerefMut for &'a mut T {
1724     fn deref_mut(&mut self) -> &mut T { *self }
1725 }
1726
1727 /// A version of the call operator that takes an immutable receiver.
1728 #[lang = "fn"]
1729 #[stable(feature = "rust1", since = "1.0.0")]
1730 #[rustc_paren_sugar]
1731 #[fundamental] // so that regex can rely that `&str: !FnMut`
1732 pub trait Fn<Args> : FnMut<Args> {
1733     /// This is called when the call operator is used.
1734     extern "rust-call" fn call(&self, args: Args) -> Self::Output;
1735 }
1736
1737 /// A version of the call operator that takes a mutable receiver.
1738 #[lang = "fn_mut"]
1739 #[stable(feature = "rust1", since = "1.0.0")]
1740 #[rustc_paren_sugar]
1741 #[fundamental] // so that regex can rely that `&str: !FnMut`
1742 pub trait FnMut<Args> : FnOnce<Args> {
1743     /// This is called when the call operator is used.
1744     extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
1745 }
1746
1747 /// A version of the call operator that takes a by-value receiver.
1748 #[lang = "fn_once"]
1749 #[stable(feature = "rust1", since = "1.0.0")]
1750 #[rustc_paren_sugar]
1751 #[fundamental] // so that regex can rely that `&str: !FnMut`
1752 pub trait FnOnce<Args> {
1753     /// The returned type after the call operator is used.
1754     type Output;
1755
1756     /// This is called when the call operator is used.
1757     extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
1758 }
1759
1760 mod impls {
1761     use marker::Sized;
1762     use super::{Fn, FnMut, FnOnce};
1763
1764     impl<'a,A,F:?Sized> Fn<A> for &'a F
1765         where F : Fn<A>
1766     {
1767         extern "rust-call" fn call(&self, args: A) -> F::Output {
1768             (**self).call(args)
1769         }
1770     }
1771
1772     impl<'a,A,F:?Sized> FnMut<A> for &'a F
1773         where F : Fn<A>
1774     {
1775         extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
1776             (**self).call(args)
1777         }
1778     }
1779
1780     impl<'a,A,F:?Sized> FnOnce<A> for &'a F
1781         where F : Fn<A>
1782     {
1783         type Output = F::Output;
1784
1785         extern "rust-call" fn call_once(self, args: A) -> F::Output {
1786             (*self).call(args)
1787         }
1788     }
1789
1790     impl<'a,A,F:?Sized> FnMut<A> for &'a mut F
1791         where F : FnMut<A>
1792     {
1793         extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
1794             (*self).call_mut(args)
1795         }
1796     }
1797
1798     impl<'a,A,F:?Sized> FnOnce<A> for &'a mut F
1799         where F : FnMut<A>
1800     {
1801         type Output = F::Output;
1802         extern "rust-call" fn call_once(mut self, args: A) -> F::Output {
1803             (*self).call_mut(args)
1804         }
1805     }
1806 }
1807
1808 /// Trait that indicates that this is a pointer or a wrapper for one,
1809 /// where unsizing can be performed on the pointee.
1810 #[unstable(feature = "coerce_unsized", issue = "27732")]
1811 #[lang="coerce_unsized"]
1812 pub trait CoerceUnsized<T> {
1813     // Empty.
1814 }
1815
1816 // &mut T -> &mut U
1817 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a mut U> for &'a mut T {}
1818 // &mut T -> &U
1819 impl<'a, 'b: 'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a U> for &'b mut T {}
1820 // &mut T -> *mut U
1821 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*mut U> for &'a mut T {}
1822 // &mut T -> *const U
1823 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for &'a mut T {}
1824
1825 // &T -> &U
1826 impl<'a, 'b: 'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a U> for &'b T {}
1827 // &T -> *const U
1828 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for &'a T {}
1829
1830 // *mut T -> *mut U
1831 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*mut U> for *mut T {}
1832 // *mut T -> *const U
1833 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for *mut T {}
1834
1835 // *const T -> *const U
1836 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for *const T {}
1837
1838 /// Both `in (PLACE) EXPR` and `box EXPR` desugar into expressions
1839 /// that allocate an intermediate "place" that holds uninitialized
1840 /// state.  The desugaring evaluates EXPR, and writes the result at
1841 /// the address returned by the `pointer` method of this trait.
1842 ///
1843 /// A `Place` can be thought of as a special representation for a
1844 /// hypothetical `&uninit` reference (which Rust cannot currently
1845 /// express directly). That is, it represents a pointer to
1846 /// uninitialized storage.
1847 ///
1848 /// The client is responsible for two steps: First, initializing the
1849 /// payload (it can access its address via `pointer`). Second,
1850 /// converting the agent to an instance of the owning pointer, via the
1851 /// appropriate `finalize` method (see the `InPlace`.
1852 ///
1853 /// If evaluating EXPR fails, then the destructor for the
1854 /// implementation of Place to clean up any intermediate state
1855 /// (e.g. deallocate box storage, pop a stack, etc).
1856 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1857 pub trait Place<Data: ?Sized> {
1858     /// Returns the address where the input value will be written.
1859     /// Note that the data at this address is generally uninitialized,
1860     /// and thus one should use `ptr::write` for initializing it.
1861     fn pointer(&mut self) -> *mut Data;
1862 }
1863
1864 /// Interface to implementations of  `in (PLACE) EXPR`.
1865 ///
1866 /// `in (PLACE) EXPR` effectively desugars into:
1867 ///
1868 /// ```rust,ignore
1869 /// let p = PLACE;
1870 /// let mut place = Placer::make_place(p);
1871 /// let raw_place = Place::pointer(&mut place);
1872 /// let value = EXPR;
1873 /// unsafe {
1874 ///     std::ptr::write(raw_place, value);
1875 ///     InPlace::finalize(place)
1876 /// }
1877 /// ```
1878 ///
1879 /// The type of `in (PLACE) EXPR` is derived from the type of `PLACE`;
1880 /// if the type of `PLACE` is `P`, then the final type of the whole
1881 /// expression is `P::Place::Owner` (see the `InPlace` and `Boxed`
1882 /// traits).
1883 ///
1884 /// Values for types implementing this trait usually are transient
1885 /// intermediate values (e.g. the return value of `Vec::emplace_back`)
1886 /// or `Copy`, since the `make_place` method takes `self` by value.
1887 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1888 pub trait Placer<Data: ?Sized> {
1889     /// `Place` is the intermedate agent guarding the
1890     /// uninitialized state for `Data`.
1891     type Place: InPlace<Data>;
1892
1893     /// Creates a fresh place from `self`.
1894     fn make_place(self) -> Self::Place;
1895 }
1896
1897 /// Specialization of `Place` trait supporting `in (PLACE) EXPR`.
1898 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1899 pub trait InPlace<Data: ?Sized>: Place<Data> {
1900     /// `Owner` is the type of the end value of `in (PLACE) EXPR`
1901     ///
1902     /// Note that when `in (PLACE) EXPR` is solely used for
1903     /// side-effecting an existing data-structure,
1904     /// e.g. `Vec::emplace_back`, then `Owner` need not carry any
1905     /// information at all (e.g. it can be the unit type `()` in that
1906     /// case).
1907     type Owner;
1908
1909     /// Converts self into the final value, shifting
1910     /// deallocation/cleanup responsibilities (if any remain), over to
1911     /// the returned instance of `Owner` and forgetting self.
1912     unsafe fn finalize(self) -> Self::Owner;
1913 }
1914
1915 /// Core trait for the `box EXPR` form.
1916 ///
1917 /// `box EXPR` effectively desugars into:
1918 ///
1919 /// ```rust,ignore
1920 /// let mut place = BoxPlace::make_place();
1921 /// let raw_place = Place::pointer(&mut place);
1922 /// let value = EXPR;
1923 /// unsafe {
1924 ///     ::std::ptr::write(raw_place, value);
1925 ///     Boxed::finalize(place)
1926 /// }
1927 /// ```
1928 ///
1929 /// The type of `box EXPR` is supplied from its surrounding
1930 /// context; in the above expansion, the result type `T` is used
1931 /// to determine which implementation of `Boxed` to use, and that
1932 /// `<T as Boxed>` in turn dictates determines which
1933 /// implementation of `BoxPlace` to use, namely:
1934 /// `<<T as Boxed>::Place as BoxPlace>`.
1935 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1936 pub trait Boxed {
1937     /// The kind of data that is stored in this kind of box.
1938     type Data;  /* (`Data` unused b/c cannot yet express below bound.) */
1939     /// The place that will negotiate the storage of the data.
1940     type Place: BoxPlace<Self::Data>;
1941
1942     /// Converts filled place into final owning value, shifting
1943     /// deallocation/cleanup responsibilities (if any remain), over to
1944     /// returned instance of `Self` and forgetting `filled`.
1945     unsafe fn finalize(filled: Self::Place) -> Self;
1946 }
1947
1948 /// Specialization of `Place` trait supporting `box EXPR`.
1949 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1950 pub trait BoxPlace<Data: ?Sized> : Place<Data> {
1951     /// Creates a globally fresh place.
1952     fn make_place() -> Self;
1953 }