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_integer {
 355     ($($t:ty)*) => ($(
 356         /// This operation rounds towards zero, truncating any
 357         /// fractional part of the exact result.
 358         #[stable(feature = "rust1", since = "1.0.0")]
 359         impl Div for $t {
 360             type Output = $t;
 361
 362             #[inline]
 363             fn div(self, other: $t) -> $t { self / other }
 364         }
 365
 366         forward_ref_binop! { impl Div, div for $t, $t }
 367     )*)
 368 }
 369
 370 div_impl_integer! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 371
 372 macro_rules! div_impl_float {
 373     ($($t:ty)*) => ($(
 374         #[stable(feature = "rust1", since = "1.0.0")]
 375         impl Div for $t {
 376             type Output = $t;
 377
 378             #[inline]
 379             fn div(self, other: $t) -> $t { self / other }
 380         }
 381
 382         forward_ref_binop! { impl Div, div for $t, $t }
 383     )*)
 384 }
 385
 386 div_impl_float! { f32 f64 }
 387
 388 /// The `Rem` trait is used to specify the functionality of `%`.
 389 ///
 390 /// # Examples
 391 ///
 392 /// A trivial implementation of `Rem`. When `Foo % Foo` happens, it ends up
 393 /// calling `rem`, and therefore, `main` prints `Remainder-ing!`.
 394 ///
 395 /// ```
 396 /// use std::ops::Rem;
 397 ///
 398 /// #[derive(Copy, Clone)]
 399 /// struct Foo;
 400 ///
 401 /// impl Rem for Foo {
 402 ///     type Output = Foo;
 403 ///
 404 ///     fn rem(self, _rhs: Foo) -> Foo {
 405 ///         println!("Remainder-ing!");
 406 ///         self
 407 ///     }
 408 /// }
 409 ///
 410 /// fn main() {
 411 ///     Foo % Foo;
 412 /// }
 413 /// ```
 414 #[lang = "rem"]
 415 #[stable(feature = "rust1", since = "1.0.0")]
 416 pub trait Rem<RHS=Self> {
 417     /// The resulting type after applying the `%` operator
 418     #[stable(feature = "rust1", since = "1.0.0")]
 419     type Output = Self;
 420
 421     /// The method for the `%` operator
 422     #[stable(feature = "rust1", since = "1.0.0")]
 423     fn rem(self, rhs: RHS) -> Self::Output;
 424 }
 425
 426 macro_rules! rem_impl {
 427     ($($t:ty)*) => ($(
 428         /// This operation satisfies `n % d == n - (n / d) * d`.  The
 429         /// result has the same sign as the left operand.
 430         #[stable(feature = "rust1", since = "1.0.0")]
 431         impl Rem for $t {
 432             type Output = $t;
 433
 434             #[inline]
 435             fn rem(self, other: $t) -> $t { self % other }
 436         }
 437
 438         forward_ref_binop! { impl Rem, rem for $t, $t }
 439     )*)
 440 }
 441
 442 rem_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 443
 444 #[stable(feature = "rust1", since = "1.0.0")]
 445 impl Rem for f32 {
 446     type Output = f32;
 447
 448     // see notes in `core::f32::Float::floor`
 449     #[inline]
 450     #[cfg(target_env = "msvc")]
 451     fn rem(self, other: f32) -> f32 {
 452         (self as f64).rem(other as f64) as f32
 453     }
 454
 455     #[inline]
 456     #[cfg(not(target_env = "msvc"))]
 457     fn rem(self, other: f32) -> f32 {
 458         extern { fn fmodf(a: f32, b: f32) -> f32; }
 459         unsafe { fmodf(self, other) }
 460     }
 461 }
 462
 463 #[stable(feature = "rust1", since = "1.0.0")]
 464 impl Rem for f64 {
 465     type Output = f64;
 466
 467     #[inline]
 468     fn rem(self, other: f64) -> f64 {
 469         extern { fn fmod(a: f64, b: f64) -> f64; }
 470         unsafe { fmod(self, other) }
 471     }
 472 }
 473
 474 forward_ref_binop! { impl Rem, rem for f64, f64 }
 475 forward_ref_binop! { impl Rem, rem for f32, f32 }
 476
 477 /// The `Neg` trait is used to specify the functionality of unary `-`.
 478 ///
 479 /// # Examples
 480 ///
 481 /// A trivial implementation of `Neg`. When `-Foo` happens, it ends up calling
 482 /// `neg`, and therefore, `main` prints `Negating!`.
 483 ///
 484 /// ```
 485 /// use std::ops::Neg;
 486 ///
 487 /// #[derive(Copy, Clone)]
 488 /// struct Foo;
 489 ///
 490 /// impl Neg for Foo {
 491 ///     type Output = Foo;
 492 ///
 493 ///     fn neg(self) -> Foo {
 494 ///         println!("Negating!");
 495 ///         self
 496 ///     }
 497 /// }
 498 ///
 499 /// fn main() {
 500 ///     -Foo;
 501 /// }
 502 /// ```
 503 #[lang = "neg"]
 504 #[stable(feature = "rust1", since = "1.0.0")]
 505 pub trait Neg {
 506     /// The resulting type after applying the `-` operator
 507     #[stable(feature = "rust1", since = "1.0.0")]
 508     type Output;
 509
 510     /// The method for the unary `-` operator
 511     #[stable(feature = "rust1", since = "1.0.0")]
 512     fn neg(self) -> Self::Output;
 513 }
 514
 515
 516
 517 macro_rules! neg_impl_core {
 518     ($id:ident => $body:expr, $($t:ty)*) => ($(
 519         #[stable(feature = "rust1", since = "1.0.0")]
 520         impl Neg for $t {
 521             #[stable(feature = "rust1", since = "1.0.0")]
 522             type Output = $t;
 523
 524             #[inline]
 525             #[stable(feature = "rust1", since = "1.0.0")]
 526             fn neg(self) -> $t { let $id = self; $body }
 527         }
 528
 529         forward_ref_unop! { impl Neg, neg for $t }
 530     )*)
 531 }
 532
 533 macro_rules! neg_impl_numeric {
 534     ($($t:ty)*) => { neg_impl_core!{ x => -x, $($t)*} }
 535 }
 536
 537 macro_rules! neg_impl_unsigned {
 538     ($($t:ty)*) => {
 539         neg_impl_core!{ x => {
 540             !x.wrapping_add(1)
 541         }, $($t)*} }
 542 }
 543
 544 // neg_impl_unsigned! { usize u8 u16 u32 u64 }
 545 neg_impl_numeric! { isize i8 i16 i32 i64 f32 f64 }
 546
 547 /// The `Not` trait is used to specify the functionality of unary `!`.
 548 ///
 549 /// # Examples
 550 ///
 551 /// A trivial implementation of `Not`. When `!Foo` happens, it ends up calling
 552 /// `not`, and therefore, `main` prints `Not-ing!`.
 553 ///
 554 /// ```
 555 /// use std::ops::Not;
 556 ///
 557 /// #[derive(Copy, Clone)]
 558 /// struct Foo;
 559 ///
 560 /// impl Not for Foo {
 561 ///     type Output = Foo;
 562 ///
 563 ///     fn not(self) -> Foo {
 564 ///         println!("Not-ing!");
 565 ///         self
 566 ///     }
 567 /// }
 568 ///
 569 /// fn main() {
 570 ///     !Foo;
 571 /// }
 572 /// ```
 573 #[lang = "not"]
 574 #[stable(feature = "rust1", since = "1.0.0")]
 575 pub trait Not {
 576     /// The resulting type after applying the `!` operator
 577     #[stable(feature = "rust1", since = "1.0.0")]
 578     type Output;
 579
 580     /// The method for the unary `!` operator
 581     #[stable(feature = "rust1", since = "1.0.0")]
 582     fn not(self) -> Self::Output;
 583 }
 584
 585 macro_rules! not_impl {
 586     ($($t:ty)*) => ($(
 587         #[stable(feature = "rust1", since = "1.0.0")]
 588         impl Not for $t {
 589             type Output = $t;
 590
 591             #[inline]
 592             fn not(self) -> $t { !self }
 593         }
 594
 595         forward_ref_unop! { impl Not, not for $t }
 596     )*)
 597 }
 598
 599 not_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 600
 601 /// The `BitAnd` trait is used to specify the functionality of `&`.
 602 ///
 603 /// # Examples
 604 ///
 605 /// A trivial implementation of `BitAnd`. When `Foo & Foo` happens, it ends up
 606 /// calling `bitand`, and therefore, `main` prints `Bitwise And-ing!`.
 607 ///
 608 /// ```
 609 /// use std::ops::BitAnd;
 610 ///
 611 /// #[derive(Copy, Clone)]
 612 /// struct Foo;
 613 ///
 614 /// impl BitAnd for Foo {
 615 ///     type Output = Foo;
 616 ///
 617 ///     fn bitand(self, _rhs: Foo) -> Foo {
 618 ///         println!("Bitwise And-ing!");
 619 ///         self
 620 ///     }
 621 /// }
 622 ///
 623 /// fn main() {
 624 ///     Foo & Foo;
 625 /// }
 626 /// ```
 627 #[lang = "bitand"]
 628 #[stable(feature = "rust1", since = "1.0.0")]
 629 pub trait BitAnd<RHS=Self> {
 630     /// The resulting type after applying the `&` operator
 631     #[stable(feature = "rust1", since = "1.0.0")]
 632     type Output;
 633
 634     /// The method for the `&` operator
 635     #[stable(feature = "rust1", since = "1.0.0")]
 636     fn bitand(self, rhs: RHS) -> Self::Output;
 637 }
 638
 639 macro_rules! bitand_impl {
 640     ($($t:ty)*) => ($(
 641         #[stable(feature = "rust1", since = "1.0.0")]
 642         impl BitAnd for $t {
 643             type Output = $t;
 644
 645             #[inline]
 646             fn bitand(self, rhs: $t) -> $t { self & rhs }
 647         }
 648
 649         forward_ref_binop! { impl BitAnd, bitand for $t, $t }
 650     )*)
 651 }
 652
 653 bitand_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 654
 655 /// The `BitOr` trait is used to specify the functionality of `|`.
 656 ///
 657 /// # Examples
 658 ///
 659 /// A trivial implementation of `BitOr`. When `Foo | Foo` happens, it ends up
 660 /// calling `bitor`, and therefore, `main` prints `Bitwise Or-ing!`.
 661 ///
 662 /// ```
 663 /// use std::ops::BitOr;
 664 ///
 665 /// #[derive(Copy, Clone)]
 666 /// struct Foo;
 667 ///
 668 /// impl BitOr for Foo {
 669 ///     type Output = Foo;
 670 ///
 671 ///     fn bitor(self, _rhs: Foo) -> Foo {
 672 ///         println!("Bitwise Or-ing!");
 673 ///         self
 674 ///     }
 675 /// }
 676 ///
 677 /// fn main() {
 678 ///     Foo | Foo;
 679 /// }
 680 /// ```
 681 #[lang = "bitor"]
 682 #[stable(feature = "rust1", since = "1.0.0")]
 683 pub trait BitOr<RHS=Self> {
 684     /// The resulting type after applying the `|` operator
 685     #[stable(feature = "rust1", since = "1.0.0")]
 686     type Output;
 687
 688     /// The method for the `|` operator
 689     #[stable(feature = "rust1", since = "1.0.0")]
 690     fn bitor(self, rhs: RHS) -> Self::Output;
 691 }
 692
 693 macro_rules! bitor_impl {
 694     ($($t:ty)*) => ($(
 695         #[stable(feature = "rust1", since = "1.0.0")]
 696         impl BitOr for $t {
 697             type Output = $t;
 698
 699             #[inline]
 700             fn bitor(self, rhs: $t) -> $t { self | rhs }
 701         }
 702
 703         forward_ref_binop! { impl BitOr, bitor for $t, $t }
 704     )*)
 705 }
 706
 707 bitor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 708
 709 /// The `BitXor` trait is used to specify the functionality of `^`.
 710 ///
 711 /// # Examples
 712 ///
 713 /// A trivial implementation of `BitXor`. When `Foo ^ Foo` happens, it ends up
 714 /// calling `bitxor`, and therefore, `main` prints `Bitwise Xor-ing!`.
 715 ///
 716 /// ```
 717 /// use std::ops::BitXor;
 718 ///
 719 /// #[derive(Copy, Clone)]
 720 /// struct Foo;
 721 ///
 722 /// impl BitXor for Foo {
 723 ///     type Output = Foo;
 724 ///
 725 ///     fn bitxor(self, _rhs: Foo) -> Foo {
 726 ///         println!("Bitwise Xor-ing!");
 727 ///         self
 728 ///     }
 729 /// }
 730 ///
 731 /// fn main() {
 732 ///     Foo ^ Foo;
 733 /// }
 734 /// ```
 735 #[lang = "bitxor"]
 736 #[stable(feature = "rust1", since = "1.0.0")]
 737 pub trait BitXor<RHS=Self> {
 738     /// The resulting type after applying the `^` operator
 739     #[stable(feature = "rust1", since = "1.0.0")]
 740     type Output;
 741
 742     /// The method for the `^` operator
 743     #[stable(feature = "rust1", since = "1.0.0")]
 744     fn bitxor(self, rhs: RHS) -> Self::Output;
 745 }
 746
 747 macro_rules! bitxor_impl {
 748     ($($t:ty)*) => ($(
 749         #[stable(feature = "rust1", since = "1.0.0")]
 750         impl BitXor for $t {
 751             type Output = $t;
 752
 753             #[inline]
 754             fn bitxor(self, other: $t) -> $t { self ^ other }
 755         }
 756
 757         forward_ref_binop! { impl BitXor, bitxor for $t, $t }
 758     )*)
 759 }
 760
 761 bitxor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 762
 763 /// The `Shl` trait is used to specify the functionality of `<<`.
 764 ///
 765 /// # Examples
 766 ///
 767 /// A trivial implementation of `Shl`. When `Foo << Foo` happens, it ends up
 768 /// calling `shl`, and therefore, `main` prints `Shifting left!`.
 769 ///
 770 /// ```
 771 /// use std::ops::Shl;
 772 ///
 773 /// #[derive(Copy, Clone)]
 774 /// struct Foo;
 775 ///
 776 /// impl Shl<Foo> for Foo {
 777 ///     type Output = Foo;
 778 ///
 779 ///     fn shl(self, _rhs: Foo) -> Foo {
 780 ///         println!("Shifting left!");
 781 ///         self
 782 ///     }
 783 /// }
 784 ///
 785 /// fn main() {
 786 ///     Foo << Foo;
 787 /// }
 788 /// ```
 789 #[lang = "shl"]
 790 #[stable(feature = "rust1", since = "1.0.0")]
 791 pub trait Shl<RHS> {
 792     /// The resulting type after applying the `<<` operator
 793     #[stable(feature = "rust1", since = "1.0.0")]
 794     type Output;
 795
 796     /// The method for the `<<` operator
 797     #[stable(feature = "rust1", since = "1.0.0")]
 798     fn shl(self, rhs: RHS) -> Self::Output;
 799 }
 800
 801 macro_rules! shl_impl {
 802     ($t:ty, $f:ty) => (
 803         #[stable(feature = "rust1", since = "1.0.0")]
 804         impl Shl<$f> for $t {
 805             type Output = $t;
 806
 807             #[inline]
 808             fn shl(self, other: $f) -> $t {
 809                 self << other
 810             }
 811         }
 812
 813         forward_ref_binop! { impl Shl, shl for $t, $f }
 814     )
 815 }
 816
 817 macro_rules! shl_impl_all {
 818     ($($t:ty)*) => ($(
 819         shl_impl! { $t, u8 }
 820         shl_impl! { $t, u16 }
 821         shl_impl! { $t, u32 }
 822         shl_impl! { $t, u64 }
 823         shl_impl! { $t, usize }
 824
 825         shl_impl! { $t, i8 }
 826         shl_impl! { $t, i16 }
 827         shl_impl! { $t, i32 }
 828         shl_impl! { $t, i64 }
 829         shl_impl! { $t, isize }
 830     )*)
 831 }
 832
 833 shl_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 834
 835 /// The `Shr` trait is used to specify the functionality of `>>`.
 836 ///
 837 /// # Examples
 838 ///
 839 /// A trivial implementation of `Shr`. When `Foo >> Foo` happens, it ends up
 840 /// calling `shr`, and therefore, `main` prints `Shifting right!`.
 841 ///
 842 /// ```
 843 /// use std::ops::Shr;
 844 ///
 845 /// #[derive(Copy, Clone)]
 846 /// struct Foo;
 847 ///
 848 /// impl Shr<Foo> for Foo {
 849 ///     type Output = Foo;
 850 ///
 851 ///     fn shr(self, _rhs: Foo) -> Foo {
 852 ///         println!("Shifting right!");
 853 ///         self
 854 ///     }
 855 /// }
 856 ///
 857 /// fn main() {
 858 ///     Foo >> Foo;
 859 /// }
 860 /// ```
 861 #[lang = "shr"]
 862 #[stable(feature = "rust1", since = "1.0.0")]
 863 pub trait Shr<RHS> {
 864     /// The resulting type after applying the `>>` operator
 865     #[stable(feature = "rust1", since = "1.0.0")]
 866     type Output;
 867
 868     /// The method for the `>>` operator
 869     #[stable(feature = "rust1", since = "1.0.0")]
 870     fn shr(self, rhs: RHS) -> Self::Output;
 871 }
 872
 873 macro_rules! shr_impl {
 874     ($t:ty, $f:ty) => (
 875         impl Shr<$f> for $t {
 876             type Output = $t;
 877
 878             #[inline]
 879             fn shr(self, other: $f) -> $t {
 880                 self >> other
 881             }
 882         }
 883
 884         forward_ref_binop! { impl Shr, shr for $t, $f }
 885     )
 886 }
 887
 888 macro_rules! shr_impl_all {
 889     ($($t:ty)*) => ($(
 890         shr_impl! { $t, u8 }
 891         shr_impl! { $t, u16 }
 892         shr_impl! { $t, u32 }
 893         shr_impl! { $t, u64 }
 894         shr_impl! { $t, usize }
 895
 896         shr_impl! { $t, i8 }
 897         shr_impl! { $t, i16 }
 898         shr_impl! { $t, i32 }
 899         shr_impl! { $t, i64 }
 900         shr_impl! { $t, isize }
 901     )*)
 902 }
 903
 904 shr_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 905
 906 /// The `Index` trait is used to specify the functionality of indexing operations
 907 /// like `arr[idx]` when used in an immutable context.
 908 ///
 909 /// # Examples
 910 ///
 911 /// A trivial implementation of `Index`. When `Foo[Bar]` happens, it ends up
 912 /// calling `index`, and therefore, `main` prints `Indexing!`.
 913 ///
 914 /// ```
 915 /// use std::ops::Index;
 916 ///
 917 /// #[derive(Copy, Clone)]
 918 /// struct Foo;
 919 /// struct Bar;
 920 ///
 921 /// impl Index<Bar> for Foo {
 922 ///     type Output = Foo;
 923 ///
 924 ///     fn index<'a>(&'a self, _index: Bar) -> &'a Foo {
 925 ///         println!("Indexing!");
 926 ///         self
 927 ///     }
 928 /// }
 929 ///
 930 /// fn main() {
 931 ///     Foo[Bar];
 932 /// }
 933 /// ```
 934 #[lang = "index"]
 935 #[rustc_on_unimplemented = "the type `{Self}` cannot be indexed by `{Idx}`"]
 936 #[stable(feature = "rust1", since = "1.0.0")]
 937 pub trait Index<Idx: ?Sized> {
 938     /// The returned type after indexing
 939     #[stable(feature = "rust1", since = "1.0.0")]
 940     type Output: ?Sized;
 941
 942     /// The method for the indexing (`Foo[Bar]`) operation
 943     #[stable(feature = "rust1", since = "1.0.0")]
 944     fn index<'a>(&'a self, index: Idx) -> &'a Self::Output;
 945 }
 946
 947 /// The `IndexMut` trait is used to specify the functionality of indexing
 948 /// operations like `arr[idx]`, when used in a mutable context.
 949 ///
 950 /// # Examples
 951 ///
 952 /// A trivial implementation of `IndexMut`. When `Foo[Bar]` happens, it ends up
 953 /// calling `index_mut`, and therefore, `main` prints `Indexing!`.
 954 ///
 955 /// ```
 956 /// use std::ops::{Index, IndexMut};
 957 ///
 958 /// #[derive(Copy, Clone)]
 959 /// struct Foo;
 960 /// struct Bar;
 961 ///
 962 /// impl Index<Bar> for Foo {
 963 ///     type Output = Foo;
 964 ///
 965 ///     fn index<'a>(&'a self, _index: Bar) -> &'a Foo {
 966 ///         self
 967 ///     }
 968 /// }
 969 ///
 970 /// impl IndexMut<Bar> for Foo {
 971 ///     fn index_mut<'a>(&'a mut self, _index: Bar) -> &'a mut Foo {
 972 ///         println!("Indexing!");
 973 ///         self
 974 ///     }
 975 /// }
 976 ///
 977 /// fn main() {
 978 ///     &mut Foo[Bar];
 979 /// }
 980 /// ```
 981 #[lang = "index_mut"]
 982 #[rustc_on_unimplemented = "the type `{Self}` cannot be mutably indexed by `{Idx}`"]
 983 #[stable(feature = "rust1", since = "1.0.0")]
 984 pub trait IndexMut<Idx: ?Sized>: Index<Idx> {
 985     /// The method for the indexing (`Foo[Bar]`) operation
 986     #[stable(feature = "rust1", since = "1.0.0")]
 987     fn index_mut<'a>(&'a mut self, index: Idx) -> &'a mut Self::Output;
 988 }
 989
 990 /// An unbounded range.
 991 #[derive(Copy, Clone, PartialEq, Eq)]
 992 #[lang = "range_full"]
 993 #[stable(feature = "rust1", since = "1.0.0")]
 994 pub struct RangeFull;
 995
 996 #[stable(feature = "rust1", since = "1.0.0")]
 997 impl fmt::Debug for RangeFull {
 998     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
 999         write!(fmt, "..")
1000     }
1001 }
1002
1003 /// A (half-open) range which is bounded at both ends.
1004 #[derive(Clone, PartialEq, Eq)]
1005 #[lang = "range"]
1006 #[stable(feature = "rust1", since = "1.0.0")]
1007 pub struct Range<Idx> {
1008     /// The lower bound of the range (inclusive).
1009     #[stable(feature = "rust1", since = "1.0.0")]
1010     pub start: Idx,
1011     /// The upper bound of the range (exclusive).
1012     #[stable(feature = "rust1", since = "1.0.0")]
1013     pub end: Idx,
1014 }
1015
1016 #[stable(feature = "rust1", since = "1.0.0")]
1017 impl<Idx: fmt::Debug> fmt::Debug for Range<Idx> {
1018     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1019         write!(fmt, "{:?}..{:?}", self.start, self.end)
1020     }
1021 }
1022
1023 /// A range which is only bounded below.
1024 #[derive(Clone, PartialEq, Eq)]
1025 #[lang = "range_from"]
1026 #[stable(feature = "rust1", since = "1.0.0")]
1027 pub struct RangeFrom<Idx> {
1028     /// The lower bound of the range (inclusive).
1029     #[stable(feature = "rust1", since = "1.0.0")]
1030     pub start: Idx,
1031 }
1032
1033 #[stable(feature = "rust1", since = "1.0.0")]
1034 impl<Idx: fmt::Debug> fmt::Debug for RangeFrom<Idx> {
1035     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1036         write!(fmt, "{:?}..", self.start)
1037     }
1038 }
1039
1040 /// A range which is only bounded above.
1041 #[derive(Copy, Clone, PartialEq, Eq)]
1042 #[lang = "range_to"]
1043 #[stable(feature = "rust1", since = "1.0.0")]
1044 pub struct RangeTo<Idx> {
1045     /// The upper bound of the range (exclusive).
1046     #[stable(feature = "rust1", since = "1.0.0")]
1047     pub end: Idx,
1048 }
1049
1050 #[stable(feature = "rust1", since = "1.0.0")]
1051 impl<Idx: fmt::Debug> fmt::Debug for RangeTo<Idx> {
1052     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1053         write!(fmt, "..{:?}", self.end)
1054     }
1055 }
1056
1057 /// The `Deref` trait is used to specify the functionality of dereferencing
1058 /// operations like `*v`.
1059 ///
1060 /// `Deref` also enables ['`Deref` coercions'][coercions].
1061 ///
1062 /// [coercions]: ../../book/deref-coercions.html
1063 ///
1064 /// # Examples
1065 ///
1066 /// A struct with a single field which is accessible via dereferencing the
1067 /// struct.
1068 ///
1069 /// ```
1070 /// use std::ops::Deref;
1071 ///
1072 /// struct DerefExample<T> {
1073 ///     value: T
1074 /// }
1075 ///
1076 /// impl<T> Deref for DerefExample<T> {
1077 ///     type Target = T;
1078 ///
1079 ///     fn deref<'a>(&'a self) -> &'a T {
1080 ///         &self.value
1081 ///     }
1082 /// }
1083 ///
1084 /// fn main() {
1085 ///     let x = DerefExample { value: 'a' };
1086 ///     assert_eq!('a', *x);
1087 /// }
1088 /// ```
1089 #[lang = "deref"]
1090 #[stable(feature = "rust1", since = "1.0.0")]
1091 pub trait Deref {
1092     /// The resulting type after dereferencing
1093     #[stable(feature = "rust1", since = "1.0.0")]
1094     type Target: ?Sized;
1095
1096     /// The method called to dereference a value
1097     #[stable(feature = "rust1", since = "1.0.0")]
1098     fn deref<'a>(&'a self) -> &'a Self::Target;
1099 }
1100
1101 #[stable(feature = "rust1", since = "1.0.0")]
1102 impl<'a, T: ?Sized> Deref for &'a T {
1103     type Target = T;
1104
1105     fn deref(&self) -> &T { *self }
1106 }
1107
1108 #[stable(feature = "rust1", since = "1.0.0")]
1109 impl<'a, T: ?Sized> Deref for &'a mut T {
1110     type Target = T;
1111
1112     fn deref(&self) -> &T { *self }
1113 }
1114
1115 /// The `DerefMut` trait is used to specify the functionality of dereferencing
1116 /// mutably like `*v = 1;`
1117 ///
1118 /// `DerefMut` also enables ['`Deref` coercions'][coercions].
1119 ///
1120 /// [coercions]: ../../book/deref-coercions.html
1121 ///
1122 /// # Examples
1123 ///
1124 /// A struct with a single field which is modifiable via dereferencing the
1125 /// struct.
1126 ///
1127 /// ```
1128 /// use std::ops::{Deref, DerefMut};
1129 ///
1130 /// struct DerefMutExample<T> {
1131 ///     value: T
1132 /// }
1133 ///
1134 /// impl<T> Deref for DerefMutExample<T> {
1135 ///     type Target = T;
1136 ///
1137 ///     fn deref<'a>(&'a self) -> &'a T {
1138 ///         &self.value
1139 ///     }
1140 /// }
1141 ///
1142 /// impl<T> DerefMut for DerefMutExample<T> {
1143 ///     fn deref_mut<'a>(&'a mut self) -> &'a mut T {
1144 ///         &mut self.value
1145 ///     }
1146 /// }
1147 ///
1148 /// fn main() {
1149 ///     let mut x = DerefMutExample { value: 'a' };
1150 ///     *x = 'b';
1151 ///     assert_eq!('b', *x);
1152 /// }
1153 /// ```
1154 #[lang = "deref_mut"]
1155 #[stable(feature = "rust1", since = "1.0.0")]
1156 pub trait DerefMut: Deref {
1157     /// The method called to mutably dereference a value
1158     #[stable(feature = "rust1", since = "1.0.0")]
1159     fn deref_mut<'a>(&'a mut self) -> &'a mut Self::Target;
1160 }
1161
1162 #[stable(feature = "rust1", since = "1.0.0")]
1163 impl<'a, T: ?Sized> DerefMut for &'a mut T {
1164     fn deref_mut(&mut self) -> &mut T { *self }
1165 }
1166
1167 /// A version of the call operator that takes an immutable receiver.
1168 #[lang = "fn"]
1169 #[stable(feature = "rust1", since = "1.0.0")]
1170 #[rustc_paren_sugar]
1171 #[fundamental] // so that regex can rely that `&str: !FnMut`
1172 pub trait Fn<Args> : FnMut<Args> {
1173     /// This is called when the call operator is used.
1174     extern "rust-call" fn call(&self, args: Args) -> Self::Output;
1175 }
1176
1177 /// A version of the call operator that takes a mutable receiver.
1178 #[lang = "fn_mut"]
1179 #[stable(feature = "rust1", since = "1.0.0")]
1180 #[rustc_paren_sugar]
1181 #[fundamental] // so that regex can rely that `&str: !FnMut`
1182 pub trait FnMut<Args> : FnOnce<Args> {
1183     /// This is called when the call operator is used.
1184     extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
1185 }
1186
1187 /// A version of the call operator that takes a by-value receiver.
1188 #[lang = "fn_once"]
1189 #[stable(feature = "rust1", since = "1.0.0")]
1190 #[rustc_paren_sugar]
1191 #[fundamental] // so that regex can rely that `&str: !FnMut`
1192 pub trait FnOnce<Args> {
1193     /// The returned type after the call operator is used.
1194     type Output;
1195
1196     /// This is called when the call operator is used.
1197     extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
1198 }
1199
1200 mod impls {
1201     use marker::Sized;
1202     use super::{Fn, FnMut, FnOnce};
1203
1204     impl<'a,A,F:?Sized> Fn<A> for &'a F
1205         where F : Fn<A>
1206     {
1207         extern "rust-call" fn call(&self, args: A) -> F::Output {
1208             (**self).call(args)
1209         }
1210     }
1211
1212     impl<'a,A,F:?Sized> FnMut<A> for &'a F
1213         where F : Fn<A>
1214     {
1215         extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
1216             (**self).call(args)
1217         }
1218     }
1219
1220     impl<'a,A,F:?Sized> FnOnce<A> for &'a F
1221         where F : Fn<A>
1222     {
1223         type Output = F::Output;
1224
1225         extern "rust-call" fn call_once(self, args: A) -> F::Output {
1226             (*self).call(args)
1227         }
1228     }
1229
1230     impl<'a,A,F:?Sized> FnMut<A> for &'a mut F
1231         where F : FnMut<A>
1232     {
1233         extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
1234             (*self).call_mut(args)
1235         }
1236     }
1237
1238     impl<'a,A,F:?Sized> FnOnce<A> for &'a mut F
1239         where F : FnMut<A>
1240     {
1241         type Output = F::Output;
1242         extern "rust-call" fn call_once(mut self, args: A) -> F::Output {
1243             (*self).call_mut(args)
1244         }
1245     }
1246 }
1247
1248 /// Trait that indicates that this is a pointer or a wrapper for one,
1249 /// where unsizing can be performed on the pointee.
1250 #[unstable(feature = "coerce_unsized", issue = "27732")]
1251 #[lang="coerce_unsized"]
1252 pub trait CoerceUnsized<T> {
1253     // Empty.
1254 }
1255
1256 // &mut T -> &mut U
1257 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a mut U> for &'a mut T {}
1258 // &mut T -> &U
1259 impl<'a, 'b: 'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a U> for &'b mut T {}
1260 // &mut T -> *mut U
1261 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*mut U> for &'a mut T {}
1262 // &mut T -> *const U
1263 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for &'a mut T {}
1264
1265 // &T -> &U
1266 impl<'a, 'b: 'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a U> for &'b T {}
1267 // &T -> *const U
1268 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for &'a T {}
1269
1270 // *mut T -> *mut U
1271 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*mut U> for *mut T {}
1272 // *mut T -> *const U
1273 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for *mut T {}
1274
1275 // *const T -> *const U
1276 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for *const T {}
1277
1278 /// Both `in (PLACE) EXPR` and `box EXPR` desugar into expressions
1279 /// that allocate an intermediate "place" that holds uninitialized
1280 /// state.  The desugaring evaluates EXPR, and writes the result at
1281 /// the address returned by the `pointer` method of this trait.
1282 ///
1283 /// A `Place` can be thought of as a special representation for a
1284 /// hypothetical `&uninit` reference (which Rust cannot currently
1285 /// express directly). That is, it represents a pointer to
1286 /// uninitialized storage.
1287 ///
1288 /// The client is responsible for two steps: First, initializing the
1289 /// payload (it can access its address via `pointer`). Second,
1290 /// converting the agent to an instance of the owning pointer, via the
1291 /// appropriate `finalize` method (see the `InPlace`.
1292 ///
1293 /// If evaluating EXPR fails, then the destructor for the
1294 /// implementation of Place to clean up any intermediate state
1295 /// (e.g. deallocate box storage, pop a stack, etc).
1296 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1297 pub trait Place<Data: ?Sized> {
1298     /// Returns the address where the input value will be written.
1299     /// Note that the data at this address is generally uninitialized,
1300     /// and thus one should use `ptr::write` for initializing it.
1301     fn pointer(&mut self) -> *mut Data;
1302 }
1303
1304 /// Interface to implementations of  `in (PLACE) EXPR`.
1305 ///
1306 /// `in (PLACE) EXPR` effectively desugars into:
1307 ///
1308 /// ```rust,ignore
1309 /// let p = PLACE;
1310 /// let mut place = Placer::make_place(p);
1311 /// let raw_place = Place::pointer(&mut place);
1312 /// let value = EXPR;
1313 /// unsafe {
1314 ///     std::ptr::write(raw_place, value);
1315 ///     InPlace::finalize(place)
1316 /// }
1317 /// ```
1318 ///
1319 /// The type of `in (PLACE) EXPR` is derived from the type of `PLACE`;
1320 /// if the type of `PLACE` is `P`, then the final type of the whole
1321 /// expression is `P::Place::Owner` (see the `InPlace` and `Boxed`
1322 /// traits).
1323 ///
1324 /// Values for types implementing this trait usually are transient
1325 /// intermediate values (e.g. the return value of `Vec::emplace_back`)
1326 /// or `Copy`, since the `make_place` method takes `self` by value.
1327 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1328 pub trait Placer<Data: ?Sized> {
1329     /// `Place` is the intermedate agent guarding the
1330     /// uninitialized state for `Data`.
1331     type Place: InPlace<Data>;
1332
1333     /// Creates a fresh place from `self`.
1334     fn make_place(self) -> Self::Place;
1335 }
1336
1337 /// Specialization of `Place` trait supporting `in (PLACE) EXPR`.
1338 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1339 pub trait InPlace<Data: ?Sized>: Place<Data> {
1340     /// `Owner` is the type of the end value of `in (PLACE) EXPR`
1341     ///
1342     /// Note that when `in (PLACE) EXPR` is solely used for
1343     /// side-effecting an existing data-structure,
1344     /// e.g. `Vec::emplace_back`, then `Owner` need not carry any
1345     /// information at all (e.g. it can be the unit type `()` in that
1346     /// case).
1347     type Owner;
1348
1349     /// Converts self into the final value, shifting
1350     /// deallocation/cleanup responsibilities (if any remain), over to
1351     /// the returned instance of `Owner` and forgetting self.
1352     unsafe fn finalize(self) -> Self::Owner;
1353 }
1354
1355 /// Core trait for the `box EXPR` form.
1356 ///
1357 /// `box EXPR` effectively desugars into:
1358 ///
1359 /// ```rust,ignore
1360 /// let mut place = BoxPlace::make_place();
1361 /// let raw_place = Place::pointer(&mut place);
1362 /// let value = EXPR;
1363 /// unsafe {
1364 ///     ::std::ptr::write(raw_place, value);
1365 ///     Boxed::finalize(place)
1366 /// }
1367 /// ```
1368 ///
1369 /// The type of `box EXPR` is supplied from its surrounding
1370 /// context; in the above expansion, the result type `T` is used
1371 /// to determine which implementation of `Boxed` to use, and that
1372 /// `<T as Boxed>` in turn dictates determines which
1373 /// implementation of `BoxPlace` to use, namely:
1374 /// `<<T as Boxed>::Place as BoxPlace>`.
1375 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1376 pub trait Boxed {
1377     /// The kind of data that is stored in this kind of box.
1378     type Data;  /* (`Data` unused b/c cannot yet express below bound.) */
1379     /// The place that will negotiate the storage of the data.
1380     type Place: BoxPlace<Self::Data>;
1381
1382     /// Converts filled place into final owning value, shifting
1383     /// deallocation/cleanup responsibilities (if any remain), over to
1384     /// returned instance of `Self` and forgetting `filled`.
1385     unsafe fn finalize(filled: Self::Place) -> Self;
1386 }
1387
1388 /// Specialization of `Place` trait supporting `box EXPR`.
1389 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1390 pub trait BoxPlace<Data: ?Sized> : Place<Data> {
1391     /// Creates a globally fresh place.
1392     fn make_place() -> Self;
1393 }