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 //! # Example
  31 //!
  32 //! This example creates a `Point` struct that implements `Add` and `Sub`, and then
  33 //! 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: int,
  41 //!     y: int
  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 prints
  66 //! something to the screen.
  67
  68 #![stable(feature = "rust1", since = "1.0.0")]
  69
  70 use marker::Sized;
  71 use fmt;
  72
  73 /// The `Drop` trait is used to run some code when a value goes out of scope. This
  74 /// is sometimes called a 'destructor'.
  75 ///
  76 /// # Example
  77 ///
  78 /// A trivial implementation of `Drop`. The `drop` method is called when `_x` goes
  79 /// out of scope, and therefore `main` prints `Dropping!`.
  80 ///
  81 /// ```rust
  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         #[unstable(feature = "core",
 107                    reason = "recently added, waiting for dust to settle")]
 108         impl<'a> $imp for &'a $t {
 109             type Output = <$t as $imp>::Output;
 110
 111             #[inline]
 112             fn $method(self) -> <$t as $imp>::Output {
 113                 $imp::$method(*self)
 114             }
 115         }
 116     }
 117 }
 118
 119 // implements binary operators "&T op U", "T op &U", "&T op &U"
 120 // based on "T op U" where T and U are expected to be `Copy`able
 121 macro_rules! forward_ref_binop {
 122     (impl $imp:ident, $method:ident for $t:ty, $u:ty) => {
 123         #[unstable(feature = "core",
 124                    reason = "recently added, waiting for dust to settle")]
 125         impl<'a> $imp<$u> for &'a $t {
 126             type Output = <$t as $imp<$u>>::Output;
 127
 128             #[inline]
 129             fn $method(self, other: $u) -> <$t as $imp<$u>>::Output {
 130                 $imp::$method(*self, other)
 131             }
 132         }
 133
 134         #[unstable(feature = "core",
 135                    reason = "recently added, waiting for dust to settle")]
 136         impl<'a> $imp<&'a $u> for $t {
 137             type Output = <$t as $imp<$u>>::Output;
 138
 139             #[inline]
 140             fn $method(self, other: &'a $u) -> <$t as $imp<$u>>::Output {
 141                 $imp::$method(self, *other)
 142             }
 143         }
 144
 145         #[unstable(feature = "core",
 146                    reason = "recently added, waiting for dust to settle")]
 147         impl<'a, 'b> $imp<&'a $u> for &'b $t {
 148             type Output = <$t as $imp<$u>>::Output;
 149
 150             #[inline]
 151             fn $method(self, other: &'a $u) -> <$t as $imp<$u>>::Output {
 152                 $imp::$method(*self, *other)
 153             }
 154         }
 155     }
 156 }
 157
 158 /// The `Add` trait is used to specify the functionality of `+`.
 159 ///
 160 /// # Example
 161 ///
 162 /// A trivial implementation of `Add`. When `Foo + Foo` happens, it ends up
 163 /// calling `add`, and therefore, `main` prints `Adding!`.
 164 ///
 165 /// ```rust
 166 /// use std::ops::Add;
 167 ///
 168 /// #[derive(Copy)]
 169 /// struct Foo;
 170 ///
 171 /// impl Add for Foo {
 172 ///     type Output = Foo;
 173 ///
 174 ///     fn add(self, _rhs: Foo) -> Foo {
 175 ///       println!("Adding!");
 176 ///       self
 177 ///   }
 178 /// }
 179 ///
 180 /// fn main() {
 181 ///   Foo + Foo;
 182 /// }
 183 /// ```
 184 #[lang="add"]
 185 #[stable(feature = "rust1", since = "1.0.0")]
 186 pub trait Add<RHS=Self> {
 187     #[stable(feature = "rust1", since = "1.0.0")]
 188     type Output;
 189
 190     /// The method for the `+` operator
 191     #[stable(feature = "rust1", since = "1.0.0")]
 192     fn add(self, rhs: RHS) -> Self::Output;
 193 }
 194
 195 macro_rules! add_impl {
 196     ($($t:ty)*) => ($(
 197         #[stable(feature = "rust1", since = "1.0.0")]
 198         impl Add for $t {
 199             type Output = $t;
 200
 201             #[inline]
 202             fn add(self, other: $t) -> $t { self + other }
 203         }
 204
 205         forward_ref_binop! { impl Add, add for $t, $t }
 206     )*)
 207 }
 208
 209 add_impl! { uint u8 u16 u32 u64 int i8 i16 i32 i64 f32 f64 }
 210
 211 /// The `Sub` trait is used to specify the functionality of `-`.
 212 ///
 213 /// # Example
 214 ///
 215 /// A trivial implementation of `Sub`. When `Foo - Foo` happens, it ends up
 216 /// calling `sub`, and therefore, `main` prints `Subtracting!`.
 217 ///
 218 /// ```rust
 219 /// use std::ops::Sub;
 220 ///
 221 /// #[derive(Copy)]
 222 /// struct Foo;
 223 ///
 224 /// impl Sub for Foo {
 225 ///     type Output = Foo;
 226 ///
 227 ///     fn sub(self, _rhs: Foo) -> Foo {
 228 ///         println!("Subtracting!");
 229 ///         self
 230 ///     }
 231 /// }
 232 ///
 233 /// fn main() {
 234 ///     Foo - Foo;
 235 /// }
 236 /// ```
 237 #[lang="sub"]
 238 #[stable(feature = "rust1", since = "1.0.0")]
 239 pub trait Sub<RHS=Self> {
 240     #[stable(feature = "rust1", since = "1.0.0")]
 241     type Output;
 242
 243     /// The method for the `-` operator
 244     #[stable(feature = "rust1", since = "1.0.0")]
 245     fn sub(self, rhs: RHS) -> Self::Output;
 246 }
 247
 248 macro_rules! sub_impl {
 249     ($($t:ty)*) => ($(
 250         #[stable(feature = "rust1", since = "1.0.0")]
 251         impl Sub for $t {
 252             type Output = $t;
 253
 254             #[inline]
 255             fn sub(self, other: $t) -> $t { self - other }
 256         }
 257
 258         forward_ref_binop! { impl Sub, sub for $t, $t }
 259     )*)
 260 }
 261
 262 sub_impl! { uint u8 u16 u32 u64 int i8 i16 i32 i64 f32 f64 }
 263
 264 /// The `Mul` trait is used to specify the functionality of `*`.
 265 ///
 266 /// # Example
 267 ///
 268 /// A trivial implementation of `Mul`. When `Foo * Foo` happens, it ends up
 269 /// calling `mul`, and therefore, `main` prints `Multiplying!`.
 270 ///
 271 /// ```rust
 272 /// use std::ops::Mul;
 273 ///
 274 /// #[derive(Copy)]
 275 /// struct Foo;
 276 ///
 277 /// impl Mul for Foo {
 278 ///     type Output = Foo;
 279 ///
 280 ///     fn mul(self, _rhs: Foo) -> Foo {
 281 ///         println!("Multiplying!");
 282 ///         self
 283 ///     }
 284 /// }
 285 ///
 286 /// fn main() {
 287 ///     Foo * Foo;
 288 /// }
 289 /// ```
 290 #[lang="mul"]
 291 #[stable(feature = "rust1", since = "1.0.0")]
 292 pub trait Mul<RHS=Self> {
 293     #[stable(feature = "rust1", since = "1.0.0")]
 294     type Output;
 295
 296     /// The method for the `*` operator
 297     #[stable(feature = "rust1", since = "1.0.0")]
 298     fn mul(self, rhs: RHS) -> Self::Output;
 299 }
 300
 301 macro_rules! mul_impl {
 302     ($($t:ty)*) => ($(
 303         #[stable(feature = "rust1", since = "1.0.0")]
 304         impl Mul for $t {
 305             type Output = $t;
 306
 307             #[inline]
 308             fn mul(self, other: $t) -> $t { self * other }
 309         }
 310
 311         forward_ref_binop! { impl Mul, mul for $t, $t }
 312     )*)
 313 }
 314
 315 mul_impl! { uint u8 u16 u32 u64 int i8 i16 i32 i64 f32 f64 }
 316
 317 /// The `Div` trait is used to specify the functionality of `/`.
 318 ///
 319 /// # Example
 320 ///
 321 /// A trivial implementation of `Div`. When `Foo / Foo` happens, it ends up
 322 /// calling `div`, and therefore, `main` prints `Dividing!`.
 323 ///
 324 /// ```
 325 /// use std::ops::Div;
 326 ///
 327 /// #[derive(Copy)]
 328 /// struct Foo;
 329 ///
 330 /// impl Div for Foo {
 331 ///     type Output = Foo;
 332 ///
 333 ///     fn div(self, _rhs: Foo) -> Foo {
 334 ///         println!("Dividing!");
 335 ///         self
 336 ///     }
 337 /// }
 338 ///
 339 /// fn main() {
 340 ///     Foo / Foo;
 341 /// }
 342 /// ```
 343 #[lang="div"]
 344 #[stable(feature = "rust1", since = "1.0.0")]
 345 pub trait Div<RHS=Self> {
 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! { uint u8 u16 u32 u64 int i8 i16 i32 i64 f32 f64 }
 369
 370 /// The `Rem` trait is used to specify the functionality of `%`.
 371 ///
 372 /// # Example
 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)]
 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     #[stable(feature = "rust1", since = "1.0.0")]
 400     type Output = Self;
 401
 402     /// The method for the `%` operator
 403     #[stable(feature = "rust1", since = "1.0.0")]
 404     fn rem(self, rhs: RHS) -> Self::Output;
 405 }
 406
 407 macro_rules! rem_impl {
 408     ($($t:ty)*) => ($(
 409         #[stable(feature = "rust1", since = "1.0.0")]
 410         impl Rem for $t {
 411             type Output = $t;
 412
 413             #[inline]
 414             fn rem(self, other: $t) -> $t { self % other }
 415         }
 416
 417         forward_ref_binop! { impl Rem, rem for $t, $t }
 418     )*)
 419 }
 420
 421 macro_rules! rem_float_impl {
 422     ($t:ty, $fmod:ident) => {
 423         #[stable(feature = "rust1", since = "1.0.0")]
 424         impl Rem for $t {
 425             type Output = $t;
 426
 427             #[inline]
 428             fn rem(self, other: $t) -> $t {
 429                 extern { fn $fmod(a: $t, b: $t) -> $t; }
 430                 unsafe { $fmod(self, other) }
 431             }
 432         }
 433
 434         forward_ref_binop! { impl Rem, rem for $t, $t }
 435     }
 436 }
 437
 438 rem_impl! { uint u8 u16 u32 u64 int i8 i16 i32 i64 }
 439 rem_float_impl! { f32, fmodf }
 440 rem_float_impl! { f64, fmod }
 441
 442 /// The `Neg` trait is used to specify the functionality of unary `-`.
 443 ///
 444 /// # Example
 445 ///
 446 /// A trivial implementation of `Neg`. When `-Foo` happens, it ends up calling
 447 /// `neg`, and therefore, `main` prints `Negating!`.
 448 ///
 449 /// ```
 450 /// use std::ops::Neg;
 451 ///
 452 /// #[derive(Copy)]
 453 /// struct Foo;
 454 ///
 455 /// impl Neg for Foo {
 456 ///     type Output = Foo;
 457 ///
 458 ///     fn neg(self) -> Foo {
 459 ///         println!("Negating!");
 460 ///         self
 461 ///     }
 462 /// }
 463 ///
 464 /// fn main() {
 465 ///     -Foo;
 466 /// }
 467 /// ```
 468 #[lang="neg"]
 469 #[stable(feature = "rust1", since = "1.0.0")]
 470 pub trait Neg {
 471     #[stable(feature = "rust1", since = "1.0.0")]
 472     type Output;
 473
 474     /// The method for the unary `-` operator
 475     #[stable(feature = "rust1", since = "1.0.0")]
 476     fn neg(self) -> Self::Output;
 477 }
 478
 479 macro_rules! neg_impl {
 480     ($($t:ty)*) => ($(
 481         #[stable(feature = "rust1", since = "1.0.0")]
 482         impl Neg for $t {
 483             #[stable(feature = "rust1", since = "1.0.0")]
 484             type Output = $t;
 485
 486             #[inline]
 487             #[stable(feature = "rust1", since = "1.0.0")]
 488             fn neg(self) -> $t { -self }
 489         }
 490
 491         forward_ref_unop! { impl Neg, neg for $t }
 492     )*)
 493 }
 494
 495 macro_rules! neg_uint_impl {
 496     ($t:ty, $t_signed:ty) => {
 497         #[stable(feature = "rust1", since = "1.0.0")]
 498         impl Neg for $t {
 499             type Output = $t;
 500
 501             #[inline]
 502             fn neg(self) -> $t { -(self as $t_signed) as $t }
 503         }
 504
 505         forward_ref_unop! { impl Neg, neg for $t }
 506     }
 507 }
 508
 509 neg_impl! { int i8 i16 i32 i64 f32 f64 }
 510
 511 neg_uint_impl! { uint, int }
 512 neg_uint_impl! { u8, i8 }
 513 neg_uint_impl! { u16, i16 }
 514 neg_uint_impl! { u32, i32 }
 515 neg_uint_impl! { u64, i64 }
 516
 517
 518 /// The `Not` trait is used to specify the functionality of unary `!`.
 519 ///
 520 /// # Example
 521 ///
 522 /// A trivial implementation of `Not`. When `!Foo` happens, it ends up calling
 523 /// `not`, and therefore, `main` prints `Not-ing!`.
 524 ///
 525 /// ```
 526 /// use std::ops::Not;
 527 ///
 528 /// #[derive(Copy)]
 529 /// struct Foo;
 530 ///
 531 /// impl Not for Foo {
 532 ///     type Output = Foo;
 533 ///
 534 ///     fn not(self) -> Foo {
 535 ///         println!("Not-ing!");
 536 ///         self
 537 ///     }
 538 /// }
 539 ///
 540 /// fn main() {
 541 ///     !Foo;
 542 /// }
 543 /// ```
 544 #[lang="not"]
 545 #[stable(feature = "rust1", since = "1.0.0")]
 546 pub trait Not {
 547     #[stable(feature = "rust1", since = "1.0.0")]
 548     type Output;
 549
 550     /// The method for the unary `!` operator
 551     #[stable(feature = "rust1", since = "1.0.0")]
 552     fn not(self) -> Self::Output;
 553 }
 554
 555 macro_rules! not_impl {
 556     ($($t:ty)*) => ($(
 557         #[stable(feature = "rust1", since = "1.0.0")]
 558         impl Not for $t {
 559             type Output = $t;
 560
 561             #[inline]
 562             fn not(self) -> $t { !self }
 563         }
 564
 565         forward_ref_unop! { impl Not, not for $t }
 566     )*)
 567 }
 568
 569 not_impl! { bool uint u8 u16 u32 u64 int i8 i16 i32 i64 }
 570
 571 /// The `BitAnd` trait is used to specify the functionality of `&`.
 572 ///
 573 /// # Example
 574 ///
 575 /// A trivial implementation of `BitAnd`. When `Foo & Foo` happens, it ends up
 576 /// calling `bitand`, and therefore, `main` prints `Bitwise And-ing!`.
 577 ///
 578 /// ```
 579 /// use std::ops::BitAnd;
 580 ///
 581 /// #[derive(Copy)]
 582 /// struct Foo;
 583 ///
 584 /// impl BitAnd for Foo {
 585 ///     type Output = Foo;
 586 ///
 587 ///     fn bitand(self, _rhs: Foo) -> Foo {
 588 ///         println!("Bitwise And-ing!");
 589 ///         self
 590 ///     }
 591 /// }
 592 ///
 593 /// fn main() {
 594 ///     Foo & Foo;
 595 /// }
 596 /// ```
 597 #[lang="bitand"]
 598 #[stable(feature = "rust1", since = "1.0.0")]
 599 pub trait BitAnd<RHS=Self> {
 600     #[stable(feature = "rust1", since = "1.0.0")]
 601     type Output;
 602
 603     /// The method for the `&` operator
 604     #[stable(feature = "rust1", since = "1.0.0")]
 605     fn bitand(self, rhs: RHS) -> Self::Output;
 606 }
 607
 608 macro_rules! bitand_impl {
 609     ($($t:ty)*) => ($(
 610         #[stable(feature = "rust1", since = "1.0.0")]
 611         impl BitAnd for $t {
 612             type Output = $t;
 613
 614             #[inline]
 615             fn bitand(self, rhs: $t) -> $t { self & rhs }
 616         }
 617
 618         forward_ref_binop! { impl BitAnd, bitand for $t, $t }
 619     )*)
 620 }
 621
 622 bitand_impl! { bool uint u8 u16 u32 u64 int i8 i16 i32 i64 }
 623
 624 /// The `BitOr` trait is used to specify the functionality of `|`.
 625 ///
 626 /// # Example
 627 ///
 628 /// A trivial implementation of `BitOr`. When `Foo | Foo` happens, it ends up
 629 /// calling `bitor`, and therefore, `main` prints `Bitwise Or-ing!`.
 630 ///
 631 /// ```
 632 /// use std::ops::BitOr;
 633 ///
 634 /// #[derive(Copy)]
 635 /// struct Foo;
 636 ///
 637 /// impl BitOr for Foo {
 638 ///     type Output = Foo;
 639 ///
 640 ///     fn bitor(self, _rhs: Foo) -> Foo {
 641 ///         println!("Bitwise Or-ing!");
 642 ///         self
 643 ///     }
 644 /// }
 645 ///
 646 /// fn main() {
 647 ///     Foo | Foo;
 648 /// }
 649 /// ```
 650 #[lang="bitor"]
 651 #[stable(feature = "rust1", since = "1.0.0")]
 652 pub trait BitOr<RHS=Self> {
 653     #[stable(feature = "rust1", since = "1.0.0")]
 654     type Output;
 655
 656     /// The method for the `|` operator
 657     #[stable(feature = "rust1", since = "1.0.0")]
 658     fn bitor(self, rhs: RHS) -> Self::Output;
 659 }
 660
 661 macro_rules! bitor_impl {
 662     ($($t:ty)*) => ($(
 663         #[stable(feature = "rust1", since = "1.0.0")]
 664         impl BitOr for $t {
 665             type Output = $t;
 666
 667             #[inline]
 668             fn bitor(self, rhs: $t) -> $t { self | rhs }
 669         }
 670
 671         forward_ref_binop! { impl BitOr, bitor for $t, $t }
 672     )*)
 673 }
 674
 675 bitor_impl! { bool uint u8 u16 u32 u64 int i8 i16 i32 i64 }
 676
 677 /// The `BitXor` trait is used to specify the functionality of `^`.
 678 ///
 679 /// # Example
 680 ///
 681 /// A trivial implementation of `BitXor`. When `Foo ^ Foo` happens, it ends up
 682 /// calling `bitxor`, and therefore, `main` prints `Bitwise Xor-ing!`.
 683 ///
 684 /// ```
 685 /// use std::ops::BitXor;
 686 ///
 687 /// #[derive(Copy)]
 688 /// struct Foo;
 689 ///
 690 /// impl BitXor for Foo {
 691 ///     type Output = Foo;
 692 ///
 693 ///     fn bitxor(self, _rhs: Foo) -> Foo {
 694 ///         println!("Bitwise Xor-ing!");
 695 ///         self
 696 ///     }
 697 /// }
 698 ///
 699 /// fn main() {
 700 ///     Foo ^ Foo;
 701 /// }
 702 /// ```
 703 #[lang="bitxor"]
 704 #[stable(feature = "rust1", since = "1.0.0")]
 705 pub trait BitXor<RHS=Self> {
 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 uint u8 u16 u32 u64 int i8 i16 i32 i64 }
 729
 730 /// The `Shl` trait is used to specify the functionality of `<<`.
 731 ///
 732 /// # Example
 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)]
 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     #[stable(feature = "rust1", since = "1.0.0")]
 760     type Output;
 761
 762     /// The method for the `<<` operator
 763     #[stable(feature = "rust1", since = "1.0.0")]
 764     fn shl(self, rhs: RHS) -> Self::Output;
 765 }
 766
 767 macro_rules! shl_impl {
 768     ($t:ty, $f:ty) => (
 769         #[stable(feature = "rust1", since = "1.0.0")]
 770         impl Shl<$f> for $t {
 771             type Output = $t;
 772
 773             #[inline]
 774             fn shl(self, other: $f) -> $t {
 775                 self << other
 776             }
 777         }
 778
 779         forward_ref_binop! { impl Shl, shl for $t, $f }
 780     )
 781 }
 782
 783 macro_rules! shl_impl_all {
 784     ($($t:ty)*) => ($(
 785         shl_impl! { $t, u8 }
 786         shl_impl! { $t, u16 }
 787         shl_impl! { $t, u32 }
 788         shl_impl! { $t, u64 }
 789         shl_impl! { $t, usize }
 790
 791         shl_impl! { $t, i8 }
 792         shl_impl! { $t, i16 }
 793         shl_impl! { $t, i32 }
 794         shl_impl! { $t, i64 }
 795         shl_impl! { $t, isize }
 796     )*)
 797 }
 798
 799 shl_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 800
 801 /// The `Shr` trait is used to specify the functionality of `>>`.
 802 ///
 803 /// # Example
 804 ///
 805 /// A trivial implementation of `Shr`. When `Foo >> Foo` happens, it ends up
 806 /// calling `shr`, and therefore, `main` prints `Shifting right!`.
 807 ///
 808 /// ```
 809 /// use std::ops::Shr;
 810 ///
 811 /// #[derive(Copy)]
 812 /// struct Foo;
 813 ///
 814 /// impl Shr<Foo> for Foo {
 815 ///     type Output = Foo;
 816 ///
 817 ///     fn shr(self, _rhs: Foo) -> Foo {
 818 ///         println!("Shifting right!");
 819 ///         self
 820 ///     }
 821 /// }
 822 ///
 823 /// fn main() {
 824 ///     Foo >> Foo;
 825 /// }
 826 /// ```
 827 #[lang="shr"]
 828 #[stable(feature = "rust1", since = "1.0.0")]
 829 pub trait Shr<RHS> {
 830     #[stable(feature = "rust1", since = "1.0.0")]
 831     type Output;
 832
 833     /// The method for the `>>` operator
 834     #[stable(feature = "rust1", since = "1.0.0")]
 835     fn shr(self, rhs: RHS) -> Self::Output;
 836 }
 837
 838 macro_rules! shr_impl {
 839     ($t:ty, $f:ty) => (
 840         impl Shr<$f> for $t {
 841             type Output = $t;
 842
 843             #[inline]
 844             fn shr(self, other: $f) -> $t {
 845                 self >> other
 846             }
 847         }
 848
 849         forward_ref_binop! { impl Shr, shr for $t, $f }
 850     )
 851 }
 852
 853 macro_rules! shr_impl_all {
 854     ($($t:ty)*) => ($(
 855         shr_impl! { $t, u8 }
 856         shr_impl! { $t, u16 }
 857         shr_impl! { $t, u32 }
 858         shr_impl! { $t, u64 }
 859         shr_impl! { $t, usize }
 860
 861         shr_impl! { $t, i8 }
 862         shr_impl! { $t, i16 }
 863         shr_impl! { $t, i32 }
 864         shr_impl! { $t, i64 }
 865         shr_impl! { $t, isize }
 866     )*)
 867 }
 868
 869 shr_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 870
 871 /// The `Index` trait is used to specify the functionality of indexing operations
 872 /// like `arr[idx]` when used in an immutable context.
 873 ///
 874 /// # Example
 875 ///
 876 /// A trivial implementation of `Index`. When `Foo[Bar]` happens, it ends up
 877 /// calling `index`, and therefore, `main` prints `Indexing!`.
 878 ///
 879 /// ```
 880 /// use std::ops::Index;
 881 ///
 882 /// #[derive(Copy)]
 883 /// struct Foo;
 884 /// struct Bar;
 885 ///
 886 /// impl Index<Bar> for Foo {
 887 ///     type Output = Foo;
 888 ///
 889 ///     fn index<'a>(&'a self, _index: &Bar) -> &'a Foo {
 890 ///         println!("Indexing!");
 891 ///         self
 892 ///     }
 893 /// }
 894 ///
 895 /// fn main() {
 896 ///     Foo[Bar];
 897 /// }
 898 /// ```
 899 #[lang="index"]
 900 #[rustc_on_unimplemented = "the type `{Self}` cannot be indexed by `{Idx}`"]
 901 #[stable(feature = "rust1", since = "1.0.0")]
 902 pub trait Index<Idx: ?Sized> {
 903     type Output: ?Sized;
 904
 905     /// The method for the indexing (`Foo[Bar]`) operation
 906     #[stable(feature = "rust1", since = "1.0.0")]
 907     fn index<'a>(&'a self, index: &Idx) -> &'a Self::Output;
 908 }
 909
 910 /// The `IndexMut` trait is used to specify the functionality of indexing
 911 /// operations like `arr[idx]`, when used in a mutable context.
 912 ///
 913 /// # Example
 914 ///
 915 /// A trivial implementation of `IndexMut`. When `Foo[Bar]` happens, it ends up
 916 /// calling `index_mut`, and therefore, `main` prints `Indexing!`.
 917 ///
 918 /// ```
 919 /// use std::ops::{Index, IndexMut};
 920 ///
 921 /// #[derive(Copy)]
 922 /// struct Foo;
 923 /// struct Bar;
 924 ///
 925 /// impl Index<Bar> for Foo {
 926 ///     type Output = Foo;
 927 ///
 928 ///     fn index<'a>(&'a self, _index: &Bar) -> &'a Foo {
 929 ///         self
 930 ///     }
 931 /// }
 932 ///
 933 /// impl IndexMut<Bar> for Foo {
 934 ///     fn index_mut<'a>(&'a mut self, _index: &Bar) -> &'a mut Foo {
 935 ///         println!("Indexing!");
 936 ///         self
 937 ///     }
 938 /// }
 939 ///
 940 /// fn main() {
 941 ///     &mut Foo[Bar];
 942 /// }
 943 /// ```
 944 #[lang="index_mut"]
 945 #[rustc_on_unimplemented = "the type `{Self}` cannot be mutably indexed by `{Idx}`"]
 946 #[stable(feature = "rust1", since = "1.0.0")]
 947 pub trait IndexMut<Idx: ?Sized>: Index<Idx> {
 948     /// The method for the indexing (`Foo[Bar]`) operation
 949     #[stable(feature = "rust1", since = "1.0.0")]
 950     fn index_mut<'a>(&'a mut self, index: &Idx) -> &'a mut Self::Output;
 951 }
 952
 953 /// An unbounded range.
 954 #[derive(Copy, Clone, PartialEq, Eq)]
 955 #[lang="range_full"]
 956 #[stable(feature = "rust1", since = "1.0.0")]
 957 pub struct RangeFull;
 958
 959 #[stable(feature = "rust1", since = "1.0.0")]
 960 impl fmt::Debug for RangeFull {
 961     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
 962         fmt::Debug::fmt("..", fmt)
 963     }
 964 }
 965
 966 /// A (half-open) range which is bounded at both ends.
 967 #[derive(Clone, PartialEq, Eq)]
 968 #[lang="range"]
 969 #[stable(feature = "rust1", since = "1.0.0")]
 970 pub struct Range<Idx> {
 971     /// The lower bound of the range (inclusive).
 972     pub start: Idx,
 973     /// The upper bound of the range (exclusive).
 974     pub end: Idx,
 975 }
 976
 977 #[stable(feature = "rust1", since = "1.0.0")]
 978 impl<Idx: fmt::Debug> fmt::Debug for Range<Idx> {
 979     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
 980         write!(fmt, "{:?}..{:?}", self.start, self.end)
 981     }
 982 }
 983
 984 /// A range which is only bounded below.
 985 #[derive(Clone, PartialEq, Eq)]
 986 #[lang="range_from"]
 987 #[stable(feature = "rust1", since = "1.0.0")]
 988 pub struct RangeFrom<Idx> {
 989     /// The lower bound of the range (inclusive).
 990     pub start: Idx,
 991 }
 992
 993
 994
 995 #[stable(feature = "rust1", since = "1.0.0")]
 996 impl<Idx: fmt::Debug> fmt::Debug for RangeFrom<Idx> {
 997     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
 998         write!(fmt, "{:?}..", self.start)
 999     }
