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!("(&minus;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> &minus; 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` &minus; `rhs` &minus; `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}