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.
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.
11 //! Overloadable operators
13 //! Implementing these traits allows you to get an effect similar to
14 //! overloading operators.
16 //! Some of these traits are imported by the prelude, so they are available in
17 //! every Rust program.
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.
32 //! This example creates a `Point` struct that implements `Add` and `Sub`, and
33 //! then demonstrates adding and subtracting two `Point`s.
36 //! use std::ops::{Add, Sub};
44 //! impl Add for Point {
45 //! type Output = Point;
47 //! fn add(self, other: Point) -> Point {
48 //! Point {x: self.x + other.x, y: self.y + other.y}
52 //! impl Sub for Point {
53 //! type Output = Point;
55 //! fn sub(self, other: Point) -> Point {
56 //! Point {x: self.x - other.x, y: self.y - other.y}
60 //! println!("{:?}", Point {x: 1, y: 0} + Point {x: 2, y: 3});
61 //! println!("{:?}", Point {x: 1, y: 0} - Point {x: 2, y: 3});
65 //! See the documentation for each trait for a minimum implementation that
66 //! prints something to the screen.
68 #![stable(feature = "rust1", since = "1.0.0")]
70 use marker::{Sized, Unsize};
73 /// The `Drop` trait is used to run some code when a value goes out of scope.
74 /// This is sometimes called a 'destructor'.
78 /// A trivial implementation of `Drop`. The `drop` method is called when `_x`
79 /// goes out of scope, and therefore `main` prints `Dropping!`.
84 /// impl Drop for HasDrop {
85 /// fn drop(&mut self) {
86 /// println!("Dropping!");
95 #[stable(feature = "rust1", since = "1.0.0")]
97 /// A method called when the value goes out of scope.
99 /// When this method has been called, `self` has not yet been deallocated.
100 /// If it were, `self` would be a dangling reference.
102 /// After this function is over, the memory of `self` will be deallocated.
106 /// Given that a `panic!` will call `drop()` as it unwinds, any `panic!` in
107 /// a `drop()` implementation will likely abort.
108 #[stable(feature = "rust1", since = "1.0.0")]
112 // implements the unary operator "op &T"
113 // based on "op T" where T is expected to be `Copy`able
114 macro_rules! forward_ref_unop {
115 (impl $imp:ident, $method:ident for $t:ty) => {
116 #[stable(feature = "rust1", since = "1.0.0")]
117 impl<'a> $imp for &'a $t {
118 type Output = <$t as $imp>::Output;
121 fn $method(self) -> <$t as $imp>::Output {
128 // implements binary operators "&T op U", "T op &U", "&T op &U"
129 // based on "T op U" where T and U are expected to be `Copy`able
130 macro_rules! forward_ref_binop {
131 (impl $imp:ident, $method:ident for $t:ty, $u:ty) => {
132 #[stable(feature = "rust1", since = "1.0.0")]
133 impl<'a> $imp<$u> for &'a $t {
134 type Output = <$t as $imp<$u>>::Output;
137 fn $method(self, other: $u) -> <$t as $imp<$u>>::Output {
138 $imp::$method(*self, other)
142 #[stable(feature = "rust1", since = "1.0.0")]
143 impl<'a> $imp<&'a $u> for $t {
144 type Output = <$t as $imp<$u>>::Output;
147 fn $method(self, other: &'a $u) -> <$t as $imp<$u>>::Output {
148 $imp::$method(self, *other)
152 #[stable(feature = "rust1", since = "1.0.0")]
153 impl<'a, 'b> $imp<&'a $u> for &'b $t {
154 type Output = <$t as $imp<$u>>::Output;
157 fn $method(self, other: &'a $u) -> <$t as $imp<$u>>::Output {
158 $imp::$method(*self, *other)
164 /// The `Add` trait is used to specify the functionality of `+`.
168 /// A trivial implementation of `Add`. When `Foo + Foo` happens, it ends up
169 /// calling `add`, and therefore, `main` prints `Adding!`.
172 /// use std::ops::Add;
176 /// impl Add for Foo {
177 /// type Output = Foo;
179 /// fn add(self, _rhs: Foo) -> Foo {
180 /// println!("Adding!");
190 #[stable(feature = "rust1", since = "1.0.0")]
191 pub trait Add<RHS=Self> {
192 /// The resulting type after applying the `+` operator
193 #[stable(feature = "rust1", since = "1.0.0")]
196 /// The method for the `+` operator
197 #[stable(feature = "rust1", since = "1.0.0")]
198 fn add(self, rhs: RHS) -> Self::Output;
201 macro_rules! add_impl {
203 #[stable(feature = "rust1", since = "1.0.0")]
208 fn add(self, other: $t) -> $t { self + other }
211 forward_ref_binop! { impl Add, add for $t, $t }
215 add_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
217 /// The `Sub` trait is used to specify the functionality of `-`.
221 /// A trivial implementation of `Sub`. When `Foo - Foo` happens, it ends up
222 /// calling `sub`, and therefore, `main` prints `Subtracting!`.
225 /// use std::ops::Sub;
229 /// impl Sub for Foo {
230 /// type Output = Foo;
232 /// fn sub(self, _rhs: Foo) -> Foo {
233 /// println!("Subtracting!");
243 #[stable(feature = "rust1", since = "1.0.0")]
244 pub trait Sub<RHS=Self> {
245 /// The resulting type after applying the `-` operator
246 #[stable(feature = "rust1", since = "1.0.0")]
249 /// The method for the `-` operator
250 #[stable(feature = "rust1", since = "1.0.0")]
251 fn sub(self, rhs: RHS) -> Self::Output;
254 macro_rules! sub_impl {
256 #[stable(feature = "rust1", since = "1.0.0")]
261 fn sub(self, other: $t) -> $t { self - other }
264 forward_ref_binop! { impl Sub, sub for $t, $t }
268 sub_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
270 /// The `Mul` trait is used to specify the functionality of `*`.
274 /// A trivial implementation of `Mul`. When `Foo * Foo` happens, it ends up
275 /// calling `mul`, and therefore, `main` prints `Multiplying!`.
278 /// use std::ops::Mul;
282 /// impl Mul for Foo {
283 /// type Output = Foo;
285 /// fn mul(self, _rhs: Foo) -> Foo {
286 /// println!("Multiplying!");
296 #[stable(feature = "rust1", since = "1.0.0")]
297 pub trait Mul<RHS=Self> {
298 /// The resulting type after applying the `*` operator
299 #[stable(feature = "rust1", since = "1.0.0")]
302 /// The method for the `*` operator
303 #[stable(feature = "rust1", since = "1.0.0")]
304 fn mul(self, rhs: RHS) -> Self::Output;
307 macro_rules! mul_impl {
309 #[stable(feature = "rust1", since = "1.0.0")]
314 fn mul(self, other: $t) -> $t { self * other }
317 forward_ref_binop! { impl Mul, mul for $t, $t }
321 mul_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
323 /// The `Div` trait is used to specify the functionality of `/`.
327 /// A trivial implementation of `Div`. When `Foo / Foo` happens, it ends up
328 /// calling `div`, and therefore, `main` prints `Dividing!`.
331 /// use std::ops::Div;
335 /// impl Div for Foo {
336 /// type Output = Foo;
338 /// fn div(self, _rhs: Foo) -> Foo {
339 /// println!("Dividing!");
349 #[stable(feature = "rust1", since = "1.0.0")]
350 pub trait Div<RHS=Self> {
351 /// The resulting type after applying the `/` operator
352 #[stable(feature = "rust1", since = "1.0.0")]
355 /// The method for the `/` operator
356 #[stable(feature = "rust1", since = "1.0.0")]
357 fn div(self, rhs: RHS) -> Self::Output;
360 macro_rules! div_impl_integer {
362 /// This operation rounds towards zero, truncating any
363 /// fractional part of the exact result.
364 #[stable(feature = "rust1", since = "1.0.0")]
369 fn div(self, other: $t) -> $t { self / other }
372 forward_ref_binop! { impl Div, div for $t, $t }
376 div_impl_integer! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
378 macro_rules! div_impl_float {
380 #[stable(feature = "rust1", since = "1.0.0")]
385 fn div(self, other: $t) -> $t { self / other }
388 forward_ref_binop! { impl Div, div for $t, $t }
392 div_impl_float! { f32 f64 }
394 /// The `Rem` trait is used to specify the functionality of `%`.
398 /// A trivial implementation of `Rem`. When `Foo % Foo` happens, it ends up
399 /// calling `rem`, and therefore, `main` prints `Remainder-ing!`.
402 /// use std::ops::Rem;
406 /// impl Rem for Foo {
407 /// type Output = Foo;
409 /// fn rem(self, _rhs: Foo) -> Foo {
410 /// println!("Remainder-ing!");
420 #[stable(feature = "rust1", since = "1.0.0")]
421 pub trait Rem<RHS=Self> {
422 /// The resulting type after applying the `%` operator
423 #[stable(feature = "rust1", since = "1.0.0")]
426 /// The method for the `%` operator
427 #[stable(feature = "rust1", since = "1.0.0")]
428 fn rem(self, rhs: RHS) -> Self::Output;
431 macro_rules! rem_impl_integer {
433 /// This operation satisfies `n % d == n - (n / d) * d`. The
434 /// result has the same sign as the left operand.
435 #[stable(feature = "rust1", since = "1.0.0")]
440 fn rem(self, other: $t) -> $t { self % other }
443 forward_ref_binop! { impl Rem, rem for $t, $t }
447 rem_impl_integer! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
449 macro_rules! rem_impl_float {
451 #[stable(feature = "rust1", since = "1.0.0")]
456 fn rem(self, other: $t) -> $t { self % other }
459 forward_ref_binop! { impl Rem, rem for $t, $t }
463 rem_impl_float! { f32 f64 }
465 /// The `Neg` trait is used to specify the functionality of unary `-`.
469 /// A trivial implementation of `Neg`. When `-Foo` happens, it ends up calling
470 /// `neg`, and therefore, `main` prints `Negating!`.
473 /// use std::ops::Neg;
477 /// impl Neg for Foo {
478 /// type Output = Foo;
480 /// fn neg(self) -> Foo {
481 /// println!("Negating!");
491 #[stable(feature = "rust1", since = "1.0.0")]
493 /// The resulting type after applying the `-` operator
494 #[stable(feature = "rust1", since = "1.0.0")]
497 /// The method for the unary `-` operator
498 #[stable(feature = "rust1", since = "1.0.0")]
499 fn neg(self) -> Self::Output;
504 macro_rules! neg_impl_core {
505 ($id:ident => $body:expr, $($t:ty)*) => ($(
506 #[stable(feature = "rust1", since = "1.0.0")]
511 fn neg(self) -> $t { let $id = self; $body }
514 forward_ref_unop! { impl Neg, neg for $t }
518 macro_rules! neg_impl_numeric {
519 ($($t:ty)*) => { neg_impl_core!{ x => -x, $($t)*} }
522 macro_rules! neg_impl_unsigned {
524 neg_impl_core!{ x => {
529 // neg_impl_unsigned! { usize u8 u16 u32 u64 }
530 neg_impl_numeric! { isize i8 i16 i32 i64 f32 f64 }
532 /// The `Not` trait is used to specify the functionality of unary `!`.
536 /// A trivial implementation of `Not`. When `!Foo` happens, it ends up calling
537 /// `not`, and therefore, `main` prints `Not-ing!`.
540 /// use std::ops::Not;
544 /// impl Not for Foo {
545 /// type Output = Foo;
547 /// fn not(self) -> Foo {
548 /// println!("Not-ing!");
558 #[stable(feature = "rust1", since = "1.0.0")]
560 /// The resulting type after applying the `!` operator
561 #[stable(feature = "rust1", since = "1.0.0")]
564 /// The method for the unary `!` operator
565 #[stable(feature = "rust1", since = "1.0.0")]
566 fn not(self) -> Self::Output;
569 macro_rules! not_impl {
571 #[stable(feature = "rust1", since = "1.0.0")]
576 fn not(self) -> $t { !self }
579 forward_ref_unop! { impl Not, not for $t }
583 not_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
585 /// The `BitAnd` trait is used to specify the functionality of `&`.
589 /// A trivial implementation of `BitAnd`. When `Foo & Foo` happens, it ends up
590 /// calling `bitand`, and therefore, `main` prints `Bitwise And-ing!`.
593 /// use std::ops::BitAnd;
597 /// impl BitAnd for Foo {
598 /// type Output = Foo;
600 /// fn bitand(self, _rhs: Foo) -> Foo {
601 /// println!("Bitwise And-ing!");
611 #[stable(feature = "rust1", since = "1.0.0")]
612 pub trait BitAnd<RHS=Self> {
613 /// The resulting type after applying the `&` operator
614 #[stable(feature = "rust1", since = "1.0.0")]
617 /// The method for the `&` operator
618 #[stable(feature = "rust1", since = "1.0.0")]
619 fn bitand(self, rhs: RHS) -> Self::Output;
622 macro_rules! bitand_impl {
624 #[stable(feature = "rust1", since = "1.0.0")]
629 fn bitand(self, rhs: $t) -> $t { self & rhs }
632 forward_ref_binop! { impl BitAnd, bitand for $t, $t }
636 bitand_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
638 /// The `BitOr` trait is used to specify the functionality of `|`.
642 /// A trivial implementation of `BitOr`. When `Foo | Foo` happens, it ends up
643 /// calling `bitor`, and therefore, `main` prints `Bitwise Or-ing!`.
646 /// use std::ops::BitOr;
650 /// impl BitOr for Foo {
651 /// type Output = Foo;
653 /// fn bitor(self, _rhs: Foo) -> Foo {
654 /// println!("Bitwise Or-ing!");
664 #[stable(feature = "rust1", since = "1.0.0")]
665 pub trait BitOr<RHS=Self> {
666 /// The resulting type after applying the `|` operator
667 #[stable(feature = "rust1", since = "1.0.0")]
670 /// The method for the `|` operator
671 #[stable(feature = "rust1", since = "1.0.0")]
672 fn bitor(self, rhs: RHS) -> Self::Output;
675 macro_rules! bitor_impl {
677 #[stable(feature = "rust1", since = "1.0.0")]
682 fn bitor(self, rhs: $t) -> $t { self | rhs }
685 forward_ref_binop! { impl BitOr, bitor for $t, $t }
689 bitor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
691 /// The `BitXor` trait is used to specify the functionality of `^`.
695 /// A trivial implementation of `BitXor`. When `Foo ^ Foo` happens, it ends up
696 /// calling `bitxor`, and therefore, `main` prints `Bitwise Xor-ing!`.
699 /// use std::ops::BitXor;
703 /// impl BitXor for Foo {
704 /// type Output = Foo;
706 /// fn bitxor(self, _rhs: Foo) -> Foo {
707 /// println!("Bitwise Xor-ing!");
717 #[stable(feature = "rust1", since = "1.0.0")]
718 pub trait BitXor<RHS=Self> {
719 /// The resulting type after applying the `^` operator
720 #[stable(feature = "rust1", since = "1.0.0")]
723 /// The method for the `^` operator
724 #[stable(feature = "rust1", since = "1.0.0")]
725 fn bitxor(self, rhs: RHS) -> Self::Output;
728 macro_rules! bitxor_impl {
730 #[stable(feature = "rust1", since = "1.0.0")]
735 fn bitxor(self, other: $t) -> $t { self ^ other }
738 forward_ref_binop! { impl BitXor, bitxor for $t, $t }
742 bitxor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
744 /// The `Shl` trait is used to specify the functionality of `<<`.
748 /// A trivial implementation of `Shl`. When `Foo << Foo` happens, it ends up
749 /// calling `shl`, and therefore, `main` prints `Shifting left!`.
752 /// use std::ops::Shl;
756 /// impl Shl<Foo> for Foo {
757 /// type Output = Foo;
759 /// fn shl(self, _rhs: Foo) -> Foo {
760 /// println!("Shifting left!");
770 #[stable(feature = "rust1", since = "1.0.0")]
772 /// The resulting type after applying the `<<` operator
773 #[stable(feature = "rust1", since = "1.0.0")]
776 /// The method for the `<<` operator
777 #[stable(feature = "rust1", since = "1.0.0")]
778 fn shl(self, rhs: RHS) -> Self::Output;
781 macro_rules! shl_impl {
783 #[stable(feature = "rust1", since = "1.0.0")]
784 impl Shl<$f> for $t {
788 fn shl(self, other: $f) -> $t {
793 forward_ref_binop! { impl Shl, shl for $t, $f }
797 macro_rules! shl_impl_all {
800 shl_impl! { $t, u16 }
801 shl_impl! { $t, u32 }
802 shl_impl! { $t, u64 }
803 shl_impl! { $t, usize }
806 shl_impl! { $t, i16 }
807 shl_impl! { $t, i32 }
808 shl_impl! { $t, i64 }
809 shl_impl! { $t, isize }
813 shl_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
815 /// The `Shr` trait is used to specify the functionality of `>>`.
819 /// A trivial implementation of `Shr`. When `Foo >> Foo` happens, it ends up
820 /// calling `shr`, and therefore, `main` prints `Shifting right!`.
823 /// use std::ops::Shr;
827 /// impl Shr<Foo> for Foo {
828 /// type Output = Foo;
830 /// fn shr(self, _rhs: Foo) -> Foo {
831 /// println!("Shifting right!");
841 #[stable(feature = "rust1", since = "1.0.0")]
843 /// The resulting type after applying the `>>` operator
844 #[stable(feature = "rust1", since = "1.0.0")]
847 /// The method for the `>>` operator
848 #[stable(feature = "rust1", since = "1.0.0")]
849 fn shr(self, rhs: RHS) -> Self::Output;
852 macro_rules! shr_impl {
854 #[stable(feature = "rust1", since = "1.0.0")]
855 impl Shr<$f> for $t {
859 fn shr(self, other: $f) -> $t {
864 forward_ref_binop! { impl Shr, shr for $t, $f }
868 macro_rules! shr_impl_all {
871 shr_impl! { $t, u16 }
872 shr_impl! { $t, u32 }
873 shr_impl! { $t, u64 }
874 shr_impl! { $t, usize }
877 shr_impl! { $t, i16 }
878 shr_impl! { $t, i32 }
879 shr_impl! { $t, i64 }
880 shr_impl! { $t, isize }
884 shr_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
886 /// The `AddAssign` trait is used to specify the functionality of `+=`.
890 /// A trivial implementation of `AddAssign`. When `Foo += Foo` happens, it ends up
891 /// calling `add_assign`, and therefore, `main` prints `Adding!`.
894 /// #![feature(augmented_assignments)]
895 /// #![feature(op_assign_traits)]
897 /// use std::ops::AddAssign;
901 /// impl AddAssign for Foo {
902 /// fn add_assign(&mut self, _rhs: Foo) {
903 /// println!("Adding!");
907 /// # #[allow(unused_assignments)]
909 /// let mut foo = Foo;
913 #[lang = "add_assign"]
914 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
915 pub trait AddAssign<Rhs=Self> {
916 /// The method for the `+=` operator
917 fn add_assign(&mut self, Rhs);
920 macro_rules! add_assign_impl {
922 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
923 impl AddAssign for $t {
925 fn add_assign(&mut self, other: $t) { *self += other }
930 add_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
932 /// The `SubAssign` trait is used to specify the functionality of `-=`.
936 /// A trivial implementation of `SubAssign`. When `Foo -= Foo` happens, it ends up
937 /// calling `sub_assign`, and therefore, `main` prints `Subtracting!`.
940 /// #![feature(augmented_assignments)]
941 /// #![feature(op_assign_traits)]
943 /// use std::ops::SubAssign;
947 /// impl SubAssign for Foo {
948 /// fn sub_assign(&mut self, _rhs: Foo) {
949 /// println!("Subtracting!");
953 /// # #[allow(unused_assignments)]
955 /// let mut foo = Foo;
959 #[lang = "sub_assign"]
960 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
961 pub trait SubAssign<Rhs=Self> {
962 /// The method for the `-=` operator
963 fn sub_assign(&mut self, Rhs);
966 macro_rules! sub_assign_impl {
968 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
969 impl SubAssign for $t {
971 fn sub_assign(&mut self, other: $t) { *self -= other }
976 sub_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
978 /// The `MulAssign` trait is used to specify the functionality of `*=`.
982 /// A trivial implementation of `MulAssign`. When `Foo *= Foo` happens, it ends up
983 /// calling `mul_assign`, and therefore, `main` prints `Multiplying!`.
986 /// #![feature(augmented_assignments)]
987 /// #![feature(op_assign_traits)]
989 /// use std::ops::MulAssign;
993 /// impl MulAssign for Foo {
994 /// fn mul_assign(&mut self, _rhs: Foo) {
995 /// println!("Multiplying!");
999 /// # #[allow(unused_assignments)]
1001 /// let mut foo = Foo;
1005 #[lang = "mul_assign"]
1006 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1007 pub trait MulAssign<Rhs=Self> {
1008 /// The method for the `*=` operator
1009 fn mul_assign(&mut self, Rhs);
1012 macro_rules! mul_assign_impl {
1014 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1015 impl MulAssign for $t {
1017 fn mul_assign(&mut self, other: $t) { *self *= other }
1022 mul_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
1024 /// The `DivAssign` trait is used to specify the functionality of `/=`.
1028 /// A trivial implementation of `DivAssign`. When `Foo /= Foo` happens, it ends up
1029 /// calling `div_assign`, and therefore, `main` prints `Dividing!`.
1032 /// #![feature(augmented_assignments)]
1033 /// #![feature(op_assign_traits)]
1035 /// use std::ops::DivAssign;
1039 /// impl DivAssign for Foo {
1040 /// fn div_assign(&mut self, _rhs: Foo) {
1041 /// println!("Dividing!");
1045 /// # #[allow(unused_assignments)]
1047 /// let mut foo = Foo;
1051 #[lang = "div_assign"]
1052 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1053 pub trait DivAssign<Rhs=Self> {
1054 /// The method for the `/=` operator
1055 fn div_assign(&mut self, Rhs);
1058 macro_rules! div_assign_impl {
1060 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1061 impl DivAssign for $t {
1063 fn div_assign(&mut self, other: $t) { *self /= other }
1068 div_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
1070 /// The `RemAssign` trait is used to specify the functionality of `%=`.
1074 /// A trivial implementation of `RemAssign`. When `Foo %= Foo` happens, it ends up
1075 /// calling `rem_assign`, and therefore, `main` prints `Remainder-ing!`.
1078 /// #![feature(augmented_assignments)]
1079 /// #![feature(op_assign_traits)]
1081 /// use std::ops::RemAssign;
1085 /// impl RemAssign for Foo {
1086 /// fn rem_assign(&mut self, _rhs: Foo) {
1087 /// println!("Remainder-ing!");
1091 /// # #[allow(unused_assignments)]
1093 /// let mut foo = Foo;
1097 #[lang = "rem_assign"]
1098 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1099 pub trait RemAssign<Rhs=Self> {
1100 /// The method for the `%=` operator
1101 fn rem_assign(&mut self, Rhs);
1104 macro_rules! rem_assign_impl {
1106 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1107 impl RemAssign for $t {
1109 fn rem_assign(&mut self, other: $t) { *self %= other }
1114 rem_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
1116 /// The `BitAndAssign` trait is used to specify the functionality of `&=`.
1120 /// A trivial implementation of `BitAndAssign`. When `Foo &= Foo` happens, it ends up
1121 /// calling `bitand_assign`, and therefore, `main` prints `Bitwise And-ing!`.
1124 /// #![feature(augmented_assignments)]
1125 /// #![feature(op_assign_traits)]
1127 /// use std::ops::BitAndAssign;
1131 /// impl BitAndAssign for Foo {
1132 /// fn bitand_assign(&mut self, _rhs: Foo) {
1133 /// println!("Bitwise And-ing!");
1137 /// # #[allow(unused_assignments)]
1139 /// let mut foo = Foo;
1143 #[lang = "bitand_assign"]
1144 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1145 pub trait BitAndAssign<Rhs=Self> {
1146 /// The method for the `&` operator
1147 fn bitand_assign(&mut self, Rhs);
1150 macro_rules! bitand_assign_impl {
1152 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1153 impl BitAndAssign for $t {
1155 fn bitand_assign(&mut self, other: $t) { *self &= other }
1160 bitand_assign_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
1162 /// The `BitOrAssign` trait is used to specify the functionality of `|=`.
1166 /// A trivial implementation of `BitOrAssign`. When `Foo |= Foo` happens, it ends up
1167 /// calling `bitor_assign`, and therefore, `main` prints `Bitwise Or-ing!`.
1170 /// #![feature(augmented_assignments)]
1171 /// #![feature(op_assign_traits)]
1173 /// use std::ops::BitOrAssign;
1177 /// impl BitOrAssign for Foo {
1178 /// fn bitor_assign(&mut self, _rhs: Foo) {
1179 /// println!("Bitwise Or-ing!");
1183 /// # #[allow(unused_assignments)]
1185 /// let mut foo = Foo;
1189 #[lang = "bitor_assign"]
1190 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1191 pub trait BitOrAssign<Rhs=Self> {
1192 /// The method for the `|=` operator
1193 fn bitor_assign(&mut self, Rhs);
1196 macro_rules! bitor_assign_impl {
1198 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1199 impl BitOrAssign for $t {
1201 fn bitor_assign(&mut self, other: $t) { *self |= other }
1206 bitor_assign_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
1208 /// The `BitXorAssign` trait is used to specify the functionality of `^=`.
1212 /// A trivial implementation of `BitXorAssign`. When `Foo ^= Foo` happens, it ends up
1213 /// calling `bitxor_assign`, and therefore, `main` prints `Bitwise Xor-ing!`.
1216 /// #![feature(augmented_assignments)]
1217 /// #![feature(op_assign_traits)]
1219 /// use std::ops::BitXorAssign;
1223 /// impl BitXorAssign for Foo {
1224 /// fn bitxor_assign(&mut self, _rhs: Foo) {
1225 /// println!("Bitwise Xor-ing!");
1229 /// # #[allow(unused_assignments)]
1231 /// let mut foo = Foo;
1235 #[lang = "bitxor_assign"]
1236 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1237 pub trait BitXorAssign<Rhs=Self> {
1238 /// The method for the `^=` operator
1239 fn bitxor_assign(&mut self, Rhs);
1242 macro_rules! bitxor_assign_impl {
1244 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1245 impl BitXorAssign for $t {
1247 fn bitxor_assign(&mut self, other: $t) { *self ^= other }
1252 bitxor_assign_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
1254 /// The `ShlAssign` trait is used to specify the functionality of `<<=`.
1258 /// A trivial implementation of `ShlAssign`. When `Foo <<= Foo` happens, it ends up
1259 /// calling `shl_assign`, and therefore, `main` prints `Shifting left!`.
1262 /// #![feature(augmented_assignments)]
1263 /// #![feature(op_assign_traits)]
1265 /// use std::ops::ShlAssign;
1269 /// impl ShlAssign<Foo> for Foo {
1270 /// fn shl_assign(&mut self, _rhs: Foo) {
1271 /// println!("Shifting left!");
1275 /// # #[allow(unused_assignments)]
1277 /// let mut foo = Foo;
1281 #[lang = "shl_assign"]
1282 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1283 pub trait ShlAssign<Rhs> {
1284 /// The method for the `<<=` operator
1285 fn shl_assign(&mut self, Rhs);
1288 macro_rules! shl_assign_impl {
1290 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1291 impl ShlAssign<$f> for $t {
1293 fn shl_assign(&mut self, other: $f) {
1300 macro_rules! shl_assign_impl_all {
1302 shl_assign_impl! { $t, u8 }
1303 shl_assign_impl! { $t, u16 }
1304 shl_assign_impl! { $t, u32 }
1305 shl_assign_impl! { $t, u64 }
1306 shl_assign_impl! { $t, usize }
1308 shl_assign_impl! { $t, i8 }
1309 shl_assign_impl! { $t, i16 }
1310 shl_assign_impl! { $t, i32 }
1311 shl_assign_impl! { $t, i64 }
1312 shl_assign_impl! { $t, isize }
1316 shl_assign_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
1318 /// The `ShrAssign` trait is used to specify the functionality of `>>=`.
1322 /// A trivial implementation of `ShrAssign`. When `Foo >>= Foo` happens, it ends up
1323 /// calling `shr_assign`, and therefore, `main` prints `Shifting right!`.
1326 /// #![feature(augmented_assignments)]
1327 /// #![feature(op_assign_traits)]
1329 /// use std::ops::ShrAssign;
1333 /// impl ShrAssign<Foo> for Foo {
1334 /// fn shr_assign(&mut self, _rhs: Foo) {
1335 /// println!("Shifting right!");
1339 /// # #[allow(unused_assignments)]
1341 /// let mut foo = Foo;
1345 #[lang = "shr_assign"]
1346 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1347 pub trait ShrAssign<Rhs=Self> {
1348 /// The method for the `>>=` operator
1349 fn shr_assign(&mut self, Rhs);
1352 macro_rules! shr_assign_impl {
1354 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1355 impl ShrAssign<$f> for $t {
1357 fn shr_assign(&mut self, other: $f) {
1364 macro_rules! shr_assign_impl_all {
1366 shr_assign_impl! { $t, u8 }
1367 shr_assign_impl! { $t, u16 }
1368 shr_assign_impl! { $t, u32 }
1369 shr_assign_impl! { $t, u64 }
1370 shr_assign_impl! { $t, usize }
1372 shr_assign_impl! { $t, i8 }
1373 shr_assign_impl! { $t, i16 }
1374 shr_assign_impl! { $t, i32 }
1375 shr_assign_impl! { $t, i64 }
1376 shr_assign_impl! { $t, isize }
1380 shr_assign_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
1382 /// The `Index` trait is used to specify the functionality of indexing operations
1383 /// like `arr[idx]` when used in an immutable context.
1387 /// A trivial implementation of `Index`. When `Foo[Bar]` happens, it ends up
1388 /// calling `index`, and therefore, `main` prints `Indexing!`.
1391 /// use std::ops::Index;
1393 /// #[derive(Copy, Clone)]
1397 /// impl Index<Bar> for Foo {
1398 /// type Output = Foo;
1400 /// fn index<'a>(&'a self, _index: Bar) -> &'a Foo {
1401 /// println!("Indexing!");
1411 #[rustc_on_unimplemented = "the type `{Self}` cannot be indexed by `{Idx}`"]
1412 #[stable(feature = "rust1", since = "1.0.0")]
1413 pub trait Index<Idx: ?Sized> {
1414 /// The returned type after indexing
1415 #[stable(feature = "rust1", since = "1.0.0")]
1416 type Output: ?Sized;
1418 /// The method for the indexing (`Foo[Bar]`) operation
1419 #[stable(feature = "rust1", since = "1.0.0")]
1420 fn index(&self, index: Idx) -> &Self::Output;
1423 /// The `IndexMut` trait is used to specify the functionality of indexing
1424 /// operations like `arr[idx]`, when used in a mutable context.
1428 /// A trivial implementation of `IndexMut`. When `Foo[Bar]` happens, it ends up
1429 /// calling `index_mut`, and therefore, `main` prints `Indexing!`.
1432 /// use std::ops::{Index, IndexMut};
1434 /// #[derive(Copy, Clone)]
1438 /// impl Index<Bar> for Foo {
1439 /// type Output = Foo;
1441 /// fn index<'a>(&'a self, _index: Bar) -> &'a Foo {
1446 /// impl IndexMut<Bar> for Foo {
1447 /// fn index_mut<'a>(&'a mut self, _index: Bar) -> &'a mut Foo {
1448 /// println!("Indexing!");
1457 #[lang = "index_mut"]
1458 #[rustc_on_unimplemented = "the type `{Self}` cannot be mutably indexed by `{Idx}`"]
1459 #[stable(feature = "rust1", since = "1.0.0")]
1460 pub trait IndexMut<Idx: ?Sized>: Index<Idx> {
1461 /// The method for the indexing (`Foo[Bar]`) operation
1462 #[stable(feature = "rust1", since = "1.0.0")]
1463 fn index_mut(&mut self, index: Idx) -> &mut Self::Output;
1466 /// An unbounded range.
1467 #[derive(Copy, Clone, PartialEq, Eq)]
1468 #[lang = "range_full"]
1469 #[stable(feature = "rust1", since = "1.0.0")]
1470 pub struct RangeFull;
1472 #[stable(feature = "rust1", since = "1.0.0")]
1473 impl fmt::Debug for RangeFull {
1474 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1479 /// A (half-open) range which is bounded at both ends.
1480 #[derive(Clone, PartialEq, Eq)]
1482 #[stable(feature = "rust1", since = "1.0.0")]
1483 pub struct Range<Idx> {
1484 /// The lower bound of the range (inclusive).
1485 #[stable(feature = "rust1", since = "1.0.0")]
1487 /// The upper bound of the range (exclusive).
1488 #[stable(feature = "rust1", since = "1.0.0")]
1492 #[stable(feature = "rust1", since = "1.0.0")]
1493 impl<Idx: fmt::Debug> fmt::Debug for Range<Idx> {
1494 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1495 write!(fmt, "{:?}..{:?}", self.start, self.end)
1499 /// A range which is only bounded below.
1500 #[derive(Clone, PartialEq, Eq)]
1501 #[lang = "range_from"]
1502 #[stable(feature = "rust1", since = "1.0.0")]
1503 pub struct RangeFrom<Idx> {
1504 /// The lower bound of the range (inclusive).
1505 #[stable(feature = "rust1", since = "1.0.0")]
1509 #[stable(feature = "rust1", since = "1.0.0")]
1510 impl<Idx: fmt::Debug> fmt::Debug for RangeFrom<Idx> {
1511 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1512 write!(fmt, "{:?}..", self.start)
1516 /// A range which is only bounded above.
1517 #[derive(Copy, Clone, PartialEq, Eq)]
1518 #[lang = "range_to"]
1519 #[stable(feature = "rust1", since = "1.0.0")]
1520 pub struct RangeTo<Idx> {
1521 /// The upper bound of the range (exclusive).
1522 #[stable(feature = "rust1", since = "1.0.0")]
1526 #[stable(feature = "rust1", since = "1.0.0")]
1527 impl<Idx: fmt::Debug> fmt::Debug for RangeTo<Idx> {
1528 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1529 write!(fmt, "..{:?}", self.end)
1533 /// The `Deref` trait is used to specify the functionality of dereferencing
1534 /// operations, like `*v`.
1536 /// `Deref` also enables ['`Deref` coercions'][coercions].
1538 /// [coercions]: ../../book/deref-coercions.html
1542 /// A struct with a single field which is accessible via dereferencing the
1546 /// use std::ops::Deref;
1548 /// struct DerefExample<T> {
1552 /// impl<T> Deref for DerefExample<T> {
1553 /// type Target = T;
1555 /// fn deref(&self) -> &T {
1561 /// let x = DerefExample { value: 'a' };
1562 /// assert_eq!('a', *x);
1566 #[stable(feature = "rust1", since = "1.0.0")]
1568 /// The resulting type after dereferencing
1569 #[stable(feature = "rust1", since = "1.0.0")]
1570 type Target: ?Sized;
1572 /// The method called to dereference a value
1573 #[stable(feature = "rust1", since = "1.0.0")]
1574 fn deref(&self) -> &Self::Target;
1577 #[stable(feature = "rust1", since = "1.0.0")]
1578 impl<'a, T: ?Sized> Deref for &'a T {
1581 fn deref(&self) -> &T { *self }
1584 #[stable(feature = "rust1", since = "1.0.0")]
1585 impl<'a, T: ?Sized> Deref for &'a mut T {
1588 fn deref(&self) -> &T { *self }
1591 /// The `DerefMut` trait is used to specify the functionality of dereferencing
1592 /// mutably like `*v = 1;`
1594 /// `DerefMut` also enables ['`Deref` coercions'][coercions].
1596 /// [coercions]: ../../book/deref-coercions.html
1600 /// A struct with a single field which is modifiable via dereferencing the
1604 /// use std::ops::{Deref, DerefMut};
1606 /// struct DerefMutExample<T> {
1610 /// impl<T> Deref for DerefMutExample<T> {
1611 /// type Target = T;
1613 /// fn deref<'a>(&'a self) -> &'a T {
1618 /// impl<T> DerefMut for DerefMutExample<T> {
1619 /// fn deref_mut<'a>(&'a mut self) -> &'a mut T {
1625 /// let mut x = DerefMutExample { value: 'a' };
1627 /// assert_eq!('b', *x);
1630 #[lang = "deref_mut"]
1631 #[stable(feature = "rust1", since = "1.0.0")]
1632 pub trait DerefMut: Deref {
1633 /// The method called to mutably dereference a value
1634 #[stable(feature = "rust1", since = "1.0.0")]
1635 fn deref_mut(&mut self) -> &mut Self::Target;
1638 #[stable(feature = "rust1", since = "1.0.0")]
1639 impl<'a, T: ?Sized> DerefMut for &'a mut T {
1640 fn deref_mut(&mut self) -> &mut T { *self }
1643 /// A version of the call operator that takes an immutable receiver.
1645 #[stable(feature = "rust1", since = "1.0.0")]
1646 #[rustc_paren_sugar]
1647 #[fundamental] // so that regex can rely that `&str: !FnMut`
1648 pub trait Fn<Args> : FnMut<Args> {
1649 /// This is called when the call operator is used.
1650 #[unstable(feature = "fn_traits", issue = "29625")]
1651 extern "rust-call" fn call(&self, args: Args) -> Self::Output;
1654 /// A version of the call operator that takes a mutable receiver.
1656 #[stable(feature = "rust1", since = "1.0.0")]
1657 #[rustc_paren_sugar]
1658 #[fundamental] // so that regex can rely that `&str: !FnMut`
1659 pub trait FnMut<Args> : FnOnce<Args> {
1660 /// This is called when the call operator is used.
1661 #[unstable(feature = "fn_traits", issue = "29625")]
1662 extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
1665 /// A version of the call operator that takes a by-value receiver.
1667 #[stable(feature = "rust1", since = "1.0.0")]
1668 #[rustc_paren_sugar]
1669 #[fundamental] // so that regex can rely that `&str: !FnMut`
1670 pub trait FnOnce<Args> {
1671 /// The returned type after the call operator is used.
1672 #[unstable(feature = "fn_traits", issue = "29625")]
1675 /// This is called when the call operator is used.
1676 #[unstable(feature = "fn_traits", issue = "29625")]
1677 extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
1682 use super::{Fn, FnMut, FnOnce};
1684 #[stable(feature = "rust1", since = "1.0.0")]
1685 impl<'a,A,F:?Sized> Fn<A> for &'a F
1688 extern "rust-call" fn call(&self, args: A) -> F::Output {
1693 #[stable(feature = "rust1", since = "1.0.0")]
1694 impl<'a,A,F:?Sized> FnMut<A> for &'a F
1697 extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
1702 #[stable(feature = "rust1", since = "1.0.0")]
1703 impl<'a,A,F:?Sized> FnOnce<A> for &'a F
1706 type Output = F::Output;
1708 extern "rust-call" fn call_once(self, args: A) -> F::Output {
1713 #[stable(feature = "rust1", since = "1.0.0")]
1714 impl<'a,A,F:?Sized> FnMut<A> for &'a mut F
1717 extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
1718 (*self).call_mut(args)
1722 #[stable(feature = "rust1", since = "1.0.0")]
1723 impl<'a,A,F:?Sized> FnOnce<A> for &'a mut F
1726 type Output = F::Output;
1727 extern "rust-call" fn call_once(mut self, args: A) -> F::Output {
1728 (*self).call_mut(args)
1733 /// Trait that indicates that this is a pointer or a wrapper for one,
1734 /// where unsizing can be performed on the pointee.
1735 #[unstable(feature = "coerce_unsized", issue = "27732")]
1736 #[lang="coerce_unsized"]
1737 pub trait CoerceUnsized<T> {
1742 #[unstable(feature = "coerce_unsized", issue = "27732")]
1743 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a mut U> for &'a mut T {}
1745 #[unstable(feature = "coerce_unsized", issue = "27732")]
1746 impl<'a, 'b: 'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a U> for &'b mut T {}
1748 #[unstable(feature = "coerce_unsized", issue = "27732")]
1749 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*mut U> for &'a mut T {}
1750 // &mut T -> *const U
1751 #[unstable(feature = "coerce_unsized", issue = "27732")]
1752 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for &'a mut T {}
1755 #[unstable(feature = "coerce_unsized", issue = "27732")]
1756 impl<'a, 'b: 'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a U> for &'b T {}
1758 #[unstable(feature = "coerce_unsized", issue = "27732")]
1759 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for &'a T {}
1762 #[unstable(feature = "coerce_unsized", issue = "27732")]
1763 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*mut U> for *mut T {}
1764 // *mut T -> *const U
1765 #[unstable(feature = "coerce_unsized", issue = "27732")]
1766 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for *mut T {}
1768 // *const T -> *const U
1769 #[unstable(feature = "coerce_unsized", issue = "27732")]
1770 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for *const T {}
1772 /// Both `in (PLACE) EXPR` and `box EXPR` desugar into expressions
1773 /// that allocate an intermediate "place" that holds uninitialized
1774 /// state. The desugaring evaluates EXPR, and writes the result at
1775 /// the address returned by the `pointer` method of this trait.
1777 /// A `Place` can be thought of as a special representation for a
1778 /// hypothetical `&uninit` reference (which Rust cannot currently
1779 /// express directly). That is, it represents a pointer to
1780 /// uninitialized storage.
1782 /// The client is responsible for two steps: First, initializing the
1783 /// payload (it can access its address via `pointer`). Second,
1784 /// converting the agent to an instance of the owning pointer, via the
1785 /// appropriate `finalize` method (see the `InPlace`.
1787 /// If evaluating EXPR fails, then the destructor for the
1788 /// implementation of Place to clean up any intermediate state
1789 /// (e.g. deallocate box storage, pop a stack, etc).
1790 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1791 pub trait Place<Data: ?Sized> {
1792 /// Returns the address where the input value will be written.
1793 /// Note that the data at this address is generally uninitialized,
1794 /// and thus one should use `ptr::write` for initializing it.
1795 fn pointer(&mut self) -> *mut Data;
1798 /// Interface to implementations of `in (PLACE) EXPR`.
1800 /// `in (PLACE) EXPR` effectively desugars into:
1804 /// let mut place = Placer::make_place(p);
1805 /// let raw_place = Place::pointer(&mut place);
1806 /// let value = EXPR;
1808 /// std::ptr::write(raw_place, value);
1809 /// InPlace::finalize(place)
1813 /// The type of `in (PLACE) EXPR` is derived from the type of `PLACE`;
1814 /// if the type of `PLACE` is `P`, then the final type of the whole
1815 /// expression is `P::Place::Owner` (see the `InPlace` and `Boxed`
1818 /// Values for types implementing this trait usually are transient
1819 /// intermediate values (e.g. the return value of `Vec::emplace_back`)
1820 /// or `Copy`, since the `make_place` method takes `self` by value.
1821 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1822 pub trait Placer<Data: ?Sized> {
1823 /// `Place` is the intermedate agent guarding the
1824 /// uninitialized state for `Data`.
1825 type Place: InPlace<Data>;
1827 /// Creates a fresh place from `self`.
1828 fn make_place(self) -> Self::Place;
1831 /// Specialization of `Place` trait supporting `in (PLACE) EXPR`.
1832 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1833 pub trait InPlace<Data: ?Sized>: Place<Data> {
1834 /// `Owner` is the type of the end value of `in (PLACE) EXPR`
1836 /// Note that when `in (PLACE) EXPR` is solely used for
1837 /// side-effecting an existing data-structure,
1838 /// e.g. `Vec::emplace_back`, then `Owner` need not carry any
1839 /// information at all (e.g. it can be the unit type `()` in that
1843 /// Converts self into the final value, shifting
1844 /// deallocation/cleanup responsibilities (if any remain), over to
1845 /// the returned instance of `Owner` and forgetting self.
1846 unsafe fn finalize(self) -> Self::Owner;
1849 /// Core trait for the `box EXPR` form.
1851 /// `box EXPR` effectively desugars into:
1854 /// let mut place = BoxPlace::make_place();
1855 /// let raw_place = Place::pointer(&mut place);
1856 /// let value = EXPR;
1858 /// ::std::ptr::write(raw_place, value);
1859 /// Boxed::finalize(place)
1863 /// The type of `box EXPR` is supplied from its surrounding
1864 /// context; in the above expansion, the result type `T` is used
1865 /// to determine which implementation of `Boxed` to use, and that
1866 /// `<T as Boxed>` in turn dictates determines which
1867 /// implementation of `BoxPlace` to use, namely:
1868 /// `<<T as Boxed>::Place as BoxPlace>`.
1869 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1871 /// The kind of data that is stored in this kind of box.
1872 type Data; /* (`Data` unused b/c cannot yet express below bound.) */
1873 /// The place that will negotiate the storage of the data.
1874 type Place: BoxPlace<Self::Data>;
1876 /// Converts filled place into final owning value, shifting
1877 /// deallocation/cleanup responsibilities (if any remain), over to
1878 /// returned instance of `Self` and forgetting `filled`.
1879 unsafe fn finalize(filled: Self::Place) -> Self;
1882 /// Specialization of `Place` trait supporting `box EXPR`.
1883 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1884 pub trait BoxPlace<Data: ?Sized> : Place<Data> {
1885 /// Creates a globally fresh place.
1886 fn make_place() -> Self;