1000 }
1001
1002 /// A range which is only bounded above.
1003 #[derive(Copy, Clone, PartialEq, Eq)]
1004 #[lang="range_to"]
1005 #[stable(feature = "rust1", since = "1.0.0")]
1006 pub struct RangeTo<Idx> {
1007     /// The upper bound of the range (exclusive).
1008     pub end: Idx,
1009 }
1010
1011 #[stable(feature = "rust1", since = "1.0.0")]
1012 impl<Idx: fmt::Debug> fmt::Debug for RangeTo<Idx> {
1013     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1014         write!(fmt, "..{:?}", self.end)
1015     }
1016 }
1017
1018
1019 /// The `Deref` trait is used to specify the functionality of dereferencing
1020 /// operations like `*v`.
1021 ///
1022 /// # Example
1023 ///
1024 /// A struct with a single field which is accessible via dereferencing the
1025 /// struct.
1026 ///
1027 /// ```
1028 /// use std::ops::Deref;
1029 ///
1030 /// struct DerefExample<T> {
1031 ///     value: T
1032 /// }
1033 ///
1034 /// impl<T> Deref for DerefExample<T> {
1035 ///     type Target = T;
1036 ///
1037 ///     fn deref<'a>(&'a self) -> &'a T {
1038 ///         &self.value
1039 ///     }
1040 /// }
1041 ///
1042 /// fn main() {
1043 ///     let x = DerefExample { value: 'a' };
1044 ///     assert_eq!('a', *x);
1045 /// }
1046 /// ```
1047 #[lang="deref"]
1048 #[stable(feature = "rust1", since = "1.0.0")]
1049 pub trait Deref {
1050     #[stable(feature = "rust1", since = "1.0.0")]
1051     type Target: ?Sized;
1052
1053     /// The method called to dereference a value
1054     #[stable(feature = "rust1", since = "1.0.0")]
1055     fn deref<'a>(&'a self) -> &'a Self::Target;
1056 }
1057
1058 #[stable(feature = "rust1", since = "1.0.0")]
1059 impl<'a, T: ?Sized> Deref for &'a T {
1060     type Target = T;
1061
1062     fn deref(&self) -> &T { *self }
1063 }
1064
1065 #[stable(feature = "rust1", since = "1.0.0")]
1066 impl<'a, T: ?Sized> Deref for &'a mut T {
1067     type Target = T;
1068
1069     fn deref(&self) -> &T { *self }
1070 }
1071
1072 /// The `DerefMut` trait is used to specify the functionality of dereferencing
1073 /// mutably like `*v = 1;`
1074 ///
1075 /// # Example
1076 ///
1077 /// A struct with a single field which is modifiable via dereferencing the
1078 /// struct.
1079 ///
1080 /// ```
1081 /// use std::ops::{Deref, DerefMut};
1082 ///
1083 /// struct DerefMutExample<T> {
1084 ///     value: T
1085 /// }
1086 ///
1087 /// impl<T> Deref for DerefMutExample<T> {
1088 ///     type Target = T;
1089 ///
1090 ///     fn deref<'a>(&'a self) -> &'a T {
1091 ///         &self.value
1092 ///     }
1093 /// }
1094 ///
1095 /// impl<T> DerefMut for DerefMutExample<T> {
1096 ///     fn deref_mut<'a>(&'a mut self) -> &'a mut T {
1097 ///         &mut self.value
1098 ///     }
1099 /// }
1100 ///
1101 /// fn main() {
1102 ///     let mut x = DerefMutExample { value: 'a' };
1103 ///     *x = 'b';
1104 ///     assert_eq!('b', *x);
1105 /// }
1106 /// ```
1107 #[lang="deref_mut"]
1108 #[stable(feature = "rust1", since = "1.0.0")]
1109 pub trait DerefMut: Deref {
1110     /// The method called to mutably dereference a value
1111     #[stable(feature = "rust1", since = "1.0.0")]
1112     fn deref_mut<'a>(&'a mut self) -> &'a mut Self::Target;
1113 }
1114
1115 #[stable(feature = "rust1", since = "1.0.0")]
1116 impl<'a, T: ?Sized> DerefMut for &'a mut T {
1117     fn deref_mut(&mut self) -> &mut T { *self }
1118 }
1119
1120 /// A version of the call operator that takes an immutable receiver.
1121 #[lang="fn"]
1122 #[unstable(feature = "core",
1123            reason = "uncertain about variadic generics, input versus associated types")]
1124 #[rustc_paren_sugar]
1125 pub trait Fn<Args> {
1126     type Output;
1127
1128     /// This is called when the call operator is used.
1129     extern "rust-call" fn call(&self, args: Args) -> Self::Output;
1130 }
1131
1132 /// A version of the call operator that takes a mutable receiver.
1133 #[lang="fn_mut"]
1134 #[unstable(feature = "core",
1135            reason = "uncertain about variadic generics, input versus associated types")]
1136 #[rustc_paren_sugar]
1137 pub trait FnMut<Args> {
1138     type Output;
1139
1140     /// This is called when the call operator is used.
1141     extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
1142 }
1143
1144 /// A version of the call operator that takes a by-value receiver.
1145 #[lang="fn_once"]
1146 #[unstable(feature = "core",
1147            reason = "uncertain about variadic generics, input versus associated types")]
1148 #[rustc_paren_sugar]
1149 pub trait FnOnce<Args> {
1150     type Output;
1151
1152     /// This is called when the call operator is used.
1153     extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
1154 }
1155
1156 impl<F: ?Sized, A> FnMut<A> for F
1157     where F : Fn<A>
1158 {
1159     type Output = <F as Fn<A>>::Output;
1160
1161     extern "rust-call" fn call_mut(&mut self, args: A) -> <F as Fn<A>>::Output {
1162         self.call(args)
1163     }
1164 }
1165
1166 impl<F,A> FnOnce<A> for F
1167     where F : FnMut<A>
1168 {
1169     type Output = <F as FnMut<A>>::Output;
1170
1171     extern "rust-call" fn call_once(mut self, args: A) -> <F as FnMut<A>>::Output {
1172         self.call_mut(args)
1173     }
1174 }