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.
98 #[stable(feature = "rust1", since = "1.0.0")]
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;
111 fn $method(self) -> <$t as $imp>::Output {
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;
127 fn $method(self, other: $u) -> <$t as $imp<$u>>::Output {
128 $imp::$method(*self, other)
132 #[stable(feature = "rust1", since = "1.0.0")]
133 impl<'a> $imp<&'a $u> for $t {
134 type Output = <$t as $imp<$u>>::Output;
137 fn $method(self, other: &'a $u) -> <$t as $imp<$u>>::Output {
138 $imp::$method(self, *other)
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;
147 fn $method(self, other: &'a $u) -> <$t as $imp<$u>>::Output {
148 $imp::$method(*self, *other)
154 /// The `Add` trait is used to specify the functionality of `+`.
158 /// A trivial implementation of `Add`. When `Foo + Foo` happens, it ends up
159 /// calling `add`, and therefore, `main` prints `Adding!`.
162 /// use std::ops::Add;
164 /// #[derive(Copy, Clone)]
167 /// impl Add for Foo {
168 /// type Output = Foo;
170 /// fn add(self, _rhs: Foo) -> Foo {
171 /// println!("Adding!");
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")]
187 /// The method for the `+` operator
188 #[stable(feature = "rust1", since = "1.0.0")]
189 fn add(self, rhs: RHS) -> Self::Output;
192 macro_rules! add_impl {
194 #[stable(feature = "rust1", since = "1.0.0")]
199 fn add(self, other: $t) -> $t { self + other }
202 forward_ref_binop! { impl Add, add for $t, $t }
206 add_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
208 /// The `Sub` trait is used to specify the functionality of `-`.
212 /// A trivial implementation of `Sub`. When `Foo - Foo` happens, it ends up
213 /// calling `sub`, and therefore, `main` prints `Subtracting!`.
216 /// use std::ops::Sub;
218 /// #[derive(Copy, Clone)]
221 /// impl Sub for Foo {
222 /// type Output = Foo;
224 /// fn sub(self, _rhs: Foo) -> Foo {
225 /// println!("Subtracting!");
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")]
241 /// The method for the `-` operator
242 #[stable(feature = "rust1", since = "1.0.0")]
243 fn sub(self, rhs: RHS) -> Self::Output;
246 macro_rules! sub_impl {
248 #[stable(feature = "rust1", since = "1.0.0")]
253 fn sub(self, other: $t) -> $t { self - other }
256 forward_ref_binop! { impl Sub, sub for $t, $t }
260 sub_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
262 /// The `Mul` trait is used to specify the functionality of `*`.
266 /// A trivial implementation of `Mul`. When `Foo * Foo` happens, it ends up
267 /// calling `mul`, and therefore, `main` prints `Multiplying!`.
270 /// use std::ops::Mul;
272 /// #[derive(Copy, Clone)]
275 /// impl Mul for Foo {
276 /// type Output = Foo;
278 /// fn mul(self, _rhs: Foo) -> Foo {
279 /// println!("Multiplying!");
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")]
295 /// The method for the `*` operator
296 #[stable(feature = "rust1", since = "1.0.0")]
297 fn mul(self, rhs: RHS) -> Self::Output;
300 macro_rules! mul_impl {
302 #[stable(feature = "rust1", since = "1.0.0")]
307 fn mul(self, other: $t) -> $t { self * other }
310 forward_ref_binop! { impl Mul, mul for $t, $t }
314 mul_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
316 /// The `Div` trait is used to specify the functionality of `/`.
320 /// A trivial implementation of `Div`. When `Foo / Foo` happens, it ends up
321 /// calling `div`, and therefore, `main` prints `Dividing!`.
324 /// use std::ops::Div;
326 /// #[derive(Copy, Clone)]
329 /// impl Div for Foo {
330 /// type Output = Foo;
332 /// fn div(self, _rhs: Foo) -> Foo {
333 /// println!("Dividing!");
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")]
349 /// The method for the `/` operator
350 #[stable(feature = "rust1", since = "1.0.0")]
351 fn div(self, rhs: RHS) -> Self::Output;
354 macro_rules! div_impl_integer {
356 /// This operation rounds towards zero, truncating any
357 /// fractional part of the exact result.
358 #[stable(feature = "rust1", since = "1.0.0")]
363 fn div(self, other: $t) -> $t { self / other }
366 forward_ref_binop! { impl Div, div for $t, $t }
370 div_impl_integer! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
372 macro_rules! div_impl_float {
374 #[stable(feature = "rust1", since = "1.0.0")]
379 fn div(self, other: $t) -> $t { self / other }
382 forward_ref_binop! { impl Div, div for $t, $t }
386 div_impl_float! { f32 f64 }
388 /// The `Rem` trait is used to specify the functionality of `%`.
392 /// A trivial implementation of `Rem`. When `Foo % Foo` happens, it ends up
393 /// calling `rem`, and therefore, `main` prints `Remainder-ing!`.
396 /// use std::ops::Rem;
398 /// #[derive(Copy, Clone)]
401 /// impl Rem for Foo {
402 /// type Output = Foo;
404 /// fn rem(self, _rhs: Foo) -> Foo {
405 /// println!("Remainder-ing!");
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")]
421 /// The method for the `%` operator
422 #[stable(feature = "rust1", since = "1.0.0")]
423 fn rem(self, rhs: RHS) -> Self::Output;
426 macro_rules! rem_impl_integer {
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")]
435 fn rem(self, other: $t) -> $t { self % other }
438 forward_ref_binop! { impl Rem, rem for $t, $t }
442 rem_impl_integer! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
445 macro_rules! rem_impl_float {
447 #[stable(feature = "rust1", since = "1.0.0")]
452 fn rem(self, other: $t) -> $t { self % other }
455 forward_ref_binop! { impl Rem, rem for $t, $t }
460 rem_impl_float! { f32 f64 }
462 #[stable(feature = "rust1", since = "1.0.0")]
467 // The builtin f32 rem operator is broken when targeting
468 // MSVC; see comment in std::f32::floor.
469 // FIXME: See also #27859.
471 #[cfg(target_env = "msvc")]
472 fn rem(self, other: f32) -> f32 {
473 (self as f64).rem(other as f64) as f32
477 #[cfg(not(target_env = "msvc"))]
478 fn rem(self, other: f32) -> f32 {
479 extern { fn fmodf(a: f32, b: f32) -> f32; }
480 unsafe { fmodf(self, other) }
484 #[stable(feature = "rust1", since = "1.0.0")]
490 fn rem(self, other: f64) -> f64 {
491 extern { fn fmod(a: f64, b: f64) -> f64; }
492 unsafe { fmod(self, other) }
497 forward_ref_binop! { impl Rem, rem for f64, f64 }
499 forward_ref_binop! { impl Rem, rem for f32, f32 }
501 /// The `Neg` trait is used to specify the functionality of unary `-`.
505 /// A trivial implementation of `Neg`. When `-Foo` happens, it ends up calling
506 /// `neg`, and therefore, `main` prints `Negating!`.
509 /// use std::ops::Neg;
511 /// #[derive(Copy, Clone)]
514 /// impl Neg for Foo {
515 /// type Output = Foo;
517 /// fn neg(self) -> Foo {
518 /// println!("Negating!");
528 #[stable(feature = "rust1", since = "1.0.0")]
530 /// The resulting type after applying the `-` operator
531 #[stable(feature = "rust1", since = "1.0.0")]
534 /// The method for the unary `-` operator
535 #[stable(feature = "rust1", since = "1.0.0")]
536 fn neg(self) -> Self::Output;
541 macro_rules! neg_impl_core {
542 ($id:ident => $body:expr, $($t:ty)*) => ($(
543 #[stable(feature = "rust1", since = "1.0.0")]
548 fn neg(self) -> $t { let $id = self; $body }
551 forward_ref_unop! { impl Neg, neg for $t }
555 macro_rules! neg_impl_numeric {
556 ($($t:ty)*) => { neg_impl_core!{ x => -x, $($t)*} }
559 macro_rules! neg_impl_unsigned {
561 neg_impl_core!{ x => {
566 // neg_impl_unsigned! { usize u8 u16 u32 u64 }
567 neg_impl_numeric! { isize i8 i16 i32 i64 f32 f64 }
569 /// The `Not` trait is used to specify the functionality of unary `!`.
573 /// A trivial implementation of `Not`. When `!Foo` happens, it ends up calling
574 /// `not`, and therefore, `main` prints `Not-ing!`.
577 /// use std::ops::Not;
579 /// #[derive(Copy, Clone)]
582 /// impl Not for Foo {
583 /// type Output = Foo;
585 /// fn not(self) -> Foo {
586 /// println!("Not-ing!");
596 #[stable(feature = "rust1", since = "1.0.0")]
598 /// The resulting type after applying the `!` operator
599 #[stable(feature = "rust1", since = "1.0.0")]
602 /// The method for the unary `!` operator
603 #[stable(feature = "rust1", since = "1.0.0")]
604 fn not(self) -> Self::Output;
607 macro_rules! not_impl {
609 #[stable(feature = "rust1", since = "1.0.0")]
614 fn not(self) -> $t { !self }
617 forward_ref_unop! { impl Not, not for $t }
621 not_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
623 /// The `BitAnd` trait is used to specify the functionality of `&`.
627 /// A trivial implementation of `BitAnd`. When `Foo & Foo` happens, it ends up
628 /// calling `bitand`, and therefore, `main` prints `Bitwise And-ing!`.
631 /// use std::ops::BitAnd;
633 /// #[derive(Copy, Clone)]
636 /// impl BitAnd for Foo {
637 /// type Output = Foo;
639 /// fn bitand(self, _rhs: Foo) -> Foo {
640 /// println!("Bitwise And-ing!");
650 #[stable(feature = "rust1", since = "1.0.0")]
651 pub trait BitAnd<RHS=Self> {
652 /// The resulting type after applying the `&` operator
653 #[stable(feature = "rust1", since = "1.0.0")]
656 /// The method for the `&` operator
657 #[stable(feature = "rust1", since = "1.0.0")]
658 fn bitand(self, rhs: RHS) -> Self::Output;
661 macro_rules! bitand_impl {
663 #[stable(feature = "rust1", since = "1.0.0")]
668 fn bitand(self, rhs: $t) -> $t { self & rhs }
671 forward_ref_binop! { impl BitAnd, bitand for $t, $t }
675 bitand_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
677 /// The `BitOr` trait is used to specify the functionality of `|`.
681 /// A trivial implementation of `BitOr`. When `Foo | Foo` happens, it ends up
682 /// calling `bitor`, and therefore, `main` prints `Bitwise Or-ing!`.
685 /// use std::ops::BitOr;
687 /// #[derive(Copy, Clone)]
690 /// impl BitOr for Foo {
691 /// type Output = Foo;
693 /// fn bitor(self, _rhs: Foo) -> Foo {
694 /// println!("Bitwise Or-ing!");
704 #[stable(feature = "rust1", since = "1.0.0")]
705 pub trait BitOr<RHS=Self> {
706 /// The resulting type after applying the `|` operator
707 #[stable(feature = "rust1", since = "1.0.0")]
710 /// The method for the `|` operator
711 #[stable(feature = "rust1", since = "1.0.0")]
712 fn bitor(self, rhs: RHS) -> Self::Output;
715 macro_rules! bitor_impl {
717 #[stable(feature = "rust1", since = "1.0.0")]
722 fn bitor(self, rhs: $t) -> $t { self | rhs }
725 forward_ref_binop! { impl BitOr, bitor for $t, $t }
729 bitor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
731 /// The `BitXor` trait is used to specify the functionality of `^`.
735 /// A trivial implementation of `BitXor`. When `Foo ^ Foo` happens, it ends up
736 /// calling `bitxor`, and therefore, `main` prints `Bitwise Xor-ing!`.
739 /// use std::ops::BitXor;
741 /// #[derive(Copy, Clone)]
744 /// impl BitXor for Foo {
745 /// type Output = Foo;
747 /// fn bitxor(self, _rhs: Foo) -> Foo {
748 /// println!("Bitwise Xor-ing!");
758 #[stable(feature = "rust1", since = "1.0.0")]
759 pub trait BitXor<RHS=Self> {
760 /// The resulting type after applying the `^` operator
761 #[stable(feature = "rust1", since = "1.0.0")]
764 /// The method for the `^` operator
765 #[stable(feature = "rust1", since = "1.0.0")]
766 fn bitxor(self, rhs: RHS) -> Self::Output;
769 macro_rules! bitxor_impl {
771 #[stable(feature = "rust1", since = "1.0.0")]
776 fn bitxor(self, other: $t) -> $t { self ^ other }
779 forward_ref_binop! { impl BitXor, bitxor for $t, $t }
783 bitxor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
785 /// The `Shl` trait is used to specify the functionality of `<<`.
789 /// A trivial implementation of `Shl`. When `Foo << Foo` happens, it ends up
790 /// calling `shl`, and therefore, `main` prints `Shifting left!`.
793 /// use std::ops::Shl;
795 /// #[derive(Copy, Clone)]
798 /// impl Shl<Foo> for Foo {
799 /// type Output = Foo;
801 /// fn shl(self, _rhs: Foo) -> Foo {
802 /// println!("Shifting left!");
812 #[stable(feature = "rust1", since = "1.0.0")]
814 /// The resulting type after applying the `<<` operator
815 #[stable(feature = "rust1", since = "1.0.0")]
818 /// The method for the `<<` operator
819 #[stable(feature = "rust1", since = "1.0.0")]
820 fn shl(self, rhs: RHS) -> Self::Output;
823 macro_rules! shl_impl {
825 #[stable(feature = "rust1", since = "1.0.0")]
826 impl Shl<$f> for $t {
830 fn shl(self, other: $f) -> $t {
835 forward_ref_binop! { impl Shl, shl for $t, $f }
839 macro_rules! shl_impl_all {
842 shl_impl! { $t, u16 }
843 shl_impl! { $t, u32 }
844 shl_impl! { $t, u64 }
845 shl_impl! { $t, usize }
848 shl_impl! { $t, i16 }
849 shl_impl! { $t, i32 }
850 shl_impl! { $t, i64 }
851 shl_impl! { $t, isize }
855 shl_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
857 /// The `Shr` trait is used to specify the functionality of `>>`.
861 /// A trivial implementation of `Shr`. When `Foo >> Foo` happens, it ends up
862 /// calling `shr`, and therefore, `main` prints `Shifting right!`.
865 /// use std::ops::Shr;
867 /// #[derive(Copy, Clone)]
870 /// impl Shr<Foo> for Foo {
871 /// type Output = Foo;
873 /// fn shr(self, _rhs: Foo) -> Foo {
874 /// println!("Shifting right!");
884 #[stable(feature = "rust1", since = "1.0.0")]
886 /// The resulting type after applying the `>>` operator
887 #[stable(feature = "rust1", since = "1.0.0")]
890 /// The method for the `>>` operator
891 #[stable(feature = "rust1", since = "1.0.0")]
892 fn shr(self, rhs: RHS) -> Self::Output;
895 macro_rules! shr_impl {
897 impl Shr<$f> for $t {
901 fn shr(self, other: $f) -> $t {
906 forward_ref_binop! { impl Shr, shr for $t, $f }
910 macro_rules! shr_impl_all {
913 shr_impl! { $t, u16 }
914 shr_impl! { $t, u32 }
915 shr_impl! { $t, u64 }
916 shr_impl! { $t, usize }
919 shr_impl! { $t, i16 }
920 shr_impl! { $t, i32 }
921 shr_impl! { $t, i64 }
922 shr_impl! { $t, isize }
926 shr_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
928 /// The `AddAssign` trait is used to specify the functionality of `+=`.
932 /// A trivial implementation of `AddAssign`. When `Foo += Foo` happens, it ends up
933 /// calling `add_assign`, and therefore, `main` prints `Adding!`.
936 /// #![feature(augmented_assignments)]
937 /// #![feature(op_assign_traits)]
939 /// use std::ops::AddAssign;
941 /// #[derive(Copy, Clone)]
944 /// impl AddAssign for Foo {
945 /// fn add_assign(&mut self, _rhs: Foo) {
946 /// println!("Adding!");
950 /// # #[allow(unused_assignments)]
952 /// let mut foo = Foo;
957 #[lang = "add_assign"]
958 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
959 pub trait AddAssign<Rhs=Self> {
960 /// The method for the `+=` operator
961 fn add_assign(&mut self, Rhs);
965 macro_rules! add_assign_impl {
967 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
968 impl AddAssign for $t {
970 fn add_assign(&mut self, other: $t) { *self += other }
976 add_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
978 /// The `SubAssign` trait is used to specify the functionality of `-=`.
982 /// A trivial implementation of `SubAssign`. When `Foo -= Foo` happens, it ends up
983 /// calling `sub_assign`, and therefore, `main` prints `Subtracting!`.
986 /// #![feature(augmented_assignments)]
987 /// #![feature(op_assign_traits)]
989 /// use std::ops::SubAssign;
991 /// #[derive(Copy, Clone)]
994 /// impl SubAssign for Foo {
995 /// fn sub_assign(&mut self, _rhs: Foo) {
996 /// println!("Subtracting!");
1000 /// # #[allow(unused_assignments)]
1002 /// let mut foo = Foo;
1007 #[lang = "sub_assign"]
1008 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1009 pub trait SubAssign<Rhs=Self> {
1010 /// The method for the `-=` operator
1011 fn sub_assign(&mut self, Rhs);
1015 macro_rules! sub_assign_impl {
1017 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1018 impl SubAssign for $t {
1020 fn sub_assign(&mut self, other: $t) { *self -= other }
1026 sub_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
1028 /// The `MulAssign` trait is used to specify the functionality of `*=`.
1032 /// A trivial implementation of `MulAssign`. When `Foo *= Foo` happens, it ends up
1033 /// calling `mul_assign`, and therefore, `main` prints `Multiplying!`.
1036 /// #![feature(augmented_assignments)]
1037 /// #![feature(op_assign_traits)]
1039 /// use std::ops::MulAssign;
1041 /// #[derive(Copy, Clone)]
1044 /// impl MulAssign for Foo {
1045 /// fn mul_assign(&mut self, _rhs: Foo) {
1046 /// println!("Multiplying!");
1050 /// # #[allow(unused_assignments)]
1052 /// let mut foo = Foo;
1057 #[lang = "mul_assign"]
1058 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1059 pub trait MulAssign<Rhs=Self> {
1060 /// The method for the `*=` operator
1061 fn mul_assign(&mut self, Rhs);
1065 macro_rules! mul_assign_impl {
1067 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1068 impl MulAssign for $t {
1070 fn mul_assign(&mut self, other: $t) { *self *= other }
1076 mul_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
1078 /// The `DivAssign` trait is used to specify the functionality of `/=`.
1082 /// A trivial implementation of `DivAssign`. When `Foo /= Foo` happens, it ends up
1083 /// calling `div_assign`, and therefore, `main` prints `Dividing!`.
1086 /// #![feature(augmented_assignments)]
1087 /// #![feature(op_assign_traits)]
1089 /// use std::ops::DivAssign;
1091 /// #[derive(Copy, Clone)]
1094 /// impl DivAssign for Foo {
1095 /// fn div_assign(&mut self, _rhs: Foo) {
1096 /// println!("Dividing!");
1100 /// # #[allow(unused_assignments)]
1102 /// let mut foo = Foo;
1107 #[lang = "div_assign"]
1108 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1109 pub trait DivAssign<Rhs=Self> {
1110 /// The method for the `/=` operator
1111 fn div_assign(&mut self, Rhs);
1115 macro_rules! div_assign_impl {
1117 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1118 impl DivAssign for $t {
1120 fn div_assign(&mut self, other: $t) { *self /= other }
1126 div_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
1128 /// The `RemAssign` trait is used to specify the functionality of `%=`.
1132 /// A trivial implementation of `RemAssign`. When `Foo %= Foo` happens, it ends up
1133 /// calling `rem_assign`, and therefore, `main` prints `Remainder-ing!`.
1136 /// #![feature(augmented_assignments)]
1137 /// #![feature(op_assign_traits)]
1139 /// use std::ops::RemAssign;
1141 /// #[derive(Copy, Clone)]
1144 /// impl RemAssign for Foo {
1145 /// fn rem_assign(&mut self, _rhs: Foo) {
1146 /// println!("Remainder-ing!");
1150 /// # #[allow(unused_assignments)]
1152 /// let mut foo = Foo;
1157 #[lang = "rem_assign"]
1158 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1159 pub trait RemAssign<Rhs=Self> {
1160 /// The method for the `%=` operator
1161 fn rem_assign(&mut self, Rhs);
1165 macro_rules! rem_assign_impl {
1167 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1168 impl RemAssign for $t {
1170 fn rem_assign(&mut self, other: $t) { *self %= other }
1176 rem_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
1178 /// The `BitAndAssign` trait is used to specify the functionality of `&=`.
1182 /// A trivial implementation of `BitAndAssign`. When `Foo &= Foo` happens, it ends up
1183 /// calling `bitand_assign`, and therefore, `main` prints `Bitwise And-ing!`.
1186 /// #![feature(augmented_assignments)]
1187 /// #![feature(op_assign_traits)]
1189 /// use std::ops::BitAndAssign;
1191 /// #[derive(Copy, Clone)]
1194 /// impl BitAndAssign for Foo {
1195 /// fn bitand_assign(&mut self, _rhs: Foo) {
1196 /// println!("Bitwise And-ing!");
1200 /// # #[allow(unused_assignments)]
1202 /// let mut foo = Foo;
1207 #[lang = "bitand_assign"]
1208 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1209 pub trait BitAndAssign<Rhs=Self> {
1210 /// The method for the `&` operator
1211 fn bitand_assign(&mut self, Rhs);
1215 macro_rules! bitand_assign_impl {
1217 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1218 impl BitAndAssign for $t {
1220 fn bitand_assign(&mut self, other: $t) { *self &= other }
1226 bitand_assign_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
1228 /// The `BitOrAssign` trait is used to specify the functionality of `|=`.
1232 /// A trivial implementation of `BitOrAssign`. When `Foo |= Foo` happens, it ends up
1233 /// calling `bitor_assign`, and therefore, `main` prints `Bitwise Or-ing!`.
1236 /// #![feature(augmented_assignments)]
1237 /// #![feature(op_assign_traits)]
1239 /// use std::ops::BitOrAssign;
1241 /// #[derive(Copy, Clone)]
1244 /// impl BitOrAssign for Foo {
1245 /// fn bitor_assign(&mut self, _rhs: Foo) {
1246 /// println!("Bitwise Or-ing!");
1250 /// # #[allow(unused_assignments)]
1252 /// let mut foo = Foo;
1257 #[lang = "bitor_assign"]
1258 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1259 pub trait BitOrAssign<Rhs=Self> {
1260 /// The method for the `|=` operator
1261 fn bitor_assign(&mut self, Rhs);
1265 macro_rules! bitor_assign_impl {
1267 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1268 impl BitOrAssign for $t {
1270 fn bitor_assign(&mut self, other: $t) { *self |= other }
1276 bitor_assign_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
1278 /// The `BitXorAssign` trait is used to specify the functionality of `^=`.
1282 /// A trivial implementation of `BitXorAssign`. When `Foo ^= Foo` happens, it ends up
1283 /// calling `bitxor_assign`, and therefore, `main` prints `Bitwise Xor-ing!`.
1286 /// #![feature(augmented_assignments)]
1287 /// #![feature(op_assign_traits)]
1289 /// use std::ops::BitXorAssign;
1291 /// #[derive(Copy, Clone)]
1294 /// impl BitXorAssign for Foo {
1295 /// fn bitxor_assign(&mut self, _rhs: Foo) {
1296 /// println!("Bitwise Xor-ing!");
1300 /// # #[allow(unused_assignments)]
1302 /// let mut foo = Foo;
1307 #[lang = "bitxor_assign"]
1308 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1309 pub trait BitXorAssign<Rhs=Self> {
1310 /// The method for the `^=` operator
1311 fn bitxor_assign(&mut self, Rhs);
1315 macro_rules! bitxor_assign_impl {
1317 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1318 impl BitXorAssign for $t {
1320 fn bitxor_assign(&mut self, other: $t) { *self ^= other }
1326 bitxor_assign_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
1328 /// The `ShlAssign` trait is used to specify the functionality of `<<=`.
1332 /// A trivial implementation of `ShlAssign`. When `Foo <<= Foo` happens, it ends up
1333 /// calling `shl_assign`, and therefore, `main` prints `Shifting left!`.
1336 /// #![feature(augmented_assignments)]
1337 /// #![feature(op_assign_traits)]
1339 /// use std::ops::ShlAssign;
1341 /// #[derive(Copy, Clone)]
1344 /// impl ShlAssign<Foo> for Foo {
1345 /// fn shl_assign(&mut self, _rhs: Foo) {
1346 /// println!("Shifting left!");
1350 /// # #[allow(unused_assignments)]
1352 /// let mut foo = Foo;
1357 #[lang = "shl_assign"]
1358 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1359 pub trait ShlAssign<Rhs> {
1360 /// The method for the `<<=` operator
1361 fn shl_assign(&mut self, Rhs);
1365 macro_rules! shl_assign_impl {
1367 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1368 impl ShlAssign<$f> for $t {
1370 fn shl_assign(&mut self, other: $f) {
1378 macro_rules! shl_assign_impl_all {
1380 shl_assign_impl! { $t, u8 }
1381 shl_assign_impl! { $t, u16 }
1382 shl_assign_impl! { $t, u32 }
1383 shl_assign_impl! { $t, u64 }
1384 shl_assign_impl! { $t, usize }
1386 shl_assign_impl! { $t, i8 }
1387 shl_assign_impl! { $t, i16 }
1388 shl_assign_impl! { $t, i32 }
1389 shl_assign_impl! { $t, i64 }
1390 shl_assign_impl! { $t, isize }
1395 shl_assign_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
1397 /// The `ShrAssign` trait is used to specify the functionality of `>>=`.
1401 /// A trivial implementation of `ShrAssign`. When `Foo >>= Foo` happens, it ends up
1402 /// calling `shr_assign`, and therefore, `main` prints `Shifting right!`.
1405 /// #![feature(augmented_assignments)]
1406 /// #![feature(op_assign_traits)]
1408 /// use std::ops::ShrAssign;
1410 /// #[derive(Copy, Clone)]
1413 /// impl ShrAssign<Foo> for Foo {
1414 /// fn shr_assign(&mut self, _rhs: Foo) {
1415 /// println!("Shifting right!");
1419 /// # #[allow(unused_assignments)]
1421 /// let mut foo = Foo;
1426 #[lang = "shr_assign"]
1427 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1428 pub trait ShrAssign<Rhs=Self> {
1429 /// The method for the `>>=` operator
1430 fn shr_assign(&mut self, Rhs);
1434 macro_rules! shr_assign_impl {
1436 #[unstable(feature = "op_assign_traits", reason = "recently added", issue = "28235")]
1437 impl ShrAssign<$f> for $t {
1439 fn shr_assign(&mut self, other: $f) {
1447 macro_rules! shr_assign_impl_all {
1449 shr_assign_impl! { $t, u8 }
1450 shr_assign_impl! { $t, u16 }
1451 shr_assign_impl! { $t, u32 }
1452 shr_assign_impl! { $t, u64 }
1453 shr_assign_impl! { $t, usize }
1455 shr_assign_impl! { $t, i8 }
1456 shr_assign_impl! { $t, i16 }
1457 shr_assign_impl! { $t, i32 }
1458 shr_assign_impl! { $t, i64 }
1459 shr_assign_impl! { $t, isize }
1464 shr_assign_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
1466 /// The `Index` trait is used to specify the functionality of indexing operations
1467 /// like `arr[idx]` when used in an immutable context.
1471 /// A trivial implementation of `Index`. When `Foo[Bar]` happens, it ends up
1472 /// calling `index`, and therefore, `main` prints `Indexing!`.
1475 /// use std::ops::Index;
1477 /// #[derive(Copy, Clone)]
1481 /// impl Index<Bar> for Foo {
1482 /// type Output = Foo;
1484 /// fn index<'a>(&'a self, _index: Bar) -> &'a Foo {
1485 /// println!("Indexing!");
1495 #[rustc_on_unimplemented = "the type `{Self}` cannot be indexed by `{Idx}`"]
1496 #[stable(feature = "rust1", since = "1.0.0")]
1497 pub trait Index<Idx: ?Sized> {
1498 /// The returned type after indexing
1499 #[stable(feature = "rust1", since = "1.0.0")]
1500 type Output: ?Sized;
1502 /// The method for the indexing (`Foo[Bar]`) operation
1503 #[stable(feature = "rust1", since = "1.0.0")]
1504 fn index(&self, index: Idx) -> &Self::Output;
1507 /// The `IndexMut` trait is used to specify the functionality of indexing
1508 /// operations like `arr[idx]`, when used in a mutable context.
1512 /// A trivial implementation of `IndexMut`. When `Foo[Bar]` happens, it ends up
1513 /// calling `index_mut`, and therefore, `main` prints `Indexing!`.
1516 /// use std::ops::{Index, IndexMut};
1518 /// #[derive(Copy, Clone)]
1522 /// impl Index<Bar> for Foo {
1523 /// type Output = Foo;
1525 /// fn index<'a>(&'a self, _index: Bar) -> &'a Foo {
1530 /// impl IndexMut<Bar> for Foo {
1531 /// fn index_mut<'a>(&'a mut self, _index: Bar) -> &'a mut Foo {
1532 /// println!("Indexing!");
1541 #[lang = "index_mut"]
1542 #[rustc_on_unimplemented = "the type `{Self}` cannot be mutably indexed by `{Idx}`"]
1543 #[stable(feature = "rust1", since = "1.0.0")]
1544 pub trait IndexMut<Idx: ?Sized>: Index<Idx> {
1545 /// The method for the indexing (`Foo[Bar]`) operation
1546 #[stable(feature = "rust1", since = "1.0.0")]
1547 fn index_mut(&mut self, index: Idx) -> &mut Self::Output;
1550 /// An unbounded range.
1551 #[derive(Copy, Clone, PartialEq, Eq)]
1552 #[lang = "range_full"]
1553 #[stable(feature = "rust1", since = "1.0.0")]
1554 pub struct RangeFull;
1556 #[stable(feature = "rust1", since = "1.0.0")]
1557 impl fmt::Debug for RangeFull {
1558 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1563 /// A (half-open) range which is bounded at both ends.
1564 #[derive(Clone, PartialEq, Eq)]
1566 #[stable(feature = "rust1", since = "1.0.0")]
1567 pub struct Range<Idx> {
1568 /// The lower bound of the range (inclusive).
1569 #[stable(feature = "rust1", since = "1.0.0")]
1571 /// The upper bound of the range (exclusive).
1572 #[stable(feature = "rust1", since = "1.0.0")]
1576 #[stable(feature = "rust1", since = "1.0.0")]
1577 impl<Idx: fmt::Debug> fmt::Debug for Range<Idx> {
1578 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1579 write!(fmt, "{:?}..{:?}", self.start, self.end)
1583 /// A range which is only bounded below.
1584 #[derive(Clone, PartialEq, Eq)]
1585 #[lang = "range_from"]
1586 #[stable(feature = "rust1", since = "1.0.0")]
1587 pub struct RangeFrom<Idx> {
1588 /// The lower bound of the range (inclusive).
1589 #[stable(feature = "rust1", since = "1.0.0")]
1593 #[stable(feature = "rust1", since = "1.0.0")]
1594 impl<Idx: fmt::Debug> fmt::Debug for RangeFrom<Idx> {
1595 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1596 write!(fmt, "{:?}..", self.start)
1600 /// A range which is only bounded above.
1601 #[derive(Copy, Clone, PartialEq, Eq)]
1602 #[lang = "range_to"]
1603 #[stable(feature = "rust1", since = "1.0.0")]
1604 pub struct RangeTo<Idx> {
1605 /// The upper bound of the range (exclusive).
1606 #[stable(feature = "rust1", since = "1.0.0")]
1610 #[stable(feature = "rust1", since = "1.0.0")]
1611 impl<Idx: fmt::Debug> fmt::Debug for RangeTo<Idx> {
1612 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1613 write!(fmt, "..{:?}", self.end)
1617 /// The `Deref` trait is used to specify the functionality of dereferencing
1618 /// operations like `*v`.
1620 /// `Deref` also enables ['`Deref` coercions'][coercions].
1622 /// [coercions]: ../../book/deref-coercions.html
1626 /// A struct with a single field which is accessible via dereferencing the
1630 /// use std::ops::Deref;
1632 /// struct DerefExample<T> {
1636 /// impl<T> Deref for DerefExample<T> {
1637 /// type Target = T;
1639 /// fn deref(&self) -> &T {
1645 /// let x = DerefExample { value: 'a' };
1646 /// assert_eq!('a', *x);
1650 #[stable(feature = "rust1", since = "1.0.0")]
1652 /// The resulting type after dereferencing
1653 #[stable(feature = "rust1", since = "1.0.0")]
1654 type Target: ?Sized;
1656 /// The method called to dereference a value
1657 #[stable(feature = "rust1", since = "1.0.0")]
1658 fn deref(&self) -> &Self::Target;
1661 #[stable(feature = "rust1", since = "1.0.0")]
1662 impl<'a, T: ?Sized> Deref for &'a T {
1665 fn deref(&self) -> &T { *self }
1668 #[stable(feature = "rust1", since = "1.0.0")]
1669 impl<'a, T: ?Sized> Deref for &'a mut T {
1672 fn deref(&self) -> &T { *self }
1675 /// The `DerefMut` trait is used to specify the functionality of dereferencing
1676 /// mutably like `*v = 1;`
1678 /// `DerefMut` also enables ['`Deref` coercions'][coercions].
1680 /// [coercions]: ../../book/deref-coercions.html
1684 /// A struct with a single field which is modifiable via dereferencing the
1688 /// use std::ops::{Deref, DerefMut};
1690 /// struct DerefMutExample<T> {
1694 /// impl<T> Deref for DerefMutExample<T> {
1695 /// type Target = T;
1697 /// fn deref<'a>(&'a self) -> &'a T {
1702 /// impl<T> DerefMut for DerefMutExample<T> {
1703 /// fn deref_mut<'a>(&'a mut self) -> &'a mut T {
1709 /// let mut x = DerefMutExample { value: 'a' };
1711 /// assert_eq!('b', *x);
1714 #[lang = "deref_mut"]
1715 #[stable(feature = "rust1", since = "1.0.0")]
1716 pub trait DerefMut: Deref {
1717 /// The method called to mutably dereference a value
1718 #[stable(feature = "rust1", since = "1.0.0")]
1719 fn deref_mut(&mut self) -> &mut Self::Target;
1722 #[stable(feature = "rust1", since = "1.0.0")]
1723 impl<'a, T: ?Sized> DerefMut for &'a mut T {
1724 fn deref_mut(&mut self) -> &mut T { *self }
1727 /// A version of the call operator that takes an immutable receiver.
1729 #[stable(feature = "rust1", since = "1.0.0")]
1730 #[rustc_paren_sugar]
1731 #[fundamental] // so that regex can rely that `&str: !FnMut`
1732 pub trait Fn<Args> : FnMut<Args> {
1733 /// This is called when the call operator is used.
1734 extern "rust-call" fn call(&self, args: Args) -> Self::Output;
1737 /// A version of the call operator that takes a mutable receiver.
1739 #[stable(feature = "rust1", since = "1.0.0")]
1740 #[rustc_paren_sugar]
1741 #[fundamental] // so that regex can rely that `&str: !FnMut`
1742 pub trait FnMut<Args> : FnOnce<Args> {
1743 /// This is called when the call operator is used.
1744 extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
1747 /// A version of the call operator that takes a by-value receiver.
1749 #[stable(feature = "rust1", since = "1.0.0")]
1750 #[rustc_paren_sugar]
1751 #[fundamental] // so that regex can rely that `&str: !FnMut`
1752 pub trait FnOnce<Args> {
1753 /// The returned type after the call operator is used.
1756 /// This is called when the call operator is used.
1757 extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
1762 use super::{Fn, FnMut, FnOnce};
1764 impl<'a,A,F:?Sized> Fn<A> for &'a F
1767 extern "rust-call" fn call(&self, args: A) -> F::Output {
1772 impl<'a,A,F:?Sized> FnMut<A> for &'a F
1775 extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
1780 impl<'a,A,F:?Sized> FnOnce<A> for &'a F
1783 type Output = F::Output;
1785 extern "rust-call" fn call_once(self, args: A) -> F::Output {
1790 impl<'a,A,F:?Sized> FnMut<A> for &'a mut F
1793 extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
1794 (*self).call_mut(args)
1798 impl<'a,A,F:?Sized> FnOnce<A> for &'a mut F
1801 type Output = F::Output;
1802 extern "rust-call" fn call_once(mut self, args: A) -> F::Output {
1803 (*self).call_mut(args)
1808 /// Trait that indicates that this is a pointer or a wrapper for one,
1809 /// where unsizing can be performed on the pointee.
1810 #[unstable(feature = "coerce_unsized", issue = "27732")]
1811 #[lang="coerce_unsized"]
1812 pub trait CoerceUnsized<T> {
1817 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a mut U> for &'a mut T {}
1819 impl<'a, 'b: 'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a U> for &'b mut T {}
1821 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*mut U> for &'a mut T {}
1822 // &mut T -> *const U
1823 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for &'a mut T {}
1826 impl<'a, 'b: 'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<&'a U> for &'b T {}
1828 impl<'a, T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for &'a T {}
1831 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*mut U> for *mut T {}
1832 // *mut T -> *const U
1833 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for *mut T {}
1835 // *const T -> *const U
1836 impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<*const U> for *const T {}
1838 /// Both `in (PLACE) EXPR` and `box EXPR` desugar into expressions
1839 /// that allocate an intermediate "place" that holds uninitialized
1840 /// state. The desugaring evaluates EXPR, and writes the result at
1841 /// the address returned by the `pointer` method of this trait.
1843 /// A `Place` can be thought of as a special representation for a
1844 /// hypothetical `&uninit` reference (which Rust cannot currently
1845 /// express directly). That is, it represents a pointer to
1846 /// uninitialized storage.
1848 /// The client is responsible for two steps: First, initializing the
1849 /// payload (it can access its address via `pointer`). Second,
1850 /// converting the agent to an instance of the owning pointer, via the
1851 /// appropriate `finalize` method (see the `InPlace`.
1853 /// If evaluating EXPR fails, then the destructor for the
1854 /// implementation of Place to clean up any intermediate state
1855 /// (e.g. deallocate box storage, pop a stack, etc).
1856 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1857 pub trait Place<Data: ?Sized> {
1858 /// Returns the address where the input value will be written.
1859 /// Note that the data at this address is generally uninitialized,
1860 /// and thus one should use `ptr::write` for initializing it.
1861 fn pointer(&mut self) -> *mut Data;
1864 /// Interface to implementations of `in (PLACE) EXPR`.
1866 /// `in (PLACE) EXPR` effectively desugars into:
1870 /// let mut place = Placer::make_place(p);
1871 /// let raw_place = Place::pointer(&mut place);
1872 /// let value = EXPR;
1874 /// std::ptr::write(raw_place, value);
1875 /// InPlace::finalize(place)
1879 /// The type of `in (PLACE) EXPR` is derived from the type of `PLACE`;
1880 /// if the type of `PLACE` is `P`, then the final type of the whole
1881 /// expression is `P::Place::Owner` (see the `InPlace` and `Boxed`
1884 /// Values for types implementing this trait usually are transient
1885 /// intermediate values (e.g. the return value of `Vec::emplace_back`)
1886 /// or `Copy`, since the `make_place` method takes `self` by value.
1887 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1888 pub trait Placer<Data: ?Sized> {
1889 /// `Place` is the intermedate agent guarding the
1890 /// uninitialized state for `Data`.
1891 type Place: InPlace<Data>;
1893 /// Creates a fresh place from `self`.
1894 fn make_place(self) -> Self::Place;
1897 /// Specialization of `Place` trait supporting `in (PLACE) EXPR`.
1898 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1899 pub trait InPlace<Data: ?Sized>: Place<Data> {
1900 /// `Owner` is the type of the end value of `in (PLACE) EXPR`
1902 /// Note that when `in (PLACE) EXPR` is solely used for
1903 /// side-effecting an existing data-structure,
1904 /// e.g. `Vec::emplace_back`, then `Owner` need not carry any
1905 /// information at all (e.g. it can be the unit type `()` in that
1909 /// Converts self into the final value, shifting
1910 /// deallocation/cleanup responsibilities (if any remain), over to
1911 /// the returned instance of `Owner` and forgetting self.
1912 unsafe fn finalize(self) -> Self::Owner;
1915 /// Core trait for the `box EXPR` form.
1917 /// `box EXPR` effectively desugars into:
1920 /// let mut place = BoxPlace::make_place();
1921 /// let raw_place = Place::pointer(&mut place);
1922 /// let value = EXPR;
1924 /// ::std::ptr::write(raw_place, value);
1925 /// Boxed::finalize(place)
1929 /// The type of `box EXPR` is supplied from its surrounding
1930 /// context; in the above expansion, the result type `T` is used
1931 /// to determine which implementation of `Boxed` to use, and that
1932 /// `<T as Boxed>` in turn dictates determines which
1933 /// implementation of `BoxPlace` to use, namely:
1934 /// `<<T as Boxed>::Place as BoxPlace>`.
1935 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1937 /// The kind of data that is stored in this kind of box.
1938 type Data; /* (`Data` unused b/c cannot yet express below bound.) */
1939 /// The place that will negotiate the storage of the data.
1940 type Place: BoxPlace<Self::Data>;
1942 /// Converts filled place into final owning value, shifting
1943 /// deallocation/cleanup responsibilities (if any remain), over to
1944 /// returned instance of `Self` and forgetting `filled`.
1945 unsafe fn finalize(filled: Self::Place) -> Self;
1948 /// Specialization of `Place` trait supporting `box EXPR`.
1949 #[unstable(feature = "placement_new_protocol", issue = "27779")]
1950 pub trait BoxPlace<Data: ?Sized> : Place<Data> {
1951 /// Creates a globally fresh place.
1952 fn make_place() -> Self;