core/num/int_macros.rs
1macro_rules! int_impl {
2 (
3 Self = $SelfT:ty,
4 ActualT = $ActualT:ident,
5 UnsignedT = $UnsignedT:ty,
6
7 // These are all for use *only* in doc comments.
8 // As such, they're all passed as literals -- passing them as a string
9 // literal is fine if they need to be multiple code tokens.
10 // In non-comments, use the associated constants rather than these.
11 BITS = $BITS:literal,
12 BITS_MINUS_ONE = $BITS_MINUS_ONE:literal,
13 Min = $Min:literal,
14 Max = $Max:literal,
15 rot = $rot:literal,
16 rot_op = $rot_op:literal,
17 rot_result = $rot_result:literal,
18 swap_op = $swap_op:literal,
19 swapped = $swapped:literal,
20 reversed = $reversed:literal,
21 le_bytes = $le_bytes:literal,
22 be_bytes = $be_bytes:literal,
23 to_xe_bytes_doc = $to_xe_bytes_doc:expr,
24 from_xe_bytes_doc = $from_xe_bytes_doc:expr,
25 bound_condition = $bound_condition:literal,
26 ) => {
27 /// The smallest value that can be represented by this integer type
28 #[doc = concat!("(−2<sup>", $BITS_MINUS_ONE, "</sup>", $bound_condition, ").")]
29 ///
30 /// # Examples
31 ///
32 /// ```
33 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN, ", stringify!($Min), ");")]
34 /// ```
35 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
36 pub const MIN: Self = !Self::MAX;
37
38 /// The largest value that can be represented by this integer type
39 #[doc = concat!("(2<sup>", $BITS_MINUS_ONE, "</sup> − 1", $bound_condition, ").")]
40 ///
41 /// # Examples
42 ///
43 /// ```
44 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX, ", stringify!($Max), ");")]
45 /// ```
46 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
47 pub const MAX: Self = (<$UnsignedT>::MAX >> 1) as Self;
48
49 /// The size of this integer type in bits.
50 ///
51 /// # Examples
52 ///
53 /// ```
54 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::BITS, ", stringify!($BITS), ");")]
55 /// ```
56 #[stable(feature = "int_bits_const", since = "1.53.0")]
57 #[cfg(not(feature = "ferrocene_certified"))]
58 pub const BITS: u32 = <$UnsignedT>::BITS;
59
60 /// Returns the number of ones in the binary representation of `self`.
61 ///
62 /// # Examples
63 ///
64 /// ```
65 #[doc = concat!("let n = 0b100_0000", stringify!($SelfT), ";")]
66 ///
67 /// assert_eq!(n.count_ones(), 1);
68 /// ```
69 ///
70 #[stable(feature = "rust1", since = "1.0.0")]
71 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
72 #[doc(alias = "popcount")]
73 #[doc(alias = "popcnt")]
74 #[must_use = "this returns the result of the operation, \
75 without modifying the original"]
76 #[inline(always)]
77 #[cfg(not(feature = "ferrocene_certified"))]
78 pub const fn count_ones(self) -> u32 { (self as $UnsignedT).count_ones() }
79
80 /// Returns the number of zeros in the binary representation of `self`.
81 ///
82 /// # Examples
83 ///
84 /// ```
85 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.count_zeros(), 1);")]
86 /// ```
87 #[stable(feature = "rust1", since = "1.0.0")]
88 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
89 #[must_use = "this returns the result of the operation, \
90 without modifying the original"]
91 #[inline(always)]
92 #[cfg(not(feature = "ferrocene_certified"))]
93 pub const fn count_zeros(self) -> u32 {
94 (!self).count_ones()
95 }
96
97 /// Returns the number of leading zeros in the binary representation of `self`.
98 ///
99 /// Depending on what you're doing with the value, you might also be interested in the
100 /// [`ilog2`] function which returns a consistent number, even if the type widens.
101 ///
102 /// # Examples
103 ///
104 /// ```
105 #[doc = concat!("let n = -1", stringify!($SelfT), ";")]
106 ///
107 /// assert_eq!(n.leading_zeros(), 0);
108 /// ```
109 #[doc = concat!("[`ilog2`]: ", stringify!($SelfT), "::ilog2")]
110 #[stable(feature = "rust1", since = "1.0.0")]
111 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
112 #[must_use = "this returns the result of the operation, \
113 without modifying the original"]
114 #[inline(always)]
115 #[cfg(not(feature = "ferrocene_certified"))]
116 pub const fn leading_zeros(self) -> u32 {
117 (self as $UnsignedT).leading_zeros()
118 }
119
120 /// Returns the number of trailing zeros in the binary representation of `self`.
121 ///
122 /// # Examples
123 ///
124 /// ```
125 #[doc = concat!("let n = -4", stringify!($SelfT), ";")]
126 ///
127 /// assert_eq!(n.trailing_zeros(), 2);
128 /// ```
129 #[stable(feature = "rust1", since = "1.0.0")]
130 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
131 #[must_use = "this returns the result of the operation, \
132 without modifying the original"]
133 #[inline(always)]
134 #[cfg(not(feature = "ferrocene_certified"))]
135 pub const fn trailing_zeros(self) -> u32 {
136 (self as $UnsignedT).trailing_zeros()
137 }
138
139 /// Returns the number of leading ones in the binary representation of `self`.
140 ///
141 /// # Examples
142 ///
143 /// ```
144 #[doc = concat!("let n = -1", stringify!($SelfT), ";")]
145 ///
146 #[doc = concat!("assert_eq!(n.leading_ones(), ", stringify!($BITS), ");")]
147 /// ```
148 #[stable(feature = "leading_trailing_ones", since = "1.46.0")]
149 #[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")]
150 #[must_use = "this returns the result of the operation, \
151 without modifying the original"]
152 #[inline(always)]
153 #[cfg(not(feature = "ferrocene_certified"))]
154 pub const fn leading_ones(self) -> u32 {
155 (self as $UnsignedT).leading_ones()
156 }
157
158 /// Returns the number of trailing ones in the binary representation of `self`.
159 ///
160 /// # Examples
161 ///
162 /// ```
163 #[doc = concat!("let n = 3", stringify!($SelfT), ";")]
164 ///
165 /// assert_eq!(n.trailing_ones(), 2);
166 /// ```
167 #[stable(feature = "leading_trailing_ones", since = "1.46.0")]
168 #[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")]
169 #[must_use = "this returns the result of the operation, \
170 without modifying the original"]
171 #[inline(always)]
172 #[cfg(not(feature = "ferrocene_certified"))]
173 pub const fn trailing_ones(self) -> u32 {
174 (self as $UnsignedT).trailing_ones()
175 }
176
177 /// Returns `self` with only the most significant bit set, or `0` if
178 /// the input is `0`.
179 ///
180 /// # Examples
181 ///
182 /// ```
183 /// #![feature(isolate_most_least_significant_one)]
184 ///
185 #[doc = concat!("let n: ", stringify!($SelfT), " = 0b_01100100;")]
186 ///
187 /// assert_eq!(n.isolate_most_significant_one(), 0b_01000000);
188 #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".isolate_most_significant_one(), 0);")]
189 /// ```
190 #[unstable(feature = "isolate_most_least_significant_one", issue = "136909")]
191 #[must_use = "this returns the result of the operation, \
192 without modifying the original"]
193 #[inline(always)]
194 #[cfg(not(feature = "ferrocene_certified"))]
195 pub const fn isolate_most_significant_one(self) -> Self {
196 self & (((1 as $SelfT) << (<$SelfT>::BITS - 1)).wrapping_shr(self.leading_zeros()))
197 }
198
199 /// Returns `self` with only the least significant bit set, or `0` if
200 /// the input is `0`.
201 ///
202 /// # Examples
203 ///
204 /// ```
205 /// #![feature(isolate_most_least_significant_one)]
206 ///
207 #[doc = concat!("let n: ", stringify!($SelfT), " = 0b_01100100;")]
208 ///
209 /// assert_eq!(n.isolate_least_significant_one(), 0b_00000100);
210 #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".isolate_least_significant_one(), 0);")]
211 /// ```
212 #[unstable(feature = "isolate_most_least_significant_one", issue = "136909")]
213 #[must_use = "this returns the result of the operation, \
214 without modifying the original"]
215 #[inline(always)]
216 #[cfg(not(feature = "ferrocene_certified"))]
217 pub const fn isolate_least_significant_one(self) -> Self {
218 self & self.wrapping_neg()
219 }
220
221 /// Returns the bit pattern of `self` reinterpreted as an unsigned integer of the same size.
222 ///
223 /// This produces the same result as an `as` cast, but ensures that the bit-width remains
224 /// the same.
225 ///
226 /// # Examples
227 ///
228 /// ```
229 #[doc = concat!("let n = -1", stringify!($SelfT), ";")]
230 ///
231 #[doc = concat!("assert_eq!(n.cast_unsigned(), ", stringify!($UnsignedT), "::MAX);")]
232 /// ```
233 #[stable(feature = "integer_sign_cast", since = "1.87.0")]
234 #[rustc_const_stable(feature = "integer_sign_cast", since = "1.87.0")]
235 #[must_use = "this returns the result of the operation, \
236 without modifying the original"]
237 #[inline(always)]
238 #[cfg(not(feature = "ferrocene_certified"))]
239 pub const fn cast_unsigned(self) -> $UnsignedT {
240 self as $UnsignedT
241 }
242
243 /// Shifts the bits to the left by a specified amount, `n`,
244 /// wrapping the truncated bits to the end of the resulting integer.
245 ///
246 /// Please note this isn't the same operation as the `<<` shifting operator!
247 ///
248 /// # Examples
249 ///
250 /// ```
251 #[doc = concat!("let n = ", $rot_op, stringify!($SelfT), ";")]
252 #[doc = concat!("let m = ", $rot_result, ";")]
253 ///
254 #[doc = concat!("assert_eq!(n.rotate_left(", $rot, "), m);")]
255 /// ```
256 #[stable(feature = "rust1", since = "1.0.0")]
257 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
258 #[must_use = "this returns the result of the operation, \
259 without modifying the original"]
260 #[inline(always)]
261 #[cfg(not(feature = "ferrocene_certified"))]
262 pub const fn rotate_left(self, n: u32) -> Self {
263 (self as $UnsignedT).rotate_left(n) as Self
264 }
265
266 /// Shifts the bits to the right by a specified amount, `n`,
267 /// wrapping the truncated bits to the beginning of the resulting
268 /// integer.
269 ///
270 /// Please note this isn't the same operation as the `>>` shifting operator!
271 ///
272 /// # Examples
273 ///
274 /// ```
275 #[doc = concat!("let n = ", $rot_result, stringify!($SelfT), ";")]
276 #[doc = concat!("let m = ", $rot_op, ";")]
277 ///
278 #[doc = concat!("assert_eq!(n.rotate_right(", $rot, "), m);")]
279 /// ```
280 #[stable(feature = "rust1", since = "1.0.0")]
281 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
282 #[must_use = "this returns the result of the operation, \
283 without modifying the original"]
284 #[inline(always)]
285 #[cfg(not(feature = "ferrocene_certified"))]
286 pub const fn rotate_right(self, n: u32) -> Self {
287 (self as $UnsignedT).rotate_right(n) as Self
288 }
289
290 /// Reverses the byte order of the integer.
291 ///
292 /// # Examples
293 ///
294 /// ```
295 #[doc = concat!("let n = ", $swap_op, stringify!($SelfT), ";")]
296 ///
297 /// let m = n.swap_bytes();
298 ///
299 #[doc = concat!("assert_eq!(m, ", $swapped, ");")]
300 /// ```
301 #[stable(feature = "rust1", since = "1.0.0")]
302 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
303 #[must_use = "this returns the result of the operation, \
304 without modifying the original"]
305 #[inline(always)]
306 #[cfg(not(feature = "ferrocene_certified"))]
307 pub const fn swap_bytes(self) -> Self {
308 (self as $UnsignedT).swap_bytes() as Self
309 }
310
311 /// Reverses the order of bits in the integer. The least significant bit becomes the most significant bit,
312 /// second least-significant bit becomes second most-significant bit, etc.
313 ///
314 /// # Examples
315 ///
316 /// ```
317 #[doc = concat!("let n = ", $swap_op, stringify!($SelfT), ";")]
318 /// let m = n.reverse_bits();
319 ///
320 #[doc = concat!("assert_eq!(m, ", $reversed, ");")]
321 #[doc = concat!("assert_eq!(0, 0", stringify!($SelfT), ".reverse_bits());")]
322 /// ```
323 #[stable(feature = "reverse_bits", since = "1.37.0")]
324 #[rustc_const_stable(feature = "reverse_bits", since = "1.37.0")]
325 #[must_use = "this returns the result of the operation, \
326 without modifying the original"]
327 #[inline(always)]
328 #[cfg(not(feature = "ferrocene_certified"))]
329 pub const fn reverse_bits(self) -> Self {
330 (self as $UnsignedT).reverse_bits() as Self
331 }
332
333 /// Converts an integer from big endian to the target's endianness.
334 ///
335 /// On big endian this is a no-op. On little endian the bytes are swapped.
336 ///
337 /// # Examples
338 ///
339 /// ```
340 #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
341 ///
342 /// if cfg!(target_endian = "big") {
343 #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_be(n), n)")]
344 /// } else {
345 #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_be(n), n.swap_bytes())")]
346 /// }
347 /// ```
348 #[stable(feature = "rust1", since = "1.0.0")]
349 #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
350 #[must_use]
351 #[inline]
352 #[cfg(not(feature = "ferrocene_certified"))]
353 pub const fn from_be(x: Self) -> Self {
354 #[cfg(target_endian = "big")]
355 {
356 x
357 }
358 #[cfg(not(target_endian = "big"))]
359 {
360 x.swap_bytes()
361 }
362 }
363
364 /// Converts an integer from little endian to the target's endianness.
365 ///
366 /// On little endian this is a no-op. On big endian the bytes are swapped.
367 ///
368 /// # Examples
369 ///
370 /// ```
371 #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
372 ///
373 /// if cfg!(target_endian = "little") {
374 #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_le(n), n)")]
375 /// } else {
376 #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_le(n), n.swap_bytes())")]
377 /// }
378 /// ```
379 #[stable(feature = "rust1", since = "1.0.0")]
380 #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
381 #[must_use]
382 #[inline]
383 #[cfg(not(feature = "ferrocene_certified"))]
384 pub const fn from_le(x: Self) -> Self {
385 #[cfg(target_endian = "little")]
386 {
387 x
388 }
389 #[cfg(not(target_endian = "little"))]
390 {
391 x.swap_bytes()
392 }
393 }
394
395 /// Converts `self` to big endian from the target's endianness.
396 ///
397 /// On big endian this is a no-op. On little endian the bytes are swapped.
398 ///
399 /// # Examples
400 ///
401 /// ```
402 #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
403 ///
404 /// if cfg!(target_endian = "big") {
405 /// assert_eq!(n.to_be(), n)
406 /// } else {
407 /// assert_eq!(n.to_be(), n.swap_bytes())
408 /// }
409 /// ```
410 #[stable(feature = "rust1", since = "1.0.0")]
411 #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
412 #[must_use = "this returns the result of the operation, \
413 without modifying the original"]
414 #[inline]
415 #[cfg(not(feature = "ferrocene_certified"))]
416 pub const fn to_be(self) -> Self { // or not to be?
417 #[cfg(target_endian = "big")]
418 {
419 self
420 }
421 #[cfg(not(target_endian = "big"))]
422 {
423 self.swap_bytes()
424 }
425 }
426
427 /// Converts `self` to little endian from the target's endianness.
428 ///
429 /// On little endian this is a no-op. On big endian the bytes are swapped.
430 ///
431 /// # Examples
432 ///
433 /// ```
434 #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
435 ///
436 /// if cfg!(target_endian = "little") {
437 /// assert_eq!(n.to_le(), n)
438 /// } else {
439 /// assert_eq!(n.to_le(), n.swap_bytes())
440 /// }
441 /// ```
442 #[stable(feature = "rust1", since = "1.0.0")]
443 #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
444 #[must_use = "this returns the result of the operation, \
445 without modifying the original"]
446 #[inline]
447 #[cfg(not(feature = "ferrocene_certified"))]
448 pub const fn to_le(self) -> Self {
449 #[cfg(target_endian = "little")]
450 {
451 self
452 }
453 #[cfg(not(target_endian = "little"))]
454 {
455 self.swap_bytes()
456 }
457 }
458
459 /// Checked integer addition. Computes `self + rhs`, returning `None`
460 /// if overflow occurred.
461 ///
462 /// # Examples
463 ///
464 /// ```
465 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add(1), Some(", stringify!($SelfT), "::MAX - 1));")]
466 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add(3), None);")]
467 /// ```
468 #[stable(feature = "rust1", since = "1.0.0")]
469 #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
470 #[must_use = "this returns the result of the operation, \
471 without modifying the original"]
472 #[inline]
473 #[cfg(not(feature = "ferrocene_certified"))]
474 pub const fn checked_add(self, rhs: Self) -> Option<Self> {
475 let (a, b) = self.overflowing_add(rhs);
476 if intrinsics::unlikely(b) { None } else { Some(a) }
477 }
478
479 /// Strict integer addition. Computes `self + rhs`, panicking
480 /// if overflow occurred.
481 ///
482 /// # Panics
483 ///
484 /// ## Overflow behavior
485 ///
486 /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
487 ///
488 /// # Examples
489 ///
490 /// ```
491 /// #![feature(strict_overflow_ops)]
492 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).strict_add(1), ", stringify!($SelfT), "::MAX - 1);")]
493 /// ```
494 ///
495 /// The following panics because of overflow:
496 ///
497 /// ```should_panic
498 /// #![feature(strict_overflow_ops)]
499 #[doc = concat!("let _ = (", stringify!($SelfT), "::MAX - 2).strict_add(3);")]
500 /// ```
501 #[unstable(feature = "strict_overflow_ops", issue = "118260")]
502 #[must_use = "this returns the result of the operation, \
503 without modifying the original"]
504 #[inline]
505 #[track_caller]
506 #[cfg(not(feature = "ferrocene_certified"))]
507 pub const fn strict_add(self, rhs: Self) -> Self {
508 let (a, b) = self.overflowing_add(rhs);
509 if b { overflow_panic::add() } else { a }
510 }
511
512 /// Unchecked integer addition. Computes `self + rhs`, assuming overflow
513 /// cannot occur.
514 ///
515 /// Calling `x.unchecked_add(y)` is semantically equivalent to calling
516 /// `x.`[`checked_add`]`(y).`[`unwrap_unchecked`]`()`.
517 ///
518 /// If you're just trying to avoid the panic in debug mode, then **do not**
519 /// use this. Instead, you're looking for [`wrapping_add`].
520 ///
521 /// # Safety
522 ///
523 /// This results in undefined behavior when
524 #[doc = concat!("`self + rhs > ", stringify!($SelfT), "::MAX` or `self + rhs < ", stringify!($SelfT), "::MIN`,")]
525 /// i.e. when [`checked_add`] would return `None`.
526 ///
527 /// [`unwrap_unchecked`]: option/enum.Option.html#method.unwrap_unchecked
528 #[doc = concat!("[`checked_add`]: ", stringify!($SelfT), "::checked_add")]
529 #[doc = concat!("[`wrapping_add`]: ", stringify!($SelfT), "::wrapping_add")]
530 #[stable(feature = "unchecked_math", since = "1.79.0")]
531 #[rustc_const_stable(feature = "unchecked_math", since = "1.79.0")]
532 #[must_use = "this returns the result of the operation, \
533 without modifying the original"]
534 #[inline(always)]
535 #[track_caller]
536 #[cfg(not(feature = "ferrocene_certified"))]
537 pub const unsafe fn unchecked_add(self, rhs: Self) -> Self {
538 assert_unsafe_precondition!(
539 check_language_ub,
540 concat!(stringify!($SelfT), "::unchecked_add cannot overflow"),
541 (
542 lhs: $SelfT = self,
543 rhs: $SelfT = rhs,
544 ) => !lhs.overflowing_add(rhs).1,
545 );
546
547 // SAFETY: this is guaranteed to be safe by the caller.
548 unsafe {
549 intrinsics::unchecked_add(self, rhs)
550 }
551 }
552
553 /// Checked addition with an unsigned integer. Computes `self + rhs`,
554 /// returning `None` if overflow occurred.
555 ///
556 /// # Examples
557 ///
558 /// ```
559 #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_add_unsigned(2), Some(3));")]
560 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add_unsigned(3), None);")]
561 /// ```
562 #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
563 #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
564 #[must_use = "this returns the result of the operation, \
565 without modifying the original"]
566 #[inline]
567 #[cfg(not(feature = "ferrocene_certified"))]
568 pub const fn checked_add_unsigned(self, rhs: $UnsignedT) -> Option<Self> {
569 let (a, b) = self.overflowing_add_unsigned(rhs);
570 if intrinsics::unlikely(b) { None } else { Some(a) }
571 }
572
573 /// Strict addition with an unsigned integer. Computes `self + rhs`,
574 /// panicking if overflow occurred.
575 ///
576 /// # Panics
577 ///
578 /// ## Overflow behavior
579 ///
580 /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
581 ///
582 /// # Examples
583 ///
584 /// ```
585 /// #![feature(strict_overflow_ops)]
586 #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".strict_add_unsigned(2), 3);")]
587 /// ```
588 ///
589 /// The following panics because of overflow:
590 ///
591 /// ```should_panic
592 /// #![feature(strict_overflow_ops)]
593 #[doc = concat!("let _ = (", stringify!($SelfT), "::MAX - 2).strict_add_unsigned(3);")]
594 /// ```
595 #[unstable(feature = "strict_overflow_ops", issue = "118260")]
596 #[must_use = "this returns the result of the operation, \
597 without modifying the original"]
598 #[inline]
599 #[track_caller]
600 #[cfg(not(feature = "ferrocene_certified"))]
601 pub const fn strict_add_unsigned(self, rhs: $UnsignedT) -> Self {
602 let (a, b) = self.overflowing_add_unsigned(rhs);
603 if b { overflow_panic::add() } else { a }
604 }
605
606 /// Checked integer subtraction. Computes `self - rhs`, returning `None` if
607 /// overflow occurred.
608 ///
609 /// # Examples
610 ///
611 /// ```
612 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).checked_sub(1), Some(", stringify!($SelfT), "::MIN + 1));")]
613 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).checked_sub(3), None);")]
614 /// ```
615 #[stable(feature = "rust1", since = "1.0.0")]
616 #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
617 #[must_use = "this returns the result of the operation, \
618 without modifying the original"]
619 #[inline]
620 #[cfg(not(feature = "ferrocene_certified"))]
621 pub const fn checked_sub(self, rhs: Self) -> Option<Self> {
622 let (a, b) = self.overflowing_sub(rhs);
623 if intrinsics::unlikely(b) { None } else { Some(a) }
624 }
625
626 /// Strict integer subtraction. Computes `self - rhs`, panicking if
627 /// overflow occurred.
628 ///
629 /// # Panics
630 ///
631 /// ## Overflow behavior
632 ///
633 /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
634 ///
635 /// # Examples
636 ///
637 /// ```
638 /// #![feature(strict_overflow_ops)]
639 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).strict_sub(1), ", stringify!($SelfT), "::MIN + 1);")]
640 /// ```
641 ///
642 /// The following panics because of overflow:
643 ///
644 /// ```should_panic
645 /// #![feature(strict_overflow_ops)]
646 #[doc = concat!("let _ = (", stringify!($SelfT), "::MIN + 2).strict_sub(3);")]
647 /// ```
648 #[unstable(feature = "strict_overflow_ops", issue = "118260")]
649 #[must_use = "this returns the result of the operation, \
650 without modifying the original"]
651 #[inline]
652 #[track_caller]
653 #[cfg(not(feature = "ferrocene_certified"))]
654 pub const fn strict_sub(self, rhs: Self) -> Self {
655 let (a, b) = self.overflowing_sub(rhs);
656 if b { overflow_panic::sub() } else { a }
657 }
658
659 /// Unchecked integer subtraction. Computes `self - rhs`, assuming overflow
660 /// cannot occur.
661 ///
662 /// Calling `x.unchecked_sub(y)` is semantically equivalent to calling
663 /// `x.`[`checked_sub`]`(y).`[`unwrap_unchecked`]`()`.
664 ///
665 /// If you're just trying to avoid the panic in debug mode, then **do not**
666 /// use this. Instead, you're looking for [`wrapping_sub`].
667 ///
668 /// # Safety
669 ///
670 /// This results in undefined behavior when
671 #[doc = concat!("`self - rhs > ", stringify!($SelfT), "::MAX` or `self - rhs < ", stringify!($SelfT), "::MIN`,")]
672 /// i.e. when [`checked_sub`] would return `None`.
673 ///
674 /// [`unwrap_unchecked`]: option/enum.Option.html#method.unwrap_unchecked
675 #[doc = concat!("[`checked_sub`]: ", stringify!($SelfT), "::checked_sub")]
676 #[doc = concat!("[`wrapping_sub`]: ", stringify!($SelfT), "::wrapping_sub")]
677 #[stable(feature = "unchecked_math", since = "1.79.0")]
678 #[rustc_const_stable(feature = "unchecked_math", since = "1.79.0")]
679 #[must_use = "this returns the result of the operation, \
680 without modifying the original"]
681 #[inline(always)]
682 #[track_caller]
683 #[cfg(not(feature = "ferrocene_certified"))]
684 pub const unsafe fn unchecked_sub(self, rhs: Self) -> Self {
685 assert_unsafe_precondition!(
686 check_language_ub,
687 concat!(stringify!($SelfT), "::unchecked_sub cannot overflow"),
688 (
689 lhs: $SelfT = self,
690 rhs: $SelfT = rhs,
691 ) => !lhs.overflowing_sub(rhs).1,
692 );
693
694 // SAFETY: this is guaranteed to be safe by the caller.
695 unsafe {
696 intrinsics::unchecked_sub(self, rhs)
697 }
698 }
699
700 /// Checked subtraction with an unsigned integer. Computes `self - rhs`,
701 /// returning `None` if overflow occurred.
702 ///
703 /// # Examples
704 ///
705 /// ```
706 #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_sub_unsigned(2), Some(-1));")]
707 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).checked_sub_unsigned(3), None);")]
708 /// ```
709 #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
710 #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
711 #[must_use = "this returns the result of the operation, \
712 without modifying the original"]
713 #[inline]
714 #[cfg(not(feature = "ferrocene_certified"))]
715 pub const fn checked_sub_unsigned(self, rhs: $UnsignedT) -> Option<Self> {
716 let (a, b) = self.overflowing_sub_unsigned(rhs);
717 if intrinsics::unlikely(b) { None } else { Some(a) }
718 }
719
720 /// Strict subtraction with an unsigned integer. Computes `self - rhs`,
721 /// panicking if overflow occurred.
722 ///
723 /// # Panics
724 ///
725 /// ## Overflow behavior
726 ///
727 /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
728 ///
729 /// # Examples
730 ///
731 /// ```
732 /// #![feature(strict_overflow_ops)]
733 #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".strict_sub_unsigned(2), -1);")]
734 /// ```
735 ///
736 /// The following panics because of overflow:
737 ///
738 /// ```should_panic
739 /// #![feature(strict_overflow_ops)]
740 #[doc = concat!("let _ = (", stringify!($SelfT), "::MIN + 2).strict_sub_unsigned(3);")]
741 /// ```
742 #[unstable(feature = "strict_overflow_ops", issue = "118260")]
743 #[must_use = "this returns the result of the operation, \
744 without modifying the original"]
745 #[inline]
746 #[track_caller]
747 #[cfg(not(feature = "ferrocene_certified"))]
748 pub const fn strict_sub_unsigned(self, rhs: $UnsignedT) -> Self {
749 let (a, b) = self.overflowing_sub_unsigned(rhs);
750 if b { overflow_panic::sub() } else { a }
751 }
752
753 /// Checked integer multiplication. Computes `self * rhs`, returning `None` if
754 /// overflow occurred.
755 ///
756 /// # Examples
757 ///
758 /// ```
759 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_mul(1), Some(", stringify!($SelfT), "::MAX));")]
760 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_mul(2), None);")]
761 /// ```
762 #[stable(feature = "rust1", since = "1.0.0")]
763 #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
764 #[must_use = "this returns the result of the operation, \
765 without modifying the original"]
766 #[inline]
767 #[cfg(not(feature = "ferrocene_certified"))]
768 pub const fn checked_mul(self, rhs: Self) -> Option<Self> {
769 let (a, b) = self.overflowing_mul(rhs);
770 if intrinsics::unlikely(b) { None } else { Some(a) }
771 }
772
773 /// Strict integer multiplication. Computes `self * rhs`, panicking if
774 /// overflow occurred.
775 ///
776 /// # Panics
777 ///
778 /// ## Overflow behavior
779 ///
780 /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
781 ///
782 /// # Examples
783 ///
784 /// ```
785 /// #![feature(strict_overflow_ops)]
786 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.strict_mul(1), ", stringify!($SelfT), "::MAX);")]
787 /// ```
788 ///
789 /// The following panics because of overflow:
790 ///
791 /// ``` should_panic
792 /// #![feature(strict_overflow_ops)]
793 #[doc = concat!("let _ = ", stringify!($SelfT), "::MAX.strict_mul(2);")]
794 /// ```
795 #[unstable(feature = "strict_overflow_ops", issue = "118260")]
796 #[must_use = "this returns the result of the operation, \
797 without modifying the original"]
798 #[inline]
799 #[track_caller]
800 #[cfg(not(feature = "ferrocene_certified"))]
801 pub const fn strict_mul(self, rhs: Self) -> Self {
802 let (a, b) = self.overflowing_mul(rhs);
803 if b { overflow_panic::mul() } else { a }
804 }
805
806 /// Unchecked integer multiplication. Computes `self * rhs`, assuming overflow
807 /// cannot occur.
808 ///
809 /// Calling `x.unchecked_mul(y)` is semantically equivalent to calling
810 /// `x.`[`checked_mul`]`(y).`[`unwrap_unchecked`]`()`.
811 ///
812 /// If you're just trying to avoid the panic in debug mode, then **do not**
813 /// use this. Instead, you're looking for [`wrapping_mul`].
814 ///
815 /// # Safety
816 ///
817 /// This results in undefined behavior when
818 #[doc = concat!("`self * rhs > ", stringify!($SelfT), "::MAX` or `self * rhs < ", stringify!($SelfT), "::MIN`,")]
819 /// i.e. when [`checked_mul`] would return `None`.
820 ///
821 /// [`unwrap_unchecked`]: option/enum.Option.html#method.unwrap_unchecked
822 #[doc = concat!("[`checked_mul`]: ", stringify!($SelfT), "::checked_mul")]
823 #[doc = concat!("[`wrapping_mul`]: ", stringify!($SelfT), "::wrapping_mul")]
824 #[stable(feature = "unchecked_math", since = "1.79.0")]
825 #[rustc_const_stable(feature = "unchecked_math", since = "1.79.0")]
826 #[must_use = "this returns the result of the operation, \
827 without modifying the original"]
828 #[inline(always)]
829 #[track_caller]
830 #[cfg(not(feature = "ferrocene_certified"))]
831 pub const unsafe fn unchecked_mul(self, rhs: Self) -> Self {
832 assert_unsafe_precondition!(
833 check_language_ub,
834 concat!(stringify!($SelfT), "::unchecked_mul cannot overflow"),
835 (
836 lhs: $SelfT = self,
837 rhs: $SelfT = rhs,
838 ) => !lhs.overflowing_mul(rhs).1,
839 );
840
841 // SAFETY: this is guaranteed to be safe by the caller.
842 unsafe {
843 intrinsics::unchecked_mul(self, rhs)
844 }
845 }
846
847 /// Checked integer division. Computes `self / rhs`, returning `None` if `rhs == 0`
848 /// or the division results in overflow.
849 ///
850 /// # Examples
851 ///
852 /// ```
853 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).checked_div(-1), Some(", stringify!($Max), "));")]
854 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_div(-1), None);")]
855 #[doc = concat!("assert_eq!((1", stringify!($SelfT), ").checked_div(0), None);")]
856 /// ```
857 #[stable(feature = "rust1", since = "1.0.0")]
858 #[rustc_const_stable(feature = "const_checked_int_div", since = "1.52.0")]
859 #[must_use = "this returns the result of the operation, \
860 without modifying the original"]
861 #[inline]
862 #[cfg(not(feature = "ferrocene_certified"))]
863 pub const fn checked_div(self, rhs: Self) -> Option<Self> {
864 if intrinsics::unlikely(rhs == 0 || ((self == Self::MIN) && (rhs == -1))) {
865 None
866 } else {
867 // SAFETY: div by zero and by INT_MIN have been checked above
868 Some(unsafe { intrinsics::unchecked_div(self, rhs) })
869 }
870 }
871
872 /// Strict integer division. Computes `self / rhs`, panicking
873 /// if overflow occurred.
874 ///
875 /// # Panics
876 ///
877 /// This function will panic if `rhs` is zero.
878 ///
879 /// ## Overflow behavior
880 ///
881 /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
882 ///
883 /// The only case where such an overflow can occur is when one divides `MIN / -1` on a signed type (where
884 /// `MIN` is the negative minimal value for the type); this is equivalent to `-MIN`, a positive value
885 /// that is too large to represent in the type.
886 ///
887 /// # Examples
888 ///
889 /// ```
890 /// #![feature(strict_overflow_ops)]
891 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).strict_div(-1), ", stringify!($Max), ");")]
892 /// ```
893 ///
894 /// The following panics because of overflow:
895 ///
896 /// ```should_panic
897 /// #![feature(strict_overflow_ops)]
898 #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_div(-1);")]
899 /// ```
900 ///
901 /// The following panics because of division by zero:
902 ///
903 /// ```should_panic
904 /// #![feature(strict_overflow_ops)]
905 #[doc = concat!("let _ = (1", stringify!($SelfT), ").strict_div(0);")]
906 /// ```
907 #[unstable(feature = "strict_overflow_ops", issue = "118260")]
908 #[must_use = "this returns the result of the operation, \
909 without modifying the original"]
910 #[inline]
911 #[track_caller]
912 #[cfg(not(feature = "ferrocene_certified"))]
913 pub const fn strict_div(self, rhs: Self) -> Self {
914 let (a, b) = self.overflowing_div(rhs);
915 if b { overflow_panic::div() } else { a }
916 }
917
918 /// Checked Euclidean division. Computes `self.div_euclid(rhs)`,
919 /// returning `None` if `rhs == 0` or the division results in overflow.
920 ///
921 /// # Examples
922 ///
923 /// ```
924 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).checked_div_euclid(-1), Some(", stringify!($Max), "));")]
925 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_div_euclid(-1), None);")]
926 #[doc = concat!("assert_eq!((1", stringify!($SelfT), ").checked_div_euclid(0), None);")]
927 /// ```
928 #[stable(feature = "euclidean_division", since = "1.38.0")]
929 #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
930 #[must_use = "this returns the result of the operation, \
931 without modifying the original"]
932 #[inline]
933 #[cfg(not(feature = "ferrocene_certified"))]
934 pub const fn checked_div_euclid(self, rhs: Self) -> Option<Self> {
935 // Using `&` helps LLVM see that it is the same check made in division.
936 if intrinsics::unlikely(rhs == 0 || ((self == Self::MIN) & (rhs == -1))) {
937 None
938 } else {
939 Some(self.div_euclid(rhs))
940 }
941 }
942
943 /// Strict Euclidean division. Computes `self.div_euclid(rhs)`, panicking
944 /// if overflow occurred.
945 ///
946 /// # Panics
947 ///
948 /// This function will panic if `rhs` is zero.
949 ///
950 /// ## Overflow behavior
951 ///
952 /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
953 ///
954 /// The only case where such an overflow can occur is when one divides `MIN / -1` on a signed type (where
955 /// `MIN` is the negative minimal value for the type); this is equivalent to `-MIN`, a positive value
956 /// that is too large to represent in the type.
957 ///
958 /// # Examples
959 ///
960 /// ```
961 /// #![feature(strict_overflow_ops)]
962 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).strict_div_euclid(-1), ", stringify!($Max), ");")]
963 /// ```
964 ///
965 /// The following panics because of overflow:
966 ///
967 /// ```should_panic
968 /// #![feature(strict_overflow_ops)]
969 #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_div_euclid(-1);")]
970 /// ```
971 ///
972 /// The following panics because of division by zero:
973 ///
974 /// ```should_panic
975 /// #![feature(strict_overflow_ops)]
976 #[doc = concat!("let _ = (1", stringify!($SelfT), ").strict_div_euclid(0);")]
977 /// ```
978 #[unstable(feature = "strict_overflow_ops", issue = "118260")]
979 #[must_use = "this returns the result of the operation, \
980 without modifying the original"]
981 #[inline]
982 #[track_caller]
983 #[cfg(not(feature = "ferrocene_certified"))]
984 pub const fn strict_div_euclid(self, rhs: Self) -> Self {
985 let (a, b) = self.overflowing_div_euclid(rhs);
986 if b { overflow_panic::div() } else { a }
987 }
988
989 /// Checked integer division without remainder. Computes `self / rhs`,
990 /// returning `None` if `rhs == 0`, the division results in overflow,
991 /// or `self % rhs != 0`.
992 ///
993 /// # Examples
994 ///
995 /// ```
996 /// #![feature(exact_div)]
997 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).checked_exact_div(-1), Some(", stringify!($Max), "));")]
998 #[doc = concat!("assert_eq!((-5", stringify!($SelfT), ").checked_exact_div(2), None);")]
999 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_exact_div(-1), None);")]
1000 #[doc = concat!("assert_eq!((1", stringify!($SelfT), ").checked_exact_div(0), None);")]
1001 /// ```
1002 #[unstable(
1003 feature = "exact_div",
1004 issue = "139911",
1005 )]
1006 #[must_use = "this returns the result of the operation, \
1007 without modifying the original"]
1008 #[inline]
1009 #[cfg(not(feature = "ferrocene_certified"))]
1010 pub const fn checked_exact_div(self, rhs: Self) -> Option<Self> {
1011 if intrinsics::unlikely(rhs == 0 || ((self == Self::MIN) && (rhs == -1))) {
1012 None
1013 } else {
1014 // SAFETY: division by zero and overflow are checked above
1015 unsafe {
1016 if intrinsics::unlikely(intrinsics::unchecked_rem(self, rhs) != 0) {
1017 None
1018 } else {
1019 Some(intrinsics::exact_div(self, rhs))
1020 }
1021 }
1022 }
1023 }
1024
1025 /// Checked integer division without remainder. Computes `self / rhs`.
1026 ///
1027 /// # Panics
1028 ///
1029 /// This function will panic if `rhs == 0`, the division results in overflow,
1030 /// or `self % rhs != 0`.
1031 ///
1032 /// # Examples
1033 ///
1034 /// ```
1035 /// #![feature(exact_div)]
1036 #[doc = concat!("assert_eq!(64", stringify!($SelfT), ".exact_div(2), 32);")]
1037 #[doc = concat!("assert_eq!(64", stringify!($SelfT), ".exact_div(32), 2);")]
1038 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).exact_div(-1), ", stringify!($Max), ");")]
1039 /// ```
1040 ///
1041 /// ```should_panic
1042 /// #![feature(exact_div)]
1043 #[doc = concat!("let _ = 65", stringify!($SelfT), ".exact_div(2);")]
1044 /// ```
1045 /// ```should_panic
1046 /// #![feature(exact_div)]
1047 #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.exact_div(-1);")]
1048 /// ```
1049 #[unstable(
1050 feature = "exact_div",
1051 issue = "139911",
1052 )]
1053 #[must_use = "this returns the result of the operation, \
1054 without modifying the original"]
1055 #[inline]
1056 #[cfg(not(feature = "ferrocene_certified"))]
1057 pub const fn exact_div(self, rhs: Self) -> Self {
1058 match self.checked_exact_div(rhs) {
1059 Some(x) => x,
1060 None => panic!("Failed to divide without remainder"),
1061 }
1062 }
1063
1064 /// Unchecked integer division without remainder. Computes `self / rhs`.
1065 ///
1066 /// # Safety
1067 ///
1068 /// This results in undefined behavior when `rhs == 0`, `self % rhs != 0`, or
1069 #[doc = concat!("`self == ", stringify!($SelfT), "::MIN && rhs == -1`,")]
1070 /// i.e. when [`checked_exact_div`](Self::checked_exact_div) would return `None`.
1071 #[unstable(
1072 feature = "exact_div",
1073 issue = "139911",
1074 )]
1075 #[must_use = "this returns the result of the operation, \
1076 without modifying the original"]
1077 #[inline]
1078 #[cfg(not(feature = "ferrocene_certified"))]
1079 pub const unsafe fn unchecked_exact_div(self, rhs: Self) -> Self {
1080 assert_unsafe_precondition!(
1081 check_language_ub,
1082 concat!(stringify!($SelfT), "::unchecked_exact_div cannot overflow, divide by zero, or leave a remainder"),
1083 (
1084 lhs: $SelfT = self,
1085 rhs: $SelfT = rhs,
1086 ) => rhs > 0 && lhs % rhs == 0 && (lhs != <$SelfT>::MIN || rhs != -1),
1087 );
1088 // SAFETY: Same precondition
1089 unsafe { intrinsics::exact_div(self, rhs) }
1090 }
1091
1092 /// Checked integer remainder. Computes `self % rhs`, returning `None` if
1093 /// `rhs == 0` or the division results in overflow.
1094 ///
1095 /// # Examples
1096 ///
1097 /// ```
1098 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem(2), Some(1));")]
1099 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem(0), None);")]
1100 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_rem(-1), None);")]
1101 /// ```
1102 #[stable(feature = "wrapping", since = "1.7.0")]
1103 #[rustc_const_stable(feature = "const_checked_int_div", since = "1.52.0")]
1104 #[must_use = "this returns the result of the operation, \
1105 without modifying the original"]
1106 #[inline]
1107 #[cfg(not(feature = "ferrocene_certified"))]
1108 pub const fn checked_rem(self, rhs: Self) -> Option<Self> {
1109 if intrinsics::unlikely(rhs == 0 || ((self == Self::MIN) && (rhs == -1))) {
1110 None
1111 } else {
1112 // SAFETY: div by zero and by INT_MIN have been checked above
1113 Some(unsafe { intrinsics::unchecked_rem(self, rhs) })
1114 }
1115 }
1116
1117 /// Strict integer remainder. Computes `self % rhs`, panicking if
1118 /// the division results in overflow.
1119 ///
1120 /// # Panics
1121 ///
1122 /// This function will panic if `rhs` is zero.
1123 ///
1124 /// ## Overflow behavior
1125 ///
1126 /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
1127 ///
1128 /// The only case where such an overflow can occur is `x % y` for `MIN / -1` on a
1129 /// signed type (where `MIN` is the negative minimal value), which is invalid due to implementation artifacts.
1130 ///
1131 /// # Examples
1132 ///
1133 /// ```
1134 /// #![feature(strict_overflow_ops)]
1135 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".strict_rem(2), 1);")]
1136 /// ```
1137 ///
1138 /// The following panics because of division by zero:
1139 ///
1140 /// ```should_panic
1141 /// #![feature(strict_overflow_ops)]
1142 #[doc = concat!("let _ = 5", stringify!($SelfT), ".strict_rem(0);")]
1143 /// ```
1144 ///
1145 /// The following panics because of overflow:
1146 ///
1147 /// ```should_panic
1148 /// #![feature(strict_overflow_ops)]
1149 #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_rem(-1);")]
1150 /// ```
1151 #[unstable(feature = "strict_overflow_ops", issue = "118260")]
1152 #[must_use = "this returns the result of the operation, \
1153 without modifying the original"]
1154 #[inline]
1155 #[track_caller]
1156 #[cfg(not(feature = "ferrocene_certified"))]
1157 pub const fn strict_rem(self, rhs: Self) -> Self {
1158 let (a, b) = self.overflowing_rem(rhs);
1159 if b { overflow_panic::rem() } else { a }
1160 }
1161
1162 /// Checked Euclidean remainder. Computes `self.rem_euclid(rhs)`, returning `None`
1163 /// if `rhs == 0` or the division results in overflow.
1164 ///
1165 /// # Examples
1166 ///
1167 /// ```
1168 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(2), Some(1));")]
1169 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(0), None);")]
1170 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_rem_euclid(-1), None);")]
1171 /// ```
1172 #[stable(feature = "euclidean_division", since = "1.38.0")]
1173 #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1174 #[must_use = "this returns the result of the operation, \
1175 without modifying the original"]
1176 #[inline]
1177 #[cfg(not(feature = "ferrocene_certified"))]
1178 pub const fn checked_rem_euclid(self, rhs: Self) -> Option<Self> {
1179 // Using `&` helps LLVM see that it is the same check made in division.
1180 if intrinsics::unlikely(rhs == 0 || ((self == Self::MIN) & (rhs == -1))) {
1181 None
1182 } else {
1183 Some(self.rem_euclid(rhs))
1184 }
1185 }
1186
1187 /// Strict Euclidean remainder. Computes `self.rem_euclid(rhs)`, panicking if
1188 /// the division results in overflow.
1189 ///
1190 /// # Panics
1191 ///
1192 /// This function will panic if `rhs` is zero.
1193 ///
1194 /// ## Overflow behavior
1195 ///
1196 /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
1197 ///
1198 /// The only case where such an overflow can occur is `x % y` for `MIN / -1` on a
1199 /// signed type (where `MIN` is the negative minimal value), which is invalid due to implementation artifacts.
1200 ///
1201 /// # Examples
1202 ///
1203 /// ```
1204 /// #![feature(strict_overflow_ops)]
1205 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".strict_rem_euclid(2), 1);")]
1206 /// ```
1207 ///
1208 /// The following panics because of division by zero:
1209 ///
1210 /// ```should_panic
1211 /// #![feature(strict_overflow_ops)]
1212 #[doc = concat!("let _ = 5", stringify!($SelfT), ".strict_rem_euclid(0);")]
1213 /// ```
1214 ///
1215 /// The following panics because of overflow:
1216 ///
1217 /// ```should_panic
1218 /// #![feature(strict_overflow_ops)]
1219 #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_rem_euclid(-1);")]
1220 /// ```
1221 #[unstable(feature = "strict_overflow_ops", issue = "118260")]
1222 #[must_use = "this returns the result of the operation, \
1223 without modifying the original"]
1224 #[inline]
1225 #[track_caller]
1226 #[cfg(not(feature = "ferrocene_certified"))]
1227 pub const fn strict_rem_euclid(self, rhs: Self) -> Self {
1228 let (a, b) = self.overflowing_rem_euclid(rhs);
1229 if b { overflow_panic::rem() } else { a }
1230 }
1231
1232 /// Checked negation. Computes `-self`, returning `None` if `self == MIN`.
1233 ///
1234 /// # Examples
1235 ///
1236 /// ```
1237 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_neg(), Some(-5));")]
1238 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_neg(), None);")]
1239 /// ```
1240 #[stable(feature = "wrapping", since = "1.7.0")]
1241 #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
1242 #[must_use = "this returns the result of the operation, \
1243 without modifying the original"]
1244 #[inline]
1245 #[cfg(not(feature = "ferrocene_certified"))]
1246 pub const fn checked_neg(self) -> Option<Self> {
1247 let (a, b) = self.overflowing_neg();
1248 if intrinsics::unlikely(b) { None } else { Some(a) }
1249 }
1250
1251 /// Unchecked negation. Computes `-self`, assuming overflow cannot occur.
1252 ///
1253 /// # Safety
1254 ///
1255 /// This results in undefined behavior when
1256 #[doc = concat!("`self == ", stringify!($SelfT), "::MIN`,")]
1257 /// i.e. when [`checked_neg`] would return `None`.
1258 ///
1259 #[doc = concat!("[`checked_neg`]: ", stringify!($SelfT), "::checked_neg")]
1260 #[unstable(
1261 feature = "unchecked_neg",
1262 reason = "niche optimization path",
1263 issue = "85122",
1264 )]
1265 #[must_use = "this returns the result of the operation, \
1266 without modifying the original"]
1267 #[inline(always)]
1268 #[track_caller]
1269 #[cfg(not(feature = "ferrocene_certified"))]
1270 pub const unsafe fn unchecked_neg(self) -> Self {
1271 assert_unsafe_precondition!(
1272 check_language_ub,
1273 concat!(stringify!($SelfT), "::unchecked_neg cannot overflow"),
1274 (
1275 lhs: $SelfT = self,
1276 ) => !lhs.overflowing_neg().1,
1277 );
1278
1279 // SAFETY: this is guaranteed to be safe by the caller.
1280 unsafe {
1281 intrinsics::unchecked_sub(0, self)
1282 }
1283 }
1284
1285 /// Strict negation. Computes `-self`, panicking if `self == MIN`.
1286 ///
1287 /// # Panics
1288 ///
1289 /// ## Overflow behavior
1290 ///
1291 /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
1292 ///
1293 /// # Examples
1294 ///
1295 /// ```
1296 /// #![feature(strict_overflow_ops)]
1297 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".strict_neg(), -5);")]
1298 /// ```
1299 ///
1300 /// The following panics because of overflow:
1301 ///
1302 /// ```should_panic
1303 /// #![feature(strict_overflow_ops)]
1304 #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_neg();")]
1305 ///
1306 #[unstable(feature = "strict_overflow_ops", issue = "118260")]
1307 #[must_use = "this returns the result of the operation, \
1308 without modifying the original"]
1309 #[inline]
1310 #[track_caller]
1311 #[cfg(not(feature = "ferrocene_certified"))]
1312 pub const fn strict_neg(self) -> Self {
1313 let (a, b) = self.overflowing_neg();
1314 if b { overflow_panic::neg() } else { a }
1315 }
1316
1317 /// Checked shift left. Computes `self << rhs`, returning `None` if `rhs` is larger
1318 /// than or equal to the number of bits in `self`.
1319 ///
1320 /// # Examples
1321 ///
1322 /// ```
1323 #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));")]
1324 #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(129), None);")]
1325 #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shl(", stringify!($BITS_MINUS_ONE), "), Some(0));")]
1326 /// ```
1327 #[stable(feature = "wrapping", since = "1.7.0")]
1328 #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
1329 #[must_use = "this returns the result of the operation, \
1330 without modifying the original"]
1331 #[inline]
1332 #[cfg(not(feature = "ferrocene_certified"))]
1333 pub const fn checked_shl(self, rhs: u32) -> Option<Self> {
1334 // Not using overflowing_shl as that's a wrapping shift
1335 if rhs < Self::BITS {
1336 // SAFETY: just checked the RHS is in-range
1337 Some(unsafe { self.unchecked_shl(rhs) })
1338 } else {
1339 None
1340 }
1341 }
1342
1343 /// Strict shift left. Computes `self << rhs`, panicking if `rhs` is larger
1344 /// than or equal to the number of bits in `self`.
1345 ///
1346 /// # Panics
1347 ///
1348 /// ## Overflow behavior
1349 ///
1350 /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
1351 ///
1352 /// # Examples
1353 ///
1354 /// ```
1355 /// #![feature(strict_overflow_ops)]
1356 #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".strict_shl(4), 0x10);")]
1357 /// ```
1358 ///
1359 /// The following panics because of overflow:
1360 ///
1361 /// ```should_panic
1362 /// #![feature(strict_overflow_ops)]
1363 #[doc = concat!("let _ = 0x1", stringify!($SelfT), ".strict_shl(129);")]
1364 /// ```
1365 #[unstable(feature = "strict_overflow_ops", issue = "118260")]
1366 #[must_use = "this returns the result of the operation, \
1367 without modifying the original"]
1368 #[inline]
1369 #[track_caller]
1370 #[cfg(not(feature = "ferrocene_certified"))]
1371 pub const fn strict_shl(self, rhs: u32) -> Self {
1372 let (a, b) = self.overflowing_shl(rhs);
1373 if b { overflow_panic::shl() } else { a }
1374 }
1375
1376 /// Unchecked shift left. Computes `self << rhs`, assuming that
1377 /// `rhs` is less than the number of bits in `self`.
1378 ///
1379 /// # Safety
1380 ///
1381 /// This results in undefined behavior if `rhs` is larger than
1382 /// or equal to the number of bits in `self`,
1383 /// i.e. when [`checked_shl`] would return `None`.
1384 ///
1385 #[doc = concat!("[`checked_shl`]: ", stringify!($SelfT), "::checked_shl")]
1386 #[unstable(
1387 feature = "unchecked_shifts",
1388 reason = "niche optimization path",
1389 issue = "85122",
1390 )]
1391 #[must_use = "this returns the result of the operation, \
1392 without modifying the original"]
1393 #[inline(always)]
1394 #[track_caller]
1395 #[cfg(not(feature = "ferrocene_certified"))]
1396 pub const unsafe fn unchecked_shl(self, rhs: u32) -> Self {
1397 assert_unsafe_precondition!(
1398 check_language_ub,
1399 concat!(stringify!($SelfT), "::unchecked_shl cannot overflow"),
1400 (
1401 rhs: u32 = rhs,
1402 ) => rhs < <$ActualT>::BITS,
1403 );
1404
1405 // SAFETY: this is guaranteed to be safe by the caller.
1406 unsafe {
1407 intrinsics::unchecked_shl(self, rhs)
1408 }
1409 }
1410
1411 /// Unbounded shift left. Computes `self << rhs`, without bounding the value of `rhs`.
1412 ///
1413 /// If `rhs` is larger or equal to the number of bits in `self`,
1414 /// the entire value is shifted out, and `0` is returned.
1415 ///
1416 /// # Examples
1417 ///
1418 /// ```
1419 #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".unbounded_shl(4), 0x10);")]
1420 #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".unbounded_shl(129), 0);")]
1421 /// ```
1422 #[stable(feature = "unbounded_shifts", since = "1.87.0")]
1423 #[rustc_const_stable(feature = "unbounded_shifts", since = "1.87.0")]
1424 #[must_use = "this returns the result of the operation, \
1425 without modifying the original"]
1426 #[inline]
1427 #[cfg(not(feature = "ferrocene_certified"))]
1428 pub const fn unbounded_shl(self, rhs: u32) -> $SelfT{
1429 if rhs < Self::BITS {
1430 // SAFETY:
1431 // rhs is just checked to be in-range above
1432 unsafe { self.unchecked_shl(rhs) }
1433 } else {
1434 0
1435 }
1436 }
1437
1438 /// Checked shift right. Computes `self >> rhs`, returning `None` if `rhs` is
1439 /// larger than or equal to the number of bits in `self`.
1440 ///
1441 /// # Examples
1442 ///
1443 /// ```
1444 #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(4), Some(0x1));")]
1445 #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(128), None);")]
1446 /// ```
1447 #[stable(feature = "wrapping", since = "1.7.0")]
1448 #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
1449 #[must_use = "this returns the result of the operation, \
1450 without modifying the original"]
1451 #[inline]
1452 #[cfg(not(feature = "ferrocene_certified"))]
1453 pub const fn checked_shr(self, rhs: u32) -> Option<Self> {
1454 // Not using overflowing_shr as that's a wrapping shift
1455 if rhs < Self::BITS {
1456 // SAFETY: just checked the RHS is in-range
1457 Some(unsafe { self.unchecked_shr(rhs) })
1458 } else {
1459 None
1460 }
1461 }
1462
1463 /// Strict shift right. Computes `self >> rhs`, panicking `rhs` is
1464 /// larger than or equal to the number of bits in `self`.
1465 ///
1466 /// # Panics
1467 ///
1468 /// ## Overflow behavior
1469 ///
1470 /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
1471 ///
1472 /// # Examples
1473 ///
1474 /// ```
1475 /// #![feature(strict_overflow_ops)]
1476 #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".strict_shr(4), 0x1);")]
1477 /// ```
1478 ///
1479 /// The following panics because of overflow:
1480 ///
1481 /// ```should_panic
1482 /// #![feature(strict_overflow_ops)]
1483 #[doc = concat!("let _ = 0x10", stringify!($SelfT), ".strict_shr(128);")]
1484 /// ```
1485 #[unstable(feature = "strict_overflow_ops", issue = "118260")]
1486 #[must_use = "this returns the result of the operation, \
1487 without modifying the original"]
1488 #[inline]
1489 #[track_caller]
1490 #[cfg(not(feature = "ferrocene_certified"))]
1491 pub const fn strict_shr(self, rhs: u32) -> Self {
1492 let (a, b) = self.overflowing_shr(rhs);
1493 if b { overflow_panic::shr() } else { a }
1494 }
1495
1496 /// Unchecked shift right. Computes `self >> rhs`, assuming that
1497 /// `rhs` is less than the number of bits in `self`.
1498 ///
1499 /// # Safety
1500 ///
1501 /// This results in undefined behavior if `rhs` is larger than
1502 /// or equal to the number of bits in `self`,
1503 /// i.e. when [`checked_shr`] would return `None`.
1504 ///
1505 #[doc = concat!("[`checked_shr`]: ", stringify!($SelfT), "::checked_shr")]
1506 #[unstable(
1507 feature = "unchecked_shifts",
1508 reason = "niche optimization path",
1509 issue = "85122",
1510 )]
1511 #[must_use = "this returns the result of the operation, \
1512 without modifying the original"]
1513 #[inline(always)]
1514 #[track_caller]
1515 #[cfg(not(feature = "ferrocene_certified"))]
1516 pub const unsafe fn unchecked_shr(self, rhs: u32) -> Self {
1517 assert_unsafe_precondition!(
1518 check_language_ub,
1519 concat!(stringify!($SelfT), "::unchecked_shr cannot overflow"),
1520 (
1521 rhs: u32 = rhs,
1522 ) => rhs < <$ActualT>::BITS,
1523 );
1524
1525 // SAFETY: this is guaranteed to be safe by the caller.
1526 unsafe {
1527 intrinsics::unchecked_shr(self, rhs)
1528 }
1529 }
1530
1531 /// Unbounded shift right. Computes `self >> rhs`, without bounding the value of `rhs`.
1532 ///
1533 /// If `rhs` is larger or equal to the number of bits in `self`,
1534 /// the entire value is shifted out, which yields `0` for a positive number,
1535 /// and `-1` for a negative number.
1536 ///
1537 /// # Examples
1538 ///
1539 /// ```
1540 #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".unbounded_shr(4), 0x1);")]
1541 #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".unbounded_shr(129), 0);")]
1542 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.unbounded_shr(129), -1);")]
1543 /// ```
1544 #[stable(feature = "unbounded_shifts", since = "1.87.0")]
1545 #[rustc_const_stable(feature = "unbounded_shifts", since = "1.87.0")]
1546 #[must_use = "this returns the result of the operation, \
1547 without modifying the original"]
1548 #[inline]
1549 #[cfg(not(feature = "ferrocene_certified"))]
1550 pub const fn unbounded_shr(self, rhs: u32) -> $SelfT{
1551 if rhs < Self::BITS {
1552 // SAFETY:
1553 // rhs is just checked to be in-range above
1554 unsafe { self.unchecked_shr(rhs) }
1555 } else {
1556 // A shift by `Self::BITS-1` suffices for signed integers, because the sign bit is copied for each of the shifted bits.
1557
1558 // SAFETY:
1559 // `Self::BITS-1` is guaranteed to be less than `Self::BITS`
1560 unsafe { self.unchecked_shr(Self::BITS - 1) }
1561 }
1562 }
1563
1564 /// Checked absolute value. Computes `self.abs()`, returning `None` if
1565 /// `self == MIN`.
1566 ///
1567 /// # Examples
1568 ///
1569 /// ```
1570 #[doc = concat!("assert_eq!((-5", stringify!($SelfT), ").checked_abs(), Some(5));")]
1571 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_abs(), None);")]
1572 /// ```
1573 #[stable(feature = "no_panic_abs", since = "1.13.0")]
1574 #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
1575 #[must_use = "this returns the result of the operation, \
1576 without modifying the original"]
1577 #[inline]
1578 #[cfg(not(feature = "ferrocene_certified"))]
1579 pub const fn checked_abs(self) -> Option<Self> {
1580 if self.is_negative() {
1581 self.checked_neg()
1582 } else {
1583 Some(self)
1584 }
1585 }
1586
1587 /// Strict absolute value. Computes `self.abs()`, panicking if
1588 /// `self == MIN`.
1589 ///
1590 /// # Panics
1591 ///
1592 /// ## Overflow behavior
1593 ///
1594 /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
1595 ///
1596 /// # Examples
1597 ///
1598 /// ```
1599 /// #![feature(strict_overflow_ops)]
1600 #[doc = concat!("assert_eq!((-5", stringify!($SelfT), ").strict_abs(), 5);")]
1601 /// ```
1602 ///
1603 /// The following panics because of overflow:
1604 ///
1605 /// ```should_panic
1606 /// #![feature(strict_overflow_ops)]
1607 #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_abs();")]
1608 /// ```
1609 #[unstable(feature = "strict_overflow_ops", issue = "118260")]
1610 #[must_use = "this returns the result of the operation, \
1611 without modifying the original"]
1612 #[inline]
1613 #[track_caller]
1614 #[cfg(not(feature = "ferrocene_certified"))]
1615 pub const fn strict_abs(self) -> Self {
1616 if self.is_negative() {
1617 self.strict_neg()
1618 } else {
1619 self
1620 }
1621 }
1622
1623 /// Checked exponentiation. Computes `self.pow(exp)`, returning `None` if
1624 /// overflow occurred.
1625 ///
1626 /// # Examples
1627 ///
1628 /// ```
1629 #[doc = concat!("assert_eq!(8", stringify!($SelfT), ".checked_pow(2), Some(64));")]
1630 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_pow(2), None);")]
1631 /// ```
1632
1633 #[stable(feature = "no_panic_pow", since = "1.34.0")]
1634 #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1635 #[must_use = "this returns the result of the operation, \
1636 without modifying the original"]
1637 #[inline]
1638 #[cfg(not(feature = "ferrocene_certified"))]
1639 pub const fn checked_pow(self, mut exp: u32) -> Option<Self> {
1640 if exp == 0 {
1641 return Some(1);
1642 }
1643 let mut base = self;
1644 let mut acc: Self = 1;
1645
1646 loop {
1647 if (exp & 1) == 1 {
1648 acc = try_opt!(acc.checked_mul(base));
1649 // since exp!=0, finally the exp must be 1.
1650 if exp == 1 {
1651 return Some(acc);
1652 }
1653 }
1654 exp /= 2;
1655 base = try_opt!(base.checked_mul(base));
1656 }
1657 }
1658
1659 /// Strict exponentiation. Computes `self.pow(exp)`, panicking if
1660 /// overflow occurred.
1661 ///
1662 /// # Panics
1663 ///
1664 /// ## Overflow behavior
1665 ///
1666 /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
1667 ///
1668 /// # Examples
1669 ///
1670 /// ```
1671 /// #![feature(strict_overflow_ops)]
1672 #[doc = concat!("assert_eq!(8", stringify!($SelfT), ".strict_pow(2), 64);")]
1673 /// ```
1674 ///
1675 /// The following panics because of overflow:
1676 ///
1677 /// ```should_panic
1678 /// #![feature(strict_overflow_ops)]
1679 #[doc = concat!("let _ = ", stringify!($SelfT), "::MAX.strict_pow(2);")]
1680 /// ```
1681 #[unstable(feature = "strict_overflow_ops", issue = "118260")]
1682 #[must_use = "this returns the result of the operation, \
1683 without modifying the original"]
1684 #[inline]
1685 #[track_caller]
1686 #[cfg(not(feature = "ferrocene_certified"))]
1687 pub const fn strict_pow(self, mut exp: u32) -> Self {
1688 if exp == 0 {
1689 return 1;
1690 }
1691 let mut base = self;
1692 let mut acc: Self = 1;
1693
1694 loop {
1695 if (exp & 1) == 1 {
1696 acc = acc.strict_mul(base);
1697 // since exp!=0, finally the exp must be 1.
1698 if exp == 1 {
1699 return acc;
1700 }
1701 }
1702 exp /= 2;
1703 base = base.strict_mul(base);
1704 }
1705 }
1706
1707 /// Returns the square root of the number, rounded down.
1708 ///
1709 /// Returns `None` if `self` is negative.
1710 ///
1711 /// # Examples
1712 ///
1713 /// ```
1714 #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".checked_isqrt(), Some(3));")]
1715 /// ```
1716 #[stable(feature = "isqrt", since = "1.84.0")]
1717 #[rustc_const_stable(feature = "isqrt", since = "1.84.0")]
1718 #[must_use = "this returns the result of the operation, \
1719 without modifying the original"]
1720 #[inline]
1721 #[cfg(not(feature = "ferrocene_certified"))]
1722 pub const fn checked_isqrt(self) -> Option<Self> {
1723 if self < 0 {
1724 None
1725 } else {
1726 // SAFETY: Input is nonnegative in this `else` branch.
1727 let result = unsafe {
1728 crate::num::int_sqrt::$ActualT(self as $ActualT) as $SelfT
1729 };
1730
1731 // Inform the optimizer what the range of outputs is. If
1732 // testing `core` crashes with no panic message and a
1733 // `num::int_sqrt::i*` test failed, it's because your edits
1734 // caused these assertions to become false.
1735 //
1736 // SAFETY: Integer square root is a monotonically nondecreasing
1737 // function, which means that increasing the input will never
1738 // cause the output to decrease. Thus, since the input for
1739 // nonnegative signed integers is bounded by
1740 // `[0, <$ActualT>::MAX]`, sqrt(n) will be bounded by
1741 // `[sqrt(0), sqrt(<$ActualT>::MAX)]`.
1742 unsafe {
1743 // SAFETY: `<$ActualT>::MAX` is nonnegative.
1744 const MAX_RESULT: $SelfT = unsafe {
1745 crate::num::int_sqrt::$ActualT(<$ActualT>::MAX) as $SelfT
1746 };
1747
1748 crate::hint::assert_unchecked(result >= 0);
1749 crate::hint::assert_unchecked(result <= MAX_RESULT);
1750 }
1751
1752 Some(result)
1753 }
1754 }
1755
1756 /// Saturating integer addition. Computes `self + rhs`, saturating at the numeric
1757 /// bounds instead of overflowing.
1758 ///
1759 /// # Examples
1760 ///
1761 /// ```
1762 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_add(1), 101);")]
1763 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_add(100), ", stringify!($SelfT), "::MAX);")]
1764 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_add(-1), ", stringify!($SelfT), "::MIN);")]
1765 /// ```
1766
1767 #[stable(feature = "rust1", since = "1.0.0")]
1768 #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
1769 #[must_use = "this returns the result of the operation, \
1770 without modifying the original"]
1771 #[inline(always)]
1772 #[cfg(not(feature = "ferrocene_certified"))]
1773 pub const fn saturating_add(self, rhs: Self) -> Self {
1774 intrinsics::saturating_add(self, rhs)
1775 }
1776
1777 /// Saturating addition with an unsigned integer. Computes `self + rhs`,
1778 /// saturating at the numeric bounds instead of overflowing.
1779 ///
1780 /// # Examples
1781 ///
1782 /// ```
1783 #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".saturating_add_unsigned(2), 3);")]
1784 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_add_unsigned(100), ", stringify!($SelfT), "::MAX);")]
1785 /// ```
1786 #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
1787 #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
1788 #[must_use = "this returns the result of the operation, \
1789 without modifying the original"]
1790 #[inline]
1791 #[cfg(not(feature = "ferrocene_certified"))]
1792 pub const fn saturating_add_unsigned(self, rhs: $UnsignedT) -> Self {
1793 // Overflow can only happen at the upper bound
1794 // We cannot use `unwrap_or` here because it is not `const`
1795 match self.checked_add_unsigned(rhs) {
1796 Some(x) => x,
1797 None => Self::MAX,
1798 }
1799 }
1800
1801 /// Saturating integer subtraction. Computes `self - rhs`, saturating at the
1802 /// numeric bounds instead of overflowing.
1803 ///
1804 /// # Examples
1805 ///
1806 /// ```
1807 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_sub(127), -27);")]
1808 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_sub(100), ", stringify!($SelfT), "::MIN);")]
1809 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_sub(-1), ", stringify!($SelfT), "::MAX);")]
1810 /// ```
1811 #[stable(feature = "rust1", since = "1.0.0")]
1812 #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
1813 #[must_use = "this returns the result of the operation, \
1814 without modifying the original"]
1815 #[inline(always)]
1816 #[cfg(not(feature = "ferrocene_certified"))]
1817 pub const fn saturating_sub(self, rhs: Self) -> Self {
1818 intrinsics::saturating_sub(self, rhs)
1819 }
1820
1821 /// Saturating subtraction with an unsigned integer. Computes `self - rhs`,
1822 /// saturating at the numeric bounds instead of overflowing.
1823 ///
1824 /// # Examples
1825 ///
1826 /// ```
1827 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_sub_unsigned(127), -27);")]
1828 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_sub_unsigned(100), ", stringify!($SelfT), "::MIN);")]
1829 /// ```
1830 #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
1831 #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
1832 #[must_use = "this returns the result of the operation, \
1833 without modifying the original"]
1834 #[inline]
1835 #[cfg(not(feature = "ferrocene_certified"))]
1836 pub const fn saturating_sub_unsigned(self, rhs: $UnsignedT) -> Self {
1837 // Overflow can only happen at the lower bound
1838 // We cannot use `unwrap_or` here because it is not `const`
1839 match self.checked_sub_unsigned(rhs) {
1840 Some(x) => x,
1841 None => Self::MIN,
1842 }
1843 }
1844
1845 /// Saturating integer negation. Computes `-self`, returning `MAX` if `self == MIN`
1846 /// instead of overflowing.
1847 ///
1848 /// # Examples
1849 ///
1850 /// ```
1851 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_neg(), -100);")]
1852 #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").saturating_neg(), 100);")]
1853 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_neg(), ", stringify!($SelfT), "::MAX);")]
1854 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_neg(), ", stringify!($SelfT), "::MIN + 1);")]
1855 /// ```
1856
1857 #[stable(feature = "saturating_neg", since = "1.45.0")]
1858 #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
1859 #[must_use = "this returns the result of the operation, \
1860 without modifying the original"]
1861 #[inline(always)]
1862 #[cfg(not(feature = "ferrocene_certified"))]
1863 pub const fn saturating_neg(self) -> Self {
1864 intrinsics::saturating_sub(0, self)
1865 }
1866
1867 /// Saturating absolute value. Computes `self.abs()`, returning `MAX` if `self ==
1868 /// MIN` instead of overflowing.
1869 ///
1870 /// # Examples
1871 ///
1872 /// ```
1873 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_abs(), 100);")]
1874 #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").saturating_abs(), 100);")]
1875 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_abs(), ", stringify!($SelfT), "::MAX);")]
1876 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).saturating_abs(), ", stringify!($SelfT), "::MAX);")]
1877 /// ```
1878
1879 #[stable(feature = "saturating_neg", since = "1.45.0")]
1880 #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
1881 #[must_use = "this returns the result of the operation, \
1882 without modifying the original"]
1883 #[inline]
1884 #[cfg(not(feature = "ferrocene_certified"))]
1885 pub const fn saturating_abs(self) -> Self {
1886 if self.is_negative() {
1887 self.saturating_neg()
1888 } else {
1889 self
1890 }
1891 }
1892
1893 /// Saturating integer multiplication. Computes `self * rhs`, saturating at the
1894 /// numeric bounds instead of overflowing.
1895 ///
1896 /// # Examples
1897 ///
1898 /// ```
1899 #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".saturating_mul(12), 120);")]
1900 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_mul(10), ", stringify!($SelfT), "::MAX);")]
1901 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_mul(10), ", stringify!($SelfT), "::MIN);")]
1902 /// ```
1903 #[stable(feature = "wrapping", since = "1.7.0")]
1904 #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
1905 #[must_use = "this returns the result of the operation, \
1906 without modifying the original"]
1907 #[inline]
1908 #[cfg(not(feature = "ferrocene_certified"))]
1909 pub const fn saturating_mul(self, rhs: Self) -> Self {
1910 match self.checked_mul(rhs) {
1911 Some(x) => x,
1912 None => if (self < 0) == (rhs < 0) {
1913 Self::MAX
1914 } else {
1915 Self::MIN
1916 }
1917 }
1918 }
1919
1920 /// Saturating integer division. Computes `self / rhs`, saturating at the
1921 /// numeric bounds instead of overflowing.
1922 ///
1923 /// # Panics
1924 ///
1925 /// This function will panic if `rhs` is zero.
1926 ///
1927 /// # Examples
1928 ///
1929 /// ```
1930 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".saturating_div(2), 2);")]
1931 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_div(-1), ", stringify!($SelfT), "::MIN + 1);")]
1932 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_div(-1), ", stringify!($SelfT), "::MAX);")]
1933 ///
1934 /// ```
1935 #[stable(feature = "saturating_div", since = "1.58.0")]
1936 #[rustc_const_stable(feature = "saturating_div", since = "1.58.0")]
1937 #[must_use = "this returns the result of the operation, \
1938 without modifying the original"]
1939 #[inline]
1940 #[cfg(not(feature = "ferrocene_certified"))]
1941 pub const fn saturating_div(self, rhs: Self) -> Self {
1942 match self.overflowing_div(rhs) {
1943 (result, false) => result,
1944 (_result, true) => Self::MAX, // MIN / -1 is the only possible saturating overflow
1945 }
1946 }
1947
1948 /// Saturating integer exponentiation. Computes `self.pow(exp)`,
1949 /// saturating at the numeric bounds instead of overflowing.
1950 ///
1951 /// # Examples
1952 ///
1953 /// ```
1954 #[doc = concat!("assert_eq!((-4", stringify!($SelfT), ").saturating_pow(3), -64);")]
1955 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(2), ", stringify!($SelfT), "::MAX);")]
1956 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(3), ", stringify!($SelfT), "::MIN);")]
1957 /// ```
1958 #[stable(feature = "no_panic_pow", since = "1.34.0")]
1959 #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1960 #[must_use = "this returns the result of the operation, \
1961 without modifying the original"]
1962 #[inline]
1963 #[cfg(not(feature = "ferrocene_certified"))]
1964 pub const fn saturating_pow(self, exp: u32) -> Self {
1965 match self.checked_pow(exp) {
1966 Some(x) => x,
1967 None if self < 0 && exp % 2 == 1 => Self::MIN,
1968 None => Self::MAX,
1969 }
1970 }
1971
1972 /// Wrapping (modular) addition. Computes `self + rhs`, wrapping around at the
1973 /// boundary of the type.
1974 ///
1975 /// # Examples
1976 ///
1977 /// ```
1978 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_add(27), 127);")]
1979 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.wrapping_add(2), ", stringify!($SelfT), "::MIN + 1);")]
1980 /// ```
1981 #[stable(feature = "rust1", since = "1.0.0")]
1982 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1983 #[must_use = "this returns the result of the operation, \
1984 without modifying the original"]
1985 #[inline(always)]
1986 #[cfg(not(feature = "ferrocene_certified"))]
1987 pub const fn wrapping_add(self, rhs: Self) -> Self {
1988 intrinsics::wrapping_add(self, rhs)
1989 }
1990
1991 /// Wrapping (modular) addition with an unsigned integer. Computes
1992 /// `self + rhs`, wrapping around at the boundary of the type.
1993 ///
1994 /// # Examples
1995 ///
1996 /// ```
1997 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_add_unsigned(27), 127);")]
1998 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.wrapping_add_unsigned(2), ", stringify!($SelfT), "::MIN + 1);")]
1999 /// ```
2000 #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
2001 #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
2002 #[must_use = "this returns the result of the operation, \
2003 without modifying the original"]
2004 #[inline(always)]
2005 #[cfg(not(feature = "ferrocene_certified"))]
2006 pub const fn wrapping_add_unsigned(self, rhs: $UnsignedT) -> Self {
2007 self.wrapping_add(rhs as Self)
2008 }
2009
2010 /// Wrapping (modular) subtraction. Computes `self - rhs`, wrapping around at the
2011 /// boundary of the type.
2012 ///
2013 /// # Examples
2014 ///
2015 /// ```
2016 #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".wrapping_sub(127), -127);")]
2017 #[doc = concat!("assert_eq!((-2", stringify!($SelfT), ").wrapping_sub(", stringify!($SelfT), "::MAX), ", stringify!($SelfT), "::MAX);")]
2018 /// ```
2019 #[stable(feature = "rust1", since = "1.0.0")]
2020 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2021 #[must_use = "this returns the result of the operation, \
2022 without modifying the original"]
2023 #[inline(always)]
2024 #[cfg(not(feature = "ferrocene_certified"))]
2025 pub const fn wrapping_sub(self, rhs: Self) -> Self {
2026 intrinsics::wrapping_sub(self, rhs)
2027 }
2028
2029 /// Wrapping (modular) subtraction with an unsigned integer. Computes
2030 /// `self - rhs`, wrapping around at the boundary of the type.
2031 ///
2032 /// # Examples
2033 ///
2034 /// ```
2035 #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".wrapping_sub_unsigned(127), -127);")]
2036 #[doc = concat!("assert_eq!((-2", stringify!($SelfT), ").wrapping_sub_unsigned(", stringify!($UnsignedT), "::MAX), -1);")]
2037 /// ```
2038 #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
2039 #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
2040 #[must_use = "this returns the result of the operation, \
2041 without modifying the original"]
2042 #[inline(always)]
2043 #[cfg(not(feature = "ferrocene_certified"))]
2044 pub const fn wrapping_sub_unsigned(self, rhs: $UnsignedT) -> Self {
2045 self.wrapping_sub(rhs as Self)
2046 }
2047
2048 /// Wrapping (modular) multiplication. Computes `self * rhs`, wrapping around at
2049 /// the boundary of the type.
2050 ///
2051 /// # Examples
2052 ///
2053 /// ```
2054 #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".wrapping_mul(12), 120);")]
2055 /// assert_eq!(11i8.wrapping_mul(12), -124);
2056 /// ```
2057 #[stable(feature = "rust1", since = "1.0.0")]
2058 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2059 #[must_use = "this returns the result of the operation, \
2060 without modifying the original"]
2061 #[inline(always)]
2062 #[cfg(not(feature = "ferrocene_certified"))]
2063 pub const fn wrapping_mul(self, rhs: Self) -> Self {
2064 intrinsics::wrapping_mul(self, rhs)
2065 }
2066
2067 /// Wrapping (modular) division. Computes `self / rhs`, wrapping around at the
2068 /// boundary of the type.
2069 ///
2070 /// The only case where such wrapping can occur is when one divides `MIN / -1` on a signed type (where
2071 /// `MIN` is the negative minimal value for the type); this is equivalent to `-MIN`, a positive value
2072 /// that is too large to represent in the type. In such a case, this function returns `MIN` itself.
2073 ///
2074 /// # Panics
2075 ///
2076 /// This function will panic if `rhs` is zero.
2077 ///
2078 /// # Examples
2079 ///
2080 /// ```
2081 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div(10), 10);")]
2082 /// assert_eq!((-128i8).wrapping_div(-1), -128);
2083 /// ```
2084 #[stable(feature = "num_wrapping", since = "1.2.0")]
2085 #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")]
2086 #[must_use = "this returns the result of the operation, \
2087 without modifying the original"]
2088 #[inline]
2089 #[cfg(not(feature = "ferrocene_certified"))]
2090 pub const fn wrapping_div(self, rhs: Self) -> Self {
2091 self.overflowing_div(rhs).0
2092 }
2093
2094 /// Wrapping Euclidean division. Computes `self.div_euclid(rhs)`,
2095 /// wrapping around at the boundary of the type.
2096 ///
2097 /// Wrapping will only occur in `MIN / -1` on a signed type (where `MIN` is the negative minimal value
2098 /// for the type). This is equivalent to `-MIN`, a positive value that is too large to represent in the
2099 /// type. In this case, this method returns `MIN` itself.
2100 ///
2101 /// # Panics
2102 ///
2103 /// This function will panic if `rhs` is zero.
2104 ///
2105 /// # Examples
2106 ///
2107 /// ```
2108 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div_euclid(10), 10);")]
2109 /// assert_eq!((-128i8).wrapping_div_euclid(-1), -128);
2110 /// ```
2111 #[stable(feature = "euclidean_division", since = "1.38.0")]
2112 #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
2113 #[must_use = "this returns the result of the operation, \
2114 without modifying the original"]
2115 #[inline]
2116 #[cfg(not(feature = "ferrocene_certified"))]
2117 pub const fn wrapping_div_euclid(self, rhs: Self) -> Self {
2118 self.overflowing_div_euclid(rhs).0
2119 }
2120
2121 /// Wrapping (modular) remainder. Computes `self % rhs`, wrapping around at the
2122 /// boundary of the type.
2123 ///
2124 /// Such wrap-around never actually occurs mathematically; implementation artifacts make `x % y`
2125 /// invalid for `MIN / -1` on a signed type (where `MIN` is the negative minimal value). In such a case,
2126 /// this function returns `0`.
2127 ///
2128 /// # Panics
2129 ///
2130 /// This function will panic if `rhs` is zero.
2131 ///
2132 /// # Examples
2133 ///
2134 /// ```
2135 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem(10), 0);")]
2136 /// assert_eq!((-128i8).wrapping_rem(-1), 0);
2137 /// ```
2138 #[stable(feature = "num_wrapping", since = "1.2.0")]
2139 #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")]
2140 #[must_use = "this returns the result of the operation, \
2141 without modifying the original"]
2142 #[inline]
2143 #[cfg(not(feature = "ferrocene_certified"))]
2144 pub const fn wrapping_rem(self, rhs: Self) -> Self {
2145 self.overflowing_rem(rhs).0
2146 }
2147
2148 /// Wrapping Euclidean remainder. Computes `self.rem_euclid(rhs)`, wrapping around
2149 /// at the boundary of the type.
2150 ///
2151 /// Wrapping will only occur in `MIN % -1` on a signed type (where `MIN` is the negative minimal value
2152 /// for the type). In this case, this method returns 0.
2153 ///
2154 /// # Panics
2155 ///
2156 /// This function will panic if `rhs` is zero.
2157 ///
2158 /// # Examples
2159 ///
2160 /// ```
2161 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem_euclid(10), 0);")]
2162 /// assert_eq!((-128i8).wrapping_rem_euclid(-1), 0);
2163 /// ```
2164 #[stable(feature = "euclidean_division", since = "1.38.0")]
2165 #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
2166 #[must_use = "this returns the result of the operation, \
2167 without modifying the original"]
2168 #[inline]
2169 #[cfg(not(feature = "ferrocene_certified"))]
2170 pub const fn wrapping_rem_euclid(self, rhs: Self) -> Self {
2171 self.overflowing_rem_euclid(rhs).0
2172 }
2173
2174 /// Wrapping (modular) negation. Computes `-self`, wrapping around at the boundary
2175 /// of the type.
2176 ///
2177 /// The only case where such wrapping can occur is when one negates `MIN` on a signed type (where `MIN`
2178 /// is the negative minimal value for the type); this is a positive value that is too large to represent
2179 /// in the type. In such a case, this function returns `MIN` itself.
2180 ///
2181 /// # Examples
2182 ///
2183 /// ```
2184 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_neg(), -100);")]
2185 #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").wrapping_neg(), 100);")]
2186 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.wrapping_neg(), ", stringify!($SelfT), "::MIN);")]
2187 /// ```
2188 #[stable(feature = "num_wrapping", since = "1.2.0")]
2189 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2190 #[must_use = "this returns the result of the operation, \
2191 without modifying the original"]
2192 #[inline(always)]
2193 #[cfg(not(feature = "ferrocene_certified"))]
2194 pub const fn wrapping_neg(self) -> Self {
2195 (0 as $SelfT).wrapping_sub(self)
2196 }
2197
2198 /// Panic-free bitwise shift-left; yields `self << mask(rhs)`, where `mask` removes
2199 /// any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type.
2200 ///
2201 /// Note that this is *not* the same as a rotate-left; the RHS of a wrapping shift-left is restricted to
2202 /// the range of the type, rather than the bits shifted out of the LHS being returned to the other end.
2203 /// The primitive integer types all implement a [`rotate_left`](Self::rotate_left) function,
2204 /// which may be what you want instead.
2205 ///
2206 /// # Examples
2207 ///
2208 /// ```
2209 #[doc = concat!("assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(7), -128);")]
2210 #[doc = concat!("assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(128), -1);")]
2211 /// ```
2212 #[stable(feature = "num_wrapping", since = "1.2.0")]
2213 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2214 #[must_use = "this returns the result of the operation, \
2215 without modifying the original"]
2216 #[inline(always)]
2217 #[cfg(not(feature = "ferrocene_certified"))]
2218 pub const fn wrapping_shl(self, rhs: u32) -> Self {
2219 // SAFETY: the masking by the bitsize of the type ensures that we do not shift
2220 // out of bounds
2221 unsafe {
2222 self.unchecked_shl(rhs & (Self::BITS - 1))
2223 }
2224 }
2225
2226 /// Panic-free bitwise shift-right; yields `self >> mask(rhs)`, where `mask`
2227 /// removes any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type.
2228 ///
2229 /// Note that this is *not* the same as a rotate-right; the RHS of a wrapping shift-right is restricted
2230 /// to the range of the type, rather than the bits shifted out of the LHS being returned to the other
2231 /// end. The primitive integer types all implement a [`rotate_right`](Self::rotate_right) function,
2232 /// which may be what you want instead.
2233 ///
2234 /// # Examples
2235 ///
2236 /// ```
2237 #[doc = concat!("assert_eq!((-128", stringify!($SelfT), ").wrapping_shr(7), -1);")]
2238 /// assert_eq!((-128i16).wrapping_shr(64), -128);
2239 /// ```
2240 #[stable(feature = "num_wrapping", since = "1.2.0")]
2241 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2242 #[must_use = "this returns the result of the operation, \
2243 without modifying the original"]
2244 #[inline(always)]
2245 #[cfg(not(feature = "ferrocene_certified"))]
2246 pub const fn wrapping_shr(self, rhs: u32) -> Self {
2247 // SAFETY: the masking by the bitsize of the type ensures that we do not shift
2248 // out of bounds
2249 unsafe {
2250 self.unchecked_shr(rhs & (Self::BITS - 1))
2251 }
2252 }
2253
2254 /// Wrapping (modular) absolute value. Computes `self.abs()`, wrapping around at
2255 /// the boundary of the type.
2256 ///
2257 /// The only case where such wrapping can occur is when one takes the absolute value of the negative
2258 /// minimal value for the type; this is a positive value that is too large to represent in the type. In
2259 /// such a case, this function returns `MIN` itself.
2260 ///
2261 /// # Examples
2262 ///
2263 /// ```
2264 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_abs(), 100);")]
2265 #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").wrapping_abs(), 100);")]
2266 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.wrapping_abs(), ", stringify!($SelfT), "::MIN);")]
2267 /// assert_eq!((-128i8).wrapping_abs() as u8, 128);
2268 /// ```
2269 #[stable(feature = "no_panic_abs", since = "1.13.0")]
2270 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2271 #[must_use = "this returns the result of the operation, \
2272 without modifying the original"]
2273 #[allow(unused_attributes)]
2274 #[inline]
2275 #[cfg(not(feature = "ferrocene_certified"))]
2276 pub const fn wrapping_abs(self) -> Self {
2277 if self.is_negative() {
2278 self.wrapping_neg()
2279 } else {
2280 self
2281 }
2282 }
2283
2284 /// Computes the absolute value of `self` without any wrapping
2285 /// or panicking.
2286 ///
2287 ///
2288 /// # Examples
2289 ///
2290 /// ```
2291 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".unsigned_abs(), 100", stringify!($UnsignedT), ");")]
2292 #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").unsigned_abs(), 100", stringify!($UnsignedT), ");")]
2293 /// assert_eq!((-128i8).unsigned_abs(), 128u8);
2294 /// ```
2295 #[stable(feature = "unsigned_abs", since = "1.51.0")]
2296 #[rustc_const_stable(feature = "unsigned_abs", since = "1.51.0")]
2297 #[must_use = "this returns the result of the operation, \
2298 without modifying the original"]
2299 #[inline]
2300 #[cfg(not(feature = "ferrocene_certified"))]
2301 pub const fn unsigned_abs(self) -> $UnsignedT {
2302 self.wrapping_abs() as $UnsignedT
2303 }
2304
2305 /// Wrapping (modular) exponentiation. Computes `self.pow(exp)`,
2306 /// wrapping around at the boundary of the type.
2307 ///
2308 /// # Examples
2309 ///
2310 /// ```
2311 #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".wrapping_pow(4), 81);")]
2312 /// assert_eq!(3i8.wrapping_pow(5), -13);
2313 /// assert_eq!(3i8.wrapping_pow(6), -39);
2314 /// ```
2315 #[stable(feature = "no_panic_pow", since = "1.34.0")]
2316 #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
2317 #[must_use = "this returns the result of the operation, \
2318 without modifying the original"]
2319 #[inline]
2320 #[cfg(not(feature = "ferrocene_certified"))]
2321 pub const fn wrapping_pow(self, mut exp: u32) -> Self {
2322 if exp == 0 {
2323 return 1;
2324 }
2325 let mut base = self;
2326 let mut acc: Self = 1;
2327
2328 if intrinsics::is_val_statically_known(exp) {
2329 while exp > 1 {
2330 if (exp & 1) == 1 {
2331 acc = acc.wrapping_mul(base);
2332 }
2333 exp /= 2;
2334 base = base.wrapping_mul(base);
2335 }
2336
2337 // since exp!=0, finally the exp must be 1.
2338 // Deal with the final bit of the exponent separately, since
2339 // squaring the base afterwards is not necessary.
2340 acc.wrapping_mul(base)
2341 } else {
2342 // This is faster than the above when the exponent is not known
2343 // at compile time. We can't use the same code for the constant
2344 // exponent case because LLVM is currently unable to unroll
2345 // this loop.
2346 loop {
2347 if (exp & 1) == 1 {
2348 acc = acc.wrapping_mul(base);
2349 // since exp!=0, finally the exp must be 1.
2350 if exp == 1 {
2351 return acc;
2352 }
2353 }
2354 exp /= 2;
2355 base = base.wrapping_mul(base);
2356 }
2357 }
2358 }
2359
2360 /// Calculates `self` + `rhs`.
2361 ///
2362 /// Returns a tuple of the addition along with a boolean indicating
2363 /// whether an arithmetic overflow would occur. If an overflow would have
2364 /// occurred then the wrapped value is returned.
2365 ///
2366 /// # Examples
2367 ///
2368 /// ```
2369 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_add(2), (7, false));")]
2370 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.overflowing_add(1), (", stringify!($SelfT), "::MIN, true));")]
2371 /// ```
2372 #[stable(feature = "wrapping", since = "1.7.0")]
2373 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2374 #[must_use = "this returns the result of the operation, \
2375 without modifying the original"]
2376 #[inline(always)]
2377 #[cfg(not(feature = "ferrocene_certified"))]
2378 pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) {
2379 let (a, b) = intrinsics::add_with_overflow(self as $ActualT, rhs as $ActualT);
2380 (a as Self, b)
2381 }
2382
2383 /// Calculates `self` + `rhs` + `carry` and checks for overflow.
2384 ///
2385 /// Performs "ternary addition" of two integer operands and a carry-in
2386 /// bit, and returns a tuple of the sum along with a boolean indicating
2387 /// whether an arithmetic overflow would occur. On overflow, the wrapped
2388 /// value is returned.
2389 ///
2390 /// This allows chaining together multiple additions to create a wider
2391 /// addition, and can be useful for bignum addition. This method should
2392 /// only be used for the most significant word; for the less significant
2393 /// words the unsigned method
2394 #[doc = concat!("[`", stringify!($UnsignedT), "::carrying_add`]")]
2395 /// should be used.
2396 ///
2397 /// The output boolean returned by this method is *not* a carry flag,
2398 /// and should *not* be added to a more significant word.
2399 ///
2400 /// If the input carry is false, this method is equivalent to
2401 /// [`overflowing_add`](Self::overflowing_add).
2402 ///
2403 /// # Examples
2404 ///
2405 /// ```
2406 /// #![feature(bigint_helper_methods)]
2407 /// // Only the most significant word is signed.
2408 /// //
2409 #[doc = concat!("// 10 MAX (a = 10 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")]
2410 #[doc = concat!("// + -5 9 (b = -5 × 2^", stringify!($BITS), " + 9)")]
2411 /// // ---------
2412 #[doc = concat!("// 6 8 (sum = 6 × 2^", stringify!($BITS), " + 8)")]
2413 ///
2414 #[doc = concat!("let (a1, a0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (10, ", stringify!($UnsignedT), "::MAX);")]
2415 #[doc = concat!("let (b1, b0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (-5, 9);")]
2416 /// let carry0 = false;
2417 ///
2418 #[doc = concat!("// ", stringify!($UnsignedT), "::carrying_add for the less significant words")]
2419 /// let (sum0, carry1) = a0.carrying_add(b0, carry0);
2420 /// assert_eq!(carry1, true);
2421 ///
2422 #[doc = concat!("// ", stringify!($SelfT), "::carrying_add for the most significant word")]
2423 /// let (sum1, overflow) = a1.carrying_add(b1, carry1);
2424 /// assert_eq!(overflow, false);
2425 ///
2426 /// assert_eq!((sum1, sum0), (6, 8));
2427 /// ```
2428 #[unstable(feature = "bigint_helper_methods", issue = "85532")]
2429 #[must_use = "this returns the result of the operation, \
2430 without modifying the original"]
2431 #[inline]
2432 #[cfg(not(feature = "ferrocene_certified"))]
2433 pub const fn carrying_add(self, rhs: Self, carry: bool) -> (Self, bool) {
2434 // note: longer-term this should be done via an intrinsic.
2435 // note: no intermediate overflow is required (https://github.com/rust-lang/rust/issues/85532#issuecomment-1032214946).
2436 let (a, b) = self.overflowing_add(rhs);
2437 let (c, d) = a.overflowing_add(carry as $SelfT);
2438 (c, b != d)
2439 }
2440
2441 /// Calculates `self` + `rhs` with an unsigned `rhs`.
2442 ///
2443 /// Returns a tuple of the addition along with a boolean indicating
2444 /// whether an arithmetic overflow would occur. If an overflow would
2445 /// have occurred then the wrapped value is returned.
2446 ///
2447 /// # Examples
2448 ///
2449 /// ```
2450 #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".overflowing_add_unsigned(2), (3, false));")]
2451 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN).overflowing_add_unsigned(", stringify!($UnsignedT), "::MAX), (", stringify!($SelfT), "::MAX, false));")]
2452 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).overflowing_add_unsigned(3), (", stringify!($SelfT), "::MIN, true));")]
2453 /// ```
2454 #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
2455 #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
2456 #[must_use = "this returns the result of the operation, \
2457 without modifying the original"]
2458 #[inline]
2459 #[cfg(not(feature = "ferrocene_certified"))]
2460 pub const fn overflowing_add_unsigned(self, rhs: $UnsignedT) -> (Self, bool) {
2461 let rhs = rhs as Self;
2462 let (res, overflowed) = self.overflowing_add(rhs);
2463 (res, overflowed ^ (rhs < 0))
2464 }
2465
2466 /// Calculates `self` - `rhs`.
2467 ///
2468 /// Returns a tuple of the subtraction along with a boolean indicating whether an arithmetic overflow
2469 /// would occur. If an overflow would have occurred then the wrapped value is returned.
2470 ///
2471 /// # Examples
2472 ///
2473 /// ```
2474 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_sub(2), (3, false));")]
2475 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_sub(1), (", stringify!($SelfT), "::MAX, true));")]
2476 /// ```
2477 #[stable(feature = "wrapping", since = "1.7.0")]
2478 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2479 #[must_use = "this returns the result of the operation, \
2480 without modifying the original"]
2481 #[inline(always)]
2482 #[cfg(not(feature = "ferrocene_certified"))]
2483 pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
2484 let (a, b) = intrinsics::sub_with_overflow(self as $ActualT, rhs as $ActualT);
2485 (a as Self, b)
2486 }
2487
2488 /// Calculates `self` − `rhs` − `borrow` and checks for
2489 /// overflow.
2490 ///
2491 /// Performs "ternary subtraction" by subtracting both an integer
2492 /// operand and a borrow-in bit from `self`, and returns a tuple of the
2493 /// difference along with a boolean indicating whether an arithmetic
2494 /// overflow would occur. On overflow, the wrapped value is returned.
2495 ///
2496 /// This allows chaining together multiple subtractions to create a
2497 /// wider subtraction, and can be useful for bignum subtraction. This
2498 /// method should only be used for the most significant word; for the
2499 /// less significant words the unsigned method
2500 #[doc = concat!("[`", stringify!($UnsignedT), "::borrowing_sub`]")]
2501 /// should be used.
2502 ///
2503 /// The output boolean returned by this method is *not* a borrow flag,
2504 /// and should *not* be subtracted from a more significant word.
2505 ///
2506 /// If the input borrow is false, this method is equivalent to
2507 /// [`overflowing_sub`](Self::overflowing_sub).
2508 ///
2509 /// # Examples
2510 ///
2511 /// ```
2512 /// #![feature(bigint_helper_methods)]
2513 /// // Only the most significant word is signed.
2514 /// //
2515 #[doc = concat!("// 6 8 (a = 6 × 2^", stringify!($BITS), " + 8)")]
2516 #[doc = concat!("// - -5 9 (b = -5 × 2^", stringify!($BITS), " + 9)")]
2517 /// // ---------
2518 #[doc = concat!("// 10 MAX (diff = 10 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")]
2519 ///
2520 #[doc = concat!("let (a1, a0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (6, 8);")]
2521 #[doc = concat!("let (b1, b0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (-5, 9);")]
2522 /// let borrow0 = false;
2523 ///
2524 #[doc = concat!("// ", stringify!($UnsignedT), "::borrowing_sub for the less significant words")]
2525 /// let (diff0, borrow1) = a0.borrowing_sub(b0, borrow0);
2526 /// assert_eq!(borrow1, true);
2527 ///
2528 #[doc = concat!("// ", stringify!($SelfT), "::borrowing_sub for the most significant word")]
2529 /// let (diff1, overflow) = a1.borrowing_sub(b1, borrow1);
2530 /// assert_eq!(overflow, false);
2531 ///
2532 #[doc = concat!("assert_eq!((diff1, diff0), (10, ", stringify!($UnsignedT), "::MAX));")]
2533 /// ```
2534 #[unstable(feature = "bigint_helper_methods", issue = "85532")]
2535 #[must_use = "this returns the result of the operation, \
2536 without modifying the original"]
2537 #[inline]
2538 #[cfg(not(feature = "ferrocene_certified"))]
2539 pub const fn borrowing_sub(self, rhs: Self, borrow: bool) -> (Self, bool) {
2540 // note: longer-term this should be done via an intrinsic.
2541 // note: no intermediate overflow is required (https://github.com/rust-lang/rust/issues/85532#issuecomment-1032214946).
2542 let (a, b) = self.overflowing_sub(rhs);
2543 let (c, d) = a.overflowing_sub(borrow as $SelfT);
2544 (c, b != d)
2545 }
2546
2547 /// Calculates `self` - `rhs` with an unsigned `rhs`.
2548 ///
2549 /// Returns a tuple of the subtraction along with a boolean indicating
2550 /// whether an arithmetic overflow would occur. If an overflow would
2551 /// have occurred then the wrapped value is returned.
2552 ///
2553 /// # Examples
2554 ///
2555 /// ```
2556 #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".overflowing_sub_unsigned(2), (-1, false));")]
2557 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX).overflowing_sub_unsigned(", stringify!($UnsignedT), "::MAX), (", stringify!($SelfT), "::MIN, false));")]
2558 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).overflowing_sub_unsigned(3), (", stringify!($SelfT), "::MAX, true));")]
2559 /// ```
2560 #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
2561 #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
2562 #[must_use = "this returns the result of the operation, \
2563 without modifying the original"]
2564 #[inline]
2565 #[cfg(not(feature = "ferrocene_certified"))]
2566 pub const fn overflowing_sub_unsigned(self, rhs: $UnsignedT) -> (Self, bool) {
2567 let rhs = rhs as Self;
2568 let (res, overflowed) = self.overflowing_sub(rhs);
2569 (res, overflowed ^ (rhs < 0))
2570 }
2571
2572 /// Calculates the multiplication of `self` and `rhs`.
2573 ///
2574 /// Returns a tuple of the multiplication along with a boolean indicating whether an arithmetic overflow
2575 /// would occur. If an overflow would have occurred then the wrapped value is returned.
2576 ///
2577 /// # Examples
2578 ///
2579 /// ```
2580 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_mul(2), (10, false));")]
2581 /// assert_eq!(1_000_000_000i32.overflowing_mul(10), (1410065408, true));
2582 /// ```
2583 #[stable(feature = "wrapping", since = "1.7.0")]
2584 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2585 #[must_use = "this returns the result of the operation, \
2586 without modifying the original"]
2587 #[inline(always)]
2588 #[cfg(not(feature = "ferrocene_certified"))]
2589 pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
2590 let (a, b) = intrinsics::mul_with_overflow(self as $ActualT, rhs as $ActualT);
2591 (a as Self, b)
2592 }
2593
2594 /// Calculates the complete product `self * rhs` without the possibility to overflow.
2595 ///
2596 /// This returns the low-order (wrapping) bits and the high-order (overflow) bits
2597 /// of the result as two separate values, in that order.
2598 ///
2599 /// If you also need to add a carry to the wide result, then you want
2600 /// [`Self::carrying_mul`] instead.
2601 ///
2602 /// # Examples
2603 ///
2604 /// Please note that this example is shared between integer types.
2605 /// Which explains why `i32` is used here.
2606 ///
2607 /// ```
2608 /// #![feature(bigint_helper_methods)]
2609 /// assert_eq!(5i32.widening_mul(-2), (4294967286, -1));
2610 /// assert_eq!(1_000_000_000i32.widening_mul(-10), (2884901888, -3));
2611 /// ```
2612 #[unstable(feature = "bigint_helper_methods", issue = "85532")]
2613 #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")]
2614 #[must_use = "this returns the result of the operation, \
2615 without modifying the original"]
2616 #[inline]
2617 #[cfg(not(feature = "ferrocene_certified"))]
2618 pub const fn widening_mul(self, rhs: Self) -> ($UnsignedT, Self) {
2619 Self::carrying_mul_add(self, rhs, 0, 0)
2620 }
2621
2622 /// Calculates the "full multiplication" `self * rhs + carry`
2623 /// without the possibility to overflow.
2624 ///
2625 /// This returns the low-order (wrapping) bits and the high-order (overflow) bits
2626 /// of the result as two separate values, in that order.
2627 ///
2628 /// Performs "long multiplication" which takes in an extra amount to add, and may return an
2629 /// additional amount of overflow. This allows for chaining together multiple
2630 /// multiplications to create "big integers" which represent larger values.
2631 ///
2632 /// If you don't need the `carry`, then you can use [`Self::widening_mul`] instead.
2633 ///
2634 /// # Examples
2635 ///
2636 /// Please note that this example is shared between integer types.
2637 /// Which explains why `i32` is used here.
2638 ///
2639 /// ```
2640 /// #![feature(bigint_helper_methods)]
2641 /// assert_eq!(5i32.carrying_mul(-2, 0), (4294967286, -1));
2642 /// assert_eq!(5i32.carrying_mul(-2, 10), (0, 0));
2643 /// assert_eq!(1_000_000_000i32.carrying_mul(-10, 0), (2884901888, -3));
2644 /// assert_eq!(1_000_000_000i32.carrying_mul(-10, 10), (2884901898, -3));
2645 #[doc = concat!("assert_eq!(",
2646 stringify!($SelfT), "::MAX.carrying_mul(", stringify!($SelfT), "::MAX, ", stringify!($SelfT), "::MAX), ",
2647 "(", stringify!($SelfT), "::MAX.unsigned_abs() + 1, ", stringify!($SelfT), "::MAX / 2));"
2648 )]
2649 /// ```
2650 #[unstable(feature = "bigint_helper_methods", issue = "85532")]
2651 #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")]
2652 #[must_use = "this returns the result of the operation, \
2653 without modifying the original"]
2654 #[inline]
2655 #[cfg(not(feature = "ferrocene_certified"))]
2656 pub const fn carrying_mul(self, rhs: Self, carry: Self) -> ($UnsignedT, Self) {
2657 Self::carrying_mul_add(self, rhs, carry, 0)
2658 }
2659
2660 /// Calculates the "full multiplication" `self * rhs + carry1 + carry2`
2661 /// without the possibility to overflow.
2662 ///
2663 /// This returns the low-order (wrapping) bits and the high-order (overflow) bits
2664 /// of the result as two separate values, in that order.
2665 ///
2666 /// Performs "long multiplication" which takes in an extra amount to add, and may return an
2667 /// additional amount of overflow. This allows for chaining together multiple
2668 /// multiplications to create "big integers" which represent larger values.
2669 ///
2670 /// If you don't need either `carry`, then you can use [`Self::widening_mul`] instead,
2671 /// and if you only need one `carry`, then you can use [`Self::carrying_mul`] instead.
2672 ///
2673 /// # Examples
2674 ///
2675 /// Please note that this example is shared between integer types.
2676 /// Which explains why `i32` is used here.
2677 ///
2678 /// ```
2679 /// #![feature(bigint_helper_methods)]
2680 /// assert_eq!(5i32.carrying_mul_add(-2, 0, 0), (4294967286, -1));
2681 /// assert_eq!(5i32.carrying_mul_add(-2, 10, 10), (10, 0));
2682 /// assert_eq!(1_000_000_000i32.carrying_mul_add(-10, 0, 0), (2884901888, -3));
2683 /// assert_eq!(1_000_000_000i32.carrying_mul_add(-10, 10, 10), (2884901908, -3));
2684 #[doc = concat!("assert_eq!(",
2685 stringify!($SelfT), "::MAX.carrying_mul_add(", stringify!($SelfT), "::MAX, ", stringify!($SelfT), "::MAX, ", stringify!($SelfT), "::MAX), ",
2686 "(", stringify!($UnsignedT), "::MAX, ", stringify!($SelfT), "::MAX / 2));"
2687 )]
2688 /// ```
2689 #[unstable(feature = "bigint_helper_methods", issue = "85532")]
2690 #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")]
2691 #[must_use = "this returns the result of the operation, \
2692 without modifying the original"]
2693 #[inline]
2694 #[cfg(not(feature = "ferrocene_certified"))]
2695 pub const fn carrying_mul_add(self, rhs: Self, carry: Self, add: Self) -> ($UnsignedT, Self) {
2696 intrinsics::carrying_mul_add(self, rhs, carry, add)
2697 }
2698
2699 /// Calculates the divisor when `self` is divided by `rhs`.
2700 ///
2701 /// Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would
2702 /// occur. If an overflow would occur then self is returned.
2703 ///
2704 /// # Panics
2705 ///
2706 /// This function will panic if `rhs` is zero.
2707 ///
2708 /// # Examples
2709 ///
2710 /// ```
2711 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div(2), (2, false));")]
2712 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div(-1), (", stringify!($SelfT), "::MIN, true));")]
2713 /// ```
2714 #[inline]
2715 #[stable(feature = "wrapping", since = "1.7.0")]
2716 #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")]
2717 #[must_use = "this returns the result of the operation, \
2718 without modifying the original"]
2719 #[cfg(not(feature = "ferrocene_certified"))]
2720 pub const fn overflowing_div(self, rhs: Self) -> (Self, bool) {
2721 // Using `&` helps LLVM see that it is the same check made in division.
2722 if intrinsics::unlikely((self == Self::MIN) & (rhs == -1)) {
2723 (self, true)
2724 } else {
2725 (self / rhs, false)
2726 }
2727 }
2728
2729 /// Calculates the quotient of Euclidean division `self.div_euclid(rhs)`.
2730 ///
2731 /// Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would
2732 /// occur. If an overflow would occur then `self` is returned.
2733 ///
2734 /// # Panics
2735 ///
2736 /// This function will panic if `rhs` is zero.
2737 ///
2738 /// # Examples
2739 ///
2740 /// ```
2741 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div_euclid(2), (2, false));")]
2742 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div_euclid(-1), (", stringify!($SelfT), "::MIN, true));")]
2743 /// ```
2744 #[inline]
2745 #[stable(feature = "euclidean_division", since = "1.38.0")]
2746 #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
2747 #[must_use = "this returns the result of the operation, \
2748 without modifying the original"]
2749 #[cfg(not(feature = "ferrocene_certified"))]
2750 pub const fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) {
2751 // Using `&` helps LLVM see that it is the same check made in division.
2752 if intrinsics::unlikely((self == Self::MIN) & (rhs == -1)) {
2753 (self, true)
2754 } else {
2755 (self.div_euclid(rhs), false)
2756 }
2757 }
2758
2759 /// Calculates the remainder when `self` is divided by `rhs`.
2760 ///
2761 /// Returns a tuple of the remainder after dividing along with a boolean indicating whether an
2762 /// arithmetic overflow would occur. If an overflow would occur then 0 is returned.
2763 ///
2764 /// # Panics
2765 ///
2766 /// This function will panic if `rhs` is zero.
2767 ///
2768 /// # Examples
2769 ///
2770 /// ```
2771 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem(2), (1, false));")]
2772 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem(-1), (0, true));")]
2773 /// ```
2774 #[inline]
2775 #[stable(feature = "wrapping", since = "1.7.0")]
2776 #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")]
2777 #[must_use = "this returns the result of the operation, \
2778 without modifying the original"]
2779 #[cfg(not(feature = "ferrocene_certified"))]
2780 pub const fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
2781 if intrinsics::unlikely(rhs == -1) {
2782 (0, self == Self::MIN)
2783 } else {
2784 (self % rhs, false)
2785 }
2786 }
2787
2788
2789 /// Overflowing Euclidean remainder. Calculates `self.rem_euclid(rhs)`.
2790 ///
2791 /// Returns a tuple of the remainder after dividing along with a boolean indicating whether an
2792 /// arithmetic overflow would occur. If an overflow would occur then 0 is returned.
2793 ///
2794 /// # Panics
2795 ///
2796 /// This function will panic if `rhs` is zero.
2797 ///
2798 /// # Examples
2799 ///
2800 /// ```
2801 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem_euclid(2), (1, false));")]
2802 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem_euclid(-1), (0, true));")]
2803 /// ```
2804 #[stable(feature = "euclidean_division", since = "1.38.0")]
2805 #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
2806 #[must_use = "this returns the result of the operation, \
2807 without modifying the original"]
2808 #[inline]
2809 #[track_caller]
2810 #[cfg(not(feature = "ferrocene_certified"))]
2811 pub const fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) {
2812 if intrinsics::unlikely(rhs == -1) {
2813 (0, self == Self::MIN)
2814 } else {
2815 (self.rem_euclid(rhs), false)
2816 }
2817 }
2818
2819
2820 /// Negates self, overflowing if this is equal to the minimum value.
2821 ///
2822 /// Returns a tuple of the negated version of self along with a boolean indicating whether an overflow
2823 /// happened. If `self` is the minimum value (e.g., `i32::MIN` for values of type `i32`), then the
2824 /// minimum value will be returned again and `true` will be returned for an overflow happening.
2825 ///
2826 /// # Examples
2827 ///
2828 /// ```
2829 #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".overflowing_neg(), (-2, false));")]
2830 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_neg(), (", stringify!($SelfT), "::MIN, true));")]
2831 /// ```
2832 #[inline]
2833 #[stable(feature = "wrapping", since = "1.7.0")]
2834 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2835 #[must_use = "this returns the result of the operation, \
2836 without modifying the original"]
2837 #[allow(unused_attributes)]
2838 #[cfg(not(feature = "ferrocene_certified"))]
2839 pub const fn overflowing_neg(self) -> (Self, bool) {
2840 if intrinsics::unlikely(self == Self::MIN) {
2841 (Self::MIN, true)
2842 } else {
2843 (-self, false)
2844 }
2845 }
2846
2847 /// Shifts self left by `rhs` bits.
2848 ///
2849 /// Returns a tuple of the shifted version of self along with a boolean indicating whether the shift
2850 /// value was larger than or equal to the number of bits. If the shift value is too large, then value is
2851 /// masked (N-1) where N is the number of bits, and this value is then used to perform the shift.
2852 ///
2853 /// # Examples
2854 ///
2855 /// ```
2856 #[doc = concat!("assert_eq!(0x1", stringify!($SelfT),".overflowing_shl(4), (0x10, false));")]
2857 /// assert_eq!(0x1i32.overflowing_shl(36), (0x10, true));
2858 #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shl(", stringify!($BITS_MINUS_ONE), "), (0, false));")]
2859 /// ```
2860 #[stable(feature = "wrapping", since = "1.7.0")]
2861 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2862 #[must_use = "this returns the result of the operation, \
2863 without modifying the original"]
2864 #[inline]
2865 #[cfg(not(feature = "ferrocene_certified"))]
2866 pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
2867 (self.wrapping_shl(rhs), rhs >= Self::BITS)
2868 }
2869
2870 /// Shifts self right by `rhs` bits.
2871 ///
2872 /// Returns a tuple of the shifted version of self along with a boolean indicating whether the shift
2873 /// value was larger than or equal to the number of bits. If the shift value is too large, then value is
2874 /// masked (N-1) where N is the number of bits, and this value is then used to perform the shift.
2875 ///
2876 /// # Examples
2877 ///
2878 /// ```
2879 #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(4), (0x1, false));")]
2880 /// assert_eq!(0x10i32.overflowing_shr(36), (0x1, true));
2881 /// ```
2882 #[stable(feature = "wrapping", since = "1.7.0")]
2883 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2884 #[must_use = "this returns the result of the operation, \
2885 without modifying the original"]
2886 #[inline]
2887 #[cfg(not(feature = "ferrocene_certified"))]
2888 pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
2889 (self.wrapping_shr(rhs), rhs >= Self::BITS)
2890 }
2891
2892 /// Computes the absolute value of `self`.
2893 ///
2894 /// Returns a tuple of the absolute version of self along with a boolean indicating whether an overflow
2895 /// happened. If self is the minimum value
2896 #[doc = concat!("(e.g., ", stringify!($SelfT), "::MIN for values of type ", stringify!($SelfT), "),")]
2897 /// then the minimum value will be returned again and true will be returned
2898 /// for an overflow happening.
2899 ///
2900 /// # Examples
2901 ///
2902 /// ```
2903 #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".overflowing_abs(), (10, false));")]
2904 #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").overflowing_abs(), (10, false));")]
2905 #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN).overflowing_abs(), (", stringify!($SelfT), "::MIN, true));")]
2906 /// ```
2907 #[stable(feature = "no_panic_abs", since = "1.13.0")]
2908 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2909 #[must_use = "this returns the result of the operation, \
2910 without modifying the original"]
2911 #[inline]
2912 #[cfg(not(feature = "ferrocene_certified"))]
2913 pub const fn overflowing_abs(self) -> (Self, bool) {
2914 (self.wrapping_abs(), self == Self::MIN)
2915 }
2916
2917 /// Raises self to the power of `exp`, using exponentiation by squaring.
2918 ///
2919 /// Returns a tuple of the exponentiation along with a bool indicating
2920 /// whether an overflow happened.
2921 ///
2922 /// # Examples
2923 ///
2924 /// ```
2925 #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".overflowing_pow(4), (81, false));")]
2926 /// assert_eq!(3i8.overflowing_pow(5), (-13, true));
2927 /// ```
2928 #[stable(feature = "no_panic_pow", since = "1.34.0")]
2929 #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
2930 #[must_use = "this returns the result of the operation, \
2931 without modifying the original"]
2932 #[inline]
2933 #[cfg(not(feature = "ferrocene_certified"))]
2934 pub const fn overflowing_pow(self, mut exp: u32) -> (Self, bool) {
2935 if exp == 0 {
2936 return (1,false);
2937 }
2938 let mut base = self;
2939 let mut acc: Self = 1;
2940 let mut overflown = false;
2941 // Scratch space for storing results of overflowing_mul.
2942 let mut r;
2943
2944 loop {
2945 if (exp & 1) == 1 {
2946 r = acc.overflowing_mul(base);
2947 // since exp!=0, finally the exp must be 1.
2948 if exp == 1 {
2949 r.1 |= overflown;
2950 return r;
2951 }
2952 acc = r.0;
2953 overflown |= r.1;
2954 }
2955 exp /= 2;
2956 r = base.overflowing_mul(base);
2957 base = r.0;
2958 overflown |= r.1;
2959 }
2960 }
2961
2962 /// Raises self to the power of `exp`, using exponentiation by squaring.
2963 ///
2964 /// # Examples
2965 ///
2966 /// ```
2967 #[doc = concat!("let x: ", stringify!($SelfT), " = 2; // or any other integer type")]
2968 ///
2969 /// assert_eq!(x.pow(5), 32);
2970 /// ```
2971 #[stable(feature = "rust1", since = "1.0.0")]
2972 #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
2973 #[must_use = "this returns the result of the operation, \
2974 without modifying the original"]
2975 #[inline]
2976 #[rustc_inherit_overflow_checks]
2977 #[cfg(not(feature = "ferrocene_certified"))]
2978 pub const fn pow(self, mut exp: u32) -> Self {
2979 if exp == 0 {
2980 return 1;
2981 }
2982 let mut base = self;
2983 let mut acc = 1;
2984
2985 if intrinsics::is_val_statically_known(exp) {
2986 while exp > 1 {
2987 if (exp & 1) == 1 {
2988 acc = acc * base;
2989 }
2990 exp /= 2;
2991 base = base * base;
2992 }
2993
2994 // since exp!=0, finally the exp must be 1.
2995 // Deal with the final bit of the exponent separately, since
2996 // squaring the base afterwards is not necessary and may cause a
2997 // needless overflow.
2998 acc * base
2999 } else {
3000 // This is faster than the above when the exponent is not known
3001 // at compile time. We can't use the same code for the constant
3002 // exponent case because LLVM is currently unable to unroll
3003 // this loop.
3004 loop {
3005 if (exp & 1) == 1 {
3006 acc = acc * base;
3007 // since exp!=0, finally the exp must be 1.
3008 if exp == 1 {
3009 return acc;
3010 }
3011 }
3012 exp /= 2;
3013 base = base * base;
3014 }
3015 }
3016 }
3017
3018 /// Returns the square root of the number, rounded down.
3019 ///
3020 /// # Panics
3021 ///
3022 /// This function will panic if `self` is negative.
3023 ///
3024 /// # Examples
3025 ///
3026 /// ```
3027 #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".isqrt(), 3);")]
3028 /// ```
3029 #[stable(feature = "isqrt", since = "1.84.0")]
3030 #[rustc_const_stable(feature = "isqrt", since = "1.84.0")]
3031 #[must_use = "this returns the result of the operation, \
3032 without modifying the original"]
3033 #[inline]
3034 #[track_caller]
3035 #[cfg(not(feature = "ferrocene_certified"))]
3036 pub const fn isqrt(self) -> Self {
3037 match self.checked_isqrt() {
3038 Some(sqrt) => sqrt,
3039 None => crate::num::int_sqrt::panic_for_negative_argument(),
3040 }
3041 }
3042
3043 /// Calculates the quotient of Euclidean division of `self` by `rhs`.
3044 ///
3045 /// This computes the integer `q` such that `self = q * rhs + r`, with
3046 /// `r = self.rem_euclid(rhs)` and `0 <= r < abs(rhs)`.
3047 ///
3048 /// In other words, the result is `self / rhs` rounded to the integer `q`
3049 /// such that `self >= q * rhs`.
3050 /// If `self > 0`, this is equal to rounding towards zero (the default in Rust);
3051 /// if `self < 0`, this is equal to rounding away from zero (towards +/- infinity).
3052 /// If `rhs > 0`, this is equal to rounding towards -infinity;
3053 /// if `rhs < 0`, this is equal to rounding towards +infinity.
3054 ///
3055 /// # Panics
3056 ///
3057 /// This function will panic if `rhs` is zero or if `self` is `Self::MIN`
3058 /// and `rhs` is -1. This behavior is not affected by the `overflow-checks` flag.
3059 ///
3060 /// # Examples
3061 ///
3062 /// ```
3063 #[doc = concat!("let a: ", stringify!($SelfT), " = 7; // or any other integer type")]
3064 /// let b = 4;
3065 ///
3066 /// assert_eq!(a.div_euclid(b), 1); // 7 >= 4 * 1
3067 /// assert_eq!(a.div_euclid(-b), -1); // 7 >= -4 * -1
3068 /// assert_eq!((-a).div_euclid(b), -2); // -7 >= 4 * -2
3069 /// assert_eq!((-a).div_euclid(-b), 2); // -7 >= -4 * 2
3070 /// ```
3071 #[stable(feature = "euclidean_division", since = "1.38.0")]
3072 #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
3073 #[must_use = "this returns the result of the operation, \
3074 without modifying the original"]
3075 #[inline]
3076 #[track_caller]
3077 #[cfg(not(feature = "ferrocene_certified"))]
3078 pub const fn div_euclid(self, rhs: Self) -> Self {
3079 let q = self / rhs;
3080 if self % rhs < 0 {
3081 return if rhs > 0 { q - 1 } else { q + 1 }
3082 }
3083 q
3084 }
3085
3086
3087 /// Calculates the least nonnegative remainder of `self (mod rhs)`.
3088 ///
3089 /// This is done as if by the Euclidean division algorithm -- given
3090 /// `r = self.rem_euclid(rhs)`, the result satisfies
3091 /// `self = rhs * self.div_euclid(rhs) + r` and `0 <= r < abs(rhs)`.
3092 ///
3093 /// # Panics
3094 ///
3095 /// This function will panic if `rhs` is zero or if `self` is `Self::MIN` and
3096 /// `rhs` is -1. This behavior is not affected by the `overflow-checks` flag.
3097 ///
3098 /// # Examples
3099 ///
3100 /// ```
3101 #[doc = concat!("let a: ", stringify!($SelfT), " = 7; // or any other integer type")]
3102 /// let b = 4;
3103 ///
3104 /// assert_eq!(a.rem_euclid(b), 3);
3105 /// assert_eq!((-a).rem_euclid(b), 1);
3106 /// assert_eq!(a.rem_euclid(-b), 3);
3107 /// assert_eq!((-a).rem_euclid(-b), 1);
3108 /// ```
3109 ///
3110 /// This will panic:
3111 /// ```should_panic
3112 #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.rem_euclid(-1);")]
3113 /// ```
3114 #[doc(alias = "modulo", alias = "mod")]
3115 #[stable(feature = "euclidean_division", since = "1.38.0")]
3116 #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
3117 #[must_use = "this returns the result of the operation, \
3118 without modifying the original"]
3119 #[inline]
3120 #[track_caller]
3121 #[cfg(not(feature = "ferrocene_certified"))]
3122 pub const fn rem_euclid(self, rhs: Self) -> Self {
3123 let r = self % rhs;
3124 if r < 0 {
3125 // Semantically equivalent to `if rhs < 0 { r - rhs } else { r + rhs }`.
3126 // If `rhs` is not `Self::MIN`, then `r + abs(rhs)` will not overflow
3127 // and is clearly equivalent, because `r` is negative.
3128 // Otherwise, `rhs` is `Self::MIN`, then we have
3129 // `r.wrapping_add(Self::MIN.wrapping_abs())`, which evaluates
3130 // to `r.wrapping_add(Self::MIN)`, which is equivalent to
3131 // `r - Self::MIN`, which is what we wanted (and will not overflow
3132 // for negative `r`).
3133 r.wrapping_add(rhs.wrapping_abs())
3134 } else {
3135 r
3136 }
3137 }
3138
3139 /// Calculates the quotient of `self` and `rhs`, rounding the result towards negative infinity.
3140 ///
3141 /// # Panics
3142 ///
3143 /// This function will panic if `rhs` is zero or if `self` is `Self::MIN`
3144 /// and `rhs` is -1. This behavior is not affected by the `overflow-checks` flag.
3145 ///
3146 /// # Examples
3147 ///
3148 /// ```
3149 /// #![feature(int_roundings)]
3150 #[doc = concat!("let a: ", stringify!($SelfT)," = 8;")]
3151 /// let b = 3;
3152 ///
3153 /// assert_eq!(a.div_floor(b), 2);
3154 /// assert_eq!(a.div_floor(-b), -3);
3155 /// assert_eq!((-a).div_floor(b), -3);
3156 /// assert_eq!((-a).div_floor(-b), 2);
3157 /// ```
3158 #[unstable(feature = "int_roundings", issue = "88581")]
3159 #[must_use = "this returns the result of the operation, \
3160 without modifying the original"]
3161 #[inline]
3162 #[track_caller]
3163 #[cfg(not(feature = "ferrocene_certified"))]
3164 pub const fn div_floor(self, rhs: Self) -> Self {
3165 let d = self / rhs;
3166 let r = self % rhs;
3167
3168 // If the remainder is non-zero, we need to subtract one if the
3169 // signs of self and rhs differ, as this means we rounded upwards
3170 // instead of downwards. We do this branchlessly by creating a mask
3171 // which is all-ones iff the signs differ, and 0 otherwise. Then by
3172 // adding this mask (which corresponds to the signed value -1), we
3173 // get our correction.
3174 let correction = (self ^ rhs) >> (Self::BITS - 1);
3175 if r != 0 {
3176 d + correction
3177 } else {
3178 d
3179 }
3180 }
3181
3182 /// Calculates the quotient of `self` and `rhs`, rounding the result towards positive infinity.
3183 ///
3184 /// # Panics
3185 ///
3186 /// This function will panic if `rhs` is zero or if `self` is `Self::MIN`
3187 /// and `rhs` is -1. This behavior is not affected by the `overflow-checks` flag.
3188 ///
3189 /// # Examples
3190 ///
3191 /// ```
3192 /// #![feature(int_roundings)]
3193 #[doc = concat!("let a: ", stringify!($SelfT)," = 8;")]
3194 /// let b = 3;
3195 ///
3196 /// assert_eq!(a.div_ceil(b), 3);
3197 /// assert_eq!(a.div_ceil(-b), -2);
3198 /// assert_eq!((-a).div_ceil(b), -2);
3199 /// assert_eq!((-a).div_ceil(-b), 3);
3200 /// ```
3201 #[unstable(feature = "int_roundings", issue = "88581")]
3202 #[must_use = "this returns the result of the operation, \
3203 without modifying the original"]
3204 #[inline]
3205 #[track_caller]
3206 #[cfg(not(feature = "ferrocene_certified"))]
3207 pub const fn div_ceil(self, rhs: Self) -> Self {
3208 let d = self / rhs;
3209 let r = self % rhs;
3210
3211 // When remainder is non-zero we have a.div_ceil(b) == 1 + a.div_floor(b),
3212 // so we can re-use the algorithm from div_floor, just adding 1.
3213 let correction = 1 + ((self ^ rhs) >> (Self::BITS - 1));
3214 if r != 0 {
3215 d + correction
3216 } else {
3217 d
3218 }
3219 }
3220
3221 /// If `rhs` is positive, calculates the smallest value greater than or
3222 /// equal to `self` that is a multiple of `rhs`. If `rhs` is negative,
3223 /// calculates the largest value less than or equal to `self` that is a
3224 /// multiple of `rhs`.
3225 ///
3226 /// # Panics
3227 ///
3228 /// This function will panic if `rhs` is zero.
3229 ///
3230 /// ## Overflow behavior
3231 ///
3232 /// On overflow, this function will panic if overflow checks are enabled (default in debug
3233 /// mode) and wrap if overflow checks are disabled (default in release mode).
3234 ///
3235 /// # Examples
3236 ///
3237 /// ```
3238 /// #![feature(int_roundings)]
3239 #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".next_multiple_of(8), 16);")]
3240 #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".next_multiple_of(8), 24);")]
3241 #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".next_multiple_of(-8), 16);")]
3242 #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".next_multiple_of(-8), 16);")]
3243 #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").next_multiple_of(8), -16);")]
3244 #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").next_multiple_of(8), -16);")]
3245 #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").next_multiple_of(-8), -16);")]
3246 #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").next_multiple_of(-8), -24);")]
3247 /// ```
3248 #[unstable(feature = "int_roundings", issue = "88581")]
3249 #[must_use = "this returns the result of the operation, \
3250 without modifying the original"]
3251 #[inline]
3252 #[rustc_inherit_overflow_checks]
3253 #[cfg(not(feature = "ferrocene_certified"))]
3254 pub const fn next_multiple_of(self, rhs: Self) -> Self {
3255 // This would otherwise fail when calculating `r` when self == T::MIN.
3256 if rhs == -1 {
3257 return self;
3258 }
3259
3260 let r = self % rhs;
3261 let m = if (r > 0 && rhs < 0) || (r < 0 && rhs > 0) {
3262 r + rhs
3263 } else {
3264 r
3265 };
3266
3267 if m == 0 {
3268 self
3269 } else {
3270 self + (rhs - m)
3271 }
3272 }
3273
3274 /// If `rhs` is positive, calculates the smallest value greater than or
3275 /// equal to `self` that is a multiple of `rhs`. If `rhs` is negative,
3276 /// calculates the largest value less than or equal to `self` that is a
3277 /// multiple of `rhs`. Returns `None` if `rhs` is zero or the operation
3278 /// would result in overflow.
3279 ///
3280 /// # Examples
3281 ///
3282 /// ```
3283 /// #![feature(int_roundings)]
3284 #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(16));")]
3285 #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(24));")]
3286 #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".checked_next_multiple_of(-8), Some(16));")]
3287 #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".checked_next_multiple_of(-8), Some(16));")]
3288 #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").checked_next_multiple_of(8), Some(-16));")]
3289 #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").checked_next_multiple_of(8), Some(-16));")]
3290 #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").checked_next_multiple_of(-8), Some(-16));")]
3291 #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").checked_next_multiple_of(-8), Some(-24));")]
3292 #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".checked_next_multiple_of(0), None);")]
3293 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_next_multiple_of(2), None);")]
3294 /// ```
3295 #[unstable(feature = "int_roundings", issue = "88581")]
3296 #[must_use = "this returns the result of the operation, \
3297 without modifying the original"]
3298 #[inline]
3299 #[cfg(not(feature = "ferrocene_certified"))]
3300 pub const fn checked_next_multiple_of(self, rhs: Self) -> Option<Self> {
3301 // This would otherwise fail when calculating `r` when self == T::MIN.
3302 if rhs == -1 {
3303 return Some(self);
3304 }
3305
3306 let r = try_opt!(self.checked_rem(rhs));
3307 let m = if (r > 0 && rhs < 0) || (r < 0 && rhs > 0) {
3308 // r + rhs cannot overflow because they have opposite signs
3309 r + rhs
3310 } else {
3311 r
3312 };
3313
3314 if m == 0 {
3315 Some(self)
3316 } else {
3317 // rhs - m cannot overflow because m has the same sign as rhs
3318 self.checked_add(rhs - m)
3319 }
3320 }
3321
3322 /// Returns the logarithm of the number with respect to an arbitrary base,
3323 /// rounded down.
3324 ///
3325 /// This method might not be optimized owing to implementation details;
3326 /// `ilog2` can produce results more efficiently for base 2, and `ilog10`
3327 /// can produce results more efficiently for base 10.
3328 ///
3329 /// # Panics
3330 ///
3331 /// This function will panic if `self` is less than or equal to zero,
3332 /// or if `base` is less than 2.
3333 ///
3334 /// # Examples
3335 ///
3336 /// ```
3337 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".ilog(5), 1);")]
3338 /// ```
3339 #[stable(feature = "int_log", since = "1.67.0")]
3340 #[rustc_const_stable(feature = "int_log", since = "1.67.0")]
3341 #[must_use = "this returns the result of the operation, \
3342 without modifying the original"]
3343 #[inline]
3344 #[track_caller]
3345 #[cfg(not(feature = "ferrocene_certified"))]
3346 pub const fn ilog(self, base: Self) -> u32 {
3347 assert!(base >= 2, "base of integer logarithm must be at least 2");
3348 if let Some(log) = self.checked_ilog(base) {
3349 log
3350 } else {
3351 int_log10::panic_for_nonpositive_argument()
3352 }
3353 }
3354
3355 /// Returns the base 2 logarithm of the number, rounded down.
3356 ///
3357 /// # Panics
3358 ///
3359 /// This function will panic if `self` is less than or equal to zero.
3360 ///
3361 /// # Examples
3362 ///
3363 /// ```
3364 #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".ilog2(), 1);")]
3365 /// ```
3366 #[stable(feature = "int_log", since = "1.67.0")]
3367 #[rustc_const_stable(feature = "int_log", since = "1.67.0")]
3368 #[must_use = "this returns the result of the operation, \
3369 without modifying the original"]
3370 #[inline]
3371 #[track_caller]
3372 #[cfg(not(feature = "ferrocene_certified"))]
3373 pub const fn ilog2(self) -> u32 {
3374 if let Some(log) = self.checked_ilog2() {
3375 log
3376 } else {
3377 int_log10::panic_for_nonpositive_argument()
3378 }
3379 }
3380
3381 /// Returns the base 10 logarithm of the number, rounded down.
3382 ///
3383 /// # Panics
3384 ///
3385 /// This function will panic if `self` is less than or equal to zero.
3386 ///
3387 /// # Example
3388 ///
3389 /// ```
3390 #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".ilog10(), 1);")]
3391 /// ```
3392 #[stable(feature = "int_log", since = "1.67.0")]
3393 #[rustc_const_stable(feature = "int_log", since = "1.67.0")]
3394 #[must_use = "this returns the result of the operation, \
3395 without modifying the original"]
3396 #[inline]
3397 #[track_caller]
3398 #[cfg(not(feature = "ferrocene_certified"))]
3399 pub const fn ilog10(self) -> u32 {
3400 if let Some(log) = self.checked_ilog10() {
3401 log
3402 } else {
3403 int_log10::panic_for_nonpositive_argument()
3404 }
3405 }
3406
3407 /// Returns the logarithm of the number with respect to an arbitrary base,
3408 /// rounded down.
3409 ///
3410 /// Returns `None` if the number is negative or zero, or if the base is not at least 2.
3411 ///
3412 /// This method might not be optimized owing to implementation details;
3413 /// `checked_ilog2` can produce results more efficiently for base 2, and
3414 /// `checked_ilog10` can produce results more efficiently for base 10.
3415 ///
3416 /// # Examples
3417 ///
3418 /// ```
3419 #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_ilog(5), Some(1));")]
3420 /// ```
3421 #[stable(feature = "int_log", since = "1.67.0")]
3422 #[rustc_const_stable(feature = "int_log", since = "1.67.0")]
3423 #[must_use = "this returns the result of the operation, \
3424 without modifying the original"]
3425 #[inline]
3426 #[cfg(not(feature = "ferrocene_certified"))]
3427 pub const fn checked_ilog(self, base: Self) -> Option<u32> {
3428 if self <= 0 || base <= 1 {
3429 None
3430 } else {
3431 // Delegate to the unsigned implementation.
3432 // The condition makes sure that both casts are exact.
3433 (self as $UnsignedT).checked_ilog(base as $UnsignedT)
3434 }
3435 }
3436
3437 /// Returns the base 2 logarithm of the number, rounded down.
3438 ///
3439 /// Returns `None` if the number is negative or zero.
3440 ///
3441 /// # Examples
3442 ///
3443 /// ```
3444 #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".checked_ilog2(), Some(1));")]
3445 /// ```
3446 #[stable(feature = "int_log", since = "1.67.0")]
3447 #[rustc_const_stable(feature = "int_log", since = "1.67.0")]
3448 #[must_use = "this returns the result of the operation, \
3449 without modifying the original"]
3450 #[inline]
3451 #[cfg(not(feature = "ferrocene_certified"))]
3452 pub const fn checked_ilog2(self) -> Option<u32> {
3453 if self <= 0 {
3454 None
3455 } else {
3456 // SAFETY: We just checked that this number is positive
3457 let log = (Self::BITS - 1) - unsafe { intrinsics::ctlz_nonzero(self) as u32 };
3458 Some(log)
3459 }
3460 }
3461
3462 /// Returns the base 10 logarithm of the number, rounded down.
3463 ///
3464 /// Returns `None` if the number is negative or zero.
3465 ///
3466 /// # Example
3467 ///
3468 /// ```
3469 #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".checked_ilog10(), Some(1));")]
3470 /// ```
3471 #[stable(feature = "int_log", since = "1.67.0")]
3472 #[rustc_const_stable(feature = "int_log", since = "1.67.0")]
3473 #[must_use = "this returns the result of the operation, \
3474 without modifying the original"]
3475 #[inline]
3476 #[cfg(not(feature = "ferrocene_certified"))]
3477 pub const fn checked_ilog10(self) -> Option<u32> {
3478 if self > 0 {
3479 Some(int_log10::$ActualT(self as $ActualT))
3480 } else {
3481 None
3482 }
3483 }
3484
3485 /// Computes the absolute value of `self`.
3486 ///
3487 /// # Overflow behavior
3488 ///
3489 /// The absolute value of
3490 #[doc = concat!("`", stringify!($SelfT), "::MIN`")]
3491 /// cannot be represented as an
3492 #[doc = concat!("`", stringify!($SelfT), "`,")]
3493 /// and attempting to calculate it will cause an overflow. This means
3494 /// that code in debug mode will trigger a panic on this case and
3495 /// optimized code will return
3496 #[doc = concat!("`", stringify!($SelfT), "::MIN`")]
3497 /// without a panic. If you do not want this behavior, consider
3498 /// using [`unsigned_abs`](Self::unsigned_abs) instead.
3499 ///
3500 /// # Examples
3501 ///
3502 /// ```
3503 #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".abs(), 10);")]
3504 #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").abs(), 10);")]
3505 /// ```
3506 #[stable(feature = "rust1", since = "1.0.0")]
3507 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
3508 #[allow(unused_attributes)]
3509 #[must_use = "this returns the result of the operation, \
3510 without modifying the original"]
3511 #[inline]
3512 #[rustc_inherit_overflow_checks]
3513 #[cfg(not(feature = "ferrocene_certified"))]
3514 pub const fn abs(self) -> Self {
3515 // Note that the #[rustc_inherit_overflow_checks] and #[inline]
3516 // above mean that the overflow semantics of the subtraction
3517 // depend on the crate we're being called from.
3518 if self.is_negative() {
3519 -self
3520 } else {
3521 self
3522 }
3523 }
3524
3525 /// Computes the absolute difference between `self` and `other`.
3526 ///
3527 /// This function always returns the correct answer without overflow or
3528 /// panics by returning an unsigned integer.
3529 ///
3530 /// # Examples
3531 ///
3532 /// ```
3533 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".abs_diff(80), 20", stringify!($UnsignedT), ");")]
3534 #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".abs_diff(110), 10", stringify!($UnsignedT), ");")]
3535 #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").abs_diff(80), 180", stringify!($UnsignedT), ");")]
3536 #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").abs_diff(-120), 20", stringify!($UnsignedT), ");")]
3537 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.abs_diff(", stringify!($SelfT), "::MAX), ", stringify!($UnsignedT), "::MAX);")]
3538 /// ```
3539 #[stable(feature = "int_abs_diff", since = "1.60.0")]
3540 #[rustc_const_stable(feature = "int_abs_diff", since = "1.60.0")]
3541 #[must_use = "this returns the result of the operation, \
3542 without modifying the original"]
3543 #[inline]
3544 #[cfg(not(feature = "ferrocene_certified"))]
3545 pub const fn abs_diff(self, other: Self) -> $UnsignedT {
3546 if self < other {
3547 // Converting a non-negative x from signed to unsigned by using
3548 // `x as U` is left unchanged, but a negative x is converted
3549 // to value x + 2^N. Thus if `s` and `o` are binary variables
3550 // respectively indicating whether `self` and `other` are
3551 // negative, we are computing the mathematical value:
3552 //
3553 // (other + o*2^N) - (self + s*2^N) mod 2^N
3554 // other - self + (o-s)*2^N mod 2^N
3555 // other - self mod 2^N
3556 //
3557 // Finally, taking the mod 2^N of the mathematical value of
3558 // `other - self` does not change it as it already is
3559 // in the range [0, 2^N).
3560 (other as $UnsignedT).wrapping_sub(self as $UnsignedT)
3561 } else {
3562 (self as $UnsignedT).wrapping_sub(other as $UnsignedT)
3563 }
3564 }
3565
3566 /// Returns a number representing sign of `self`.
3567 ///
3568 /// - `0` if the number is zero
3569 /// - `1` if the number is positive
3570 /// - `-1` if the number is negative
3571 ///
3572 /// # Examples
3573 ///
3574 /// ```
3575 #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".signum(), 1);")]
3576 #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".signum(), 0);")]
3577 #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").signum(), -1);")]
3578 /// ```
3579 #[stable(feature = "rust1", since = "1.0.0")]
3580 #[rustc_const_stable(feature = "const_int_sign", since = "1.47.0")]
3581 #[must_use = "this returns the result of the operation, \
3582 without modifying the original"]
3583 #[inline(always)]
3584 #[cfg(not(feature = "ferrocene_certified"))]
3585 pub const fn signum(self) -> Self {
3586 // Picking the right way to phrase this is complicated
3587 // (<https://graphics.stanford.edu/~seander/bithacks.html#CopyIntegerSign>)
3588 // so delegate it to `Ord` which is already producing -1/0/+1
3589 // exactly like we need and can be the place to deal with the complexity.
3590
3591 crate::intrinsics::three_way_compare(self, 0) as Self
3592 }
3593
3594 /// Returns `true` if `self` is positive and `false` if the number is zero or
3595 /// negative.
3596 ///
3597 /// # Examples
3598 ///
3599 /// ```
3600 #[doc = concat!("assert!(10", stringify!($SelfT), ".is_positive());")]
3601 #[doc = concat!("assert!(!(-10", stringify!($SelfT), ").is_positive());")]
3602 /// ```
3603 #[must_use]
3604 #[stable(feature = "rust1", since = "1.0.0")]
3605 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
3606 #[inline(always)]
3607 #[cfg(not(feature = "ferrocene_certified"))]
3608 pub const fn is_positive(self) -> bool { self > 0 }
3609
3610 /// Returns `true` if `self` is negative and `false` if the number is zero or
3611 /// positive.
3612 ///
3613 /// # Examples
3614 ///
3615 /// ```
3616 #[doc = concat!("assert!((-10", stringify!($SelfT), ").is_negative());")]
3617 #[doc = concat!("assert!(!10", stringify!($SelfT), ".is_negative());")]
3618 /// ```
3619 #[must_use]
3620 #[stable(feature = "rust1", since = "1.0.0")]
3621 #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
3622 #[inline(always)]
3623 #[cfg(not(feature = "ferrocene_certified"))]
3624 pub const fn is_negative(self) -> bool { self < 0 }
3625
3626 /// Returns the memory representation of this integer as a byte array in
3627 /// big-endian (network) byte order.
3628 ///
3629 #[doc = $to_xe_bytes_doc]
3630 ///
3631 /// # Examples
3632 ///
3633 /// ```
3634 #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();")]
3635 #[doc = concat!("assert_eq!(bytes, ", $be_bytes, ");")]
3636 /// ```
3637 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3638 #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
3639 #[must_use = "this returns the result of the operation, \
3640 without modifying the original"]
3641 #[inline]
3642 #[cfg(not(feature = "ferrocene_certified"))]
3643 pub const fn to_be_bytes(self) -> [u8; size_of::<Self>()] {
3644 self.to_be().to_ne_bytes()
3645 }
3646
3647 /// Returns the memory representation of this integer as a byte array in
3648 /// little-endian byte order.
3649 ///
3650 #[doc = $to_xe_bytes_doc]
3651 ///
3652 /// # Examples
3653 ///
3654 /// ```
3655 #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();")]
3656 #[doc = concat!("assert_eq!(bytes, ", $le_bytes, ");")]
3657 /// ```
3658 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3659 #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
3660 #[must_use = "this returns the result of the operation, \
3661 without modifying the original"]
3662 #[inline]
3663 #[cfg(not(feature = "ferrocene_certified"))]
3664 pub const fn to_le_bytes(self) -> [u8; size_of::<Self>()] {
3665 self.to_le().to_ne_bytes()
3666 }
3667
3668 /// Returns the memory representation of this integer as a byte array in
3669 /// native byte order.
3670 ///
3671 /// As the target platform's native endianness is used, portable code
3672 /// should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
3673 /// instead.
3674 ///
3675 #[doc = $to_xe_bytes_doc]
3676 ///
3677 /// [`to_be_bytes`]: Self::to_be_bytes
3678 /// [`to_le_bytes`]: Self::to_le_bytes
3679 ///
3680 /// # Examples
3681 ///
3682 /// ```
3683 #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();")]
3684 /// assert_eq!(
3685 /// bytes,
3686 /// if cfg!(target_endian = "big") {
3687 #[doc = concat!(" ", $be_bytes)]
3688 /// } else {
3689 #[doc = concat!(" ", $le_bytes)]
3690 /// }
3691 /// );
3692 /// ```
3693 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3694 #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
3695 #[allow(unnecessary_transmutes)]
3696 // SAFETY: const sound because integers are plain old datatypes so we can always
3697 // transmute them to arrays of bytes
3698 #[must_use = "this returns the result of the operation, \
3699 without modifying the original"]
3700 #[inline]
3701 #[cfg(not(feature = "ferrocene_certified"))]
3702 pub const fn to_ne_bytes(self) -> [u8; size_of::<Self>()] {
3703 // SAFETY: integers are plain old datatypes so we can always transmute them to
3704 // arrays of bytes
3705 unsafe { mem::transmute(self) }
3706 }
3707
3708 /// Creates an integer value from its representation as a byte array in
3709 /// big endian.
3710 ///
3711 #[doc = $from_xe_bytes_doc]
3712 ///
3713 /// # Examples
3714 ///
3715 /// ```
3716 #[doc = concat!("let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");")]
3717 #[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
3718 /// ```
3719 ///
3720 /// When starting from a slice rather than an array, fallible conversion APIs can be used:
3721 ///
3722 /// ```
3723 #[doc = concat!("fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
3724 #[doc = concat!(" let (int_bytes, rest) = input.split_at(size_of::<", stringify!($SelfT), ">());")]
3725 /// *input = rest;
3726 #[doc = concat!(" ", stringify!($SelfT), "::from_be_bytes(int_bytes.try_into().unwrap())")]
3727 /// }
3728 /// ```
3729 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3730 #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
3731 #[must_use]
3732 #[inline]
3733 #[cfg(not(feature = "ferrocene_certified"))]
3734 pub const fn from_be_bytes(bytes: [u8; size_of::<Self>()]) -> Self {
3735 Self::from_be(Self::from_ne_bytes(bytes))
3736 }
3737
3738 /// Creates an integer value from its representation as a byte array in
3739 /// little endian.
3740 ///
3741 #[doc = $from_xe_bytes_doc]
3742 ///
3743 /// # Examples
3744 ///
3745 /// ```
3746 #[doc = concat!("let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");")]
3747 #[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
3748 /// ```
3749 ///
3750 /// When starting from a slice rather than an array, fallible conversion APIs can be used:
3751 ///
3752 /// ```
3753 #[doc = concat!("fn read_le_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
3754 #[doc = concat!(" let (int_bytes, rest) = input.split_at(size_of::<", stringify!($SelfT), ">());")]
3755 /// *input = rest;
3756 #[doc = concat!(" ", stringify!($SelfT), "::from_le_bytes(int_bytes.try_into().unwrap())")]
3757 /// }
3758 /// ```
3759 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3760 #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
3761 #[must_use]
3762 #[inline]
3763 #[cfg(not(feature = "ferrocene_certified"))]
3764 pub const fn from_le_bytes(bytes: [u8; size_of::<Self>()]) -> Self {
3765 Self::from_le(Self::from_ne_bytes(bytes))
3766 }
3767
3768 /// Creates an integer value from its memory representation as a byte
3769 /// array in native endianness.
3770 ///
3771 /// As the target platform's native endianness is used, portable code
3772 /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
3773 /// appropriate instead.
3774 ///
3775 /// [`from_be_bytes`]: Self::from_be_bytes
3776 /// [`from_le_bytes`]: Self::from_le_bytes
3777 ///
3778 #[doc = $from_xe_bytes_doc]
3779 ///
3780 /// # Examples
3781 ///
3782 /// ```
3783 #[doc = concat!("let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = \"big\") {")]
3784 #[doc = concat!(" ", $be_bytes)]
3785 /// } else {
3786 #[doc = concat!(" ", $le_bytes)]
3787 /// });
3788 #[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
3789 /// ```
3790 ///
3791 /// When starting from a slice rather than an array, fallible conversion APIs can be used:
3792 ///
3793 /// ```
3794 #[doc = concat!("fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
3795 #[doc = concat!(" let (int_bytes, rest) = input.split_at(size_of::<", stringify!($SelfT), ">());")]
3796 /// *input = rest;
3797 #[doc = concat!(" ", stringify!($SelfT), "::from_ne_bytes(int_bytes.try_into().unwrap())")]
3798 /// }
3799 /// ```
3800 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3801 #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
3802 #[allow(unnecessary_transmutes)]
3803 #[must_use]
3804 // SAFETY: const sound because integers are plain old datatypes so we can always
3805 // transmute to them
3806 #[inline]
3807 #[cfg(not(feature = "ferrocene_certified"))]
3808 pub const fn from_ne_bytes(bytes: [u8; size_of::<Self>()]) -> Self {
3809 // SAFETY: integers are plain old datatypes so we can always transmute to them
3810 unsafe { mem::transmute(bytes) }
3811 }
3812
3813 /// New code should prefer to use
3814 #[doc = concat!("[`", stringify!($SelfT), "::MIN", "`] instead.")]
3815 ///
3816 /// Returns the smallest value that can be represented by this integer type.
3817 #[stable(feature = "rust1", since = "1.0.0")]
3818 #[inline(always)]
3819 #[rustc_promotable]
3820 #[rustc_const_stable(feature = "const_min_value", since = "1.32.0")]
3821 #[deprecated(since = "TBD", note = "replaced by the `MIN` associated constant on this type")]
3822 #[rustc_diagnostic_item = concat!(stringify!($SelfT), "_legacy_fn_min_value")]
3823 #[cfg(not(feature = "ferrocene_certified"))]
3824 pub const fn min_value() -> Self {
3825 Self::MIN
3826 }
3827
3828 /// New code should prefer to use
3829 #[doc = concat!("[`", stringify!($SelfT), "::MAX", "`] instead.")]
3830 ///
3831 /// Returns the largest value that can be represented by this integer type.
3832 #[stable(feature = "rust1", since = "1.0.0")]
3833 #[inline(always)]
3834 #[rustc_promotable]
3835 #[rustc_const_stable(feature = "const_max_value", since = "1.32.0")]
3836 #[deprecated(since = "TBD", note = "replaced by the `MAX` associated constant on this type")]
3837 #[rustc_diagnostic_item = concat!(stringify!($SelfT), "_legacy_fn_max_value")]
3838 #[cfg(not(feature = "ferrocene_certified"))]
3839 pub const fn max_value() -> Self {
3840 Self::MAX
3841 }
3842 }
3843}