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     /// The `drop` 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 {
 355     ($($t:ty)*) => ($(
 356         #[stable(feature = "rust1", since = "1.0.0")]
 357         impl Div for $t {
 358             type Output = $t;
 359
 360             #[inline]
 361             fn div(self, other: $t) -> $t { self / other }
 362         }
 363
 364         forward_ref_binop! { impl Div, div for $t, $t }
 365     )*)
 366 }
 367
 368 div_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 369
 370 /// The `Rem` trait is used to specify the functionality of `%`.
 371 ///
 372 /// # Examples
 373 ///
 374 /// A trivial implementation of `Rem`. When `Foo % Foo` happens, it ends up
 375 /// calling `rem`, and therefore, `main` prints `Remainder-ing!`.
 376 ///
 377 /// ```
 378 /// use std::ops::Rem;
 379 ///
 380 /// #[derive(Copy, Clone)]
 381 /// struct Foo;
 382 ///
 383 /// impl Rem for Foo {
 384 ///     type Output = Foo;
 385 ///
 386 ///     fn rem(self, _rhs: Foo) -> Foo {
 387 ///         println!("Remainder-ing!");
 388 ///         self
 389 ///     }
 390 /// }
 391 ///
 392 /// fn main() {
 393 ///     Foo % Foo;
 394 /// }
 395 /// ```
 396 #[lang = "rem"]
 397 #[stable(feature = "rust1", since = "1.0.0")]
 398 pub trait Rem<RHS=Self> {
 399     /// The resulting type after applying the `%` operator
 400     #[stable(feature = "rust1", since = "1.0.0")]
 401     type Output = Self;
 402
 403     /// The method for the `%` operator
 404     #[stable(feature = "rust1", since = "1.0.0")]
 405     fn rem(self, rhs: RHS) -> Self::Output;
 406 }
 407
 408 macro_rules! rem_impl {
 409     ($($t:ty)*) => ($(
 410         #[stable(feature = "rust1", since = "1.0.0")]
 411         impl Rem for $t {
 412             type Output = $t;
 413
 414             #[inline]
 415             fn rem(self, other: $t) -> $t { self % other }
 416         }
 417
 418         forward_ref_binop! { impl Rem, rem for $t, $t }
 419     )*)
 420 }
 421
 422 macro_rules! rem_float_impl {
 423     ($t:ty, $fmod:ident) => {
 424         #[stable(feature = "rust1", since = "1.0.0")]
 425         impl Rem for $t {
 426             type Output = $t;
 427
 428             #[inline]
 429             fn rem(self, other: $t) -> $t {
 430                 extern { fn $fmod(a: $t, b: $t) -> $t; }
 431                 unsafe { $fmod(self, other) }
 432             }
 433         }
 434
 435         forward_ref_binop! { impl Rem, rem for $t, $t }
 436     }
 437 }
 438
 439 rem_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 440 rem_float_impl! { f32, fmodf }
 441 rem_float_impl! { f64, fmod }
 442
 443 /// The `Neg` trait is used to specify the functionality of unary `-`.
 444 ///
 445 /// # Examples
 446 ///
 447 /// A trivial implementation of `Neg`. When `-Foo` happens, it ends up calling
 448 /// `neg`, and therefore, `main` prints `Negating!`.
 449 ///
 450 /// ```
 451 /// use std::ops::Neg;
 452 ///
 453 /// #[derive(Copy, Clone)]
 454 /// struct Foo;
 455 ///
 456 /// impl Neg for Foo {
 457 ///     type Output = Foo;
 458 ///
 459 ///     fn neg(self) -> Foo {
 460 ///         println!("Negating!");
 461 ///         self
 462 ///     }
 463 /// }
 464 ///
 465 /// fn main() {
 466 ///     -Foo;
 467 /// }
 468 /// ```
 469 #[lang = "neg"]
 470 #[stable(feature = "rust1", since = "1.0.0")]
 471 pub trait Neg {
 472     /// The resulting type after applying the `-` operator
 473     #[stable(feature = "rust1", since = "1.0.0")]
 474     type Output;
 475
 476     /// The method for the unary `-` operator
 477     #[stable(feature = "rust1", since = "1.0.0")]
 478     fn neg(self) -> Self::Output;
 479 }
 480
 481
 482
 483 macro_rules! neg_impl_core {
 484     ($id:ident => $body:expr, $($t:ty)*) => ($(
 485         #[stable(feature = "rust1", since = "1.0.0")]
 486         #[allow(unsigned_negation)]
 487         impl Neg for $t {
 488             #[stable(feature = "rust1", since = "1.0.0")]
 489             type Output = $t;
 490
 491             #[inline]
 492             #[stable(feature = "rust1", since = "1.0.0")]
 493             fn neg(self) -> $t { let $id = self; $body }
 494         }
 495
 496         forward_ref_unop! { impl Neg, neg for $t }
 497     )*)
 498 }
 499
 500 macro_rules! neg_impl_numeric {
 501     ($($t:ty)*) => { neg_impl_core!{ x => -x, $($t)*} }
 502 }
 503
 504 macro_rules! neg_impl_unsigned {
 505     ($($t:ty)*) => {
 506         neg_impl_core!{ x => {
 507             !x.wrapping_add(1)
 508         }, $($t)*} }
 509 }
 510
 511 // neg_impl_unsigned! { usize u8 u16 u32 u64 }
 512 neg_impl_numeric! { isize i8 i16 i32 i64 f32 f64 }
 513
 514 /// The `Not` trait is used to specify the functionality of unary `!`.
 515 ///
 516 /// # Examples
 517 ///
 518 /// A trivial implementation of `Not`. When `!Foo` happens, it ends up calling
 519 /// `not`, and therefore, `main` prints `Not-ing!`.
 520 ///
 521 /// ```
 522 /// use std::ops::Not;
 523 ///
 524 /// #[derive(Copy, Clone)]
 525 /// struct Foo;
 526 ///
 527 /// impl Not for Foo {
 528 ///     type Output = Foo;
 529 ///
 530 ///     fn not(self) -> Foo {
 531 ///         println!("Not-ing!");
 532 ///         self
 533 ///     }
 534 /// }
 535 ///
 536 /// fn main() {
 537 ///     !Foo;
 538 /// }
 539 /// ```
 540 #[lang = "not"]
 541 #[stable(feature = "rust1", since = "1.0.0")]
 542 pub trait Not {
 543     /// The resulting type after applying the `!` operator
 544     #[stable(feature = "rust1", since = "1.0.0")]
 545     type Output;
 546
 547     /// The method for the unary `!` operator
 548     #[stable(feature = "rust1", since = "1.0.0")]
 549     fn not(self) -> Self::Output;
 550 }
 551
 552 macro_rules! not_impl {
 553     ($($t:ty)*) => ($(
 554         #[stable(feature = "rust1", since = "1.0.0")]
 555         impl Not for $t {
 556             type Output = $t;
 557
 558             #[inline]
 559             fn not(self) -> $t { !self }
 560         }
 561
 562         forward_ref_unop! { impl Not, not for $t }
 563     )*)
 564 }
 565
 566 not_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 567
 568 /// The `BitAnd` trait is used to specify the functionality of `&`.
 569 ///
 570 /// # Examples
 571 ///
 572 /// A trivial implementation of `BitAnd`. When `Foo & Foo` happens, it ends up
 573 /// calling `bitand`, and therefore, `main` prints `Bitwise And-ing!`.
 574 ///
 575 /// ```
 576 /// use std::ops::BitAnd;
 577 ///
 578 /// #[derive(Copy, Clone)]
 579 /// struct Foo;
 580 ///
 581 /// impl BitAnd for Foo {
 582 ///     type Output = Foo;
 583 ///
 584 ///     fn bitand(self, _rhs: Foo) -> Foo {
 585 ///         println!("Bitwise And-ing!");
 586 ///         self
 587 ///     }
 588 /// }
 589 ///
 590 /// fn main() {
 591 ///     Foo & Foo;
 592 /// }
 593 /// ```
 594 #[lang = "bitand"]
 595 #[stable(feature = "rust1", since = "1.0.0")]
 596 pub trait BitAnd<RHS=Self> {
 597     /// The resulting type after applying the `&` operator
 598     #[stable(feature = "rust1", since = "1.0.0")]
 599     type Output;
 600
 601     /// The method for the `&` operator
 602     #[stable(feature = "rust1", since = "1.0.0")]
 603     fn bitand(self, rhs: RHS) -> Self::Output;
 604 }
 605
 606 macro_rules! bitand_impl {
 607     ($($t:ty)*) => ($(
 608         #[stable(feature = "rust1", since = "1.0.0")]
 609         impl BitAnd for $t {
 610             type Output = $t;
 611
 612             #[inline]
 613             fn bitand(self, rhs: $t) -> $t { self & rhs }
 614         }
 615
 616         forward_ref_binop! { impl BitAnd, bitand for $t, $t }
 617     )*)
 618 }
 619
 620 bitand_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 621
 622 /// The `BitOr` trait is used to specify the functionality of `|`.
 623 ///
 624 /// # Examples
 625 ///
 626 /// A trivial implementation of `BitOr`. When `Foo | Foo` happens, it ends up
 627 /// calling `bitor`, and therefore, `main` prints `Bitwise Or-ing!`.
 628 ///
 629 /// ```
 630 /// use std::ops::BitOr;
 631 ///
 632 /// #[derive(Copy, Clone)]
 633 /// struct Foo;
 634 ///
 635 /// impl BitOr for Foo {
 636 ///     type Output = Foo;
 637 ///
 638 ///     fn bitor(self, _rhs: Foo) -> Foo {
 639 ///         println!("Bitwise Or-ing!");
 640 ///         self
 641 ///     }
 642 /// }
 643 ///
 644 /// fn main() {
 645 ///     Foo | Foo;
 646 /// }
 647 /// ```
 648 #[lang = "bitor"]
 649 #[stable(feature = "rust1", since = "1.0.0")]
 650 pub trait BitOr<RHS=Self> {
 651     /// The resulting type after applying the `|` operator
 652     #[stable(feature = "rust1", since = "1.0.0")]
 653     type Output;
 654
 655     /// The method for the `|` operator
 656     #[stable(feature = "rust1", since = "1.0.0")]
 657     fn bitor(self, rhs: RHS) -> Self::Output;
 658 }
 659
 660 macro_rules! bitor_impl {
 661     ($($t:ty)*) => ($(
 662         #[stable(feature = "rust1", since = "1.0.0")]
 663         impl BitOr for $t {
 664             type Output = $t;
 665
 666             #[inline]
 667             fn bitor(self, rhs: $t) -> $t { self | rhs }
 668         }
 669
 670         forward_ref_binop! { impl BitOr, bitor for $t, $t }
 671     )*)
 672 }
 673
 674 bitor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 675
 676 /// The `BitXor` trait is used to specify the functionality of `^`.
 677 ///
 678 /// # Examples
 679 ///
 680 /// A trivial implementation of `BitXor`. When `Foo ^ Foo` happens, it ends up
 681 /// calling `bitxor`, and therefore, `main` prints `Bitwise Xor-ing!`.
 682 ///
 683 /// ```
 684 /// use std::ops::BitXor;
 685 ///
 686 /// #[derive(Copy, Clone)]
 687 /// struct Foo;
 688 ///
 689 /// impl BitXor for Foo {
 690 ///     type Output = Foo;
 691 ///
 692 ///     fn bitxor(self, _rhs: Foo) -> Foo {
 693 ///         println!("Bitwise Xor-ing!");
 694 ///         self
 695 ///     }
 696 /// }
 697 ///
 698 /// fn main() {
 699 ///     Foo ^ Foo;
 700 /// }
 701 /// ```
 702 #[lang = "bitxor"]
 703 #[stable(feature = "rust1", since = "1.0.0")]
 704 pub trait BitXor<RHS=Self> {
 705     /// The resulting type after applying the `^` operator
 706     #[stable(feature = "rust1", since = "1.0.0")]
 707     type Output;
 708
 709     /// The method for the `^` operator
 710     #[stable(feature = "rust1", since = "1.0.0")]
 711     fn bitxor(self, rhs: RHS) -> Self::Output;
 712 }
 713
 714 macro_rules! bitxor_impl {
 715     ($($t:ty)*) => ($(
 716         #[stable(feature = "rust1", since = "1.0.0")]
 717         impl BitXor for $t {
 718             type Output = $t;
 719
 720             #[inline]
 721             fn bitxor(self, other: $t) -> $t { self ^ other }
 722         }
 723
 724         forward_ref_binop! { impl BitXor, bitxor for $t, $t }
 725     )*)
 726 }
 727
 728 bitxor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 729
 730 /// The `Shl` trait is used to specify the functionality of `<<`.
 731 ///
 732 /// # Examples
 733 ///
 734 /// A trivial implementation of `Shl`. When `Foo << Foo` happens, it ends up
 735 /// calling `shl`, and therefore, `main` prints `Shifting left!`.
 736 ///
 737 /// ```
 738 /// use std::ops::Shl;
 739 ///
 740 /// #[derive(Copy, Clone)]
 741 /// struct Foo;
 742 ///
 743 /// impl Shl<Foo> for Foo {
 744 ///     type Output = Foo;
 745 ///
 746 ///     fn shl(self, _rhs: Foo) -> Foo {
 747 ///         println!("Shifting left!");
 748 ///         self
 749 ///     }
 750 /// }
 751 ///
 752 /// fn main() {
 753 ///     Foo << Foo;
 754 /// }
 755 /// ```
 756 #[lang = "shl"]
 757 #[stable(feature = "rust1", since = "1.0.0")]
 758 pub trait Shl<RHS> {
 759     /// The resulting type after applying the `<<` operator
 760     #[stable(feature = "rust1", since = "1.0.0")]
 761     type Output;
 762
 763     /// The method for the `<<` operator
 764     #[stable(feature = "rust1", since = "1.0.0")]
 765     fn shl(self, rhs: RHS) -> Self::Output;
 766 }
 767
 768 macro_rules! shl_impl {
 769     ($t:ty, $f:ty) => (
 770         #[stable(feature = "rust1", since = "1.0.0")]
 771         impl Shl<$f> for $t {
 772             type Output = $t;
 773
 774             #[inline]
 775             fn shl(self, other: $f) -> $t {
 776                 self << other
 777             }
 778         }
 779
 780         forward_ref_binop! { impl Shl, shl for $t, $f }
 781     )
 782 }
 783
 784 macro_rules! shl_impl_all {
 785     ($($t:ty)*) => ($(
 786         shl_impl! { $t, u8 }
 787         shl_impl! { $t, u16 }
 788         shl_impl! { $t, u32 }
 789         shl_impl! { $t, u64 }
 790         shl_impl! { $t, usize }
 791
 792         shl_impl! { $t, i8 }
 793         shl_impl! { $t, i16 }
 794         shl_impl! { $t, i32 }
 795         shl_impl! { $t, i64 }
 796         shl_impl! { $t, isize }
 797     )*)
 798 }
 799
 800 shl_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 801
 802 /// The `Shr` trait is used to specify the functionality of `>>`.
 803 ///
 804 /// # Examples
 805 ///
 806 /// A trivial implementation of `Shr`. When `Foo >> Foo` happens, it ends up
 807 /// calling `shr`, and therefore, `main` prints `Shifting right!`.
 808 ///
 809 /// ```
 810 /// use std::ops::Shr;
 811 ///
 812 /// #[derive(Copy, Clone)]
 813 /// struct Foo;
 814 ///
 815 /// impl Shr<Foo> for Foo {
 816 ///     type Output = Foo;
 817 ///
 818 ///     fn shr(self, _rhs: Foo) -> Foo {
 819 ///         println!("Shifting right!");
 820 ///         self
 821 ///     }
 822 /// }
 823 ///
 824 /// fn main() {
 825 ///     Foo >> Foo;
 826 /// }
 827 /// ```
 828 #[lang = "shr"]
 829 #[stable(feature = "rust1", since = "1.0.0")]
 830 pub trait Shr<RHS> {
 831     /// The resulting type after applying the `>>` operator
 832     #[stable(feature = "rust1", since = "1.0.0")]
 833     type Output;
 834
 835     /// The method for the `>>` operator
 836     #[stable(feature = "rust1", since = "1.0.0")]
 837     fn shr(self, rhs: RHS) -> Self::Output;
 838 }
 839
 840 macro_rules! shr_impl {
 841     ($t:ty, $f:ty) => (
 842         impl Shr<$f> for $t {
 843             type Output = $t;
 844
 845             #[inline]
 846             fn shr(self, other: $f) -> $t {
 847                 self >> other
 848             }
 849         }
 850
 851         forward_ref_binop! { impl Shr, shr for $t, $f }
 852     )
 853 }
 854
 855 macro_rules! shr_impl_all {
 856     ($($t:ty)*) => ($(
 857         shr_impl! { $t, u8 }
 858         shr_impl! { $t, u16 }
 859         shr_impl! { $t, u32 }
 860         shr_impl! { $t, u64 }
 861         shr_impl! { $t, usize }
 862
 863         shr_impl! { $t, i8 }
 864         shr_impl! { $t, i16 }
 865         shr_impl! { $t, i32 }
 866         shr_impl! { $t, i64 }
 867         shr_impl! { $t, isize }
 868     )*)
 869 }
 870
 871 shr_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 872
 873 /// The `Index` trait is used to specify the functionality of indexing operations
 874 /// like `arr[idx]` when used in an immutable context.
 875 ///
 876 /// # Examples
 877 ///
 878 /// A trivial implementation of `Index`. When `Foo[Bar]` happens, it ends up
 879 /// calling `index`, and therefore, `main` prints `Indexing!`.
 880 ///
 881 /// ```
 882 /// use std::ops::Index;
 883 ///
 884 /// #[derive(Copy, Clone)]
 885 /// struct Foo;
 886 /// struct Bar;
 887 ///
 888 /// impl Index<Bar> for Foo {
 889 ///     type Output = Foo;
 890 ///
 891 ///     fn index<'a>(&'a self, _index: Bar) -> &'a Foo {
 892 ///         println!("Indexing!");
 893 ///         self
 894 ///     }
 895 /// }
 896 ///
 897 /// fn main() {
 898 ///     Foo[Bar];
 899 /// }
 900 /// ```
 901 #[lang = "index"]
 902 #[rustc_on_unimplemented = "the type `{Self}` cannot be indexed by `{Idx}`"]
 903 #[stable(feature = "rust1", since = "1.0.0")]
 904 pub trait Index<Idx: ?Sized> {
 905     /// The returned type after indexing
 906     #[stable(feature = "rust1", since = "1.0.0")]
 907     type Output: ?Sized;
 908
 909     /// The method for the indexing (`Foo[Bar]`) operation
 910     #[stable(feature = "rust1", since = "1.0.0")]
 911     fn index<'a>(&'a self, index: Idx) -> &'a Self::Output;
 912 }
 913
 914 /// The `IndexMut` trait is used to specify the functionality of indexing
 915 /// operations like `arr[idx]`, when used in a mutable context.
 916 ///
 917 /// # Examples
 918 ///
 919 /// A trivial implementation of `IndexMut`. When `Foo[Bar]` happens, it ends up
 920 /// calling `index_mut`, and therefore, `main` prints `Indexing!`.
 921 ///
 922 /// ```
 923 /// use std::ops::{Index, IndexMut};
 924 ///
 925 /// #[derive(Copy, Clone)]
 926 /// struct Foo;
 927 /// struct Bar;
 928 ///
 929 /// impl Index<Bar> for Foo {
 930 ///     type Output = Foo;
 931 ///
 932 ///     fn index<'a>(&'a self, _index: Bar) -> &'a Foo {
 933 ///         self
 934 ///     }
 935 /// }
 936 ///
 937 /// impl IndexMut<Bar> for Foo {
 938 ///     fn index_mut<'a>(&'a mut self, _index: Bar) -> &'a mut Foo {
 939 ///         println!("Indexing!");
 940 ///         self
 941 ///     }
 942 /// }
 943 ///
 944 /// fn main() {
 945 ///     &mut Foo[Bar];
 946 /// }
 947 /// ```
 948 #[lang = "index_mut"]
 949 #[rustc_on_unimplemented = "the type `{Self}` cannot be mutably indexed by `{Idx}`"]
 950 #[stable(feature = "rust1", since = "1.0.0")]
 951 pub trait IndexMut<Idx: ?Sized>: Index<Idx> {
 952     /// The method for the indexing (`Foo[Bar]`) operation
 953     #[stable(feature = "rust1", since = "1.0.0")]
 954     fn index_mut<'a>(&'a mut self, index: Idx) -> &'a mut Self::Output;
 955 }
 956
 957 /// An unbounded range.
 958 #[derive(Copy, Clone, PartialEq, Eq)]
 959 #[lang = "range_full"]
 960 #[stable(feature = "rust1", since = "1.0.0")]
 961 pub struct RangeFull;
 962
 963 #[stable(feature = "rust1", since = "1.0.0")]
 964 impl fmt::Debug for RangeFull {
 965     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
 966         write!(fmt, "..")
 967     }
 968 }
 969
 970 /// A (half-open) range which is bounded at both ends.
 971 #[derive(Clone, PartialEq, Eq)]
 972 #[lang = "range"]
 973 #[stable(feature = "rust1", since = "1.0.0")]
 974 pub struct Range<Idx> {
 975     /// The lower bound of the range (inclusive).
 976     #[stable(feature = "rust1", since = "1.0.0")]
 977     pub start: Idx,
 978     /// The upper bound of the range (exclusive).
 979     #[stable(feature = "rust1", since = "1.0.0")]
 980     pub end: Idx,
 981 }
 982
 983 #[stable(feature = "rust1", since = "1.0.0")]
 984 impl<Idx: fmt::Debug> fmt::Debug for Range<Idx> {
 985     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
 986         write!(fmt, "{:?}..{:?}", self.start, self.end)
 987     }
 988 }
 989
 990 /// A range which is only bounded below.
 991 #[derive(Clone, PartialEq, Eq)]
 992 #[lang = "range_from"]
 993 #[stable(feature = "rust1", since = "1.0.0")]
 994 pub struct RangeFrom<Idx> {
 995     /// The lower bound of the range (inclusive).
 996     #[stable(feature = "rust1", since = "1.0.0")]
 997     pub start: Idx,
 998 }
 999
