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             #[stable(feature = "rust1", since = "1.0.0")]
 546             type Output = $t;
 547
 548             #[inline]
 549             #[stable(feature = "rust1", since = "1.0.0")]
 550             fn neg(self) -> $t { let $id = self; $body }
 551         }
 552
 553         forward_ref_unop! { impl Neg, neg for $t }
 554     )*)
 555 }
 556
 557 macro_rules! neg_impl_numeric {
 558     ($($t:ty)*) => { neg_impl_core!{ x => -x, $($t)*} }
 559 }
 560
 561 macro_rules! neg_impl_unsigned {
 562     ($($t:ty)*) => {
 563         neg_impl_core!{ x => {
 564             !x.wrapping_add(1)
 565         }, $($t)*} }
 566 }
 567
 568 // neg_impl_unsigned! { usize u8 u16 u32 u64 }
 569 neg_impl_numeric! { isize i8 i16 i32 i64 f32 f64 }
 570
 571 /// The `Not` trait is used to specify the functionality of unary `!`.
 572 ///
 573 /// # Examples
 574 ///
 575 /// A trivial implementation of `Not`. When `!Foo` happens, it ends up calling
 576 /// `not`, and therefore, `main` prints `Not-ing!`.
 577 ///
 578 /// ```
 579 /// use std::ops::Not;
 580 ///
 581 /// #[derive(Copy, Clone)]
 582 /// struct Foo;
 583 ///
 584 /// impl Not for Foo {
 585 ///     type Output = Foo;
 586 ///
 587 ///     fn not(self) -> Foo {
 588 ///         println!("Not-ing!");
 589 ///         self
 590 ///     }
 591 /// }
 592 ///
 593 /// fn main() {
 594 ///     !Foo;
 595 /// }
 596 /// ```
 597 #[lang = "not"]
 598 #[stable(feature = "rust1", since = "1.0.0")]
 599 pub trait Not {
 600     /// The resulting type after applying the `!` operator
 601     #[stable(feature = "rust1", since = "1.0.0")]
 602     type Output;
 603
 604     /// The method for the unary `!` operator
 605     #[stable(feature = "rust1", since = "1.0.0")]
 606     fn not(self) -> Self::Output;
 607 }
 608
 609 macro_rules! not_impl {
 610     ($($t:ty)*) => ($(
 611         #[stable(feature = "rust1", since = "1.0.0")]
 612         impl Not for $t {
 613             type Output = $t;
 614
 615             #[inline]
 616             fn not(self) -> $t { !self }
 617         }
 618
 619         forward_ref_unop! { impl Not, not for $t }
 620     )*)
 621 }
 622
 623 not_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 624
 625 /// The `BitAnd` trait is used to specify the functionality of `&`.
 626 ///
 627 /// # Examples
 628 ///
 629 /// A trivial implementation of `BitAnd`. When `Foo & Foo` happens, it ends up
 630 /// calling `bitand`, and therefore, `main` prints `Bitwise And-ing!`.
 631 ///
 632 /// ```
 633 /// use std::ops::BitAnd;
 634 ///
 635 /// #[derive(Copy, Clone)]
 636 /// struct Foo;
 637 ///
 638 /// impl BitAnd for Foo {
 639 ///     type Output = Foo;
 640 ///
 641 ///     fn bitand(self, _rhs: Foo) -> Foo {
 642 ///         println!("Bitwise And-ing!");
 643 ///         self
 644 ///     }
 645 /// }
 646 ///
 647 /// fn main() {
 648 ///     Foo & Foo;
 649 /// }
 650 /// ```
 651 #[lang = "bitand"]
 652 #[stable(feature = "rust1", since = "1.0.0")]
 653 pub trait BitAnd<RHS=Self> {
 654     /// The resulting type after applying the `&` operator
 655     #[stable(feature = "rust1", since = "1.0.0")]
 656     type Output;
 657
 658     /// The method for the `&` operator
 659     #[stable(feature = "rust1", since = "1.0.0")]
 660     fn bitand(self, rhs: RHS) -> Self::Output;
 661 }
 662
 663 macro_rules! bitand_impl {
 664     ($($t:ty)*) => ($(
 665         #[stable(feature = "rust1", since = "1.0.0")]
 666         impl BitAnd for $t {
 667             type Output = $t;
 668
 669             #[inline]
 670             fn bitand(self, rhs: $t) -> $t { self & rhs }
 671         }
 672
 673         forward_ref_binop! { impl BitAnd, bitand for $t, $t }
 674     )*)
 675 }
 676
 677 bitand_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 678
 679 /// The `BitOr` trait is used to specify the functionality of `|`.
 680 ///
 681 /// # Examples
 682 ///
 683 /// A trivial implementation of `BitOr`. When `Foo | Foo` happens, it ends up
 684 /// calling `bitor`, and therefore, `main` prints `Bitwise Or-ing!`.
 685 ///
 686 /// ```
 687 /// use std::ops::BitOr;
 688 ///
 689 /// #[derive(Copy, Clone)]
 690 /// struct Foo;
 691 ///
 692 /// impl BitOr for Foo {
 693 ///     type Output = Foo;
 694 ///
 695 ///     fn bitor(self, _rhs: Foo) -> Foo {
 696 ///         println!("Bitwise Or-ing!");
 697 ///         self
 698 ///     }
 699 /// }
 700 ///
 701 /// fn main() {
 702 ///     Foo | Foo;
 703 /// }
 704 /// ```
 705 #[lang = "bitor"]
 706 #[stable(feature = "rust1", since = "1.0.0")]
 707 pub trait BitOr<RHS=Self> {
 708     /// The resulting type after applying the `|` operator
 709     #[stable(feature = "rust1", since = "1.0.0")]
 710     type Output;
 711
 712     /// The method for the `|` operator
 713     #[stable(feature = "rust1", since = "1.0.0")]
 714     fn bitor(self, rhs: RHS) -> Self::Output;
 715 }
 716
 717 macro_rules! bitor_impl {
 718     ($($t:ty)*) => ($(
 719         #[stable(feature = "rust1", since = "1.0.0")]
 720         impl BitOr for $t {
 721             type Output = $t;
 722
 723             #[inline]
 724             fn bitor(self, rhs: $t) -> $t { self | rhs }
 725         }
 726
 727         forward_ref_binop! { impl BitOr, bitor for $t, $t }
 728     )*)
 729 }
 730
 731 bitor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 732
 733 /// The `BitXor` trait is used to specify the functionality of `^`.
 734 ///
 735 /// # Examples
 736 ///
 737 /// A trivial implementation of `BitXor`. When `Foo ^ Foo` happens, it ends up
 738 /// calling `bitxor`, and therefore, `main` prints `Bitwise Xor-ing!`.
 739 ///
 740 /// ```
 741 /// use std::ops::BitXor;
 742 ///
 743 /// #[derive(Copy, Clone)]
 744 /// struct Foo;
 745 ///
 746 /// impl BitXor for Foo {
 747 ///     type Output = Foo;
 748 ///
 749 ///     fn bitxor(self, _rhs: Foo) -> Foo {
 750 ///         println!("Bitwise Xor-ing!");
 751 ///         self
 752 ///     }
 753 /// }
 754 ///
 755 /// fn main() {
 756 ///     Foo ^ Foo;
 757 /// }
 758 /// ```
 759 #[lang = "bitxor"]
 760 #[stable(feature = "rust1", since = "1.0.0")]
 761 pub trait BitXor<RHS=Self> {
 762     /// The resulting type after applying the `^` operator
 763     #[stable(feature = "rust1", since = "1.0.0")]
 764     type Output;
 765
 766     /// The method for the `^` operator
 767     #[stable(feature = "rust1", since = "1.0.0")]
 768     fn bitxor(self, rhs: RHS) -> Self::Output;
 769 }
 770
 771 macro_rules! bitxor_impl {
 772     ($($t:ty)*) => ($(
 773         #[stable(feature = "rust1", since = "1.0.0")]
 774         impl BitXor for $t {
 775             type Output = $t;
 776
 777             #[inline]
 778             fn bitxor(self, other: $t) -> $t { self ^ other }
 779         }
 780
 781         forward_ref_binop! { impl BitXor, bitxor for $t, $t }
 782     )*)
 783 }
 784
 785 bitxor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 786
 787 /// The `Shl` trait is used to specify the functionality of `<<`.
 788 ///
 789 /// # Examples
 790 ///
 791 /// A trivial implementation of `Shl`. When `Foo << Foo` happens, it ends up
 792 /// calling `shl`, and therefore, `main` prints `Shifting left!`.
 793 ///
 794 /// ```
 795 /// use std::ops::Shl;
 796 ///
 797 /// #[derive(Copy, Clone)]
 798 /// struct Foo;
 799 ///
 800 /// impl Shl<Foo> for Foo {
 801 ///     type Output = Foo;
 802 ///
 803 ///     fn shl(self, _rhs: Foo) -> Foo {
 804 ///         println!("Shifting left!");
 805 ///         self
 806 ///     }
 807 /// }
 808 ///
 809 /// fn main() {
 810 ///     Foo << Foo;
 811 /// }
 812 /// ```
 813 #[lang = "shl"]
 814 #[stable(feature = "rust1", since = "1.0.0")]
 815 pub trait Shl<RHS> {
 816     /// The resulting type after applying the `<<` operator
 817     #[stable(feature = "rust1", since = "1.0.0")]
 818     type Output;
 819
 820     /// The method for the `<<` operator
 821     #[stable(feature = "rust1", since = "1.0.0")]
 822     fn shl(self, rhs: RHS) -> Self::Output;
 823 }
 824
 825 macro_rules! shl_impl {
 826     ($t:ty, $f:ty) => (
 827         #[stable(feature = "rust1", since = "1.0.0")]
 828         impl Shl<$f> for $t {
 829             type Output = $t;
 830
 831             #[inline]
 832             fn shl(self, other: $f) -> $t {
 833                 self << other
 834             }
 835         }
 836
 837         forward_ref_binop! { impl Shl, shl for $t, $f }
 838     )
 839 }
 840
 841 macro_rules! shl_impl_all {
 842     ($($t:ty)*) => ($(
 843         shl_impl! { $t, u8 }
 844         shl_impl! { $t, u16 }
 845         shl_impl! { $t, u32 }
 846         shl_impl! { $t, u64 }
 847         shl_impl! { $t, usize }
 848
 849         shl_impl! { $t, i8 }
 850         shl_impl! { $t, i16 }
 851         shl_impl! { $t, i32 }
 852         shl_impl! { $t, i64 }
 853         shl_impl! { $t, isize }
 854     )*)
 855 }
 856
 857 shl_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 858
 859 /// The `Shr` trait is used to specify the functionality of `>>`.
 860 ///
 861 /// # Examples
 862 ///
 863 /// A trivial implementation of `Shr`. When `Foo >> Foo` happens, it ends up
 864 /// calling `shr`, and therefore, `main` prints `Shifting right!`.
 865 ///
 866 /// ```
 867 /// use std::ops::Shr;
 868 ///
 869 /// #[derive(Copy, Clone)]
 870 /// struct Foo;
 871 ///
 872 /// impl Shr<Foo> for Foo {
 873 ///     type Output = Foo;
 874 ///
 875 ///     fn shr(self, _rhs: Foo) -> Foo {
 876 ///         println!("Shifting right!");
 877 ///         self
 878 ///     }
 879 /// }
 880 ///
 881 /// fn main() {
 882 ///     Foo >> Foo;
 883 /// }
 884 /// ```
 885 #[lang = "shr"]
 886 #[stable(feature = "rust1", since = "1.0.0")]
 887 pub trait Shr<RHS> {
 888     /// The resulting type after applying the `>>` operator
 889     #[stable(feature = "rust1", since = "1.0.0")]
 890     type Output;
 891
 892     /// The method for the `>>` operator
 893     #[stable(feature = "rust1", since = "1.0.0")]
 894     fn shr(self, rhs: RHS) -> Self::Output;
 895 }
 896
 897 macro_rules! shr_impl {
 898     ($t:ty, $f:ty) => (
 899         impl Shr<$f> for $t {
 900             type Output = $t;
 901
 902             #[inline]
 903             fn shr(self, other: $f) -> $t {
 904                 self >> other
 905             }
 906         }
 907
 908         forward_ref_binop! { impl Shr, shr for $t, $f }
 909     )
 910 }
 911
 912 macro_rules! shr_impl_all {
 913     ($($t:ty)*) => ($(
 914         shr_impl! { $t, u8 }
 915         shr_impl! { $t, u16 }
 916         shr_impl! { $t, u32 }
 917         shr_impl! { $t, u64 }
 918         shr_impl! { $t, usize }
 919
 920         shr_impl! { $t, i8 }
 921         shr_impl! { $t, i16 }
 922         shr_impl! { $t, i32 }
 923         shr_impl! { $t, i64 }
 924         shr_impl! { $t, isize }
 925     )*)
 926 }
 927
 928 shr_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 929
 930 /// The `AddAssign` trait is used to specify the functionality of `+=`.
 931 ///
 932 /// # Examples
 933 ///
 934 /// A trivial implementation of `AddAssign`. When `Foo += Foo` happens, it ends up
 935 /// calling `add_assign`, and therefore, `main` prints `Adding!`.
 936 ///
 937 /// ```
 938 /// #![feature(augmented_assignments)]
 939 /// #![feature(op_assign_traits)]
 940 ///
 941 /// use std::ops::AddAssign;
 942 ///
 943 /// #[derive(Copy, Clone)]
 944 /// struct Foo;
 945 ///
 946 /// impl AddAssign for Foo {
 947 ///     fn add_assign(&mut self, _rhs: Foo) {
 948 ///         println!("Adding!");
 949 ///     }
 950 /// }
 951 ///
 952 /// fn main() {
 953 ///     let mut foo = Foo;
 954 ///     foo += Foo;
 955 /// }
 956 /// ```
 957 #[cfg(not(stage0))]
 958 #[lang = "add_assign"]
 959 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
 960 pub trait AddAssign<Rhs=Self> {
 961     /// The method for the `+=` operator
 962     fn add_assign(&mut self, Rhs);
 963 }
 964
 965 #[cfg(not(stage0))]
 966 macro_rules! add_assign_impl {
 967     ($($t:ty)+) => ($(
 968         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
 969         impl AddAssign for $t {
 970             #[inline]
 971             fn add_assign(&mut self, other: $t) { *self += other }
 972         }
 973     )+)
 974 }
 975
 976 #[cfg(not(stage0))]
 977 add_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 978
 979 /// The `SubAssign` trait is used to specify the functionality of `-=`.
 980 ///
 981 /// # Examples
 982 ///
 983 /// A trivial implementation of `SubAssign`. When `Foo -= Foo` happens, it ends up
 984 /// calling `sub_assign`, and therefore, `main` prints `Subtracting!`.
 985 ///
 986 /// ```
 987 /// #![feature(augmented_assignments)]
 988 /// #![feature(op_assign_traits)]
 989 ///
 990 /// use std::ops::SubAssign;
 991 ///
 992 /// #[derive(Copy, Clone)]
 993 /// struct Foo;
 994 ///
 995 /// impl SubAssign for Foo {
 996 ///     fn sub_assign(&mut self, _rhs: Foo) {
 997 ///         println!("Subtracting!");
 998 ///     }
 999 /// }
