1 | /// The addition operator `+`. |
2 | /// |
3 | /// Note that `Rhs` is `Self` by default, but this is not mandatory. For |
4 | /// example, [`std::time::SystemTime`] implements `Add<Duration>`, which permits |
5 | /// operations of the form `SystemTime = SystemTime + Duration`. |
6 | /// |
7 | /// [`std::time::SystemTime`]: ../../std/time/struct.SystemTime.html |
8 | /// |
9 | /// # Examples |
10 | /// |
11 | /// ## `Add`able points |
12 | /// |
13 | /// ``` |
14 | /// use std::ops::Add; |
15 | /// |
16 | /// #[derive(Debug, Copy, Clone, PartialEq)] |
17 | /// struct Point { |
18 | /// x: i32, |
19 | /// y: i32, |
20 | /// } |
21 | /// |
22 | /// impl Add for Point { |
23 | /// type Output = Self; |
24 | /// |
25 | /// fn add(self, other: Self) -> Self { |
26 | /// Self { |
27 | /// x: self.x + other.x, |
28 | /// y: self.y + other.y, |
29 | /// } |
30 | /// } |
31 | /// } |
32 | /// |
33 | /// assert_eq!(Point { x: 1, y: 0 } + Point { x: 2, y: 3 }, |
34 | /// Point { x: 3, y: 3 }); |
35 | /// ``` |
36 | /// |
37 | /// ## Implementing `Add` with generics |
38 | /// |
39 | /// Here is an example of the same `Point` struct implementing the `Add` trait |
40 | /// using generics. |
41 | /// |
42 | /// ``` |
43 | /// use std::ops::Add; |
44 | /// |
45 | /// #[derive(Debug, Copy, Clone, PartialEq)] |
46 | /// struct Point<T> { |
47 | /// x: T, |
48 | /// y: T, |
49 | /// } |
50 | /// |
51 | /// // Notice that the implementation uses the associated type `Output`. |
52 | /// impl<T: Add<Output = T>> Add for Point<T> { |
53 | /// type Output = Self; |
54 | /// |
55 | /// fn add(self, other: Self) -> Self::Output { |
56 | /// Self { |
57 | /// x: self.x + other.x, |
58 | /// y: self.y + other.y, |
59 | /// } |
60 | /// } |
61 | /// } |
62 | /// |
63 | /// assert_eq!(Point { x: 1, y: 0 } + Point { x: 2, y: 3 }, |
64 | /// Point { x: 3, y: 3 }); |
65 | /// ``` |
66 | #[lang = "add" ] |
67 | #[stable (feature = "rust1" , since = "1.0.0" )] |
68 | #[rustc_on_unimplemented ( |
69 | on(all(_Self = "{integer}" , Rhs = "{float}" ), message = "cannot add a float to an integer" ,), |
70 | on(all(_Self = "{float}" , Rhs = "{integer}" ), message = "cannot add an integer to a float" ,), |
71 | message = "cannot add `{Rhs}` to `{Self}`" , |
72 | label = "no implementation for `{Self} + {Rhs}`" , |
73 | append_const_msg |
74 | )] |
75 | #[doc (alias = "+" )] |
76 | #[const_trait ] |
77 | pub trait Add<Rhs = Self> { |
78 | /// The resulting type after applying the `+` operator. |
79 | #[stable (feature = "rust1" , since = "1.0.0" )] |
80 | type Output; |
81 | |
82 | /// Performs the `+` operation. |
83 | /// |
84 | /// # Example |
85 | /// |
86 | /// ``` |
87 | /// assert_eq!(12 + 1, 13); |
88 | /// ``` |
89 | #[must_use = "this returns the result of the operation, without modifying the original" ] |
90 | #[rustc_diagnostic_item = "add" ] |
91 | #[stable (feature = "rust1" , since = "1.0.0" )] |
92 | fn add(self, rhs: Rhs) -> Self::Output; |
93 | } |
94 | |
95 | macro_rules! add_impl { |
96 | ($($t:ty)*) => ($( |
97 | #[stable(feature = "rust1" , since = "1.0.0" )] |
98 | #[rustc_const_unstable(feature = "const_ops" , issue = "90080" )] |
99 | impl const Add for $t { |
100 | type Output = $t; |
101 | |
102 | #[inline] |
103 | #[track_caller] |
104 | #[rustc_inherit_overflow_checks] |
105 | fn add(self, other: $t) -> $t { self + other } |
106 | } |
107 | |
108 | forward_ref_binop! { impl Add, add for $t, $t } |
109 | )*) |
110 | } |
111 | |
112 | add_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } |
113 | |
114 | /// The subtraction operator `-`. |
115 | /// |
116 | /// Note that `Rhs` is `Self` by default, but this is not mandatory. For |
117 | /// example, [`std::time::SystemTime`] implements `Sub<Duration>`, which permits |
118 | /// operations of the form `SystemTime = SystemTime - Duration`. |
119 | /// |
120 | /// [`std::time::SystemTime`]: ../../std/time/struct.SystemTime.html |
121 | /// |
122 | /// # Examples |
123 | /// |
124 | /// ## `Sub`tractable points |
125 | /// |
126 | /// ``` |
127 | /// use std::ops::Sub; |
128 | /// |
129 | /// #[derive(Debug, Copy, Clone, PartialEq)] |
130 | /// struct Point { |
131 | /// x: i32, |
132 | /// y: i32, |
133 | /// } |
134 | /// |
135 | /// impl Sub for Point { |
136 | /// type Output = Self; |
137 | /// |
138 | /// fn sub(self, other: Self) -> Self::Output { |
139 | /// Self { |
140 | /// x: self.x - other.x, |
141 | /// y: self.y - other.y, |
142 | /// } |
143 | /// } |
144 | /// } |
145 | /// |
146 | /// assert_eq!(Point { x: 3, y: 3 } - Point { x: 2, y: 3 }, |
147 | /// Point { x: 1, y: 0 }); |
148 | /// ``` |
149 | /// |
150 | /// ## Implementing `Sub` with generics |
151 | /// |
152 | /// Here is an example of the same `Point` struct implementing the `Sub` trait |
153 | /// using generics. |
154 | /// |
155 | /// ``` |
156 | /// use std::ops::Sub; |
157 | /// |
158 | /// #[derive(Debug, PartialEq)] |
159 | /// struct Point<T> { |
160 | /// x: T, |
161 | /// y: T, |
162 | /// } |
163 | /// |
164 | /// // Notice that the implementation uses the associated type `Output`. |
165 | /// impl<T: Sub<Output = T>> Sub for Point<T> { |
166 | /// type Output = Self; |
167 | /// |
168 | /// fn sub(self, other: Self) -> Self::Output { |
169 | /// Point { |
170 | /// x: self.x - other.x, |
171 | /// y: self.y - other.y, |
172 | /// } |
173 | /// } |
174 | /// } |
175 | /// |
176 | /// assert_eq!(Point { x: 2, y: 3 } - Point { x: 1, y: 0 }, |
177 | /// Point { x: 1, y: 3 }); |
178 | /// ``` |
179 | #[lang = "sub" ] |
180 | #[stable (feature = "rust1" , since = "1.0.0" )] |
181 | #[rustc_on_unimplemented ( |
182 | message = "cannot subtract `{Rhs}` from `{Self}`" , |
183 | label = "no implementation for `{Self} - {Rhs}`" , |
184 | append_const_msg |
185 | )] |
186 | #[doc (alias = "-" )] |
187 | pub trait Sub<Rhs = Self> { |
188 | /// The resulting type after applying the `-` operator. |
189 | #[stable (feature = "rust1" , since = "1.0.0" )] |
190 | type Output; |
191 | |
192 | /// Performs the `-` operation. |
193 | /// |
194 | /// # Example |
195 | /// |
196 | /// ``` |
197 | /// assert_eq!(12 - 1, 11); |
198 | /// ``` |
199 | #[must_use = "this returns the result of the operation, without modifying the original" ] |
200 | #[rustc_diagnostic_item = "sub" ] |
201 | #[stable (feature = "rust1" , since = "1.0.0" )] |
202 | fn sub(self, rhs: Rhs) -> Self::Output; |
203 | } |
204 | |
205 | macro_rules! sub_impl { |
206 | ($($t:ty)*) => ($( |
207 | #[stable(feature = "rust1" , since = "1.0.0" )] |
208 | impl Sub for $t { |
209 | type Output = $t; |
210 | |
211 | #[inline] |
212 | #[track_caller] |
213 | #[rustc_inherit_overflow_checks] |
214 | fn sub(self, other: $t) -> $t { self - other } |
215 | } |
216 | |
217 | forward_ref_binop! { impl Sub, sub for $t, $t } |
218 | )*) |
219 | } |
220 | |
221 | sub_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } |
222 | |
223 | /// The multiplication operator `*`. |
224 | /// |
225 | /// Note that `Rhs` is `Self` by default, but this is not mandatory. |
226 | /// |
227 | /// # Examples |
228 | /// |
229 | /// ## `Mul`tipliable rational numbers |
230 | /// |
231 | /// ``` |
232 | /// use std::ops::Mul; |
233 | /// |
234 | /// // By the fundamental theorem of arithmetic, rational numbers in lowest |
235 | /// // terms are unique. So, by keeping `Rational`s in reduced form, we can |
236 | /// // derive `Eq` and `PartialEq`. |
237 | /// #[derive(Debug, Eq, PartialEq)] |
238 | /// struct Rational { |
239 | /// numerator: usize, |
240 | /// denominator: usize, |
241 | /// } |
242 | /// |
243 | /// impl Rational { |
244 | /// fn new(numerator: usize, denominator: usize) -> Self { |
245 | /// if denominator == 0 { |
246 | /// panic!("Zero is an invalid denominator!" ); |
247 | /// } |
248 | /// |
249 | /// // Reduce to lowest terms by dividing by the greatest common |
250 | /// // divisor. |
251 | /// let gcd = gcd(numerator, denominator); |
252 | /// Self { |
253 | /// numerator: numerator / gcd, |
254 | /// denominator: denominator / gcd, |
255 | /// } |
256 | /// } |
257 | /// } |
258 | /// |
259 | /// impl Mul for Rational { |
260 | /// // The multiplication of rational numbers is a closed operation. |
261 | /// type Output = Self; |
262 | /// |
263 | /// fn mul(self, rhs: Self) -> Self { |
264 | /// let numerator = self.numerator * rhs.numerator; |
265 | /// let denominator = self.denominator * rhs.denominator; |
266 | /// Self::new(numerator, denominator) |
267 | /// } |
268 | /// } |
269 | /// |
270 | /// // Euclid's two-thousand-year-old algorithm for finding the greatest common |
271 | /// // divisor. |
272 | /// fn gcd(x: usize, y: usize) -> usize { |
273 | /// let mut x = x; |
274 | /// let mut y = y; |
275 | /// while y != 0 { |
276 | /// let t = y; |
277 | /// y = x % y; |
278 | /// x = t; |
279 | /// } |
280 | /// x |
281 | /// } |
282 | /// |
283 | /// assert_eq!(Rational::new(1, 2), Rational::new(2, 4)); |
284 | /// assert_eq!(Rational::new(2, 3) * Rational::new(3, 4), |
285 | /// Rational::new(1, 2)); |
286 | /// ``` |
287 | /// |
288 | /// ## Multiplying vectors by scalars as in linear algebra |
289 | /// |
290 | /// ``` |
291 | /// use std::ops::Mul; |
292 | /// |
293 | /// struct Scalar { value: usize } |
294 | /// |
295 | /// #[derive(Debug, PartialEq)] |
296 | /// struct Vector { value: Vec<usize> } |
297 | /// |
298 | /// impl Mul<Scalar> for Vector { |
299 | /// type Output = Self; |
300 | /// |
301 | /// fn mul(self, rhs: Scalar) -> Self::Output { |
302 | /// Self { value: self.value.iter().map(|v| v * rhs.value).collect() } |
303 | /// } |
304 | /// } |
305 | /// |
306 | /// let vector = Vector { value: vec![2, 4, 6] }; |
307 | /// let scalar = Scalar { value: 3 }; |
308 | /// assert_eq!(vector * scalar, Vector { value: vec![6, 12, 18] }); |
309 | /// ``` |
310 | #[lang = "mul" ] |
311 | #[stable (feature = "rust1" , since = "1.0.0" )] |
312 | #[diagnostic::on_unimplemented( |
313 | message = "cannot multiply `{Self}` by `{Rhs}`" , |
314 | label = "no implementation for `{Self} * {Rhs}`" |
315 | )] |
316 | #[doc (alias = "*" )] |
317 | pub trait Mul<Rhs = Self> { |
318 | /// The resulting type after applying the `*` operator. |
319 | #[stable (feature = "rust1" , since = "1.0.0" )] |
320 | type Output; |
321 | |
322 | /// Performs the `*` operation. |
323 | /// |
324 | /// # Example |
325 | /// |
326 | /// ``` |
327 | /// assert_eq!(12 * 2, 24); |
328 | /// ``` |
329 | #[must_use = "this returns the result of the operation, without modifying the original" ] |
330 | #[rustc_diagnostic_item = "mul" ] |
331 | #[stable (feature = "rust1" , since = "1.0.0" )] |
332 | fn mul(self, rhs: Rhs) -> Self::Output; |
333 | } |
334 | |
335 | macro_rules! mul_impl { |
336 | ($($t:ty)*) => ($( |
337 | #[stable(feature = "rust1" , since = "1.0.0" )] |
338 | impl Mul for $t { |
339 | type Output = $t; |
340 | |
341 | #[inline] |
342 | #[track_caller] |
343 | #[rustc_inherit_overflow_checks] |
344 | fn mul(self, other: $t) -> $t { self * other } |
345 | } |
346 | |
347 | forward_ref_binop! { impl Mul, mul for $t, $t } |
348 | )*) |
349 | } |
350 | |
351 | mul_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } |
352 | |
353 | /// The division operator `/`. |
354 | /// |
355 | /// Note that `Rhs` is `Self` by default, but this is not mandatory. |
356 | /// |
357 | /// # Examples |
358 | /// |
359 | /// ## `Div`idable rational numbers |
360 | /// |
361 | /// ``` |
362 | /// use std::ops::Div; |
363 | /// |
364 | /// // By the fundamental theorem of arithmetic, rational numbers in lowest |
365 | /// // terms are unique. So, by keeping `Rational`s in reduced form, we can |
366 | /// // derive `Eq` and `PartialEq`. |
367 | /// #[derive(Debug, Eq, PartialEq)] |
368 | /// struct Rational { |
369 | /// numerator: usize, |
370 | /// denominator: usize, |
371 | /// } |
372 | /// |
373 | /// impl Rational { |
374 | /// fn new(numerator: usize, denominator: usize) -> Self { |
375 | /// if denominator == 0 { |
376 | /// panic!("Zero is an invalid denominator!" ); |
377 | /// } |
378 | /// |
379 | /// // Reduce to lowest terms by dividing by the greatest common |
380 | /// // divisor. |
381 | /// let gcd = gcd(numerator, denominator); |
382 | /// Self { |
383 | /// numerator: numerator / gcd, |
384 | /// denominator: denominator / gcd, |
385 | /// } |
386 | /// } |
387 | /// } |
388 | /// |
389 | /// impl Div for Rational { |
390 | /// // The division of rational numbers is a closed operation. |
391 | /// type Output = Self; |
392 | /// |
393 | /// fn div(self, rhs: Self) -> Self::Output { |
394 | /// if rhs.numerator == 0 { |
395 | /// panic!("Cannot divide by zero-valued `Rational`!" ); |
396 | /// } |
397 | /// |
398 | /// let numerator = self.numerator * rhs.denominator; |
399 | /// let denominator = self.denominator * rhs.numerator; |
400 | /// Self::new(numerator, denominator) |
401 | /// } |
402 | /// } |
403 | /// |
404 | /// // Euclid's two-thousand-year-old algorithm for finding the greatest common |
405 | /// // divisor. |
406 | /// fn gcd(x: usize, y: usize) -> usize { |
407 | /// let mut x = x; |
408 | /// let mut y = y; |
409 | /// while y != 0 { |
410 | /// let t = y; |
411 | /// y = x % y; |
412 | /// x = t; |
413 | /// } |
414 | /// x |
415 | /// } |
416 | /// |
417 | /// assert_eq!(Rational::new(1, 2), Rational::new(2, 4)); |
418 | /// assert_eq!(Rational::new(1, 2) / Rational::new(3, 4), |
419 | /// Rational::new(2, 3)); |
420 | /// ``` |
421 | /// |
422 | /// ## Dividing vectors by scalars as in linear algebra |
423 | /// |
424 | /// ``` |
425 | /// use std::ops::Div; |
426 | /// |
427 | /// struct Scalar { value: f32 } |
428 | /// |
429 | /// #[derive(Debug, PartialEq)] |
430 | /// struct Vector { value: Vec<f32> } |
431 | /// |
432 | /// impl Div<Scalar> for Vector { |
433 | /// type Output = Self; |
434 | /// |
435 | /// fn div(self, rhs: Scalar) -> Self::Output { |
436 | /// Self { value: self.value.iter().map(|v| v / rhs.value).collect() } |
437 | /// } |
438 | /// } |
439 | /// |
440 | /// let scalar = Scalar { value: 2f32 }; |
441 | /// let vector = Vector { value: vec![2f32, 4f32, 6f32] }; |
442 | /// assert_eq!(vector / scalar, Vector { value: vec![1f32, 2f32, 3f32] }); |
443 | /// ``` |
444 | #[lang = "div" ] |
445 | #[stable (feature = "rust1" , since = "1.0.0" )] |
446 | #[diagnostic::on_unimplemented( |
447 | message = "cannot divide `{Self}` by `{Rhs}`" , |
448 | label = "no implementation for `{Self} / {Rhs}`" |
449 | )] |
450 | #[doc (alias = "/" )] |
451 | pub trait Div<Rhs = Self> { |
452 | /// The resulting type after applying the `/` operator. |
453 | #[stable (feature = "rust1" , since = "1.0.0" )] |
454 | type Output; |
455 | |
456 | /// Performs the `/` operation. |
457 | /// |
458 | /// # Example |
459 | /// |
460 | /// ``` |
461 | /// assert_eq!(12 / 2, 6); |
462 | /// ``` |
463 | #[must_use = "this returns the result of the operation, without modifying the original" ] |
464 | #[rustc_diagnostic_item = "div" ] |
465 | #[stable (feature = "rust1" , since = "1.0.0" )] |
466 | fn div(self, rhs: Rhs) -> Self::Output; |
467 | } |
468 | |
469 | macro_rules! div_impl_integer { |
470 | ($(($($t:ty)*) => $panic:expr),*) => ($($( |
471 | /// This operation rounds towards zero, truncating any |
472 | /// fractional part of the exact result. |
473 | /// |
474 | /// # Panics |
475 | /// |
476 | #[doc = $panic] |
477 | #[stable(feature = "rust1" , since = "1.0.0" )] |
478 | impl Div for $t { |
479 | type Output = $t; |
480 | |
481 | #[inline] |
482 | #[track_caller] |
483 | fn div(self, other: $t) -> $t { self / other } |
484 | } |
485 | |
486 | forward_ref_binop! { impl Div, div for $t, $t } |
487 | )*)*) |
488 | } |
489 | |
490 | div_impl_integer! { |
491 | (usize u8 u16 u32 u64 u128) => "This operation will panic if `other == 0`." , |
492 | (isize i8 i16 i32 i64 i128) => "This operation will panic if `other == 0` or the division results in overflow." |
493 | } |
494 | |
495 | macro_rules! div_impl_float { |
496 | ($($t:ty)*) => ($( |
497 | #[stable(feature = "rust1" , since = "1.0.0" )] |
498 | impl Div for $t { |
499 | type Output = $t; |
500 | |
501 | #[inline] |
502 | fn div(self, other: $t) -> $t { self / other } |
503 | } |
504 | |
505 | forward_ref_binop! { impl Div, div for $t, $t } |
506 | )*) |
507 | } |
508 | |
509 | div_impl_float! { f16 f32 f64 f128 } |
510 | |
511 | /// The remainder operator `%`. |
512 | /// |
513 | /// Note that `Rhs` is `Self` by default, but this is not mandatory. |
514 | /// |
515 | /// # Examples |
516 | /// |
517 | /// This example implements `Rem` on a `SplitSlice` object. After `Rem` is |
518 | /// implemented, one can use the `%` operator to find out what the remaining |
519 | /// elements of the slice would be after splitting it into equal slices of a |
520 | /// given length. |
521 | /// |
522 | /// ``` |
523 | /// use std::ops::Rem; |
524 | /// |
525 | /// #[derive(PartialEq, Debug)] |
526 | /// struct SplitSlice<'a, T> { |
527 | /// slice: &'a [T], |
528 | /// } |
529 | /// |
530 | /// impl<'a, T> Rem<usize> for SplitSlice<'a, T> { |
531 | /// type Output = Self; |
532 | /// |
533 | /// fn rem(self, modulus: usize) -> Self::Output { |
534 | /// let len = self.slice.len(); |
535 | /// let rem = len % modulus; |
536 | /// let start = len - rem; |
537 | /// Self {slice: &self.slice[start..]} |
538 | /// } |
539 | /// } |
540 | /// |
541 | /// // If we were to divide &[0, 1, 2, 3, 4, 5, 6, 7] into slices of size 3, |
542 | /// // the remainder would be &[6, 7]. |
543 | /// assert_eq!(SplitSlice { slice: &[0, 1, 2, 3, 4, 5, 6, 7] } % 3, |
544 | /// SplitSlice { slice: &[6, 7] }); |
545 | /// ``` |
546 | #[lang = "rem" ] |
547 | #[stable (feature = "rust1" , since = "1.0.0" )] |
548 | #[diagnostic::on_unimplemented( |
549 | message = "cannot calculate the remainder of `{Self}` divided by `{Rhs}`" , |
550 | label = "no implementation for `{Self} % {Rhs}`" |
551 | )] |
552 | #[doc (alias = "%" )] |
553 | pub trait Rem<Rhs = Self> { |
554 | /// The resulting type after applying the `%` operator. |
555 | #[stable (feature = "rust1" , since = "1.0.0" )] |
556 | type Output; |
557 | |
558 | /// Performs the `%` operation. |
559 | /// |
560 | /// # Example |
561 | /// |
562 | /// ``` |
563 | /// assert_eq!(12 % 10, 2); |
564 | /// ``` |
565 | #[must_use = "this returns the result of the operation, without modifying the original" ] |
566 | #[rustc_diagnostic_item = "rem" ] |
567 | #[stable (feature = "rust1" , since = "1.0.0" )] |
568 | fn rem(self, rhs: Rhs) -> Self::Output; |
569 | } |
570 | |
571 | macro_rules! rem_impl_integer { |
572 | ($(($($t:ty)*) => $panic:expr),*) => ($($( |
573 | /// This operation satisfies `n % d == n - (n / d) * d`. The |
574 | /// result has the same sign as the left operand. |
575 | /// |
576 | /// # Panics |
577 | /// |
578 | #[doc = $panic] |
579 | #[stable(feature = "rust1" , since = "1.0.0" )] |
580 | impl Rem for $t { |
581 | type Output = $t; |
582 | |
583 | #[inline] |
584 | #[track_caller] |
585 | fn rem(self, other: $t) -> $t { self % other } |
586 | } |
587 | |
588 | forward_ref_binop! { impl Rem, rem for $t, $t } |
589 | )*)*) |
590 | } |
591 | |
592 | rem_impl_integer! { |
593 | (usize u8 u16 u32 u64 u128) => "This operation will panic if `other == 0`." , |
594 | (isize i8 i16 i32 i64 i128) => "This operation will panic if `other == 0` or if `self / other` results in overflow." |
595 | } |
596 | |
597 | macro_rules! rem_impl_float { |
598 | ($($t:ty)*) => ($( |
599 | |
600 | /// The remainder from the division of two floats. |
601 | /// |
602 | /// The remainder has the same sign as the dividend and is computed as: |
603 | /// `x - (x / y).trunc() * y`. |
604 | /// |
605 | /// # Examples |
606 | /// ``` |
607 | /// let x: f32 = 50.50; |
608 | /// let y: f32 = 8.125; |
609 | /// let remainder = x - (x / y).trunc() * y; |
610 | /// |
611 | /// // The answer to both operations is 1.75 |
612 | /// assert_eq!(x % y, remainder); |
613 | /// ``` |
614 | #[stable(feature = "rust1" , since = "1.0.0" )] |
615 | impl Rem for $t { |
616 | type Output = $t; |
617 | |
618 | #[inline] |
619 | fn rem(self, other: $t) -> $t { self % other } |
620 | } |
621 | |
622 | forward_ref_binop! { impl Rem, rem for $t, $t } |
623 | )*) |
624 | } |
625 | |
626 | rem_impl_float! { f16 f32 f64 f128 } |
627 | |
628 | /// The unary negation operator `-`. |
629 | /// |
630 | /// # Examples |
631 | /// |
632 | /// An implementation of `Neg` for `Sign`, which allows the use of `-` to |
633 | /// negate its value. |
634 | /// |
635 | /// ``` |
636 | /// use std::ops::Neg; |
637 | /// |
638 | /// #[derive(Debug, PartialEq)] |
639 | /// enum Sign { |
640 | /// Negative, |
641 | /// Zero, |
642 | /// Positive, |
643 | /// } |
644 | /// |
645 | /// impl Neg for Sign { |
646 | /// type Output = Self; |
647 | /// |
648 | /// fn neg(self) -> Self::Output { |
649 | /// match self { |
650 | /// Sign::Negative => Sign::Positive, |
651 | /// Sign::Zero => Sign::Zero, |
652 | /// Sign::Positive => Sign::Negative, |
653 | /// } |
654 | /// } |
655 | /// } |
656 | /// |
657 | /// // A negative positive is a negative. |
658 | /// assert_eq!(-Sign::Positive, Sign::Negative); |
659 | /// // A double negative is a positive. |
660 | /// assert_eq!(-Sign::Negative, Sign::Positive); |
661 | /// // Zero is its own negation. |
662 | /// assert_eq!(-Sign::Zero, Sign::Zero); |
663 | /// ``` |
664 | #[lang = "neg" ] |
665 | #[stable (feature = "rust1" , since = "1.0.0" )] |
666 | #[doc (alias = "-" )] |
667 | pub trait Neg { |
668 | /// The resulting type after applying the `-` operator. |
669 | #[stable (feature = "rust1" , since = "1.0.0" )] |
670 | type Output; |
671 | |
672 | /// Performs the unary `-` operation. |
673 | /// |
674 | /// # Example |
675 | /// |
676 | /// ``` |
677 | /// let x: i32 = 12; |
678 | /// assert_eq!(-x, -12); |
679 | /// ``` |
680 | #[must_use = "this returns the result of the operation, without modifying the original" ] |
681 | #[rustc_diagnostic_item = "neg" ] |
682 | #[stable (feature = "rust1" , since = "1.0.0" )] |
683 | fn neg(self) -> Self::Output; |
684 | } |
685 | |
686 | macro_rules! neg_impl { |
687 | ($($t:ty)*) => ($( |
688 | #[stable(feature = "rust1" , since = "1.0.0" )] |
689 | impl Neg for $t { |
690 | type Output = $t; |
691 | |
692 | #[inline] |
693 | #[rustc_inherit_overflow_checks] |
694 | fn neg(self) -> $t { -self } |
695 | } |
696 | |
697 | forward_ref_unop! { impl Neg, neg for $t } |
698 | )*) |
699 | } |
700 | |
701 | neg_impl! { isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } |
702 | |
703 | /// The addition assignment operator `+=`. |
704 | /// |
705 | /// # Examples |
706 | /// |
707 | /// This example creates a `Point` struct that implements the `AddAssign` |
708 | /// trait, and then demonstrates add-assigning to a mutable `Point`. |
709 | /// |
710 | /// ``` |
711 | /// use std::ops::AddAssign; |
712 | /// |
713 | /// #[derive(Debug, Copy, Clone, PartialEq)] |
714 | /// struct Point { |
715 | /// x: i32, |
716 | /// y: i32, |
717 | /// } |
718 | /// |
719 | /// impl AddAssign for Point { |
720 | /// fn add_assign(&mut self, other: Self) { |
721 | /// *self = Self { |
722 | /// x: self.x + other.x, |
723 | /// y: self.y + other.y, |
724 | /// }; |
725 | /// } |
726 | /// } |
727 | /// |
728 | /// let mut point = Point { x: 1, y: 0 }; |
729 | /// point += Point { x: 2, y: 3 }; |
730 | /// assert_eq!(point, Point { x: 3, y: 3 }); |
731 | /// ``` |
732 | #[lang = "add_assign" ] |
733 | #[stable (feature = "op_assign_traits" , since = "1.8.0" )] |
734 | #[diagnostic::on_unimplemented( |
735 | message = "cannot add-assign `{Rhs}` to `{Self}`" , |
736 | label = "no implementation for `{Self} += {Rhs}`" |
737 | )] |
738 | #[doc (alias = "+" )] |
739 | #[doc (alias = "+=" )] |
740 | pub trait AddAssign<Rhs = Self> { |
741 | /// Performs the `+=` operation. |
742 | /// |
743 | /// # Example |
744 | /// |
745 | /// ``` |
746 | /// let mut x: u32 = 12; |
747 | /// x += 1; |
748 | /// assert_eq!(x, 13); |
749 | /// ``` |
750 | #[stable (feature = "op_assign_traits" , since = "1.8.0" )] |
751 | fn add_assign(&mut self, rhs: Rhs); |
752 | } |
753 | |
754 | macro_rules! add_assign_impl { |
755 | ($($t:ty)+) => ($( |
756 | #[stable(feature = "op_assign_traits" , since = "1.8.0" )] |
757 | impl AddAssign for $t { |
758 | #[inline] |
759 | #[track_caller] |
760 | #[rustc_inherit_overflow_checks] |
761 | fn add_assign(&mut self, other: $t) { *self += other } |
762 | } |
763 | |
764 | forward_ref_op_assign! { impl AddAssign, add_assign for $t, $t } |
765 | )+) |
766 | } |
767 | |
768 | add_assign_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } |
769 | |
770 | /// The subtraction assignment operator `-=`. |
771 | /// |
772 | /// # Examples |
773 | /// |
774 | /// This example creates a `Point` struct that implements the `SubAssign` |
775 | /// trait, and then demonstrates sub-assigning to a mutable `Point`. |
776 | /// |
777 | /// ``` |
778 | /// use std::ops::SubAssign; |
779 | /// |
780 | /// #[derive(Debug, Copy, Clone, PartialEq)] |
781 | /// struct Point { |
782 | /// x: i32, |
783 | /// y: i32, |
784 | /// } |
785 | /// |
786 | /// impl SubAssign for Point { |
787 | /// fn sub_assign(&mut self, other: Self) { |
788 | /// *self = Self { |
789 | /// x: self.x - other.x, |
790 | /// y: self.y - other.y, |
791 | /// }; |
792 | /// } |
793 | /// } |
794 | /// |
795 | /// let mut point = Point { x: 3, y: 3 }; |
796 | /// point -= Point { x: 2, y: 3 }; |
797 | /// assert_eq!(point, Point {x: 1, y: 0}); |
798 | /// ``` |
799 | #[lang = "sub_assign" ] |
800 | #[stable (feature = "op_assign_traits" , since = "1.8.0" )] |
801 | #[diagnostic::on_unimplemented( |
802 | message = "cannot subtract-assign `{Rhs}` from `{Self}`" , |
803 | label = "no implementation for `{Self} -= {Rhs}`" |
804 | )] |
805 | #[doc (alias = "-" )] |
806 | #[doc (alias = "-=" )] |
807 | pub trait SubAssign<Rhs = Self> { |
808 | /// Performs the `-=` operation. |
809 | /// |
810 | /// # Example |
811 | /// |
812 | /// ``` |
813 | /// let mut x: u32 = 12; |
814 | /// x -= 1; |
815 | /// assert_eq!(x, 11); |
816 | /// ``` |
817 | #[stable (feature = "op_assign_traits" , since = "1.8.0" )] |
818 | fn sub_assign(&mut self, rhs: Rhs); |
819 | } |
820 | |
821 | macro_rules! sub_assign_impl { |
822 | ($($t:ty)+) => ($( |
823 | #[stable(feature = "op_assign_traits" , since = "1.8.0" )] |
824 | impl SubAssign for $t { |
825 | #[inline] |
826 | #[track_caller] |
827 | #[rustc_inherit_overflow_checks] |
828 | fn sub_assign(&mut self, other: $t) { *self -= other } |
829 | } |
830 | |
831 | forward_ref_op_assign! { impl SubAssign, sub_assign for $t, $t } |
832 | )+) |
833 | } |
834 | |
835 | sub_assign_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } |
836 | |
837 | /// The multiplication assignment operator `*=`. |
838 | /// |
839 | /// # Examples |
840 | /// |
841 | /// ``` |
842 | /// use std::ops::MulAssign; |
843 | /// |
844 | /// #[derive(Debug, PartialEq)] |
845 | /// struct Frequency { hertz: f64 } |
846 | /// |
847 | /// impl MulAssign<f64> for Frequency { |
848 | /// fn mul_assign(&mut self, rhs: f64) { |
849 | /// self.hertz *= rhs; |
850 | /// } |
851 | /// } |
852 | /// |
853 | /// let mut frequency = Frequency { hertz: 50.0 }; |
854 | /// frequency *= 4.0; |
855 | /// assert_eq!(Frequency { hertz: 200.0 }, frequency); |
856 | /// ``` |
857 | #[lang = "mul_assign" ] |
858 | #[stable (feature = "op_assign_traits" , since = "1.8.0" )] |
859 | #[diagnostic::on_unimplemented( |
860 | message = "cannot multiply-assign `{Self}` by `{Rhs}`" , |
861 | label = "no implementation for `{Self} *= {Rhs}`" |
862 | )] |
863 | #[doc (alias = "*" )] |
864 | #[doc (alias = "*=" )] |
865 | pub trait MulAssign<Rhs = Self> { |
866 | /// Performs the `*=` operation. |
867 | /// |
868 | /// # Example |
869 | /// |
870 | /// ``` |
871 | /// let mut x: u32 = 12; |
872 | /// x *= 2; |
873 | /// assert_eq!(x, 24); |
874 | /// ``` |
875 | #[stable (feature = "op_assign_traits" , since = "1.8.0" )] |
876 | fn mul_assign(&mut self, rhs: Rhs); |
877 | } |
878 | |
879 | macro_rules! mul_assign_impl { |
880 | ($($t:ty)+) => ($( |
881 | #[stable(feature = "op_assign_traits" , since = "1.8.0" )] |
882 | impl MulAssign for $t { |
883 | #[inline] |
884 | #[track_caller] |
885 | #[rustc_inherit_overflow_checks] |
886 | fn mul_assign(&mut self, other: $t) { *self *= other } |
887 | } |
888 | |
889 | forward_ref_op_assign! { impl MulAssign, mul_assign for $t, $t } |
890 | )+) |
891 | } |
892 | |
893 | mul_assign_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } |
894 | |
895 | /// The division assignment operator `/=`. |
896 | /// |
897 | /// # Examples |
898 | /// |
899 | /// ``` |
900 | /// use std::ops::DivAssign; |
901 | /// |
902 | /// #[derive(Debug, PartialEq)] |
903 | /// struct Frequency { hertz: f64 } |
904 | /// |
905 | /// impl DivAssign<f64> for Frequency { |
906 | /// fn div_assign(&mut self, rhs: f64) { |
907 | /// self.hertz /= rhs; |
908 | /// } |
909 | /// } |
910 | /// |
911 | /// let mut frequency = Frequency { hertz: 200.0 }; |
912 | /// frequency /= 4.0; |
913 | /// assert_eq!(Frequency { hertz: 50.0 }, frequency); |
914 | /// ``` |
915 | #[lang = "div_assign" ] |
916 | #[stable (feature = "op_assign_traits" , since = "1.8.0" )] |
917 | #[diagnostic::on_unimplemented( |
918 | message = "cannot divide-assign `{Self}` by `{Rhs}`" , |
919 | label = "no implementation for `{Self} /= {Rhs}`" |
920 | )] |
921 | #[doc (alias = "/" )] |
922 | #[doc (alias = "/=" )] |
923 | pub trait DivAssign<Rhs = Self> { |
924 | /// Performs the `/=` operation. |
925 | /// |
926 | /// # Example |
927 | /// |
928 | /// ``` |
929 | /// let mut x: u32 = 12; |
930 | /// x /= 2; |
931 | /// assert_eq!(x, 6); |
932 | /// ``` |
933 | #[stable (feature = "op_assign_traits" , since = "1.8.0" )] |
934 | fn div_assign(&mut self, rhs: Rhs); |
935 | } |
936 | |
937 | macro_rules! div_assign_impl { |
938 | ($($t:ty)+) => ($( |
939 | #[stable(feature = "op_assign_traits" , since = "1.8.0" )] |
940 | impl DivAssign for $t { |
941 | #[inline] |
942 | #[track_caller] |
943 | fn div_assign(&mut self, other: $t) { *self /= other } |
944 | } |
945 | |
946 | forward_ref_op_assign! { impl DivAssign, div_assign for $t, $t } |
947 | )+) |
948 | } |
949 | |
950 | div_assign_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } |
951 | |
952 | /// The remainder assignment operator `%=`. |
953 | /// |
954 | /// # Examples |
955 | /// |
956 | /// ``` |
957 | /// use std::ops::RemAssign; |
958 | /// |
959 | /// struct CookieJar { cookies: u32 } |
960 | /// |
961 | /// impl RemAssign<u32> for CookieJar { |
962 | /// fn rem_assign(&mut self, piles: u32) { |
963 | /// self.cookies %= piles; |
964 | /// } |
965 | /// } |
966 | /// |
967 | /// let mut jar = CookieJar { cookies: 31 }; |
968 | /// let piles = 4; |
969 | /// |
970 | /// println!("Splitting up {} cookies into {} even piles!" , jar.cookies, piles); |
971 | /// |
972 | /// jar %= piles; |
973 | /// |
974 | /// println!("{} cookies remain in the cookie jar!" , jar.cookies); |
975 | /// ``` |
976 | #[lang = "rem_assign" ] |
977 | #[stable (feature = "op_assign_traits" , since = "1.8.0" )] |
978 | #[diagnostic::on_unimplemented( |
979 | message = "cannot calculate and assign the remainder of `{Self}` divided by `{Rhs}`" , |
980 | label = "no implementation for `{Self} %= {Rhs}`" |
981 | )] |
982 | #[doc (alias = "%" )] |
983 | #[doc (alias = "%=" )] |
984 | pub trait RemAssign<Rhs = Self> { |
985 | /// Performs the `%=` operation. |
986 | /// |
987 | /// # Example |
988 | /// |
989 | /// ``` |
990 | /// let mut x: u32 = 12; |
991 | /// x %= 10; |
992 | /// assert_eq!(x, 2); |
993 | /// ``` |
994 | #[stable (feature = "op_assign_traits" , since = "1.8.0" )] |
995 | fn rem_assign(&mut self, rhs: Rhs); |
996 | } |
997 | |
998 | macro_rules! rem_assign_impl { |
999 | ($($t:ty)+) => ($( |
1000 | #[stable(feature = "op_assign_traits" , since = "1.8.0" )] |
1001 | impl RemAssign for $t { |
1002 | #[inline] |
1003 | #[track_caller] |
1004 | fn rem_assign(&mut self, other: $t) { *self %= other } |
1005 | } |
1006 | |
1007 | forward_ref_op_assign! { impl RemAssign, rem_assign for $t, $t } |
1008 | )+) |
1009 | } |
1010 | |
1011 | rem_assign_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } |
1012 | |