1 //! Overloadable operators.
3 //! Implementing these traits allows you to overload certain operators.
5 //! Some of these traits are imported by the prelude, so they are available in
6 //! every Rust program. Only operators backed by traits can be overloaded. For
7 //! example, the addition operator (`+`) can be overloaded through the [`Add`]
8 //! trait, but since the assignment operator (`=`) has no backing trait, there
9 //! is no way of overloading its semantics. Additionally, this module does not
10 //! provide any mechanism to create new operators. If traitless overloading or
11 //! custom operators are required, you should look toward macros or compiler
12 //! plugins to extend Rust's syntax.
14 //! Implementations of operator traits should be unsurprising in their
15 //! respective contexts, keeping in mind their usual meanings and
16 //! [operator precedence]. For example, when implementing [`Mul`], the operation
17 //! should have some resemblance to multiplication (and share expected
18 //! properties like associativity).
20 //! Note that the `&&` and `||` operators short-circuit, i.e., they only
21 //! evaluate their second operand if it contributes to the result. Since this
22 //! behavior is not enforceable by traits, `&&` and `||` are not supported as
23 //! overloadable operators.
25 //! Many of the operators take their operands by value. In non-generic
26 //! contexts involving built-in types, this is usually not a problem.
27 //! However, using these operators in generic code, requires some
28 //! attention if values have to be reused as opposed to letting the operators
29 //! consume them. One option is to occasionally use [`clone`].
30 //! Another option is to rely on the types involved providing additional
31 //! operator implementations for references. For example, for a user-defined
32 //! type `T` which is supposed to support addition, it is probably a good
33 //! idea to have both `T` and `&T` implement the traits [`Add<T>`][`Add`] and
34 //! [`Add<&T>`][`Add`] so that generic code can be written without unnecessary
39 //! This example creates a `Point` struct that implements [`Add`] and [`Sub`],
40 //! and then demonstrates adding and subtracting two `Point`s.
43 //! use std::ops::{Add, Sub};
45 //! #[derive(Debug, PartialEq)]
51 //! impl Add for Point {
52 //! type Output = Point;
54 //! fn add(self, other: Point) -> Point {
55 //! Point {x: self.x + other.x, y: self.y + other.y}
59 //! impl Sub for Point {
60 //! type Output = Point;
62 //! fn sub(self, other: Point) -> Point {
63 //! Point {x: self.x - other.x, y: self.y - other.y}
67 //! assert_eq!(Point {x: 3, y: 3}, Point {x: 1, y: 0} + Point {x: 2, y: 3});
68 //! assert_eq!(Point {x: -1, y: -3}, Point {x: 1, y: 0} - Point {x: 2, y: 3});
71 //! See the documentation for each trait for an example implementation.
73 //! The [`Fn`], [`FnMut`], and [`FnOnce`] traits are implemented by types that can be
74 //! invoked like functions. Note that [`Fn`] takes `&self`, [`FnMut`] takes `&mut
75 //! self` and [`FnOnce`] takes `self`. These correspond to the three kinds of
76 //! methods that can be invoked on an instance: call-by-reference,
77 //! call-by-mutable-reference, and call-by-value. The most common use of these
78 //! traits is to act as bounds to higher-level functions that take functions or
79 //! closures as arguments.
81 //! Taking a [`Fn`] as a parameter:
84 //! fn call_with_one<F>(func: F) -> usize
85 //! where F: Fn(usize) -> usize
90 //! let double = |x| x * 2;
91 //! assert_eq!(call_with_one(double), 2);
94 //! Taking a [`FnMut`] as a parameter:
97 //! fn do_twice<F>(mut func: F)
104 //! let mut x: usize = 1;
106 //! let add_two_to_x = || x += 2;
107 //! do_twice(add_two_to_x);
110 //! assert_eq!(x, 5);
113 //! Taking a [`FnOnce`] as a parameter:
116 //! fn consume_with_relish<F>(func: F)
117 //! where F: FnOnce() -> String
119 //! // `func` consumes its captured variables, so it cannot be run more
121 //! println!("Consumed: {}", func());
123 //! println!("Delicious!");
125 //! // Attempting to invoke `func()` again will throw a `use of moved
126 //! // value` error for `func`
129 //! let x = String::from("x");
130 //! let consume_and_return_x = move || x;
131 //! consume_with_relish(consume_and_return_x);
133 //! // `consume_and_return_x` can no longer be invoked at this point
136 //! [`Fn`]: trait.Fn.html
137 //! [`FnMut`]: trait.FnMut.html
138 //! [`FnOnce`]: trait.FnOnce.html
139 //! [`Add`]: trait.Add.html
140 //! [`Sub`]: trait.Sub.html
141 //! [`Mul`]: trait.Mul.html
142 //! [`clone`]: ../clone/trait.Clone.html#tymethod.clone
143 //! [operator precedence]: ../../reference/expressions.html#expression-precedence
145 #![stable(feature = "rust1", since = "1.0.0")]
158 #[stable(feature = "rust1", since = "1.0.0")]
159 pub use self::arith::{Add, Div, Mul, Neg, Rem, Sub};
160 #[stable(feature = "op_assign_traits", since = "1.8.0")]
161 pub use self::arith::{AddAssign, DivAssign, MulAssign, RemAssign, SubAssign};
163 #[stable(feature = "rust1", since = "1.0.0")]
164 pub use self::bit::{BitAnd, BitOr, BitXor, Not, Shl, Shr};
165 #[stable(feature = "op_assign_traits", since = "1.8.0")]
166 pub use self::bit::{BitAndAssign, BitOrAssign, BitXorAssign, ShlAssign, ShrAssign};
168 #[stable(feature = "rust1", since = "1.0.0")]
169 pub use self::deref::{Deref, DerefMut};
171 #[unstable(feature = "receiver_trait", issue = "none")]
172 pub use self::deref::Receiver;
174 #[stable(feature = "rust1", since = "1.0.0")]
175 pub use self::drop::Drop;
177 #[stable(feature = "rust1", since = "1.0.0")]
178 pub use self::function::{Fn, FnMut, FnOnce};
180 #[stable(feature = "rust1", since = "1.0.0")]
181 pub use self::index::{Index, IndexMut};
183 #[stable(feature = "rust1", since = "1.0.0")]
184 pub use self::range::{Range, RangeFrom, RangeFull, RangeTo};
186 #[stable(feature = "inclusive_range", since = "1.26.0")]
187 pub use self::range::{Bound, RangeBounds, RangeInclusive, RangeToInclusive};
189 #[unstable(feature = "try_trait", issue = "42327")]
190 pub use self::r#try::Try;
192 #[unstable(feature = "generator_trait", issue = "43122")]
193 pub use self::generator::{Generator, GeneratorState};
195 #[unstable(feature = "coerce_unsized", issue = "27732")]
196 pub use self::unsize::CoerceUnsized;
198 #[unstable(feature = "dispatch_from_dyn", issue = "none")]
199 pub use self::unsize::DispatchFromDyn;