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 //! The values for the right hand side of an operator are automatically
  17 //! borrowed, so `a + b` is sugar for `a.add(&b)`.
  18 //!
  19 //! All of these traits are imported by the prelude, so they are available in
  20 //! every Rust program.
  21 //!
  22 //! # Example
  23 //!
  24 //! This example creates a `Point` struct that implements `Add` and `Sub`, and then
  25 //! demonstrates adding and subtracting two `Point`s.
  26 //!
  27 //! ```rust
  28 //! #[deriving(Show)]
  29 //! struct Point {
  30 //!     x: int,
  31 //!     y: int
  32 //! }
  33 //!
  34 //! impl Add<Point, Point> for Point {
  35 //!     fn add(self, other: Point) -> Point {
  36 //!         Point {x: self.x + other.x, y: self.y + other.y}
  37 //!     }
  38 //! }
  39 //!
  40 //! impl Sub<Point, Point> for Point {
  41 //!     fn sub(self, other: Point) -> Point {
  42 //!         Point {x: self.x - other.x, y: self.y - other.y}
  43 //!     }
  44 //! }
  45 //! fn main() {
  46 //!     println!("{}", Point {x: 1, y: 0} + Point {x: 2, y: 3});
  47 //!     println!("{}", Point {x: 1, y: 0} - Point {x: 2, y: 3});
  48 //! }
  49 //! ```
  50 //!
  51 //! See the documentation for each trait for a minimum implementation that prints
  52 //! something to the screen.
  53
  54 use kinds::Sized;
  55
  56 /// The `Drop` trait is used to run some code when a value goes out of scope. This
  57 /// is sometimes called a 'destructor'.
  58 ///
  59 /// # Example
  60 ///
  61 /// A trivial implementation of `Drop`. The `drop` method is called when `_x` goes
  62 /// out of scope, and therefore `main` prints `Dropping!`.
  63 ///
  64 /// ```rust
  65 /// struct HasDrop;
  66 ///
  67 /// impl Drop for HasDrop {
  68 ///   fn drop(&mut self) {
  69 ///       println!("Dropping!");
  70 ///   }
  71 /// }
  72 ///
  73 /// fn main() {
  74 ///   let _x = HasDrop;
  75 /// }
  76 /// ```
  77 #[lang="drop"]
  78 pub trait Drop {
  79     /// The `drop` method, called when the value goes out of scope.
  80     fn drop(&mut self);
  81 }
  82
  83 /// The `Add` trait is used to specify the functionality of `+`.
  84 ///
  85 /// # Example
  86 ///
  87 /// A trivial implementation of `Add`. When `Foo + Foo` happens, it ends up
  88 /// calling `add`, and therefore, `main` prints `Adding!`.
  89 ///
  90 /// ```rust
  91 /// #[deriving(Copy)]
  92 /// struct Foo;
  93 ///
  94 /// impl Add<Foo, Foo> for Foo {
  95 ///     fn add(self, _rhs: Foo) -> Foo {
  96 ///       println!("Adding!");
  97 ///       self
  98 ///   }
  99 /// }
 100 ///
 101 /// fn main() {
 102 ///   Foo + Foo;
 103 /// }
 104 /// ```
 105 #[lang="add"]
 106 pub trait Add<RHS, Result> {
 107     /// The method for the `+` operator
 108     fn add(self, rhs: RHS) -> Result;
 109 }
 110
 111 macro_rules! add_impl {
 112     ($($t:ty)*) => ($(
 113         impl Add<$t, $t> for $t {
 114             #[inline]
 115             fn add(self, other: $t) -> $t { self + other }
 116         }
 117     )*)
 118 }
 119
 120 add_impl! { uint u8 u16 u32 u64 int i8 i16 i32 i64 f32 f64 }
 121
 122 /// The `Sub` trait is used to specify the functionality of `-`.
 123 ///
 124 /// # Example
 125 ///
 126 /// A trivial implementation of `Sub`. When `Foo - Foo` happens, it ends up
 127 /// calling `sub`, and therefore, `main` prints `Subtracting!`.
 128 ///
 129 /// ```rust
 130 /// #[deriving(Copy)]
 131 /// struct Foo;
 132 ///
 133 /// impl Sub<Foo, Foo> for Foo {
 134 ///     fn sub(self, _rhs: Foo) -> Foo {
 135 ///         println!("Subtracting!");
 136 ///         self
 137 ///     }
 138 /// }
 139 ///
 140 /// fn main() {
 141 ///     Foo - Foo;
 142 /// }
 143 /// ```
 144 #[lang="sub"]
 145 pub trait Sub<RHS, Result> {
 146     /// The method for the `-` operator
 147     fn sub(self, rhs: RHS) -> Result;
 148 }
 149
 150 macro_rules! sub_impl {
 151     ($($t:ty)*) => ($(
 152         impl Sub<$t, $t> for $t {
 153             #[inline]
 154             fn sub(self, other: $t) -> $t { self - other }
 155         }
 156     )*)
 157 }
 158
 159 sub_impl! { uint u8 u16 u32 u64 int i8 i16 i32 i64 f32 f64 }
 160
 161 /// The `Mul` trait is used to specify the functionality of `*`.
 162 ///
 163 /// # Example
 164 ///
 165 /// A trivial implementation of `Mul`. When `Foo * Foo` happens, it ends up
 166 /// calling `mul`, and therefore, `main` prints `Multiplying!`.
 167 ///
 168 /// ```rust
 169 /// #[deriving(Copy)]
 170 /// struct Foo;
 171 ///
 172 /// impl Mul<Foo, Foo> for Foo {
 173 ///     fn mul(self, _rhs: Foo) -> Foo {
 174 ///         println!("Multiplying!");
 175 ///         self
 176 ///     }
 177 /// }
 178 ///
 179 /// fn main() {
 180 ///     Foo * Foo;
 181 /// }
 182 /// ```
 183 #[lang="mul"]
 184 pub trait Mul<RHS, Result> {
 185     /// The method for the `*` operator
 186     fn mul(self, rhs: RHS) -> Result;
 187 }
 188
 189 macro_rules! mul_impl {
 190     ($($t:ty)*) => ($(
 191         impl Mul<$t, $t> for $t {
 192             #[inline]
 193             fn mul(self, other: $t) -> $t { self * other }
 194         }
 195     )*)
 196 }
 197
 198 mul_impl! { uint u8 u16 u32 u64 int i8 i16 i32 i64 f32 f64 }
 199
 200 /// The `Div` trait is used to specify the functionality of `/`.
 201 ///
 202 /// # Example
 203 ///
 204 /// A trivial implementation of `Div`. When `Foo / Foo` happens, it ends up
 205 /// calling `div`, and therefore, `main` prints `Dividing!`.
 206 ///
 207 /// ```
 208 /// #[deriving(Copy)]
 209 /// struct Foo;
 210 ///
 211 /// impl Div<Foo, Foo> for Foo {
 212 ///     fn div(self, _rhs: Foo) -> Foo {
 213 ///         println!("Dividing!");
 214 ///         self
 215 ///     }
 216 /// }
 217 ///
 218 /// fn main() {
 219 ///     Foo / Foo;
 220 /// }
 221 /// ```
 222 #[lang="div"]
 223 pub trait Div<RHS, Result> {
 224     /// The method for the `/` operator
 225     fn div(self, rhs: RHS) -> Result;
 226 }
 227
 228 macro_rules! div_impl {
 229     ($($t:ty)*) => ($(
 230         impl Div<$t, $t> for $t {
 231             #[inline]
 232             fn div(self, other: $t) -> $t { self / other }
 233         }
 234     )*)
 235 }
 236
 237 div_impl! { uint u8 u16 u32 u64 int i8 i16 i32 i64 f32 f64 }
 238
 239 /// The `Rem` trait is used to specify the functionality of `%`.
 240 ///
 241 /// # Example
 242 ///
 243 /// A trivial implementation of `Rem`. When `Foo % Foo` happens, it ends up
 244 /// calling `rem`, and therefore, `main` prints `Remainder-ing!`.
 245 ///
 246 /// ```
 247 /// #[deriving(Copy)]
 248 /// struct Foo;
 249 ///
 250 /// impl Rem<Foo, Foo> for Foo {
 251 ///     fn rem(self, _rhs: Foo) -> Foo {
 252 ///         println!("Remainder-ing!");
 253 ///         self
 254 ///     }
 255 /// }
 256 ///
 257 /// fn main() {
 258 ///     Foo % Foo;
 259 /// }
 260 /// ```
 261 #[lang="rem"]
 262 pub trait Rem<RHS, Result> {
 263     /// The method for the `%` operator
 264     fn rem(self, rhs: RHS) -> Result;
 265 }
 266
 267 macro_rules! rem_impl {
 268     ($($t:ty)*) => ($(
 269         impl Rem<$t, $t> for $t {
 270             #[inline]
 271             fn rem(self, other: $t) -> $t { self % other }
 272         }
 273     )*)
 274 }
 275
 276 macro_rules! rem_float_impl {
 277     ($t:ty, $fmod:ident) => {
 278         impl Rem<$t, $t> for $t {
 279             #[inline]
 280             fn rem(self, other: $t) -> $t {
 281                 extern { fn $fmod(a: $t, b: $t) -> $t; }
 282                 unsafe { $fmod(self, other) }
 283             }
 284         }
 285     }
 286 }
 287
 288 rem_impl! { uint u8 u16 u32 u64 int i8 i16 i32 i64 }
 289 rem_float_impl! { f32, fmodf }
 290 rem_float_impl! { f64, fmod }
 291
 292 /// The `Neg` trait is used to specify the functionality of unary `-`.
 293 ///
 294 /// # Example
 295 ///
 296 /// A trivial implementation of `Neg`. When `-Foo` happens, it ends up calling
 297 /// `neg`, and therefore, `main` prints `Negating!`.
 298 ///
 299 /// ```
 300 /// #[deriving(Copy)]
 301 /// struct Foo;
 302 ///
 303 /// impl Neg<Foo> for Foo {
 304 ///     fn neg(&self) -> Foo {
 305 ///         println!("Negating!");
 306 ///         *self
 307 ///     }
 308 /// }
 309 ///
 310 /// fn main() {
 311 ///     -Foo;
 312 /// }
 313 /// ```
 314 // NOTE(stage0): Remove trait after a snapshot
 315 #[cfg(stage0)]
 316 #[lang="neg"]
 317 pub trait Neg<Result> for Sized? {
 318     /// The method for the unary `-` operator
 319     fn neg(&self) -> Result;
 320 }
 321
 322 // NOTE(stage0): Remove macro after a snapshot
 323 #[cfg(stage0)]
 324 macro_rules! neg_impl {
 325     ($($t:ty)*) => ($(
 326         impl Neg<$t> for $t {
 327             #[inline]
 328             fn neg(&self) -> $t { -*self }
 329         }
 330     )*)
 331 }
 332
 333 // NOTE(stage0): Remove macro after a snapshot
 334 #[cfg(stage0)]
 335 macro_rules! neg_uint_impl {
 336     ($t:ty, $t_signed:ty) => {
 337         impl Neg<$t> for $t {
 338             #[inline]
 339             fn neg(&self) -> $t { -(*self as $t_signed) as $t }
 340         }
 341     }
 342 }
 343
 344 /// The `Neg` trait is used to specify the functionality of unary `-`.
 345 ///
 346 /// # Example
 347 ///
 348 /// A trivial implementation of `Neg`. When `-Foo` happens, it ends up calling
 349 /// `neg`, and therefore, `main` prints `Negating!`.
 350 ///
 351 /// ```
 352 /// struct Foo;
 353 ///
 354 /// impl Copy for Foo {}
 355 ///
 356 /// impl Neg<Foo> for Foo {
 357 ///     fn neg(self) -> Foo {
 358 ///         println!("Negating!");
 359 ///         self
 360 ///     }
 361 /// }
 362 ///
 363 /// fn main() {
 364 ///     -Foo;
 365 /// }
 366 /// ```
 367 #[cfg(not(stage0))]  // NOTE(stage0): Remove cfg after a snapshot
 368 #[lang="neg"]
 369 pub trait Neg<Result> {
 370     /// The method for the unary `-` operator
 371     fn neg(self) -> Result;
 372 }
 373
 374 #[cfg(not(stage0))]  // NOTE(stage0): Remove cfg after a snapshot
 375 macro_rules! neg_impl {
 376     ($($t:ty)*) => ($(
 377         impl Neg<$t> for $t {
 378             #[inline]
 379             fn neg(self) -> $t { -self }
 380         }
 381     )*)
 382 }
 383
 384 #[cfg(not(stage0))]  // NOTE(stage0): Remove cfg after a snapshot
 385 macro_rules! neg_uint_impl {
 386     ($t:ty, $t_signed:ty) => {
 387         impl Neg<$t> for $t {
 388             #[inline]
 389             fn neg(self) -> $t { -(self as $t_signed) as $t }
 390         }
 391     }
 392 }
 393
 394 neg_impl! { int i8 i16 i32 i64 f32 f64 }
 395
 396 neg_uint_impl! { uint, int }
 397 neg_uint_impl! { u8, i8 }
 398 neg_uint_impl! { u16, i16 }
 399 neg_uint_impl! { u32, i32 }
 400 neg_uint_impl! { u64, i64 }
 401
 402
 403 /// The `Not` trait is used to specify the functionality of unary `!`.
 404 ///
 405 /// # Example
 406 ///
 407 /// A trivial implementation of `Not`. When `!Foo` happens, it ends up calling
 408 /// `not`, and therefore, `main` prints `Not-ing!`.
 409 ///
 410 /// ```
 411 /// #[deriving(Copy)]
 412 /// struct Foo;
 413 ///
 414 /// impl Not<Foo> for Foo {
 415 ///     fn not(&self) -> Foo {
 416 ///         println!("Not-ing!");
 417 ///         *self
 418 ///     }
 419 /// }
 420 ///
 421 /// fn main() {
 422 ///     !Foo;
 423 /// }
 424 /// ```
 425 // NOTE(stage0): Remove macro after a snapshot
 426 #[cfg(stage0)]
 427 #[lang="not"]
 428 pub trait Not<Result> for Sized? {
 429     /// The method for the unary `!` operator
 430     fn not(&self) -> Result;
 431 }
 432
 433
 434 // NOTE(stage0): Remove macro after a snapshot
 435 #[cfg(stage0)]
 436 macro_rules! not_impl {
 437     ($($t:ty)*) => ($(
 438         impl Not<$t> for $t {
 439             #[inline]
 440             fn not(&self) -> $t { !*self }
 441         }
 442     )*)
 443 }
 444
 445 /// The `Not` trait is used to specify the functionality of unary `!`.
 446 ///
 447 /// # Example
 448 ///
 449 /// A trivial implementation of `Not`. When `!Foo` happens, it ends up calling
 450 /// `not`, and therefore, `main` prints `Not-ing!`.
 451 ///
 452 /// ```
 453 /// struct Foo;
 454 ///
 455 /// impl Copy for Foo {}
 456 ///
 457 /// impl Not<Foo> for Foo {
 458 ///     fn not(self) -> Foo {
 459 ///         println!("Not-ing!");
 460 ///         self
 461 ///     }
 462 /// }
 463 ///
 464 /// fn main() {
 465 ///     !Foo;
 466 /// }
 467 /// ```
 468 #[cfg(not(stage0))]  // NOTE(stage0): Remove cfg after a snapshot
 469 #[lang="not"]
 470 pub trait Not<Result> {
 471     /// The method for the unary `!` operator
 472     fn not(self) -> Result;
 473 }
 474
 475 #[cfg(not(stage0))]  // NOTE(stage0): Remove cfg after a snapshot
 476 macro_rules! not_impl {
 477     ($($t:ty)*) => ($(
 478         impl Not<$t> for $t {
 479             #[inline]
 480             fn not(self) -> $t { !self }
 481         }
 482     )*)
 483 }
 484
 485 not_impl! { bool uint u8 u16 u32 u64 int i8 i16 i32 i64 }
 486
 487 /// The `BitAnd` trait is used to specify the functionality of `&`.
 488 ///
 489 /// # Example
 490 ///
 491 /// A trivial implementation of `BitAnd`. When `Foo & Foo` happens, it ends up
 492 /// calling `bitand`, and therefore, `main` prints `Bitwise And-ing!`.
 493 ///
 494 /// ```
 495 /// #[deriving(Copy)]
 496 /// struct Foo;
 497 ///
 498 /// impl BitAnd<Foo, Foo> for Foo {
 499 ///     fn bitand(self, _rhs: Foo) -> Foo {
 500 ///         println!("Bitwise And-ing!");
 501 ///         self
 502 ///     }
 503 /// }
 504 ///
 505 /// fn main() {
 506 ///     Foo & Foo;
 507 /// }
 508 /// ```
 509 #[lang="bitand"]
 510 pub trait BitAnd<RHS, Result> {
 511     /// The method for the `&` operator
 512     fn bitand(self, rhs: RHS) -> Result;
 513 }
 514
 515 macro_rules! bitand_impl {
 516     ($($t:ty)*) => ($(
 517         impl BitAnd<$t, $t> for $t {
 518             #[inline]
 519             fn bitand(self, rhs: $t) -> $t { self & rhs }
 520         }
 521     )*)
 522 }
 523
 524 bitand_impl! { bool uint u8 u16 u32 u64 int i8 i16 i32 i64 }
 525
 526 /// The `BitOr` trait is used to specify the functionality of `|`.
 527 ///
 528 /// # Example
 529 ///
 530 /// A trivial implementation of `BitOr`. When `Foo | Foo` happens, it ends up
 531 /// calling `bitor`, and therefore, `main` prints `Bitwise Or-ing!`.
 532 ///
 533 /// ```
 534 /// #[deriving(Copy)]
 535 /// struct Foo;
 536 ///
 537 /// impl BitOr<Foo, Foo> for Foo {
 538 ///     fn bitor(self, _rhs: Foo) -> Foo {
 539 ///         println!("Bitwise Or-ing!");
 540 ///         self
 541 ///     }
 542 /// }
 543 ///
 544 /// fn main() {
 545 ///     Foo | Foo;
 546 /// }
 547 /// ```
 548 #[lang="bitor"]
 549 pub trait BitOr<RHS, Result> {
 550     /// The method for the `|` operator
 551     fn bitor(self, rhs: RHS) -> Result;
 552 }
 553
 554 macro_rules! bitor_impl {
 555     ($($t:ty)*) => ($(
 556         impl BitOr<$t,$t> for $t {
 557             #[inline]
 558             fn bitor(self, rhs: $t) -> $t { self | rhs }
 559         }
 560     )*)
 561 }
 562
 563 bitor_impl! { bool uint u8 u16 u32 u64 int i8 i16 i32 i64 }
 564
 565 /// The `BitXor` trait is used to specify the functionality of `^`.
 566 ///
 567 /// # Example
 568 ///
 569 /// A trivial implementation of `BitXor`. When `Foo ^ Foo` happens, it ends up
 570 /// calling `bitxor`, and therefore, `main` prints `Bitwise Xor-ing!`.
 571 ///
 572 /// ```
 573 /// #[deriving(Copy)]
 574 /// struct Foo;
 575 ///
 576 /// impl BitXor<Foo, Foo> for Foo {
 577 ///     fn bitxor(self, _rhs: Foo) -> Foo {
 578 ///         println!("Bitwise Xor-ing!");
 579 ///         self
 580 ///     }
 581 /// }
 582 ///
 583 /// fn main() {
 584 ///     Foo ^ Foo;
 585 /// }
 586 /// ```
 587 #[lang="bitxor"]
 588 pub trait BitXor<RHS, Result> {
 589     /// The method for the `^` operator
 590     fn bitxor(self, rhs: RHS) -> Result;
 591 }
 592
 593 macro_rules! bitxor_impl {
 594     ($($t:ty)*) => ($(
 595         impl BitXor<$t, $t> for $t {
 596             #[inline]
 597             fn bitxor(self, other: $t) -> $t { self ^ other }
 598         }
 599     )*)
 600 }
 601
 602 bitxor_impl! { bool uint u8 u16 u32 u64 int i8 i16 i32 i64 }
 603
 604 /// The `Shl` trait is used to specify the functionality of `<<`.
 605 ///
 606 /// # Example
 607 ///
 608 /// A trivial implementation of `Shl`. When `Foo << Foo` happens, it ends up
 609 /// calling `shl`, and therefore, `main` prints `Shifting left!`.
 610 ///
 611 /// ```
 612 /// #[deriving(Copy)]
 613 /// struct Foo;
 614 ///
 615 /// impl Shl<Foo, Foo> for Foo {
 616 ///     fn shl(self, _rhs: Foo) -> Foo {
 617 ///         println!("Shifting left!");
 618 ///         self
 619 ///     }
 620 /// }
 621 ///
 622 /// fn main() {
 623 ///     Foo << Foo;
 624 /// }
 625 /// ```
 626 #[lang="shl"]
 627 pub trait Shl<RHS, Result> {
 628     /// The method for the `<<` operator
 629     fn shl(self, rhs: RHS) -> Result;
 630 }
 631
 632 macro_rules! shl_impl {
 633     ($($t:ty)*) => ($(
 634         impl Shl<uint, $t> for $t {
 635             #[inline]
 636             fn shl(self, other: uint) -> $t {
 637                 self << other
 638             }
 639         }
 640     )*)
 641 }
 642
 643 shl_impl! { uint u8 u16 u32 u64 int i8 i16 i32 i64 }
 644
 645 /// The `Shr` trait is used to specify the functionality of `>>`.
 646 ///
 647 /// # Example
 648 ///
 649 /// A trivial implementation of `Shr`. When `Foo >> Foo` happens, it ends up
 650 /// calling `shr`, and therefore, `main` prints `Shifting right!`.
 651 ///
 652 /// ```
 653 /// #[deriving(Copy)]
 654 /// struct Foo;
 655 ///
 656 /// impl Shr<Foo, Foo> for Foo {
 657 ///     fn shr(self, _rhs: Foo) -> Foo {
 658 ///         println!("Shifting right!");
 659 ///         self
 660 ///     }
 661 /// }
 662 ///
 663 /// fn main() {
 664 ///     Foo >> Foo;
 665 /// }
 666 /// ```
 667 #[lang="shr"]
 668 pub trait Shr<RHS, Result> {
 669     /// The method for the `>>` operator
 670     fn shr(self, rhs: RHS) -> Result;
 671 }
 672
 673 macro_rules! shr_impl {
 674     ($($t:ty)*) => ($(
 675         impl Shr<uint, $t> for $t {
 676             #[inline]
 677             fn shr(self, other: uint) -> $t { self >> other }
 678         }
 679     )*)
 680 }
 681
 682 shr_impl! { uint u8 u16 u32 u64 int i8 i16 i32 i64 }
 683
 684 /// The `Index` trait is used to specify the functionality of indexing operations
 685 /// like `arr[idx]` when used in an immutable context.
 686 ///
 687 /// # Example
 688 ///
 689 /// A trivial implementation of `Index`. When `Foo[Foo]` happens, it ends up
 690 /// calling `index`, and therefore, `main` prints `Indexing!`.
 691 ///
 692 /// ```
 693 /// #[deriving(Copy)]
 694 /// struct Foo;
 695 ///
 696 /// impl Index<Foo, Foo> for Foo {
 697 ///     fn index<'a>(&'a self, _index: &Foo) -> &'a Foo {
 698 ///         println!("Indexing!");
 699 ///         self
 700 ///     }
 701 /// }
 702 ///
 703 /// fn main() {
 704 ///     Foo[Foo];
 705 /// }
 706 /// ```
 707 #[lang="index"]
 708 pub trait Index<Sized? Index, Sized? Result> for Sized? {
 709     /// The method for the indexing (`Foo[Bar]`) operation
 710     fn index<'a>(&'a self, index: &Index) -> &'a Result;
 711 }
 712
 713 /// The `IndexMut` trait is used to specify the functionality of indexing
 714 /// operations like `arr[idx]`, when used in a mutable context.
 715 ///
 716 /// # Example
 717 ///
 718 /// A trivial implementation of `IndexMut`. When `Foo[Foo]` happens, it ends up
 719 /// calling `index_mut`, and therefore, `main` prints `Indexing!`.
 720 ///
 721 /// ```
 722 /// #[deriving(Copy)]
 723 /// struct Foo;
 724 ///
 725 /// impl IndexMut<Foo, Foo> for Foo {
 726 ///     fn index_mut<'a>(&'a mut self, _index: &Foo) -> &'a mut Foo {
 727 ///         println!("Indexing!");
 728 ///         self
 729 ///     }
 730 /// }
 731 ///
 732 /// fn main() {
 733 ///     &mut Foo[Foo];
 734 /// }
 735 /// ```
 736 #[lang="index_mut"]
 737 pub trait IndexMut<Sized? Index, Sized? Result> for Sized? {
 738     /// The method for the indexing (`Foo[Bar]`) operation
 739     fn index_mut<'a>(&'a mut self, index: &Index) -> &'a mut Result;
 740 }
 741
 742 /// The `Slice` trait is used to specify the functionality of slicing operations
 743 /// like `arr[from..to]` when used in an immutable context.
 744 ///
 745 /// # Example
 746 ///
 747 /// A trivial implementation of `Slice`. When `Foo[..Foo]` happens, it ends up
 748 /// calling `slice_to`, and therefore, `main` prints `Slicing!`.
 749 ///
 750 /// ```ignore
 751 /// #[deriving(Copy)]
 752 /// struct Foo;
 753 ///
 754 /// impl Slice<Foo, Foo> for Foo {
 755 ///     fn as_slice_<'a>(&'a self) -> &'a Foo {
 756 ///         println!("Slicing!");
 757 ///         self
 758 ///     }
 759 ///     fn slice_from_or_fail<'a>(&'a self, _from: &Foo) -> &'a Foo {
 760 ///         println!("Slicing!");
 761 ///         self
 762 ///     }
 763 ///     fn slice_to_or_fail<'a>(&'a self, _to: &Foo) -> &'a Foo {
 764 ///         println!("Slicing!");
 765 ///         self
 766 ///     }
 767 ///     fn slice_or_fail<'a>(&'a self, _from: &Foo, _to: &Foo) -> &'a Foo {
 768 ///         println!("Slicing!");
 769 ///         self
 770 ///     }
 771 /// }
 772 ///
 773 /// fn main() {
 774 ///     Foo[..Foo];
 775 /// }
 776 /// ```
 777 #[lang="slice"]
 778 pub trait Slice<Sized? Idx, Sized? Result> for Sized? {
 779     /// The method for the slicing operation foo[]
 780     fn as_slice_<'a>(&'a self) -> &'a Result;
 781     /// The method for the slicing operation foo[from..]
 782     fn slice_from_or_fail<'a>(&'a self, from: &Idx) -> &'a Result;
 783     /// The method for the slicing operation foo[..to]
 784     fn slice_to_or_fail<'a>(&'a self, to: &Idx) -> &'a Result;
 785     /// The method for the slicing operation foo[from..to]
 786     fn slice_or_fail<'a>(&'a self, from: &Idx, to: &Idx) -> &'a Result;
 787 }
 788
 789 /// The `SliceMut` trait is used to specify the functionality of slicing
 790 /// operations like `arr[from..to]`, when used in a mutable context.
 791 ///
 792 /// # Example
 793 ///
 794 /// A trivial implementation of `SliceMut`. When `Foo[Foo..]` happens, it ends up
 795 /// calling `slice_from_mut`, and therefore, `main` prints `Slicing!`.
 796 ///
 797 /// ```ignore
 798 /// #[deriving(Copy)]
 799 /// struct Foo;
 800 ///
 801 /// impl SliceMut<Foo, Foo> for Foo {
 802 ///     fn as_mut_slice_<'a>(&'a mut self) -> &'a mut Foo {
 803 ///         println!("Slicing!");
 804 ///         self
 805 ///     }
 806 ///     fn slice_from_or_fail_mut<'a>(&'a mut self, _from: &Foo) -> &'a mut Foo {
 807 ///         println!("Slicing!");
 808 ///         self
 809 ///     }
 810 ///     fn slice_to_or_fail_mut<'a>(&'a mut self, _to: &Foo) -> &'a mut Foo {
 811 ///         println!("Slicing!");
 812 ///         self
 813 ///     }
 814 ///     fn slice_or_fail_mut<'a>(&'a mut self, _from: &Foo, _to: &Foo) -> &'a mut Foo {
 815 ///         println!("Slicing!");
 816 ///         self
 817 ///     }
 818 /// }
 819 ///
 820 /// pub fn main() {
 821 ///     Foo[mut Foo..];
 822 /// }
 823 /// ```
 824 #[lang="slice_mut"]
 825 pub trait SliceMut<Sized? Idx, Sized? Result> for Sized? {
 826     /// The method for the slicing operation foo[]
 827     fn as_mut_slice_<'a>(&'a mut self) -> &'a mut Result;
 828     /// The method for the slicing operation foo[from..]
 829     fn slice_from_or_fail_mut<'a>(&'a mut self, from: &Idx) -> &'a mut Result;
 830     /// The method for the slicing operation foo[..to]
 831     fn slice_to_or_fail_mut<'a>(&'a mut self, to: &Idx) -> &'a mut Result;
 832     /// The method for the slicing operation foo[from..to]
 833     fn slice_or_fail_mut<'a>(&'a mut self, from: &Idx, to: &Idx) -> &'a mut Result;
 834 }
 835
 836 /// The `Deref` trait is used to specify the functionality of dereferencing
 837 /// operations like `*v`.
 838 ///
 839 /// # Example
 840 ///
 841 /// A struct with a single field which is accessible via dereferencing the
 842 /// struct.
 843 ///
 844 /// ```
 845 /// struct DerefExample<T> {
 846 ///     value: T
 847 /// }
 848 ///
 849 /// impl<T> Deref<T> for DerefExample<T> {
 850 ///     fn deref<'a>(&'a self) -> &'a T {
 851 ///         &self.value
 852 ///     }
 853 /// }
 854 ///
 855 /// fn main() {
 856 ///     let x = DerefExample { value: 'a' };
 857 ///     assert_eq!('a', *x);
 858 /// }
 859 /// ```
 860 #[lang="deref"]
 861 pub trait Deref<Sized? Result> for Sized? {
 862     /// The method called to dereference a value
 863     fn deref<'a>(&'a self) -> &'a Result;
 864 }
 865
 866 impl<'a, Sized? T> Deref<T> for &'a T {
 867     fn deref(&self) -> &T { *self }
 868 }
 869
 870 impl<'a, Sized? T> Deref<T> for &'a mut T {
 871     fn deref(&self) -> &T { *self }
 872 }
 873
 874 /// The `DerefMut` trait is used to specify the functionality of dereferencing
 875 /// mutably like `*v = 1;`
 876 ///
 877 /// # Example
 878 ///
 879 /// A struct with a single field which is modifiable via dereferencing the
 880 /// struct.
 881 ///
 882 /// ```
 883 /// struct DerefMutExample<T> {
 884 ///     value: T
 885 /// }
 886 ///
 887 /// impl<T> Deref<T> for DerefMutExample<T> {
 888 ///     fn deref<'a>(&'a self) -> &'a T {
 889 ///         &self.value
 890 ///     }
 891 /// }
 892 ///
 893 /// impl<T> DerefMut<T> for DerefMutExample<T> {
 894 ///     fn deref_mut<'a>(&'a mut self) -> &'a mut T {
 895 ///         &mut self.value
 896 ///     }
 897 /// }
 898 ///
 899 /// fn main() {
 900 ///     let mut x = DerefMutExample { value: 'a' };
 901 ///     *x = 'b';
 902 ///     assert_eq!('b', *x);
 903 /// }
 904 /// ```
 905 #[lang="deref_mut"]
 906 pub trait DerefMut<Sized? Result> for Sized? : Deref<Result> {
 907     /// The method called to mutably dereference a value
 908     fn deref_mut<'a>(&'a mut self) -> &'a mut Result;
 909 }
 910
 911 impl<'a, Sized? T> DerefMut<T> for &'a mut T {
 912     fn deref_mut(&mut self) -> &mut T { *self }
 913 }
 914
 915 /// A version of the call operator that takes an immutable receiver.
 916 #[lang="fn"]
 917 pub trait Fn<Args,Result> for Sized? {
 918     /// This is called when the call operator is used.
 919     extern "rust-call" fn call(&self, args: Args) -> Result;
 920 }
 921
 922 /// A version of the call operator that takes a mutable receiver.
 923 #[lang="fn_mut"]
 924 pub trait FnMut<Args,Result> for Sized? {
 925     /// This is called when the call operator is used.
 926     extern "rust-call" fn call_mut(&mut self, args: Args) -> Result;
 927 }
 928
 929 /// A version of the call operator that takes a by-value receiver.
 930 #[lang="fn_once"]
 931 pub trait FnOnce<Args,Result> {
 932     /// This is called when the call operator is used.
 933     extern "rust-call" fn call_once(self, args: Args) -> Result;
 934 }
 935
 936 impl<Sized? F,A,R> FnMut<A,R> for F
 937     where F : Fn<A,R>
 938 {
 939     extern "rust-call" fn call_mut(&mut self, args: A) -> R {
 940         self.call(args)
 941     }
 942 }
 943
 944 impl<F,A,R> FnOnce<A,R> for F
 945     where F : FnMut<A,R>
 946 {
 947     extern "rust-call" fn call_once(mut self, args: A) -> R {
 948         self.call_mut(args)
 949     }
 950 }