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