1000 #[stable(feature = "rust1", since = "1.0.0")]
1001 impl<Idx: fmt::Debug> fmt::Debug for RangeFrom<Idx> {
1002     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1003         write!(fmt, "{:?}..", self.start)
1004     }
1005 }
1006
1007 /// A range which is only bounded above.
1008 #[derive(Copy, Clone, PartialEq, Eq)]
1009 #[lang = "range_to"]
1010 #[stable(feature = "rust1", since = "1.0.0")]
1011 pub struct RangeTo<Idx> {
1012     /// The upper bound of the range (exclusive).
1013     #[stable(feature = "rust1", since = "1.0.0")]
1014     pub end: Idx,
1015 }
1016
1017 #[stable(feature = "rust1", since = "1.0.0")]
1018 impl<Idx: fmt::Debug> fmt::Debug for RangeTo<Idx> {
1019     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1020         write!(fmt, "..{:?}", self.end)
1021     }
1022 }
1023
1024 /// The `Deref` trait is used to specify the functionality of dereferencing
1025 /// operations like `*v`.
1026 ///
1027 /// # Examples
1028 ///
1029 /// A struct with a single field which is accessible via dereferencing the
1030 /// struct.
1031 ///
1032 /// ```
1033 /// use std::ops::Deref;
1034 ///
1035 /// struct DerefExample<T> {
1036 ///     value: T
1037 /// }
1038 ///
1039 /// impl<T> Deref for DerefExample<T> {
1040 ///     type Target = T;
1041 ///
1042 ///     fn deref<'a>(&'a self) -> &'a T {
1043 ///         &self.value
1044 ///     }
1045 /// }
1046 ///
1047 /// fn main() {
1048 ///     let x = DerefExample { value: 'a' };
1049 ///     assert_eq!('a', *x);
1050 /// }
1051 /// ```
1052 #[lang = "deref"]
1053 #[stable(feature = "rust1", since = "1.0.0")]
1054 pub trait Deref {
1055     /// The resulting type after dereferencing
1056     #[stable(feature = "rust1", since = "1.0.0")]
1057     type Target: ?Sized;
1058
1059     /// The method called to dereference a value
1060     #[stable(feature = "rust1", since = "1.0.0")]
1061     fn deref<'a>(&'a self) -> &'a Self::Target;
1062 }
1063
1064 #[stable(feature = "rust1", since = "1.0.0")]
1065 impl<'a, T: ?Sized> Deref for &'a T {
1066     type Target = T;
1067
1068     fn deref(&self) -> &T { *self }
1069 }
1070
1071 #[stable(feature = "rust1", since = "1.0.0")]
1072 impl<'a, T: ?Sized> Deref for &'a mut T {
1073     type Target = T;
1074
1075     fn deref(&self) -> &T { *self }
1076 }
1077
1078 /// The `DerefMut` trait is used to specify the functionality of dereferencing
1079 /// mutably like `*v = 1;`
1080 ///
1081 /// # Examples
1082 ///
1083 /// A struct with a single field which is modifiable via dereferencing the
1084 /// struct.
1085 ///
1086 /// ```
1087 /// use std::ops::{Deref, DerefMut};
1088 ///
1089 /// struct DerefMutExample<T> {
1090 ///     value: T
1091 /// }
1092 ///
1093 /// impl<T> Deref for DerefMutExample<T> {
1094 ///     type Target = T;
1095 ///
1096 ///     fn deref<'a>(&'a self) -> &'a T {
1097 ///         &self.value
1098 ///     }
1099 /// }
1100 ///
1101 /// impl<T> DerefMut for DerefMutExample<T> {
1102 ///     fn deref_mut<'a>(&'a mut self) -> &'a mut T {
1103 ///         &mut self.value
1104 ///     }
1105 /// }
1106 ///
1107 /// fn main() {
1108 ///     let mut x = DerefMutExample { value: 'a' };
1109 ///     *x = 'b';
1110 ///     assert_eq!('b', *x);
1111 /// }
1112 /// ```
1113 #[lang = "deref_mut"]
1114 #[stable(feature = "rust1", since = "1.0.0")]
1115 pub trait DerefMut: Deref {
1116     /// The method called to mutably dereference a value
1117     #[stable(feature = "rust1", since = "1.0.0")]
1118     fn deref_mut<'a>(&'a mut self) -> &'a mut Self::Target;
1119 }
1120
1121 #[stable(feature = "rust1", since = "1.0.0")]
1122 impl<'a, T: ?Sized> DerefMut for &'a mut T {
1123     fn deref_mut(&mut self) -> &mut T { *self }
1124 }
1125
1126 /// A version of the call operator that takes an immutable receiver.
1127 #[lang = "fn"]
1128 #[stable(feature = "rust1", since = "1.0.0")]
1129 #[rustc_paren_sugar]
1130 #[fundamental] // so that regex can rely that `&str: !FnMut`
1131 pub trait Fn<Args> : FnMut<Args> {
1132     /// This is called when the call operator is used.
1133     extern "rust-call" fn call(&self, args: Args) -> Self::Output;
1134 }
1135
1136 /// A version of the call operator that takes a mutable receiver.
1137 #[lang = "fn_mut"]
1138 #[stable(feature = "rust1", since = "1.0.0")]
1139 #[rustc_paren_sugar]
1140 #[fundamental] // so that regex can rely that `&str: !FnMut`
1141 pub trait FnMut<Args> : FnOnce<Args> {
1142     /// This is called when the call operator is used.
1143     extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
1144 }
1145
1146 /// A version of the call operator that takes a by-value receiver.
1147 #[lang = "fn_once"]
1148 #[stable(feature = "rust1", since = "1.0.0")]
1149 #[rustc_paren_sugar]
1150 #[fundamental] // so that regex can rely that `&str: !FnMut`
1151 pub trait FnOnce<Args> {
1152     /// The returned type after the call operator is used.
1153     type Output;
1154
1155     /// This is called when the call operator is used.
1156     extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
1157 }
1158
1159 mod impls {
1160     use marker::Sized;
1161     use super::{Fn, FnMut, FnOnce};
1162
1163     impl<'a,A,F:?Sized> Fn<A> for &'a F
1164         where F : Fn<A>
1165     {
1166         extern "rust-call" fn call(&self, args: A) -> F::Output {
1167             (**self).call(args)
1168         }
1169     }
1170
1171     impl<'a,A,F:?Sized> FnMut<A> for &'a F
1172         where F : Fn<A>
1173     {
1174         extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
1175             (**self).call(args)
1176         }
1177     }
1178
1179     impl<'a,A,F:?Sized> FnOnce<A> for &'a F
1180         where F : Fn<A>
1181     {
1182         type Output = F::Output;
1183
1184         extern "rust-call" fn call_once(self, args: A) -> F::Output {
1185             (*self).call(args)
1186         }
1187     }
1188
1189     impl<'a,A,F:?Sized> FnMut<A> for &'a mut F
1190         where F : FnMut<A>
1191     {
1192         extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
1193             (*self).call_mut(args)
1194         }
1195     }
1196
1197     impl<'a,A,F:?Sized> FnOnce<A> for &'a mut F
1198         where F : FnMut<A>
1199     {
1200         type Output = F::Output;
1201         extern "rust-call" fn call_once(mut self, args: A) -> F::Output {
1202             (*self).call_mut(args)
1203         }
1204     }
1205 }
1206
1207 /// Trait that indicates that this is a pointer or a wrapper for one,
1208 /// where unsizing can be performed on the pointee.
1209 #[unstable(feature = "coerce_unsized")]
1210 #[lang="coerce_unsized"]
1211 pub trait CoerceUnsized<T> {
1212     // Empty.
1213 }
1214
1215 // &mut T -> &mut U
1216 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a mut U> for &'a mut T {}
1217 // &mut T -> &U
1218 impl<'a, 'b: 'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a U> for &'b mut T {}
1219 // &mut T -> *mut U
1220 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*mut U> for &'a mut T {}
1221 // &mut T -> *const U
1222 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for &'a mut T {}
1223
1224 // &T -> &U
1225 impl<'a, 'b: 'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a U> for &'b T {}
1226 // &T -> *const U
1227 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for &'a T {}
1228
1229 // *mut T -> *mut U
1230 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*mut U> for *mut T {}
1231 // *mut T -> *const U
1232 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for *mut T {}
1233
1234 // *const T -> *const U
1235 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for *const T {}