1000 ///
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 /// fn main() {
1051 ///     let mut foo = Foo;
1052 ///     foo *= Foo;
1053 /// }
1054 /// ```
1055 #[cfg(not(stage0))]
1056 #[lang = "mul_assign"]
1057 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1058 pub trait MulAssign<Rhs=Self> {
1059     /// The method for the `*=` operator
1060     fn mul_assign(&mut self, Rhs);
1061 }
1062
1063 #[cfg(not(stage0))]
1064 macro_rules! mul_assign_impl {
1065     ($($t:ty)+) => ($(
1066         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1067         impl MulAssign for $t {
1068             #[inline]
1069             fn mul_assign(&mut self, other: $t) { *self *= other }
1070         }
1071     )+)
1072 }
1073
1074 #[cfg(not(stage0))]
1075 mul_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
1076
1077 /// The `DivAssign` trait is used to specify the functionality of `/=`.
1078 ///
1079 /// # Examples
1080 ///
1081 /// A trivial implementation of `DivAssign`. When `Foo /= Foo` happens, it ends up
1082 /// calling `div_assign`, and therefore, `main` prints `Dividing!`.
1083 ///
1084 /// ```
1085 /// #![feature(augmented_assignments)]
1086 /// #![feature(op_assign_traits)]
1087 ///
1088 /// use std::ops::DivAssign;
1089 ///
1090 /// #[derive(Copy, Clone)]
1091 /// struct Foo;
1092 ///
1093 /// impl DivAssign for Foo {
1094 ///     fn div_assign(&mut self, _rhs: Foo) {
1095 ///         println!("Dividing!");
1096 ///     }
1097 /// }
1098 ///
1099 /// fn main() {
1100 ///     let mut foo = Foo;
1101 ///     foo /= Foo;
1102 /// }
1103 /// ```
1104 #[cfg(not(stage0))]
1105 #[lang = "div_assign"]
1106 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1107 pub trait DivAssign<Rhs=Self> {
1108     /// The method for the `/=` operator
1109     fn div_assign(&mut self, Rhs);
1110 }
1111
1112 #[cfg(not(stage0))]
1113 macro_rules! div_assign_impl {
1114     ($($t:ty)+) => ($(
1115         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1116         impl DivAssign for $t {
1117             #[inline]
1118             fn div_assign(&mut self, other: $t) { *self /= other }
1119         }
1120     )+)
1121 }
1122
1123 #[cfg(not(stage0))]
1124 div_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
1125
1126 /// The `RemAssign` trait is used to specify the functionality of `%=`.
1127 ///
1128 /// # Examples
1129 ///
1130 /// A trivial implementation of `RemAssign`. When `Foo %= Foo` happens, it ends up
1131 /// calling `rem_assign`, and therefore, `main` prints `Remainder-ing!`.
1132 ///
1133 /// ```
1134 /// #![feature(augmented_assignments)]
1135 /// #![feature(op_assign_traits)]
1136 ///
1137 /// use std::ops::RemAssign;
1138 ///
1139 /// #[derive(Copy, Clone)]
1140 /// struct Foo;
1141 ///
1142 /// impl RemAssign for Foo {
1143 ///     fn rem_assign(&mut self, _rhs: Foo) {
1144 ///         println!("Remainder-ing!");
1145 ///     }
1146 /// }
1147 ///
1148 /// fn main() {
1149 ///     let mut foo = Foo;
1150 ///     foo %= Foo;
1151 /// }
1152 /// ```
1153 #[cfg(not(stage0))]
1154 #[lang = "rem_assign"]
1155 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1156 pub trait RemAssign<Rhs=Self> {
1157     /// The method for the `%=` operator
1158     fn rem_assign(&mut self, Rhs);
1159 }
1160
1161 #[cfg(not(stage0))]
1162 macro_rules! rem_assign_impl {
1163     ($($t:ty)+) => ($(
1164         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1165         impl RemAssign for $t {
1166             #[inline]
1167             fn rem_assign(&mut self, other: $t) { *self %= other }
1168         }
1169     )+)
1170 }
1171
1172 #[cfg(not(stage0))]
1173 rem_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
1174
1175 /// The `BitAndAssign` trait is used to specify the functionality of `&=`.
1176 ///
1177 /// # Examples
1178 ///
1179 /// A trivial implementation of `BitAndAssign`. When `Foo &= Foo` happens, it ends up
1180 /// calling `bitand_assign`, and therefore, `main` prints `Bitwise And-ing!`.
1181 ///
1182 /// ```
1183 /// #![feature(augmented_assignments)]
1184 /// #![feature(op_assign_traits)]
1185 ///
1186 /// use std::ops::BitAndAssign;
1187 ///
1188 /// #[derive(Copy, Clone)]
1189 /// struct Foo;
1190 ///
1191 /// impl BitAndAssign for Foo {
1192 ///     fn bitand_assign(&mut self, _rhs: Foo) {
1193 ///         println!("Bitwise And-ing!");
1194 ///     }
1195 /// }
1196 ///
1197 /// fn main() {
1198 ///     let mut foo = Foo;
1199 ///     foo &= Foo;
1200 /// }
1201 /// ```
1202 #[cfg(not(stage0))]
1203 #[lang = "bitand_assign"]
1204 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1205 pub trait BitAndAssign<Rhs=Self> {
1206     /// The method for the `&` operator
1207     fn bitand_assign(&mut self, Rhs);
1208 }
1209
1210 #[cfg(not(stage0))]
1211 macro_rules! bitand_assign_impl {
1212     ($($t:ty)+) => ($(
1213         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1214         impl BitAndAssign for $t {
1215             #[inline]
1216             fn bitand_assign(&mut self, other: $t) { *self &= other }
1217         }
1218     )+)
1219 }
1220
1221 #[cfg(not(stage0))]
1222 bitand_assign_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
1223
1224 /// The `BitOrAssign` trait is used to specify the functionality of `|=`.
1225 ///
1226 /// # Examples
1227 ///
1228 /// A trivial implementation of `BitOrAssign`. When `Foo |= Foo` happens, it ends up
1229 /// calling `bitor_assign`, and therefore, `main` prints `Bitwise Or-ing!`.
1230 ///
1231 /// ```
1232 /// #![feature(augmented_assignments)]
1233 /// #![feature(op_assign_traits)]
1234 ///
1235 /// use std::ops::BitOrAssign;
1236 ///
1237 /// #[derive(Copy, Clone)]
1238 /// struct Foo;
1239 ///
1240 /// impl BitOrAssign for Foo {
1241 ///     fn bitor_assign(&mut self, _rhs: Foo) {
1242 ///         println!("Bitwise Or-ing!");
1243 ///     }
1244 /// }
1245 ///
1246 /// fn main() {
1247 ///     let mut foo = Foo;
1248 ///     foo |= Foo;
1249 /// }
1250 /// ```
1251 #[cfg(not(stage0))]
1252 #[lang = "bitor_assign"]
1253 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1254 pub trait BitOrAssign<Rhs=Self> {
1255     /// The method for the `|=` operator
1256     fn bitor_assign(&mut self, Rhs);
1257 }
1258
1259 #[cfg(not(stage0))]
1260 macro_rules! bitor_assign_impl {
1261     ($($t:ty)+) => ($(
1262         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1263         impl BitOrAssign for $t {
1264             #[inline]
1265             fn bitor_assign(&mut self, other: $t) { *self |= other }
1266         }
1267     )+)
1268 }
1269
1270 #[cfg(not(stage0))]
1271 bitor_assign_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
1272
1273 /// The `BitXorAssign` trait is used to specify the functionality of `^=`.
1274 ///
1275 /// # Examples
1276 ///
1277 /// A trivial implementation of `BitXorAssign`. When `Foo ^= Foo` happens, it ends up
1278 /// calling `bitxor_assign`, and therefore, `main` prints `Bitwise Xor-ing!`.
1279 ///
1280 /// ```
1281 /// #![feature(augmented_assignments)]
1282 /// #![feature(op_assign_traits)]
1283 ///
1284 /// use std::ops::BitXorAssign;
1285 ///
1286 /// #[derive(Copy, Clone)]
1287 /// struct Foo;
1288 ///
1289 /// impl BitXorAssign for Foo {
1290 ///     fn bitxor_assign(&mut self, _rhs: Foo) {
1291 ///         println!("Bitwise Xor-ing!");
1292 ///     }
1293 /// }
1294 ///
1295 /// fn main() {
1296 ///     let mut foo = Foo;
1297 ///     foo ^= Foo;
1298 /// }
1299 /// ```
1300 #[cfg(not(stage0))]
1301 #[lang = "bitxor_assign"]
1302 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1303 pub trait BitXorAssign<Rhs=Self> {
1304     /// The method for the `^=` operator
1305     fn bitxor_assign(&mut self, Rhs);
1306 }
1307
1308 #[cfg(not(stage0))]
1309 macro_rules! bitxor_assign_impl {
1310     ($($t:ty)+) => ($(
1311         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1312         impl BitXorAssign for $t {
1313             #[inline]
1314             fn bitxor_assign(&mut self, other: $t) { *self ^= other }
1315         }
1316     )+)
1317 }
1318
1319 #[cfg(not(stage0))]
1320 bitxor_assign_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
1321
1322 /// The `ShlAssign` trait is used to specify the functionality of `<<=`.
1323 ///
1324 /// # Examples
1325 ///
1326 /// A trivial implementation of `ShlAssign`. When `Foo <<= Foo` happens, it ends up
1327 /// calling `shl_assign`, and therefore, `main` prints `Shifting left!`.
1328 ///
1329 /// ```
1330 /// #![feature(augmented_assignments)]
1331 /// #![feature(op_assign_traits)]
1332 ///
1333 /// use std::ops::ShlAssign;
1334 ///
1335 /// #[derive(Copy, Clone)]
1336 /// struct Foo;
1337 ///
1338 /// impl ShlAssign<Foo> for Foo {
1339 ///     fn shl_assign(&mut self, _rhs: Foo) {
1340 ///         println!("Shifting left!");
1341 ///     }
1342 /// }
1343 ///
1344 /// fn main() {
1345 ///     let mut foo = Foo;
1346 ///     foo <<= Foo;
1347 /// }
1348 /// ```
1349 #[cfg(not(stage0))]
1350 #[lang = "shl_assign"]
1351 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1352 pub trait ShlAssign<Rhs> {
1353     /// The method for the `<<=` operator
1354     fn shl_assign(&mut self, Rhs);
1355 }
1356
1357 #[cfg(not(stage0))]
1358 macro_rules! shl_assign_impl {
1359     ($t:ty, $f:ty) => (
1360         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1361         impl ShlAssign<$f> for $t {
1362             #[inline]
1363             fn shl_assign(&mut self, other: $f) {
1364                 *self <<= other
1365             }
1366         }
1367     )
1368 }
1369
1370 #[cfg(not(stage0))]
1371 macro_rules! shl_assign_impl_all {
1372     ($($t:ty)*) => ($(
1373         shl_assign_impl! { $t, u8 }
1374         shl_assign_impl! { $t, u16 }
1375         shl_assign_impl! { $t, u32 }
1376         shl_assign_impl! { $t, u64 }
1377         shl_assign_impl! { $t, usize }
1378
1379         shl_assign_impl! { $t, i8 }
1380         shl_assign_impl! { $t, i16 }
1381         shl_assign_impl! { $t, i32 }
1382         shl_assign_impl! { $t, i64 }
1383         shl_assign_impl! { $t, isize }
1384     )*)
1385 }
1386
1387 #[cfg(not(stage0))]
1388 shl_assign_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
1389
1390 /// The `ShrAssign` trait is used to specify the functionality of `>>=`.
1391 ///
1392 /// # Examples
1393 ///
1394 /// A trivial implementation of `ShrAssign`. When `Foo >>= Foo` happens, it ends up
1395 /// calling `shr_assign`, and therefore, `main` prints `Shifting right!`.
1396 ///
1397 /// ```
1398 /// #![feature(augmented_assignments)]
1399 /// #![feature(op_assign_traits)]
1400 ///
1401 /// use std::ops::ShrAssign;
1402 ///
1403 /// #[derive(Copy, Clone)]
1404 /// struct Foo;
1405 ///
1406 /// impl ShrAssign<Foo> for Foo {
1407 ///     fn shr_assign(&mut self, _rhs: Foo) {
1408 ///         println!("Shifting right!");
1409 ///     }
1410 /// }
1411 ///
1412 /// fn main() {
1413 ///     let mut foo = Foo;
1414 ///     foo >>= Foo;
1415 /// }
1416 /// ```
1417 #[cfg(not(stage0))]
1418 #[lang = "shr_assign"]
1419 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1420 pub trait ShrAssign<Rhs=Self> {
1421     /// The method for the `>>=` operator
1422     fn shr_assign(&mut self, Rhs);
1423 }
1424
1425 #[cfg(not(stage0))]
1426 macro_rules! shr_assign_impl {
1427     ($t:ty, $f:ty) => (
1428         #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1429         impl ShrAssign<$f> for $t {
1430             #[inline]
1431             fn shr_assign(&mut self, other: $f) {
1432                 *self >>= other
1433             }
1434         }
1435     )
1436 }
1437
1438 #[cfg(not(stage0))]
1439 macro_rules! shr_assign_impl_all {
1440     ($($t:ty)*) => ($(
1441         shr_assign_impl! { $t, u8 }
1442         shr_assign_impl! { $t, u16 }
1443         shr_assign_impl! { $t, u32 }
1444         shr_assign_impl! { $t, u64 }
1445         shr_assign_impl! { $t, usize }
1446
1447         shr_assign_impl! { $t, i8 }
1448         shr_assign_impl! { $t, i16 }
1449         shr_assign_impl! { $t, i32 }
1450         shr_assign_impl! { $t, i64 }
1451         shr_assign_impl! { $t, isize }
1452     )*)
1453 }
1454
1455 #[cfg(not(stage0))]
1456 shr_assign_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
1457
1458 /// The `Index` trait is used to specify the functionality of indexing operations
1459 /// like `arr[idx]` when used in an immutable context.
1460 ///
1461 /// # Examples
1462 ///
1463 /// A trivial implementation of `Index`. When `Foo[Bar]` happens, it ends up
1464 /// calling `index`, and therefore, `main` prints `Indexing!`.
1465 ///
1466 /// ```
1467 /// use std::ops::Index;
1468 ///
1469 /// #[derive(Copy, Clone)]
1470 /// struct Foo;
1471 /// struct Bar;
1472 ///
1473 /// impl Index<Bar> for Foo {
1474 ///     type Output = Foo;
1475 ///
1476 ///     fn index<'a>(&'a self, _index: Bar) -> &'a Foo {
1477 ///         println!("Indexing!");
1478 ///         self
1479 ///     }
1480 /// }
1481 ///
1482 /// fn main() {
1483 ///     Foo[Bar];
1484 /// }
1485 /// ```
1486 #[lang = "index"]
1487 #[rustc_on_unimplemented = "the type `{Self}` cannot be indexed by `{Idx}`"]
1488 #[stable(feature = "rust1", since = "1.0.0")]
1489 pub trait Index<Idx: ?Sized> {
1490     /// The returned type after indexing
1491     #[stable(feature = "rust1", since = "1.0.0")]
1492     type Output: ?Sized;
1493
1494     /// The method for the indexing (`Foo[Bar]`) operation
1495     #[stable(feature = "rust1", since = "1.0.0")]
1496     fn index(&self, index: Idx) -> &Self::Output;
1497 }
1498
1499 /// The `IndexMut` trait is used to specify the functionality of indexing
1500 /// operations like `arr[idx]`, when used in a mutable context.
1501 ///
1502 /// # Examples
1503 ///
1504 /// A trivial implementation of `IndexMut`. When `Foo[Bar]` happens, it ends up
1505 /// calling `index_mut`, and therefore, `main` prints `Indexing!`.
1506 ///
1507 /// ```
1508 /// use std::ops::{Index, IndexMut};
1509 ///
1510 /// #[derive(Copy, Clone)]
1511 /// struct Foo;
1512 /// struct Bar;
1513 ///
1514 /// impl Index<Bar> for Foo {
1515 ///     type Output = Foo;
1516 ///
1517 ///     fn index<'a>(&'a self, _index: Bar) -> &'a Foo {
1518 ///         self
1519 ///     }
1520 /// }
1521 ///
1522 /// impl IndexMut<Bar> for Foo {
1523 ///     fn index_mut<'a>(&'a mut self, _index: Bar) -> &'a mut Foo {
1524 ///         println!("Indexing!");
1525 ///         self
1526 ///     }
1527 /// }
1528 ///
1529 /// fn main() {
1530 ///     &mut Foo[Bar];
1531 /// }
1532 /// ```
1533 #[lang = "index_mut"]
1534 #[rustc_on_unimplemented = "the type `{Self}` cannot be mutably indexed by `{Idx}`"]
1535 #[stable(feature = "rust1", since = "1.0.0")]
1536 pub trait IndexMut<Idx: ?Sized>: Index<Idx> {
1537     /// The method for the indexing (`Foo[Bar]`) operation
1538     #[stable(feature = "rust1", since = "1.0.0")]
1539     fn index_mut(&mut self, index: Idx) -> &mut Self::Output;
1540 }
1541
1542 /// An unbounded range.
1543 #[derive(Copy, Clone, PartialEq, Eq)]
1544 #[lang = "range_full"]
1545 #[stable(feature = "rust1", since = "1.0.0")]
1546 pub struct RangeFull;
1547
1548 #[stable(feature = "rust1", since = "1.0.0")]
1549 impl fmt::Debug for RangeFull {
1550     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1551         write!(fmt, "..")
1552     }
1553 }
1554
1555 /// A (half-open) range which is bounded at both ends.
1556 #[derive(Clone, PartialEq, Eq)]
1557 #[lang = "range"]
1558 #[stable(feature = "rust1", since = "1.0.0")]
1559 pub struct Range<Idx> {
1560     /// The lower bound of the range (inclusive).
1561     #[stable(feature = "rust1", since = "1.0.0")]
1562     pub start: Idx,
1563     /// The upper bound of the range (exclusive).
1564     #[stable(feature = "rust1", since = "1.0.0")]
1565     pub end: Idx,
1566 }
1567
1568 #[stable(feature = "rust1", since = "1.0.0")]
1569 impl<Idx: fmt::Debug> fmt::Debug for Range<Idx> {
1570     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1571         write!(fmt, "{:?}..{:?}", self.start, self.end)
1572     }
1573 }
1574
1575 /// A range which is only bounded below.
1576 #[derive(Clone, PartialEq, Eq)]
1577 #[lang = "range_from"]
1578 #[stable(feature = "rust1", since = "1.0.0")]
1579 pub struct RangeFrom<Idx> {
1580     /// The lower bound of the range (inclusive).
1581     #[stable(feature = "rust1", since = "1.0.0")]
1582     pub start: Idx,
1583 }
1584
1585 #[stable(feature = "rust1", since = "1.0.0")]
1586 impl<Idx: fmt::Debug> fmt::Debug for RangeFrom<Idx> {
1587     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1588         write!(fmt, "{:?}..", self.start)
1589     }
1590 }
1591
1592 /// A range which is only bounded above.
1593 #[derive(Copy, Clone, PartialEq, Eq)]
1594 #[lang = "range_to"]
1595 #[stable(feature = "rust1", since = "1.0.0")]
1596 pub struct RangeTo<Idx> {
1597     /// The upper bound of the range (exclusive).
1598     #[stable(feature = "rust1", since = "1.0.0")]
1599     pub end: Idx,
1600 }
1601
1602 #[stable(feature = "rust1", since = "1.0.0")]
1603 impl<Idx: fmt::Debug> fmt::Debug for RangeTo<Idx> {
1604     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1605         write!(fmt, "..{:?}", self.end)
1606     }
1607 }
1608
1609 /// The `Deref` trait is used to specify the functionality of dereferencing
1610 /// operations like `*v`.
1611 ///
1612 /// `Deref` also enables ['`Deref` coercions'][coercions].
1613 ///
1614 /// [coercions]: ../../book/deref-coercions.html
1615 ///
1616 /// # Examples
1617 ///
1618 /// A struct with a single field which is accessible via dereferencing the
1619 /// struct.
1620 ///
1621 /// ```
1622 /// use std::ops::Deref;
1623 ///
1624 /// struct DerefExample<T> {
1625 ///     value: T
1626 /// }
1627 ///
1628 /// impl<T> Deref for DerefExample<T> {
1629 ///     type Target = T;
1630 ///
1631 ///     fn deref(&self) -> &T {
1632 ///         &self.value
1633 ///     }
1634 /// }
1635 ///
1636 /// fn main() {
1637 ///     let x = DerefExample { value: 'a' };
1638 ///     assert_eq!('a', *x);
1639 /// }
1640 /// ```
1641 #[lang = "deref"]
1642 #[stable(feature = "rust1", since = "1.0.0")]
1643 pub trait Deref {
1644     /// The resulting type after dereferencing
1645     #[stable(feature = "rust1", since = "1.0.0")]
1646     type Target: ?Sized;
1647
1648     /// The method called to dereference a value
1649     #[stable(feature = "rust1", since = "1.0.0")]
1650     fn deref(&self) -> &Self::Target;
1651 }
1652
1653 #[stable(feature = "rust1", since = "1.0.0")]
1654 impl<'a, T: ?Sized> Deref for &'a T {
1655     type Target = T;
1656
1657     fn deref(&self) -> &T { *self }
1658 }
1659
1660 #[stable(feature = "rust1", since = "1.0.0")]
1661 impl<'a, T: ?Sized> Deref for &'a mut T {
1662     type Target = T;
1663
1664     fn deref(&self) -> &T { *self }
1665 }
1666
1667 /// The `DerefMut` trait is used to specify the functionality of dereferencing
1668 /// mutably like `*v = 1;`
1669 ///
1670 /// `DerefMut` also enables ['`Deref` coercions'][coercions].
1671 ///
1672 /// [coercions]: ../../book/deref-coercions.html
1673 ///
1674 /// # Examples
1675 ///
1676 /// A struct with a single field which is modifiable via dereferencing the
1677 /// struct.
1678 ///
1679 /// ```
1680 /// use std::ops::{Deref, DerefMut};
1681 ///
1682 /// struct DerefMutExample<T> {
1683 ///     value: T
1684 /// }
1685 ///
1686 /// impl<T> Deref for DerefMutExample<T> {
1687 ///     type Target = T;
1688 ///
1689 ///     fn deref<'a>(&'a self) -> &'a T {
1690 ///         &self.value
1691 ///     }
1692 /// }
1693 ///
1694 /// impl<T> DerefMut for DerefMutExample<T> {
1695 ///     fn deref_mut<'a>(&'a mut self) -> &'a mut T {
1696 ///         &mut self.value
1697 ///     }
1698 /// }
1699 ///
1700 /// fn main() {
1701 ///     let mut x = DerefMutExample { value: 'a' };
1702 ///     *x = 'b';
1703 ///     assert_eq!('b', *x);
1704 /// }
1705 /// ```
1706 #[lang = "deref_mut"]
1707 #[stable(feature = "rust1", since = "1.0.0")]
1708 pub trait DerefMut: Deref {
1709     /// The method called to mutably dereference a value
1710     #[stable(feature = "rust1", since = "1.0.0")]
1711     fn deref_mut(&mut self) -> &mut Self::Target;
1712 }
1713
1714 #[stable(feature = "rust1", since = "1.0.0")]
1715 impl<'a, T: ?Sized> DerefMut for &'a mut T {
1716     fn deref_mut(&mut self) -> &mut T { *self }
1717 }
1718
1719 /// A version of the call operator that takes an immutable receiver.
1720 #[lang = "fn"]
1721 #[stable(feature = "rust1", since = "1.0.0")]
1722 #[rustc_paren_sugar]
1723 #[fundamental] // so that regex can rely that `&str: !FnMut`
1724 pub trait Fn<Args> : FnMut<Args> {
1725     /// This is called when the call operator is used.
1726     extern "rust-call" fn call(&self, args: Args) -> Self::Output;
1727 }
1728
1729 /// A version of the call operator that takes a mutable receiver.
1730 #[lang = "fn_mut"]
1731 #[stable(feature = "rust1", since = "1.0.0")]
1732 #[rustc_paren_sugar]
1733 #[fundamental] // so that regex can rely that `&str: !FnMut`
1734 pub trait FnMut<Args> : FnOnce<Args> {
1735     /// This is called when the call operator is used.
1736     extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
1737 }
1738
1739 /// A version of the call operator that takes a by-value receiver.
1740 #[lang = "fn_once"]
1741 #[stable(feature = "rust1", since = "1.0.0")]
1742 #[rustc_paren_sugar]
1743 #[fundamental] // so that regex can rely that `&str: !FnMut`
1744 pub trait FnOnce<Args> {
1745     /// The returned type after the call operator is used.
1746     type Output;
1747
1748     /// This is called when the call operator is used.
1749     extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
1750 }
1751
1752 mod impls {
1753     use marker::Sized;
1754     use super::{Fn, FnMut, FnOnce};
1755
1756     impl<'a,A,F:?Sized> Fn<A> for &'a F
1757         where F : Fn<A>
1758     {
1759         extern "rust-call" fn call(&self, args: A) -> F::Output {
1760             (**self).call(args)
1761         }
1762     }
1763
1764     impl<'a,A,F:?Sized> FnMut<A> for &'a F
1765         where F : Fn<A>
1766     {
1767         extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
1768             (**self).call(args)
1769         }
1770     }
1771
1772     impl<'a,A,F:?Sized> FnOnce<A> for &'a F
1773         where F : Fn<A>
1774     {
1775         type Output = F::Output;
1776
1777         extern "rust-call" fn call_once(self, args: A) -> F::Output {
1778             (*self).call(args)
1779         }
1780     }
1781
1782     impl<'a,A,F:?Sized> FnMut<A> for &'a mut F
1783         where F : FnMut<A>
1784     {
1785         extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
1786             (*self).call_mut(args)
1787         }
1788     }
1789
1790     impl<'a,A,F:?Sized> FnOnce<A> for &'a mut F
1791         where F : FnMut<A>
1792     {
1793         type Output = F::Output;
1794         extern "rust-call" fn call_once(mut self, args: A) -> F::Output {
1795             (*self).call_mut(args)
1796         }
1797     }
1798 }
1799
1800 /// Trait that indicates that this is a pointer or a wrapper for one,
1801 /// where unsizing can be performed on the pointee.
1802 #[unstable(feature = "coerce_unsized", issue = "27732")]
1803 #[lang="coerce_unsized"]
1804 pub trait CoerceUnsized<T> {
1805     // Empty.
1806 }
1807
1808 // &mut T -> &mut U
1809 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a mut U> for &'a mut T {}
1810 // &mut T -> &U
1811 impl<'a, 'b: 'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a U> for &'b mut T {}
1812 // &mut T -> *mut U
1813 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*mut U> for &'a mut T {}
1814 // &mut T -> *const U
1815 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for &'a mut T {}
1816
1817 // &T -> &U
1818 impl<'a, 'b: 'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a U> for &'b T {}
1819 // &T -> *const U
1820 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for &'a T {}
1821
1822 // *mut T -> *mut U
1823 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*mut U> for *mut T {}
1824 // *mut T -> *const U
1825 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for *mut T {}
1826
1827 // *const T -> *const U
1828 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for *const T {}
1829
1830 /// Both `in (PLACE) EXPR` and `box EXPR` desugar into expressions
1831 /// that allocate an intermediate "place" that holds uninitialized
1832 /// state.  The desugaring evaluates EXPR, and writes the result at
1833 /// the address returned by the `pointer` method of this trait.
1834 ///
1835 /// A `Place` can be thought of as a special representation for a
1836 /// hypothetical `&uninit` reference (which Rust cannot currently
1837 /// express directly). That is, it represents a pointer to
1838 /// uninitialized storage.
1839 ///
1840 /// The client is responsible for two steps: First, initializing the
1841 /// payload (it can access its address via `pointer`). Second,
1842 /// converting the agent to an instance of the owning pointer, via the
1843 /// appropriate `finalize` method (see the `InPlace`.
1844 ///
1845 /// If evaluating EXPR fails, then the destructor for the
1846 /// implementation of Place to clean up any intermediate state
1847 /// (e.g. deallocate box storage, pop a stack, etc).
1848 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1849 pub trait Place<Data: ?Sized> {
1850     /// Returns the address where the input value will be written.
1851     /// Note that the data at this address is generally uninitialized,
1852     /// and thus one should use `ptr::write` for initializing it.
1853     fn pointer(&mut self) -> *mut Data;
1854 }
1855
1856 /// Interface to implementations of  `in (PLACE) EXPR`.
1857 ///
1858 /// `in (PLACE) EXPR` effectively desugars into:
1859 ///
1860 /// ```rust,ignore
1861 /// let p = PLACE;
1862 /// let mut place = Placer::make_place(p);
1863 /// let raw_place = Place::pointer(&mut place);
1864 /// let value = EXPR;
1865 /// unsafe {
1866 ///     std::ptr::write(raw_place, value);
1867 ///     InPlace::finalize(place)
1868 /// }
1869 /// ```
1870 ///
1871 /// The type of `in (PLACE) EXPR` is derived from the type of `PLACE`;
1872 /// if the type of `PLACE` is `P`, then the final type of the whole
1873 /// expression is `P::Place::Owner` (see the `InPlace` and `Boxed`
1874 /// traits).
1875 ///
1876 /// Values for types implementing this trait usually are transient
1877 /// intermediate values (e.g. the return value of `Vec::emplace_back`)
1878 /// or `Copy`, since the `make_place` method takes `self` by value.
1879 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1880 pub trait Placer<Data: ?Sized> {
1881     /// `Place` is the intermedate agent guarding the
1882     /// uninitialized state for `Data`.
1883     type Place: InPlace<Data>;
1884
1885     /// Creates a fresh place from `self`.
1886     fn make_place(self) -> Self::Place;
1887 }
1888
1889 /// Specialization of `Place` trait supporting `in (PLACE) EXPR`.
1890 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1891 pub trait InPlace<Data: ?Sized>: Place<Data> {
1892     /// `Owner` is the type of the end value of `in (PLACE) EXPR`
1893     ///
1894     /// Note that when `in (PLACE) EXPR` is solely used for
1895     /// side-effecting an existing data-structure,
1896     /// e.g. `Vec::emplace_back`, then `Owner` need not carry any
1897     /// information at all (e.g. it can be the unit type `()` in that
1898     /// case).
1899     type Owner;
1900
1901     /// Converts self into the final value, shifting
1902     /// deallocation/cleanup responsibilities (if any remain), over to
1903     /// the returned instance of `Owner` and forgetting self.
1904     unsafe fn finalize(self) -> Self::Owner;
1905 }
1906
1907 /// Core trait for the `box EXPR` form.
1908 ///
1909 /// `box EXPR` effectively desugars into:
1910 ///
1911 /// ```rust,ignore
1912 /// let mut place = BoxPlace::make_place();
1913 /// let raw_place = Place::pointer(&mut place);
1914 /// let value = EXPR;
1915 /// unsafe {
1916 ///     ::std::ptr::write(raw_place, value);
1917 ///     Boxed::finalize(place)
1918 /// }
1919 /// ```
1920 ///
1921 /// The type of `box EXPR` is supplied from its surrounding
1922 /// context; in the above expansion, the result type `T` is used
1923 /// to determine which implementation of `Boxed` to use, and that
1924 /// `<T as Boxed>` in turn dictates determines which
1925 /// implementation of `BoxPlace` to use, namely:
1926 /// `<<T as Boxed>::Place as BoxPlace>`.
1927 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1928 pub trait Boxed {
1929     /// The kind of data that is stored in this kind of box.
1930     type Data;  /* (`Data` unused b/c cannot yet express below bound.) */
1931     /// The place that will negotiate the storage of the data.
1932     type Place: BoxPlace<Self::Data>;
1933
1934     /// Converts filled place into final owning value, shifting
1935     /// deallocation/cleanup responsibilities (if any remain), over to
1936     /// returned instance of `Self` and forgetting `filled`.
1937     unsafe fn finalize(filled: Self::Place) -> Self;
1938 }
1939
1940 /// Specialization of `Place` trait supporting `box EXPR`.
1941 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1942 pub trait BoxPlace<Data: ?Sized> : Place<Data> {
1943     /// Creates a globally fresh place.
1944     fn make_place() -> Self;
1945 }