Skip to main content

core/num/
nonzero.rs

1//! Definitions of integer that is known not to equal zero.
2
3use super::{IntErrorKind, ParseIntError, TryFromIntError};
4use crate::clone::{TrivialClone, UseCloned};
5use crate::cmp::Ordering;
6use crate::hash::{Hash, Hasher};
7use crate::marker::{Destruct, Freeze, StructuralPartialEq};
8use crate::num::imp;
9use crate::ops::{BitOr, BitOrAssign, Div, DivAssign, Neg, Rem, RemAssign};
10use crate::panic::{RefUnwindSafe, UnwindSafe};
11use crate::str::FromStr;
12use crate::{fmt, intrinsics, ptr, slice, ub_checks};
13
14/// A marker trait for primitive types which can be zero.
15///
16/// This is an implementation detail for <code>[NonZero]\<T></code> which may disappear or be replaced at any time.
17///
18/// # Safety
19///
20/// Types implementing this trait must be primitives that are valid when zeroed.
21///
22/// The associated `Self::NonZeroInner` type must have the same size+align as `Self`,
23/// but with a niche and bit validity making it so the following `transmutes` are sound:
24///
25/// - `Self::NonZeroInner` to `Option<Self::NonZeroInner>`
26/// - `Option<Self::NonZeroInner>` to `Self`
27///
28/// (And, consequently, `Self::NonZeroInner` to `Self`.)
29#[unstable(
30    feature = "nonzero_internals",
31    reason = "implementation detail which may disappear or be replaced at any time",
32    issue = "none"
33)]
34pub impl(self) unsafe trait ZeroablePrimitive: Sized + Copy {
35    /// A type like `Self` but with a niche that includes zero.
36    type NonZeroInner: Sized + Copy;
37}
38
39macro_rules! impl_zeroable_primitive {
40    ($($NonZeroInner:ident ( $primitive:ty )),+ $(,)?) => {
41        $(
42            #[unstable(
43                feature = "nonzero_internals",
44                reason = "implementation detail which may disappear or be replaced at any time",
45                issue = "none"
46            )]
47            unsafe impl ZeroablePrimitive for $primitive {
48                type NonZeroInner = super::niche_types::$NonZeroInner;
49            }
50        )+
51    };
52}
53
54impl_zeroable_primitive!(
55    NonZeroU8Inner(u8),
56    NonZeroU16Inner(u16),
57    NonZeroU32Inner(u32),
58    NonZeroU64Inner(u64),
59    NonZeroU128Inner(u128),
60    NonZeroUsizeInner(usize),
61    NonZeroI8Inner(i8),
62    NonZeroI16Inner(i16),
63    NonZeroI32Inner(i32),
64    NonZeroI64Inner(i64),
65    NonZeroI128Inner(i128),
66    NonZeroIsizeInner(isize),
67    NonZeroCharInner(char),
68);
69
70/// A value that is known not to equal zero.
71///
72/// This enables some memory layout optimization.
73/// For example, `Option<NonZero<u32>>` is the same size as `u32`:
74///
75/// ```
76/// use core::num::NonZero;
77///
78/// assert_eq!(size_of::<Option<NonZero<u32>>>(), size_of::<u32>());
79/// ```
80///
81/// # Layout
82///
83/// `NonZero<T>` is guaranteed to have the same layout and bit validity as `T`
84/// with the exception that the all-zero bit pattern is invalid.
85/// `Option<NonZero<T>>` is guaranteed to be ABI-compatible with `T`, including in
86/// FFI.
87///
88/// Thanks to the [null pointer optimization], `NonZero<T>` and
89/// `Option<NonZero<T>>` are guaranteed to have the same size and alignment:
90///
91/// ```
92/// use std::num::NonZero;
93///
94/// assert_eq!(size_of::<NonZero<u32>>(), size_of::<Option<NonZero<u32>>>());
95/// assert_eq!(align_of::<NonZero<u32>>(), align_of::<Option<NonZero<u32>>>());
96/// ```
97///
98/// [null pointer optimization]: crate::option#representation
99///
100/// # Note on generic usage
101///
102/// `NonZero<T>` can only be used with some standard library primitive types
103/// (such as `u8`, `i32`, and etc.). The type parameter `T` must implement the
104/// internal trait [`ZeroablePrimitive`], which is currently permanently unstable
105/// and cannot be implemented by users. Therefore, you cannot use `NonZero<T>`
106/// with your own types, nor can you implement traits for all `NonZero<T>`,
107/// only for concrete types.
108#[stable(feature = "generic_nonzero", since = "1.79.0")]
109#[repr(transparent)]
110#[rustc_nonnull_optimization_guaranteed]
111#[rustc_diagnostic_item = "NonZero"]
112pub struct NonZero<T: ZeroablePrimitive>(T::NonZeroInner);
113
114macro_rules! impl_nonzero_fmt {
115    ($(#[$Attribute:meta] $Trait:ident)*) => {
116        $(
117            #[$Attribute]
118            impl<T> fmt::$Trait for NonZero<T>
119            where
120                T: ZeroablePrimitive + fmt::$Trait,
121            {
122                #[inline]
123                fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
124                    self.get().fmt(f)
125                }
126            }
127        )*
128    };
129}
130
131impl_nonzero_fmt! {
132    #[stable(feature = "nonzero", since = "1.28.0")]
133    Debug
134    #[stable(feature = "nonzero", since = "1.28.0")]
135    Display
136    #[stable(feature = "nonzero", since = "1.28.0")]
137    Binary
138    #[stable(feature = "nonzero", since = "1.28.0")]
139    Octal
140    #[stable(feature = "nonzero", since = "1.28.0")]
141    LowerHex
142    #[stable(feature = "nonzero", since = "1.28.0")]
143    UpperHex
144    #[stable(feature = "nonzero_fmt_exp", since = "1.84.0")]
145    LowerExp
146    #[stable(feature = "nonzero_fmt_exp", since = "1.84.0")]
147    UpperExp
148}
149
150macro_rules! impl_nonzero_auto_trait {
151    (unsafe $Trait:ident) => {
152        #[stable(feature = "nonzero", since = "1.28.0")]
153        unsafe impl<T> $Trait for NonZero<T> where T: ZeroablePrimitive + $Trait {}
154    };
155    ($Trait:ident) => {
156        #[stable(feature = "nonzero", since = "1.28.0")]
157        impl<T> $Trait for NonZero<T> where T: ZeroablePrimitive + $Trait {}
158    };
159}
160
161// Implement auto-traits manually based on `T` to avoid docs exposing
162// the `ZeroablePrimitive::NonZeroInner` implementation detail.
163impl_nonzero_auto_trait!(unsafe Freeze);
164impl_nonzero_auto_trait!(RefUnwindSafe);
165impl_nonzero_auto_trait!(unsafe Send);
166impl_nonzero_auto_trait!(unsafe Sync);
167impl_nonzero_auto_trait!(Unpin);
168impl_nonzero_auto_trait!(UnwindSafe);
169
170#[stable(feature = "nonzero", since = "1.28.0")]
171#[rustc_const_unstable(feature = "const_clone", issue = "142757")]
172const impl<T> Clone for NonZero<T>
173where
174    T: ZeroablePrimitive,
175{
176    #[inline]
177    fn clone(&self) -> Self {
178        *self
179    }
180}
181
182#[unstable(feature = "ergonomic_clones", issue = "132290")]
183impl<T> UseCloned for NonZero<T> where T: ZeroablePrimitive {}
184
185#[stable(feature = "nonzero", since = "1.28.0")]
186impl<T> Copy for NonZero<T> where T: ZeroablePrimitive {}
187
188#[doc(hidden)]
189#[unstable(feature = "trivial_clone", issue = "none")]
190#[rustc_const_unstable(feature = "const_clone", issue = "142757")]
191const unsafe impl<T> TrivialClone for NonZero<T> where T: ZeroablePrimitive {}
192
193#[stable(feature = "nonzero", since = "1.28.0")]
194#[rustc_const_unstable(feature = "const_cmp", issue = "143800")]
195const impl<T> PartialEq for NonZero<T>
196where
197    T: ZeroablePrimitive + [const] PartialEq,
198{
199    #[inline]
200    fn eq(&self, other: &Self) -> bool {
201        self.get() == other.get()
202    }
203
204    #[inline]
205    fn ne(&self, other: &Self) -> bool {
206        self.get() != other.get()
207    }
208}
209
210#[unstable(feature = "structural_match", issue = "31434")]
211impl<T> StructuralPartialEq for NonZero<T> where T: ZeroablePrimitive + StructuralPartialEq {}
212
213#[stable(feature = "nonzero", since = "1.28.0")]
214#[rustc_const_unstable(feature = "const_cmp", issue = "143800")]
215const impl<T> Eq for NonZero<T> where T: ZeroablePrimitive + [const] Eq {}
216
217#[stable(feature = "nonzero", since = "1.28.0")]
218#[rustc_const_unstable(feature = "const_cmp", issue = "143800")]
219const impl<T> PartialOrd for NonZero<T>
220where
221    T: ZeroablePrimitive + [const] PartialOrd,
222{
223    #[inline]
224    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
225        self.get().partial_cmp(&other.get())
226    }
227
228    #[inline]
229    fn lt(&self, other: &Self) -> bool {
230        self.get() < other.get()
231    }
232
233    #[inline]
234    fn le(&self, other: &Self) -> bool {
235        self.get() <= other.get()
236    }
237
238    #[inline]
239    fn gt(&self, other: &Self) -> bool {
240        self.get() > other.get()
241    }
242
243    #[inline]
244    fn ge(&self, other: &Self) -> bool {
245        self.get() >= other.get()
246    }
247}
248
249#[stable(feature = "nonzero", since = "1.28.0")]
250#[rustc_const_unstable(feature = "const_cmp", issue = "143800")]
251const impl<T> Ord for NonZero<T>
252where
253    // FIXME(const_hack): the T: ~const Destruct should be inferred from the Self: ~const Destruct.
254    // See https://github.com/rust-lang/rust/issues/144207
255    T: ZeroablePrimitive + [const] Ord + [const] Destruct,
256{
257    #[inline]
258    fn cmp(&self, other: &Self) -> Ordering {
259        self.get().cmp(&other.get())
260    }
261
262    #[inline]
263    fn max(self, other: Self) -> Self {
264        // SAFETY: The maximum of two non-zero values is still non-zero.
265        unsafe { Self::new_unchecked(self.get().max(other.get())) }
266    }
267
268    #[inline]
269    fn min(self, other: Self) -> Self {
270        // SAFETY: The minimum of two non-zero values is still non-zero.
271        unsafe { Self::new_unchecked(self.get().min(other.get())) }
272    }
273
274    #[inline]
275    fn clamp(self, min: Self, max: Self) -> Self {
276        // SAFETY: A non-zero value clamped between two non-zero values is still non-zero.
277        unsafe { Self::new_unchecked(self.get().clamp(min.get(), max.get())) }
278    }
279}
280
281#[stable(feature = "nonzero", since = "1.28.0")]
282impl<T> Hash for NonZero<T>
283where
284    T: ZeroablePrimitive + Hash,
285{
286    #[inline]
287    fn hash<H>(&self, state: &mut H)
288    where
289        H: Hasher,
290    {
291        self.get().hash(state)
292    }
293}
294
295#[stable(feature = "from_nonzero", since = "1.31.0")]
296#[rustc_const_unstable(feature = "const_convert", issue = "143773")]
297const impl<T> From<NonZero<T>> for T
298where
299    T: ZeroablePrimitive,
300{
301    #[inline]
302    fn from(nonzero: NonZero<T>) -> Self {
303        // Call `get` method to keep range information.
304        nonzero.get()
305    }
306}
307
308#[stable(feature = "more_from_nonzero", since = "1.101.0")]
309impl<'a, T> From<&'a NonZero<T>> for &'a T
310where
311    T: ZeroablePrimitive,
312{
313    #[inline]
314    fn from(nonzero: &'a NonZero<T>) -> &'a T {
315        nonzero.as_ref()
316    }
317}
318
319// FIXME: see library/std/tests/slice-from-array-issue-113238.rs
320/*
321#[stable(feature = "more_from_nonzero", since = "1.101.0")]
322impl<'a, T> From<&'a [NonZero<T>]> for &'a [T]
323where
324    T: ZeroablePrimitive,
325{
326    #[inline]
327    fn from(nonzero: &'a [NonZero<T>]) -> &'a [T] {
328        nonzero.as_zeroable()
329    }
330}
331impl<T> [NonZero<T>]
332where
333    T: ZeroablePrimitive,
334{
335    /// Implementation of `From<&[NonZero<T>]> for &[T]`.
336    #[must_use]
337    #[inline]
338    fn as_zeroable(&self) -> &[T] {
339        // SAFETY: `repr(transparent)` ensures that `NonZero<T>` has same layout as `T`, and thus
340        //   `[NonZero<T>]` has same layout as `[T]`
341        unsafe { &*(slice::from_raw_parts(self.as_ptr().cast::<T>(), self.len())) }
342    }
343}
344*/
345
346#[stable(feature = "more_from_nonzero", since = "1.101.0")]
347impl<T, const N: usize> From<[NonZero<T>; N]> for [T; N]
348where
349    T: ZeroablePrimitive,
350{
351    #[inline]
352    fn from(nonzero: [NonZero<T>; N]) -> [T; N] {
353        nonzero.into_zeroable()
354    }
355}
356
357// FIXME: can't detect that ZeroablePrimitive is a sealed trait
358macro_rules! impl_ref_try_from {
359    ($($t:ty),* $(,)?) => {
360        $(
361            #[stable(feature = "more_from_nonzero", since = "1.101.0")]
362            impl<'a> TryFrom<&'a $t> for &'a NonZero<$t> {
363                type Error = TryFromIntError;
364
365                #[inline]
366                fn try_from(zeroable: &'a $t) -> Result<&'a NonZero<$t>, TryFromIntError> {
367                    NonZero::from_ref(zeroable).ok_or(TryFromIntError(IntErrorKind::Zero))
368                }
369            }
370        )*
371    }
372}
373
374impl_ref_try_from! {
375    u8,
376    u16,
377    u32,
378    u64,
379    u128,
380    usize,
381    i8,
382    i16,
383    i32,
384    i64,
385    i128,
386    isize,
387    char,
388}
389
390#[stable(feature = "more_from_nonzero", since = "1.101.0")]
391impl<'a, T> TryFrom<&'a [T]> for &'a [NonZero<T>]
392where
393    T: ZeroablePrimitive,
394{
395    type Error = TryFromIntError;
396
397    #[inline]
398    fn try_from(zeroable: &'a [T]) -> Result<&'a [NonZero<T>], TryFromIntError> {
399        NonZero::from_slice(zeroable).ok_or(TryFromIntError(IntErrorKind::Zero))
400    }
401}
402
403#[stable(feature = "more_from_nonzero", since = "1.101.0")]
404impl<T, const N: usize> TryFrom<[T; N]> for [NonZero<T>; N]
405where
406    T: ZeroablePrimitive,
407{
408    type Error = TryFromIntError;
409
410    #[inline]
411    fn try_from(zeroable: [T; N]) -> Result<[NonZero<T>; N], TryFromIntError> {
412        NonZero::from_array(zeroable).ok_or(TryFromIntError(IntErrorKind::Zero))
413    }
414}
415
416#[stable(feature = "nonzero_bitor", since = "1.45.0")]
417#[rustc_const_unstable(feature = "const_ops", issue = "143802")]
418const impl<T> BitOr for NonZero<T>
419where
420    T: ZeroablePrimitive + [const] BitOr<Output = T>,
421{
422    type Output = Self;
423
424    #[inline]
425    fn bitor(self, rhs: Self) -> Self::Output {
426        // SAFETY: Bitwise OR of two non-zero values is still non-zero.
427        unsafe { Self::new_unchecked(self.get() | rhs.get()) }
428    }
429}
430
431#[stable(feature = "nonzero_bitor", since = "1.45.0")]
432#[rustc_const_unstable(feature = "const_ops", issue = "143802")]
433const impl<T> BitOr<T> for NonZero<T>
434where
435    T: ZeroablePrimitive + [const] BitOr<Output = T>,
436{
437    type Output = Self;
438
439    #[inline]
440    fn bitor(self, rhs: T) -> Self::Output {
441        // SAFETY: Bitwise OR of a non-zero value with anything is still non-zero.
442        unsafe { Self::new_unchecked(self.get() | rhs) }
443    }
444}
445
446#[stable(feature = "nonzero_bitor", since = "1.45.0")]
447#[rustc_const_unstable(feature = "const_ops", issue = "143802")]
448const impl<T> BitOr<NonZero<T>> for T
449where
450    T: ZeroablePrimitive + [const] BitOr<Output = T>,
451{
452    type Output = NonZero<T>;
453
454    #[inline]
455    fn bitor(self, rhs: NonZero<T>) -> Self::Output {
456        // SAFETY: Bitwise OR of anything with a non-zero value is still non-zero.
457        unsafe { NonZero::new_unchecked(self | rhs.get()) }
458    }
459}
460
461#[stable(feature = "nonzero_bitor", since = "1.45.0")]
462#[rustc_const_unstable(feature = "const_ops", issue = "143802")]
463const impl<T> BitOrAssign for NonZero<T>
464where
465    T: ZeroablePrimitive,
466    Self: [const] BitOr<Output = Self>,
467{
468    #[inline]
469    fn bitor_assign(&mut self, rhs: Self) {
470        *self = *self | rhs;
471    }
472}
473
474#[stable(feature = "nonzero_bitor", since = "1.45.0")]
475#[rustc_const_unstable(feature = "const_ops", issue = "143802")]
476const impl<T> BitOrAssign<T> for NonZero<T>
477where
478    T: ZeroablePrimitive,
479    Self: [const] BitOr<T, Output = Self>,
480{
481    #[inline]
482    fn bitor_assign(&mut self, rhs: T) {
483        *self = *self | rhs;
484    }
485}
486
487impl<T> NonZero<T>
488where
489    T: ZeroablePrimitive,
490{
491    /// Creates a non-zero if the given value is not zero.
492    #[stable(feature = "nonzero", since = "1.28.0")]
493    #[rustc_const_stable(feature = "const_nonzero_int_methods", since = "1.47.0")]
494    #[must_use]
495    #[inline]
496    pub const fn new(n: T) -> Option<Self> {
497        // SAFETY: Memory layout optimization guarantees that `Option<NonZero<T>>` has
498        //         the same layout and size as `T`, with `0` representing `None`.
499        unsafe { intrinsics::transmute_unchecked(n) }
500    }
501
502    /// Creates a non-zero without checking whether the value is non-zero.
503    /// This results in undefined behavior if the value is zero.
504    ///
505    /// # Safety
506    ///
507    /// The value must not be zero.
508    #[stable(feature = "nonzero", since = "1.28.0")]
509    #[rustc_const_stable(feature = "nonzero", since = "1.28.0")]
510    #[must_use]
511    #[inline]
512    #[track_caller]
513    pub const unsafe fn new_unchecked(n: T) -> Self {
514        match Self::new(n) {
515            Some(n) => n,
516            None => {
517                // SAFETY: The caller guarantees that `n` is non-zero, so this is unreachable.
518                unsafe {
519                    ub_checks::assert_unsafe_precondition!(
520                        check_language_ub,
521                        "NonZero::new_unchecked requires the argument to be non-zero",
522                        () => false,
523                    );
524                    intrinsics::unreachable()
525                }
526            }
527        }
528    }
529
530    /// Converts a reference to a non-zero mutable reference
531    /// if the referenced value is not zero.
532    #[unstable(feature = "nonzero_from_mut", issue = "106290")]
533    #[must_use]
534    #[inline]
535    pub fn from_mut(n: &mut T) -> Option<&mut Self> {
536        // SAFETY: Memory layout optimization guarantees that `Option<NonZero<T>>` has
537        //         the same layout and size as `T`, with `0` representing `None`.
538        let opt_n = unsafe { &mut *(ptr::from_mut(n).cast::<Option<Self>>()) };
539
540        opt_n.as_mut()
541    }
542
543    /// Converts a mutable reference to a non-zero mutable reference
544    /// without checking whether the referenced value is non-zero.
545    /// This results in undefined behavior if the referenced value is zero.
546    ///
547    /// # Safety
548    ///
549    /// The referenced value must not be zero.
550    #[unstable(feature = "nonzero_from_mut", issue = "106290")]
551    #[must_use]
552    #[inline]
553    #[track_caller]
554    pub unsafe fn from_mut_unchecked(n: &mut T) -> &mut Self {
555        match Self::from_mut(n) {
556            Some(n) => n,
557            None => {
558                // SAFETY: The caller guarantees that `n` references a value that is non-zero, so this is unreachable.
559                unsafe {
560                    ub_checks::assert_unsafe_precondition!(
561                        check_library_ub,
562                        "NonZero::from_mut_unchecked requires the argument to dereference as non-zero",
563                        () => false,
564                    );
565                    intrinsics::unreachable()
566                }
567            }
568        }
569    }
570
571    /// Implementation of `From<&NonZero<T>> for &T`.
572    #[must_use]
573    #[inline]
574    fn as_ref(&self) -> &T {
575        // SAFETY: `repr(transparent)` ensures that `NonZero<T>` has same layout as `T`
576        unsafe { &*(ptr::from_ref(self).cast::<T>()) }
577    }
578
579    /// Implementation of `TryFrom<&T> for &NonZero<T>`.
580    #[must_use]
581    #[inline]
582    fn from_ref(n: &T) -> Option<&Self> {
583        // SAFETY: Memory layout optimization guarantees that `Option<NonZero<T>>` has
584        //         the same layout and size as `T`, with `0` representing `None`.
585        let opt_n = unsafe { &*(ptr::from_ref(n).cast::<Option<Self>>()) };
586
587        opt_n.as_ref()
588    }
589
590    /// Implementation of `TryFrom<&[T]> for &[NonZero<T>]`.
591    #[must_use]
592    #[inline]
593    fn from_slice(n: &[T]) -> Option<&[Self]> {
594        if n.iter().all(|x| NonZero::new(*x).is_some()) {
595            // SAFETY: We explicitly checked that all elements are nonzero, and because of `repr(transparent)`
596            //   the layout remains unchanged
597            Some(unsafe { slice::from_raw_parts(n.as_ptr().cast::<NonZero<T>>(), n.len()) })
598        } else {
599            None
600        }
601    }
602
603    /// Implementation of `TryFrom<[T; N]> for [NonZero<T>; N]`.
604    #[must_use]
605    #[inline]
606    fn from_array<const N: usize>(n: [T; N]) -> Option<[Self; N]> {
607        n.try_map(NonZero::new)
608    }
609
610    /// Returns the contained value as a primitive type.
611    #[stable(feature = "nonzero", since = "1.28.0")]
612    #[rustc_const_stable(feature = "const_nonzero_get", since = "1.34.0")]
613    #[inline]
614    pub const fn get(self) -> T {
615        // Rustc can set range metadata only if it loads `self` from
616        // memory somewhere. If the value of `self` was from by-value argument
617        // of some not-inlined function, LLVM don't have range metadata
618        // to understand that the value cannot be zero.
619        //
620        // Using the transmute `assume`s the range at runtime.
621        //
622        // Even once LLVM supports `!range` metadata for function arguments
623        // (see <https://github.com/llvm/llvm-project/issues/76628>), this can't
624        // be `.0` because MCP#807 bans field-projecting into `scalar_valid_range`
625        // types, and it arguably wouldn't want to be anyway because if this is
626        // MIR-inlined, there's no opportunity to put that argument metadata anywhere.
627        //
628        // The good answer here will eventually be pattern types, which will hopefully
629        // allow it to go back to `.0`, maybe with a cast of some sort.
630        //
631        // SAFETY: `ZeroablePrimitive` guarantees that the size and bit validity
632        // of `.0` is such that this transmute is sound.
633        unsafe { intrinsics::transmute_unchecked(self) }
634    }
635}
636
637impl<T, const N: usize> [NonZero<T>; N]
638where
639    T: ZeroablePrimitive,
640{
641    /// Implementation of `From<[NonZero<T>; N]> for [T; N]`.
642    #[must_use]
643    #[inline]
644    fn into_zeroable(self) -> [T; N] {
645        self.map(NonZero::get)
646    }
647}
648
649macro_rules! nonzero_integer {
650    (
651        #[$stability:meta]
652        Self = $Ty:ident,
653        Primitive = $signedness:ident $Int:ident,
654        SignedPrimitive = $Sint:ty,
655        UnsignedPrimitive = $Uint:ty,
656
657        // Used in doc comments.
658        rot = $rot:literal,
659        rot_op = $rot_op:literal,
660        rot_result = $rot_result:literal,
661        swap_op = $swap_op:literal,
662        swapped = $swapped:literal,
663        reversed = $reversed:literal,
664        leading_zeros_test = $leading_zeros_test:expr,
665    ) => {
666        #[doc = sign_dependent_expr!{
667            $signedness ?
668            if signed {
669                concat!("An [`", stringify!($Int), "`] that is known not to equal zero.")
670            }
671            if unsigned {
672                concat!("A [`", stringify!($Int), "`] that is known not to equal zero.")
673            }
674        }]
675        ///
676        /// This enables some memory layout optimization.
677        #[doc = concat!("For example, `Option<", stringify!($Ty), ">` is the same size as `", stringify!($Int), "`:")]
678        ///
679        /// ```rust
680        #[doc = concat!("assert_eq!(size_of::<Option<core::num::", stringify!($Ty), ">>(), size_of::<", stringify!($Int), ">());")]
681        /// ```
682        ///
683        /// # Layout
684        ///
685        #[doc = concat!("`", stringify!($Ty), "` is guaranteed to have the same layout and bit validity as `", stringify!($Int), "`")]
686        /// with the exception that `0` is not a valid instance.
687        #[doc = concat!("`Option<", stringify!($Ty), ">` is guaranteed to be ABI-compatible with `", stringify!($Int), "`,")]
688        /// including in FFI.
689        ///
690        /// Thanks to the [null pointer optimization],
691        #[doc = concat!("`", stringify!($Ty), "` and `Option<", stringify!($Ty), ">`")]
692        /// are guaranteed to have the same size and alignment:
693        ///
694        /// ```
695        #[doc = concat!("use std::num::", stringify!($Ty), ";")]
696        ///
697        #[doc = concat!("assert_eq!(size_of::<", stringify!($Ty), ">(), size_of::<Option<", stringify!($Ty), ">>());")]
698        #[doc = concat!("assert_eq!(align_of::<", stringify!($Ty), ">(), align_of::<Option<", stringify!($Ty), ">>());")]
699        /// ```
700        ///
701        /// # Compile-time creation
702        ///
703        /// Since both [`Option::unwrap()`] and [`Option::expect()`] are `const`, it is possible to
704        /// define a new
705        #[doc = concat!("`", stringify!($Ty), "`")]
706        /// at compile time via:
707        /// ```
708        #[doc = concat!("use std::num::", stringify!($Ty), ";")]
709        ///
710        #[doc = concat!("const TEN: ", stringify!($Ty), " = ", stringify!($Ty) , r#"::new(10).expect("ten is non-zero");"#)]
711        /// ```
712        ///
713        /// [null pointer optimization]: crate::option#representation
714        #[$stability]
715        pub type $Ty = NonZero<$Int>;
716
717        impl NonZero<$Int> {
718            /// The size of this non-zero integer type in bits.
719            ///
720            #[doc = concat!("This value is equal to [`", stringify!($Int), "::BITS`].")]
721            ///
722            /// # Examples
723            ///
724            /// ```
725            /// # use std::num::NonZero;
726            /// #
727            #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::BITS, ", stringify!($Int), "::BITS);")]
728            /// ```
729            #[stable(feature = "nonzero_bits", since = "1.67.0")]
730            pub const BITS: u32 = <$Int>::BITS;
731
732            /// Returns the number of leading zeros in the binary representation of `self`.
733            ///
734            /// On many architectures, this function can perform better than `leading_zeros()` on the underlying integer type, as special handling of zero can be avoided.
735            ///
736            /// # Examples
737            ///
738            /// ```
739            /// # use std::num::NonZero;
740            /// #
741            /// # fn main() { test().unwrap(); }
742            /// # fn test() -> Option<()> {
743            #[doc = concat!("let n = NonZero::<", stringify!($Int), ">::new(", $leading_zeros_test, ")?;")]
744            ///
745            /// assert_eq!(n.leading_zeros(), 0);
746            /// # Some(())
747            /// # }
748            /// ```
749            #[stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")]
750            #[rustc_const_stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")]
751            #[must_use = "this returns the result of the operation, \
752                          without modifying the original"]
753            #[inline]
754            pub const fn leading_zeros(self) -> u32 {
755                // SAFETY: since `self` cannot be zero, it is safe to call `ctlz_nonzero`.
756                unsafe {
757                    intrinsics::ctlz_nonzero(self.get() as $Uint)
758                }
759            }
760
761            /// Returns the number of trailing zeros in the binary representation
762            /// of `self`.
763            ///
764            /// On many architectures, this function can perform better than `trailing_zeros()` on the underlying integer type, as special handling of zero can be avoided.
765            ///
766            /// # Examples
767            ///
768            /// ```
769            /// # use std::num::NonZero;
770            /// #
771            /// # fn main() { test().unwrap(); }
772            /// # fn test() -> Option<()> {
773            #[doc = concat!("let n = NonZero::<", stringify!($Int), ">::new(0b0101000)?;")]
774            ///
775            /// assert_eq!(n.trailing_zeros(), 3);
776            /// # Some(())
777            /// # }
778            /// ```
779            #[stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")]
780            #[rustc_const_stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")]
781            #[must_use = "this returns the result of the operation, \
782                          without modifying the original"]
783            #[inline]
784            pub const fn trailing_zeros(self) -> u32 {
785                // SAFETY: since `self` cannot be zero, it is safe to call `cttz_nonzero`.
786                unsafe {
787                    intrinsics::cttz_nonzero(self.get() as $Uint)
788                }
789            }
790
791            /// Returns `self` with only the most significant bit set.
792            ///
793            /// # Example
794            ///
795            /// ```
796            /// # use core::num::NonZero;
797            /// # fn main() { test().unwrap(); }
798            /// # fn test() -> Option<()> {
799            #[doc = concat!("let a = NonZero::<", stringify!($Int), ">::new(0b_01100100)?;")]
800            #[doc = concat!("let b = NonZero::<", stringify!($Int), ">::new(0b_01000000)?;")]
801            ///
802            /// assert_eq!(a.isolate_highest_one(), b);
803            /// # Some(())
804            /// # }
805            /// ```
806            #[stable(feature = "isolate_most_least_significant_one", since = "1.97.0")]
807            #[rustc_const_stable(feature = "isolate_most_least_significant_one", since = "1.97.0")]
808            #[must_use = "this returns the result of the operation, \
809                        without modifying the original"]
810            #[inline(always)]
811            pub const fn isolate_highest_one(self) -> Self {
812                // SAFETY:
813                // `self` is non-zero, so masking to preserve only the most
814                // significant set bit will result in a non-zero `n`.
815                // and self.leading_zeros() is always < $INT::BITS since
816                // at least one of the bits in the number is not zero
817                unsafe {
818                    let bit = (((1 as $Uint) << (<$Uint>::BITS - 1)).unchecked_shr(self.leading_zeros()));
819                    NonZero::new_unchecked(bit as $Int)
820                }
821            }
822
823            /// Returns `self` with only the least significant bit set.
824            ///
825            /// # Example
826            ///
827            /// ```
828            /// # use core::num::NonZero;
829            /// # fn main() { test().unwrap(); }
830            /// # fn test() -> Option<()> {
831            #[doc = concat!("let a = NonZero::<", stringify!($Int), ">::new(0b_01100100)?;")]
832            #[doc = concat!("let b = NonZero::<", stringify!($Int), ">::new(0b_00000100)?;")]
833            ///
834            /// assert_eq!(a.isolate_lowest_one(), b);
835            /// # Some(())
836            /// # }
837            /// ```
838            #[stable(feature = "isolate_most_least_significant_one", since = "1.97.0")]
839            #[rustc_const_stable(feature = "isolate_most_least_significant_one", since = "1.97.0")]
840            #[must_use = "this returns the result of the operation, \
841                        without modifying the original"]
842            #[inline(always)]
843            pub const fn isolate_lowest_one(self) -> Self {
844                let n = self.get();
845                let n = n & n.wrapping_neg();
846
847                // SAFETY: `self` is non-zero, so `self` with only its least
848                // significant set bit will remain non-zero.
849                unsafe { NonZero::new_unchecked(n) }
850            }
851
852            /// Returns the index of the highest bit set to one in `self`.
853            ///
854            #[doc = sign_dependent_expr!{
855                $signedness ?
856                if signed {
857                    ""
858                }
859                if unsigned {
860                    "Note that this is equivalent to [`ilog2`](Self::ilog2)."
861                }
862            }]
863            ///
864            /// # Examples
865            ///
866            /// ```
867            /// # use core::num::NonZero;
868            /// # fn main() { test().unwrap(); }
869            /// # fn test() -> Option<()> {
870            #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::new(0b1)?.highest_one(), 0);")]
871            #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::new(0b1_0000)?.highest_one(), 4);")]
872            #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::new(0b1_1111)?.highest_one(), 4);")]
873            /// # Some(())
874            /// # }
875            /// ```
876            #[stable(feature = "int_lowest_highest_one", since = "1.97.0")]
877            #[rustc_const_stable(feature = "int_lowest_highest_one", since = "1.97.0")]
878            #[must_use = "this returns the result of the operation, \
879                          without modifying the original"]
880            #[inline(always)]
881            pub const fn highest_one(self) -> u32 {
882                Self::BITS - 1 - self.leading_zeros()
883            }
884
885            /// Returns the index of the lowest bit set to one in `self`.
886            ///
887            /// # Examples
888            ///
889            /// ```
890            /// # use core::num::NonZero;
891            /// # fn main() { test().unwrap(); }
892            /// # fn test() -> Option<()> {
893            #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::new(0b1)?.lowest_one(), 0);")]
894            #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::new(0b1_0000)?.lowest_one(), 4);")]
895            #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::new(0b1_1111)?.lowest_one(), 0);")]
896            /// # Some(())
897            /// # }
898            /// ```
899            #[stable(feature = "int_lowest_highest_one", since = "1.97.0")]
900            #[rustc_const_stable(feature = "int_lowest_highest_one", since = "1.97.0")]
901            #[must_use = "this returns the result of the operation, \
902                          without modifying the original"]
903            #[inline(always)]
904            pub const fn lowest_one(self) -> u32 {
905                self.trailing_zeros()
906            }
907
908            /// Returns the number of ones in the binary representation of `self`.
909            ///
910            /// # Examples
911            ///
912            /// ```
913            /// # use std::num::NonZero;
914            /// #
915            /// # fn main() { test().unwrap(); }
916            /// # fn test() -> Option<()> {
917            #[doc = concat!("let a = NonZero::<", stringify!($Int), ">::new(0b100_0000)?;")]
918            #[doc = concat!("let b = NonZero::<", stringify!($Int), ">::new(0b100_0011)?;")]
919            ///
920            /// assert_eq!(a.count_ones(), NonZero::new(1)?);
921            /// assert_eq!(b.count_ones(), NonZero::new(3)?);
922            /// # Some(())
923            /// # }
924            /// ```
925            ///
926            #[stable(feature = "non_zero_count_ones", since = "1.86.0")]
927            #[rustc_const_stable(feature = "non_zero_count_ones", since = "1.86.0")]
928            #[doc(alias = "popcount")]
929            #[doc(alias = "popcnt")]
930            #[must_use = "this returns the result of the operation, \
931                        without modifying the original"]
932            #[inline(always)]
933            pub const fn count_ones(self) -> NonZero<u32> {
934                // SAFETY:
935                // `self` is non-zero, which means it has at least one bit set, which means
936                // that the result of `count_ones` is non-zero.
937                unsafe { NonZero::new_unchecked(self.get().count_ones()) }
938            }
939
940            /// Shifts the bits to the left by a specified amount, `n`,
941            /// wrapping the truncated bits to the end of the resulting integer.
942            ///
943            /// Please note this isn't the same operation as the `<<` shifting operator!
944            ///
945            /// # Examples
946            ///
947            /// ```
948            /// #![feature(nonzero_bitwise)]
949            /// # use std::num::NonZero;
950            /// #
951            /// # fn main() { test().unwrap(); }
952            /// # fn test() -> Option<()> {
953            #[doc = concat!("let n = NonZero::new(", $rot_op, stringify!($Int), ")?;")]
954            #[doc = concat!("let m = NonZero::new(", $rot_result, ")?;")]
955            ///
956            #[doc = concat!("assert_eq!(n.rotate_left(", $rot, "), m);")]
957            /// # Some(())
958            /// # }
959            /// ```
960            #[unstable(feature = "nonzero_bitwise", issue = "128281")]
961            #[must_use = "this returns the result of the operation, \
962                        without modifying the original"]
963            #[inline(always)]
964            pub const fn rotate_left(self, n: u32) -> Self {
965                let result = self.get().rotate_left(n);
966                // SAFETY: Rotating bits preserves the property int > 0.
967                unsafe { Self::new_unchecked(result) }
968            }
969
970            /// Shifts the bits to the right by a specified amount, `n`,
971            /// wrapping the truncated bits to the beginning of the resulting
972            /// integer.
973            ///
974            /// Please note this isn't the same operation as the `>>` shifting operator!
975            ///
976            /// # Examples
977            ///
978            /// ```
979            /// #![feature(nonzero_bitwise)]
980            /// # use std::num::NonZero;
981            /// #
982            /// # fn main() { test().unwrap(); }
983            /// # fn test() -> Option<()> {
984            #[doc = concat!("let n = NonZero::new(", $rot_result, stringify!($Int), ")?;")]
985            #[doc = concat!("let m = NonZero::new(", $rot_op, ")?;")]
986            ///
987            #[doc = concat!("assert_eq!(n.rotate_right(", $rot, "), m);")]
988            /// # Some(())
989            /// # }
990            /// ```
991            #[unstable(feature = "nonzero_bitwise", issue = "128281")]
992            #[must_use = "this returns the result of the operation, \
993                        without modifying the original"]
994            #[inline(always)]
995            pub const fn rotate_right(self, n: u32) -> Self {
996                let result = self.get().rotate_right(n);
997                // SAFETY: Rotating bits preserves the property int > 0.
998                unsafe { Self::new_unchecked(result) }
999            }
1000
1001            /// Reverses the byte order of the integer.
1002            ///
1003            /// # Examples
1004            ///
1005            /// ```
1006            /// #![feature(nonzero_bitwise)]
1007            /// # use std::num::NonZero;
1008            /// #
1009            /// # fn main() { test().unwrap(); }
1010            /// # fn test() -> Option<()> {
1011            #[doc = concat!("let n = NonZero::new(", $swap_op, stringify!($Int), ")?;")]
1012            /// let m = n.swap_bytes();
1013            ///
1014            #[doc = concat!("assert_eq!(m, NonZero::new(", $swapped, ")?);")]
1015            /// # Some(())
1016            /// # }
1017            /// ```
1018            #[unstable(feature = "nonzero_bitwise", issue = "128281")]
1019            #[must_use = "this returns the result of the operation, \
1020                        without modifying the original"]
1021            #[inline(always)]
1022            pub const fn swap_bytes(self) -> Self {
1023                let result = self.get().swap_bytes();
1024                // SAFETY: Shuffling bytes preserves the property int > 0.
1025                unsafe { Self::new_unchecked(result) }
1026            }
1027
1028            /// Reverses the order of bits in the integer. The least significant bit becomes the most significant bit,
1029            /// second least-significant bit becomes second most-significant bit, etc.
1030            ///
1031            /// # Examples
1032            ///
1033            /// ```
1034            /// #![feature(nonzero_bitwise)]
1035            /// # use std::num::NonZero;
1036            /// #
1037            /// # fn main() { test().unwrap(); }
1038            /// # fn test() -> Option<()> {
1039            #[doc = concat!("let n = NonZero::new(", $swap_op, stringify!($Int), ")?;")]
1040            /// let m = n.reverse_bits();
1041            ///
1042            #[doc = concat!("assert_eq!(m, NonZero::new(", $reversed, ")?);")]
1043            /// # Some(())
1044            /// # }
1045            /// ```
1046            #[unstable(feature = "nonzero_bitwise", issue = "128281")]
1047            #[must_use = "this returns the result of the operation, \
1048                        without modifying the original"]
1049            #[inline(always)]
1050            pub const fn reverse_bits(self) -> Self {
1051                let result = self.get().reverse_bits();
1052                // SAFETY: Reversing bits preserves the property int > 0.
1053                unsafe { Self::new_unchecked(result) }
1054            }
1055
1056            /// Converts an integer from big endian to the target's endianness.
1057            ///
1058            /// On big endian this is a no-op. On little endian the bytes are
1059            /// swapped.
1060            ///
1061            /// # Examples
1062            ///
1063            /// ```
1064            /// #![feature(nonzero_bitwise)]
1065            /// # use std::num::NonZero;
1066            #[doc = concat!("use std::num::", stringify!($Ty), ";")]
1067            /// #
1068            /// # fn main() { test().unwrap(); }
1069            /// # fn test() -> Option<()> {
1070            #[doc = concat!("let n = NonZero::new(0x1A", stringify!($Int), ")?;")]
1071            ///
1072            /// if cfg!(target_endian = "big") {
1073            #[doc = concat!("    assert_eq!(", stringify!($Ty), "::from_be(n), n)")]
1074            /// } else {
1075            #[doc = concat!("    assert_eq!(", stringify!($Ty), "::from_be(n), n.swap_bytes())")]
1076            /// }
1077            /// # Some(())
1078            /// # }
1079            /// ```
1080            #[unstable(feature = "nonzero_bitwise", issue = "128281")]
1081            #[must_use]
1082            #[inline(always)]
1083            pub const fn from_be(x: Self) -> Self {
1084                let result = $Int::from_be(x.get());
1085                // SAFETY: Shuffling bytes preserves the property int > 0.
1086                unsafe { Self::new_unchecked(result) }
1087            }
1088
1089            /// Converts an integer from little endian to the target's endianness.
1090            ///
1091            /// On little endian this is a no-op. On big endian the bytes are
1092            /// swapped.
1093            ///
1094            /// # Examples
1095            ///
1096            /// ```
1097            /// #![feature(nonzero_bitwise)]
1098            /// # use std::num::NonZero;
1099            #[doc = concat!("use std::num::", stringify!($Ty), ";")]
1100            /// #
1101            /// # fn main() { test().unwrap(); }
1102            /// # fn test() -> Option<()> {
1103            #[doc = concat!("let n = NonZero::new(0x1A", stringify!($Int), ")?;")]
1104            ///
1105            /// if cfg!(target_endian = "little") {
1106            #[doc = concat!("    assert_eq!(", stringify!($Ty), "::from_le(n), n)")]
1107            /// } else {
1108            #[doc = concat!("    assert_eq!(", stringify!($Ty), "::from_le(n), n.swap_bytes())")]
1109            /// }
1110            /// # Some(())
1111            /// # }
1112            /// ```
1113            #[unstable(feature = "nonzero_bitwise", issue = "128281")]
1114            #[must_use]
1115            #[inline(always)]
1116            pub const fn from_le(x: Self) -> Self {
1117                let result = $Int::from_le(x.get());
1118                // SAFETY: Shuffling bytes preserves the property int > 0.
1119                unsafe { Self::new_unchecked(result) }
1120            }
1121
1122            /// Converts `self` to big endian from the target's endianness.
1123            ///
1124            /// On big endian this is a no-op. On little endian the bytes are
1125            /// swapped.
1126            ///
1127            /// # Examples
1128            ///
1129            /// ```
1130            /// #![feature(nonzero_bitwise)]
1131            /// # use std::num::NonZero;
1132            /// #
1133            /// # fn main() { test().unwrap(); }
1134            /// # fn test() -> Option<()> {
1135            #[doc = concat!("let n = NonZero::new(0x1A", stringify!($Int), ")?;")]
1136            ///
1137            /// if cfg!(target_endian = "big") {
1138            ///     assert_eq!(n.to_be(), n)
1139            /// } else {
1140            ///     assert_eq!(n.to_be(), n.swap_bytes())
1141            /// }
1142            /// # Some(())
1143            /// # }
1144            /// ```
1145            #[unstable(feature = "nonzero_bitwise", issue = "128281")]
1146            #[must_use = "this returns the result of the operation, \
1147                        without modifying the original"]
1148            #[inline(always)]
1149            pub const fn to_be(self) -> Self {
1150                let result = self.get().to_be();
1151                // SAFETY: Shuffling bytes preserves the property int > 0.
1152                unsafe { Self::new_unchecked(result) }
1153            }
1154
1155            /// Converts `self` to little endian from the target's endianness.
1156            ///
1157            /// On little endian this is a no-op. On big endian the bytes are
1158            /// swapped.
1159            ///
1160            /// # Examples
1161            ///
1162            /// ```
1163            /// #![feature(nonzero_bitwise)]
1164            /// # use std::num::NonZero;
1165            /// #
1166            /// # fn main() { test().unwrap(); }
1167            /// # fn test() -> Option<()> {
1168            #[doc = concat!("let n = NonZero::new(0x1A", stringify!($Int), ")?;")]
1169            ///
1170            /// if cfg!(target_endian = "little") {
1171            ///     assert_eq!(n.to_le(), n)
1172            /// } else {
1173            ///     assert_eq!(n.to_le(), n.swap_bytes())
1174            /// }
1175            /// # Some(())
1176            /// # }
1177            /// ```
1178            #[unstable(feature = "nonzero_bitwise", issue = "128281")]
1179            #[must_use = "this returns the result of the operation, \
1180                        without modifying the original"]
1181            #[inline(always)]
1182            pub const fn to_le(self) -> Self {
1183                let result = self.get().to_le();
1184                // SAFETY: Shuffling bytes preserves the property int > 0.
1185                unsafe { Self::new_unchecked(result) }
1186            }
1187
1188            nonzero_integer_signedness_dependent_methods! {
1189                Primitive = $signedness $Int,
1190                SignedPrimitive = $Sint,
1191                UnsignedPrimitive = $Uint,
1192            }
1193
1194            /// Multiplies two non-zero integers together.
1195            /// Checks for overflow and returns [`None`] on overflow.
1196            /// As a consequence, the result cannot wrap to zero.
1197            ///
1198            /// # Examples
1199            ///
1200            /// ```
1201            /// # use std::num::NonZero;
1202            /// #
1203            /// # fn main() { test().unwrap(); }
1204            /// # fn test() -> Option<()> {
1205            #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")]
1206            #[doc = concat!("let four = NonZero::new(4", stringify!($Int), ")?;")]
1207            #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")]
1208            ///
1209            /// assert_eq!(Some(four), two.checked_mul(two));
1210            /// assert_eq!(None, max.checked_mul(two));
1211            /// # Some(())
1212            /// # }
1213            /// ```
1214            #[stable(feature = "nonzero_checked_ops", since = "1.64.0")]
1215            #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")]
1216            #[must_use = "this returns the result of the operation, \
1217                          without modifying the original"]
1218            #[inline]
1219            pub const fn checked_mul(self, other: Self) -> Option<Self> {
1220                if let Some(result) = self.get().checked_mul(other.get()) {
1221                    // SAFETY:
1222                    // - `checked_mul` returns `None` on overflow
1223                    // - `self` and `other` are non-zero
1224                    // - the only way to get zero from a multiplication without overflow is for one
1225                    //   of the sides to be zero
1226                    //
1227                    // So the result cannot be zero.
1228                    Some(unsafe { Self::new_unchecked(result) })
1229                } else {
1230                    None
1231                }
1232            }
1233
1234            /// Multiplies two non-zero integers together, panicking if
1235            /// overflow occurs.
1236            ///
1237            /// # Panics
1238            ///
1239            /// ## Overflow behavior
1240            ///
1241            /// This function always panics on overflow, regardless of whether
1242            /// overflow checks are enabled.
1243            ///
1244            /// # Examples
1245            ///
1246            /// ```
1247            /// #![feature(nonzero_strict_ops)]
1248            ///
1249            /// # use std::num::NonZero;
1250            /// #
1251            /// # fn main() { test().unwrap(); }
1252            /// # fn test() -> Option<()> {
1253            #[doc = concat!("let three = NonZero::new(3", stringify!($Int), ")?;")]
1254            #[doc = concat!("let nine = NonZero::new(9", stringify!($Int), ")?;")]
1255            ///
1256            /// assert_eq!(nine, three.strict_mul(three));
1257            /// # Some(())
1258            /// # }
1259            /// ```
1260            ///
1261            /// The following panics because of overflow:
1262            ///
1263            /// ```should_panic
1264            /// #![feature(nonzero_strict_ops)]
1265            ///
1266            /// # use std::num::NonZero;
1267            /// #
1268            /// # fn main() { test().unwrap(); }
1269            /// # fn test() -> Option<()> {
1270            #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")]
1271            #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")]
1272            ///
1273            /// let _ = max.strict_mul(two);
1274            /// # Some(())
1275            /// # }
1276            /// ```
1277            #[unstable(feature = "nonzero_strict_ops", issue = "164850")]
1278            #[rustc_const_unstable(feature = "const_nonzero_strict_ops", issue = "164850")]
1279            #[must_use = "this returns the result of the operation, \
1280                          without modifying the original"]
1281            #[inline]
1282            #[track_caller]
1283            pub const fn strict_mul(self, other: Self) -> Self {
1284                // SAFETY:
1285                // - `$Int::strict_mul` panics on overflow;
1286                // - `self` and `other` are nonzero;
1287                // - the only way to get zero from a multiplication without
1288                //   overflow is for either operand to be zero.
1289                //
1290                // So the result cannot be zero.
1291                unsafe { Self::new_unchecked(self.get().strict_mul(other.get())) }
1292            }
1293
1294            /// Multiplies two non-zero integers together.
1295            #[doc = concat!("Return [`NonZero::<", stringify!($Int), ">::MAX`] on overflow.")]
1296            ///
1297            /// # Examples
1298            ///
1299            /// ```
1300            /// # use std::num::NonZero;
1301            /// #
1302            /// # fn main() { test().unwrap(); }
1303            /// # fn test() -> Option<()> {
1304            #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")]
1305            #[doc = concat!("let four = NonZero::new(4", stringify!($Int), ")?;")]
1306            #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")]
1307            ///
1308            /// assert_eq!(four, two.saturating_mul(two));
1309            /// assert_eq!(max, four.saturating_mul(max));
1310            /// # Some(())
1311            /// # }
1312            /// ```
1313            #[stable(feature = "nonzero_checked_ops", since = "1.64.0")]
1314            #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")]
1315            #[must_use = "this returns the result of the operation, \
1316                          without modifying the original"]
1317            #[inline]
1318            pub const fn saturating_mul(self, other: Self) -> Self {
1319                // SAFETY:
1320                // - `saturating_mul` returns `u*::MAX`/`i*::MAX`/`i*::MIN` on overflow/underflow,
1321                //   all of which are non-zero
1322                // - `self` and `other` are non-zero
1323                // - the only way to get zero from a multiplication without overflow is for one
1324                //   of the sides to be zero
1325                //
1326                // So the result cannot be zero.
1327                unsafe { Self::new_unchecked(self.get().saturating_mul(other.get())) }
1328            }
1329
1330            /// Multiplies two non-zero integers together,
1331            /// assuming overflow cannot occur.
1332            /// Overflow is unchecked, and it is undefined behavior to overflow
1333            /// *even if the result would wrap to a non-zero value*.
1334            ///
1335            /// # Safety
1336            ///
1337            /// This results in undefined behavior when overflow occurs, i.e.
1338            /// when [`checked_mul`] would return `None`.
1339            ///
1340            /// # Examples
1341            ///
1342            /// ```
1343            /// #![feature(nonzero_ops)]
1344            ///
1345            /// # use std::num::NonZero;
1346            /// #
1347            /// # fn main() { test().unwrap(); }
1348            /// # fn test() -> Option<()> {
1349            #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")]
1350            #[doc = concat!("let four = NonZero::new(4", stringify!($Int), ")?;")]
1351            ///
1352            /// assert_eq!(four, unsafe { two.unchecked_mul(two) });
1353            /// # Some(())
1354            /// # }
1355            /// ```
1356            ///
1357            /// [`checked_mul`]: Self::checked_mul
1358            #[unstable(feature = "nonzero_ops", issue = "84186")]
1359            #[must_use = "this returns the result of the operation, \
1360                          without modifying the original"]
1361            #[inline]
1362            pub const unsafe fn unchecked_mul(self, other: Self) -> Self {
1363                // SAFETY: The caller ensures there is no overflow.
1364                unsafe { Self::new_unchecked(self.get().unchecked_mul(other.get())) }
1365            }
1366
1367            /// Raises non-zero value to an integer power.
1368            /// Checks for overflow and returns [`None`] on overflow.
1369            /// As a consequence, the result cannot wrap to zero.
1370            ///
1371            /// # Examples
1372            ///
1373            /// ```
1374            /// # use std::num::NonZero;
1375            /// #
1376            /// # fn main() { test().unwrap(); }
1377            /// # fn test() -> Option<()> {
1378            #[doc = concat!("let three = NonZero::new(3", stringify!($Int), ")?;")]
1379            #[doc = concat!("let twenty_seven = NonZero::new(27", stringify!($Int), ")?;")]
1380            #[doc = concat!("let half_max = NonZero::new(", stringify!($Int), "::MAX / 2)?;")]
1381            ///
1382            /// assert_eq!(Some(twenty_seven), three.checked_pow(3));
1383            /// assert_eq!(None, half_max.checked_pow(3));
1384            /// # Some(())
1385            /// # }
1386            /// ```
1387            #[stable(feature = "nonzero_checked_ops", since = "1.64.0")]
1388            #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")]
1389            #[must_use = "this returns the result of the operation, \
1390                          without modifying the original"]
1391            #[inline]
1392            pub const fn checked_pow(self, other: u32) -> Option<Self> {
1393                if let Some(result) = self.get().checked_pow(other) {
1394                    // SAFETY:
1395                    // - `checked_pow` returns `None` on overflow/underflow
1396                    // - `self` is non-zero
1397                    // - the only way to get zero from an exponentiation without overflow is
1398                    //   for base to be zero
1399                    //
1400                    // So the result cannot be zero.
1401                    Some(unsafe { Self::new_unchecked(result) })
1402                } else {
1403                    None
1404                }
1405            }
1406
1407            /// Raises a non-zero value to an integer power, panicking if
1408            /// overflow occurs.
1409            ///
1410            /// # Panics
1411            ///
1412            /// ## Overflow behavior
1413            ///
1414            /// This function always panics on overflow, regardless of whether
1415            /// overflow checks are enabled.
1416            ///
1417            /// # Examples
1418            ///
1419            /// ```
1420            /// #![feature(nonzero_strict_ops)]
1421            ///
1422            /// # use std::num::NonZero;
1423            /// #
1424            /// # fn main() { test().unwrap(); }
1425            /// # fn test() -> Option<()> {
1426            #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")]
1427            #[doc = concat!("let sixteen = NonZero::new(16", stringify!($Int), ")?;")]
1428            ///
1429            /// assert_eq!(sixteen, two.strict_pow(4));
1430            /// # Some(())
1431            /// # }
1432            /// ```
1433            ///
1434            /// The following panics because of overflow:
1435            ///
1436            /// ```should_panic
1437            /// #![feature(nonzero_strict_ops)]
1438            ///
1439            /// # use std::num::NonZero;
1440            /// #
1441            /// # fn main() { test().unwrap(); }
1442            /// # fn test() -> Option<()> {
1443            #[doc = concat!("let half_max = NonZero::new(", stringify!($Int), "::MAX / 2)?;")]
1444            ///
1445            /// let _ = half_max.strict_pow(2);
1446            /// # Some(())
1447            /// # }
1448            /// ```
1449            #[unstable(feature = "nonzero_strict_ops", issue = "164850")]
1450            #[rustc_const_unstable(feature = "const_nonzero_strict_ops", issue = "164850")]
1451            #[must_use = "this returns the result of the operation, \
1452                          without modifying the original"]
1453            #[inline]
1454            #[track_caller]
1455            pub const fn strict_pow(self, exp: u32) -> Self {
1456                // SAFETY:
1457                // - `$Int::strict_pow` panics on overflow;
1458                // - `self` is nonzero;
1459                // - the only way to get zero from an exponentiation without
1460                //   overflow is for the base to be zero.
1461                //
1462                // So the result cannot be zero.
1463                unsafe { Self::new_unchecked(self.get().strict_pow(exp)) }
1464            }
1465
1466            /// Raise non-zero value to an integer power.
1467            #[doc = sign_dependent_expr!{
1468                $signedness ?
1469                if signed {
1470                    concat!("Return [`NonZero::<", stringify!($Int), ">::MIN`] ",
1471                                "or [`NonZero::<", stringify!($Int), ">::MAX`] on overflow.")
1472                }
1473                if unsigned {
1474                    concat!("Return [`NonZero::<", stringify!($Int), ">::MAX`] on overflow.")
1475                }
1476            }]
1477            ///
1478            /// # Examples
1479            ///
1480            /// ```
1481            /// # use std::num::NonZero;
1482            /// #
1483            /// # fn main() { test().unwrap(); }
1484            /// # fn test() -> Option<()> {
1485            #[doc = concat!("let three = NonZero::new(3", stringify!($Int), ")?;")]
1486            #[doc = concat!("let twenty_seven = NonZero::new(27", stringify!($Int), ")?;")]
1487            #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")]
1488            ///
1489            /// assert_eq!(twenty_seven, three.saturating_pow(3));
1490            /// assert_eq!(max, max.saturating_pow(3));
1491            /// # Some(())
1492            /// # }
1493            /// ```
1494            #[stable(feature = "nonzero_checked_ops", since = "1.64.0")]
1495            #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")]
1496            #[must_use = "this returns the result of the operation, \
1497                          without modifying the original"]
1498            #[inline]
1499            pub const fn saturating_pow(self, other: u32) -> Self {
1500                // SAFETY:
1501                // - `saturating_pow` returns `u*::MAX`/`i*::MAX`/`i*::MIN` on overflow/underflow,
1502                //   all of which are non-zero
1503                // - `self` is non-zero
1504                // - the only way to get zero from an exponentiation without overflow is
1505                //   for base to be zero
1506                //
1507                // So the result cannot be zero.
1508                unsafe { Self::new_unchecked(self.get().saturating_pow(other)) }
1509            }
1510
1511            /// Parses a non-zero integer from an ASCII-byte slice with decimal digits.
1512            ///
1513            /// The characters are expected to be an optional
1514            #[doc = sign_dependent_expr!{
1515                $signedness ?
1516                if signed {
1517                    " `+` or `-` "
1518                }
1519                if unsigned {
1520                    " `+` "
1521                }
1522            }]
1523            /// sign followed by only digits. Leading and trailing non-digit characters (including
1524            /// whitespace) represent an error. Underscores (which are accepted in Rust literals)
1525            /// also represent an error.
1526            ///
1527            /// # Examples
1528            ///
1529            /// ```
1530            /// # use std::num::NonZero;
1531            /// #
1532            /// # fn main() { test().unwrap(); }
1533            /// # fn test() -> Option<()> {
1534            #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::from_ascii_bytes(b\"+10\"), Ok(NonZero::new(10)?));")]
1535            /// # Some(())
1536            /// # }
1537            /// ```
1538            ///
1539            /// Trailing space returns error:
1540            ///
1541            /// ```
1542            /// # use std::num::NonZero;
1543            /// #
1544            #[doc = concat!("assert!(NonZero::<", stringify!($Int), ">::from_ascii_bytes(b\"1 \").is_err());")]
1545            /// ```
1546            #[stable(feature = "int_from_ascii", since = "CURRENT_RUSTC_VERSION")]
1547            #[rustc_const_unstable(feature = "const_convert", issue = "143773")]
1548            #[inline]
1549            pub const fn from_ascii_bytes<T>(src: T) -> Result<Self, ParseIntError>
1550            where
1551                T: [const] AsRef<[u8]> + [const] crate::marker::Destruct
1552            {
1553                Self::from_ascii_bytes_radix_impl(src.as_ref(), 10)
1554            }
1555
1556            /// Parses a non-zero integer from an ASCII-byte slice with digits in a given base.
1557            ///
1558            /// The characters are expected to be an optional
1559            #[doc = sign_dependent_expr!{
1560                $signedness ?
1561                if signed {
1562                    " `+` or `-` "
1563                }
1564                if unsigned {
1565                    " `+` "
1566                }
1567            }]
1568            /// sign followed by only digits. Leading and trailing non-digit characters (including
1569            /// whitespace) represent an error. Underscores (which are accepted in Rust literals)
1570            /// also represent an error.
1571            ///
1572            /// Digits are a subset of these characters, depending on `radix`:
1573            ///
1574            /// - `0-9`
1575            /// - `a-z`
1576            /// - `A-Z`
1577            ///
1578            /// # Panics
1579            ///
1580            /// This method panics if `radix` is not in the range from 2 to 36.
1581            ///
1582            /// # Examples
1583            ///
1584            /// ```
1585            /// # use std::num::NonZero;
1586            /// #
1587            /// # fn main() { test().unwrap(); }
1588            /// # fn test() -> Option<()> {
1589            #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::from_ascii_bytes_radix(b\"A\", 16), Ok(NonZero::new(10)?));")]
1590            /// # Some(())
1591            /// # }
1592            /// ```
1593            ///
1594            /// Trailing space returns error:
1595            ///
1596            /// ```
1597            /// # use std::num::NonZero;
1598            /// #
1599            #[doc = concat!("assert!(NonZero::<", stringify!($Int), ">::from_ascii_bytes_radix(b\"1 \", 10).is_err());")]
1600            /// ```
1601            #[stable(feature = "int_from_ascii", since = "CURRENT_RUSTC_VERSION")]
1602            #[rustc_const_unstable(feature = "const_convert", issue = "143773")]
1603            #[inline]
1604            pub const fn from_ascii_bytes_radix<T>(src: T, radix: u32) -> Result<Self, ParseIntError>
1605            where
1606                T: [const] AsRef<[u8]> + [const] crate::marker::Destruct
1607            {
1608                Self::from_ascii_bytes_radix_impl(src.as_ref(), radix)
1609            }
1610
1611            #[inline]
1612            const fn from_ascii_bytes_radix_impl(src: &[u8], radix: u32) -> Result<Self, ParseIntError> {
1613                // FIXME(const-hack): This should use `?` again, once it's `const`
1614                let n = match <$Int>::from_ascii_bytes_radix_impl(src, radix) {
1615                    Ok(n) => n,
1616                    Err(err) => return Err(err),
1617                };
1618                // FIXME(const-hack): This should use `Option::ok_or` again, once it's `const`
1619                if let Some(n) = Self::new(n) {
1620                    Ok(n)
1621                } else {
1622                    Err(ParseIntError { kind: IntErrorKind::Zero })
1623                }
1624            }
1625
1626            /// Parses a non-zero integer from a string slice with digits in a given base.
1627            ///
1628            /// The string is expected to be an optional
1629            #[doc = sign_dependent_expr!{
1630                $signedness ?
1631                if signed {
1632                    " `+` or `-` "
1633                }
1634                if unsigned {
1635                    " `+` "
1636                }
1637            }]
1638            /// sign followed by only digits. Leading and trailing non-digit characters (including
1639            /// whitespace) represent an error. Underscores (which are accepted in Rust literals)
1640            /// also represent an error.
1641            ///
1642            /// Digits are a subset of these characters, depending on `radix`:
1643            ///
1644            /// - `0-9`
1645            /// - `a-z`
1646            /// - `A-Z`
1647            ///
1648            /// # Panics
1649            ///
1650            /// This method panics if `radix` is not in the range from 2 to 36.
1651            ///
1652            /// # Examples
1653            ///
1654            /// ```
1655            /// # use std::num::NonZero;
1656            /// #
1657            /// # fn main() { test().unwrap(); }
1658            /// # fn test() -> Option<()> {
1659            #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::from_str_radix(\"A\", 16), Ok(NonZero::new(10)?));")]
1660            /// # Some(())
1661            /// # }
1662            /// ```
1663            ///
1664            /// Trailing space returns error:
1665            ///
1666            /// ```
1667            /// # use std::num::NonZero;
1668            /// #
1669            #[doc = concat!("assert!(NonZero::<", stringify!($Int), ">::from_str_radix(\"1 \", 10).is_err());")]
1670            /// ```
1671            #[stable(feature = "nonzero_from_str_radix", since = "1.98.0")]
1672            #[rustc_const_stable(feature = "nonzero_from_str_radix", since = "1.98.0")]
1673            #[inline]
1674            pub const fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> {
1675                Self::from_ascii_bytes_radix_impl(src.as_bytes(), radix)
1676            }
1677        }
1678
1679        #[stable(feature = "nonzero_parse", since = "1.35.0")]
1680        #[rustc_const_unstable(feature = "const_convert", issue = "143773")]
1681        const impl FromStr for NonZero<$Int> {
1682            type Err = ParseIntError;
1683
1684            /// Parses a non-zero integer from a string slice with decimal digits.
1685            ///
1686            /// The characters are expected to be an optional
1687            #[doc = sign_dependent_expr!{
1688                $signedness ?
1689                if signed {
1690                    " `+` or `-` "
1691                }
1692                if unsigned {
1693                    " `+` "
1694                }
1695            }]
1696            /// sign followed by only digits. Leading and trailing non-digit characters (including
1697            /// whitespace) represent an error. Underscores (which are accepted in Rust literals)
1698            /// also represent an error.
1699            ///
1700            /// # Examples
1701            ///
1702            /// ```
1703            /// use std::num::NonZero;
1704            /// use std::str::FromStr;
1705            ///
1706            #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::from_str(\"+10\"), Ok(NonZero::new(10).unwrap()));")]
1707            /// ```
1708            ///
1709            /// Trailing space returns error:
1710            ///
1711            /// ```
1712            /// use std::num::NonZero;
1713            /// use std::str::FromStr;
1714            ///
1715            #[doc = concat!("assert!(NonZero::<", stringify!($Int), ">::from_str(\"1 \").is_err());")]
1716            /// ```
1717            #[inline]
1718            fn from_str(src: &str) -> Result<Self, Self::Err> {
1719                Self::from_str_radix(src, 10)
1720            }
1721        }
1722
1723        nonzero_integer_signedness_dependent_impls!($signedness $Int);
1724    };
1725
1726    (
1727        Self = $Ty:ident,
1728        Primitive = unsigned $Int:ident,
1729        SignedPrimitive = $Sint:ident,
1730        rot = $rot:literal,
1731        rot_op = $rot_op:literal,
1732        rot_result = $rot_result:literal,
1733        swap_op = $swap_op:literal,
1734        swapped = $swapped:literal,
1735        reversed = $reversed:literal,
1736        $(,)?
1737    ) => {
1738        nonzero_integer! {
1739            #[stable(feature = "nonzero", since = "1.28.0")]
1740            Self = $Ty,
1741            Primitive = unsigned $Int,
1742            SignedPrimitive = $Sint,
1743            UnsignedPrimitive = $Int,
1744            rot = $rot,
1745            rot_op = $rot_op,
1746            rot_result = $rot_result,
1747            swap_op = $swap_op,
1748            swapped = $swapped,
1749            reversed = $reversed,
1750            leading_zeros_test = concat!(stringify!($Int), "::MAX"),
1751        }
1752    };
1753
1754    (
1755        Self = $Ty:ident,
1756        Primitive = signed $Int:ident,
1757        UnsignedPrimitive = $Uint:ident,
1758        rot = $rot:literal,
1759        rot_op = $rot_op:literal,
1760        rot_result = $rot_result:literal,
1761        swap_op = $swap_op:literal,
1762        swapped = $swapped:literal,
1763        reversed = $reversed:literal,
1764    ) => {
1765        nonzero_integer! {
1766            #[stable(feature = "signed_nonzero", since = "1.34.0")]
1767            Self = $Ty,
1768            Primitive = signed $Int,
1769            SignedPrimitive = $Int,
1770            UnsignedPrimitive = $Uint,
1771            rot = $rot,
1772            rot_op = $rot_op,
1773            rot_result = $rot_result,
1774            swap_op = $swap_op,
1775            swapped = $swapped,
1776            reversed = $reversed,
1777            leading_zeros_test = concat!("-1", stringify!($Int)),
1778        }
1779    };
1780}
1781
1782macro_rules! nonzero_integer_signedness_dependent_impls {
1783    // Impls for unsigned nonzero types only.
1784    (unsigned $Int:ty) => {
1785        #[stable(feature = "nonzero_div", since = "1.51.0")]
1786        #[rustc_const_unstable(feature = "const_ops", issue = "143802")]
1787        const impl Div<NonZero<$Int>> for $Int {
1788            type Output = $Int;
1789
1790            /// Same as `self / other.get()`, but because `other` is a `NonZero<_>`,
1791            /// there's never a runtime check for division-by-zero.
1792            ///
1793            /// This operation rounds towards zero, truncating any fractional
1794            /// part of the exact result, and cannot panic.
1795            #[doc(alias = "unchecked_div")]
1796            #[inline]
1797            fn div(self, other: NonZero<$Int>) -> $Int {
1798                // SAFETY: Division by zero is checked because `other` is non-zero,
1799                // and MIN/-1 is checked because `self` is an unsigned int.
1800                unsafe { intrinsics::unchecked_div(self, other.get()) }
1801            }
1802        }
1803
1804        #[stable(feature = "nonzero_div_assign", since = "1.79.0")]
1805        #[rustc_const_unstable(feature = "const_ops", issue = "143802")]
1806        const impl DivAssign<NonZero<$Int>> for $Int {
1807            /// Same as `self /= other.get()`, but because `other` is a `NonZero<_>`,
1808            /// there's never a runtime check for division-by-zero.
1809            ///
1810            /// This operation rounds towards zero, truncating any fractional
1811            /// part of the exact result, and cannot panic.
1812            #[inline]
1813            fn div_assign(&mut self, other: NonZero<$Int>) {
1814                *self = *self / other;
1815            }
1816        }
1817
1818        #[stable(feature = "nonzero_div", since = "1.51.0")]
1819        #[rustc_const_unstable(feature = "const_ops", issue = "143802")]
1820        const impl Rem<NonZero<$Int>> for $Int {
1821            type Output = $Int;
1822
1823            /// This operation satisfies `n % d == n - (n / d) * d`, and cannot panic.
1824            #[inline]
1825            fn rem(self, other: NonZero<$Int>) -> $Int {
1826                // SAFETY: Remainder by zero is checked because `other` is non-zero,
1827                // and MIN/-1 is checked because `self` is an unsigned int.
1828                unsafe { intrinsics::unchecked_rem(self, other.get()) }
1829            }
1830        }
1831
1832        #[stable(feature = "nonzero_div_assign", since = "1.79.0")]
1833        #[rustc_const_unstable(feature = "const_ops", issue = "143802")]
1834        const impl RemAssign<NonZero<$Int>> for $Int {
1835            /// This operation satisfies `n % d == n - (n / d) * d`, and cannot panic.
1836            #[inline]
1837            fn rem_assign(&mut self, other: NonZero<$Int>) {
1838                *self = *self % other;
1839            }
1840        }
1841    };
1842    // Impls for signed nonzero types only.
1843    (signed $Int:ty) => {
1844        #[stable(feature = "signed_nonzero_neg", since = "1.71.0")]
1845        #[rustc_const_unstable(feature = "const_ops", issue = "143802")]
1846        const impl Neg for NonZero<$Int> {
1847            type Output = Self;
1848
1849            #[inline]
1850            fn neg(self) -> Self {
1851                // SAFETY: negation of nonzero cannot yield zero values.
1852                unsafe { Self::new_unchecked(self.get().neg()) }
1853            }
1854        }
1855
1856        forward_ref_unop! { impl Neg, neg for NonZero<$Int>,
1857        #[stable(feature = "signed_nonzero_neg", since = "1.71.0")]
1858        #[rustc_const_unstable(feature = "const_ops", issue = "143802")] }
1859    };
1860}
1861
1862#[rustfmt::skip] // https://github.com/rust-lang/rustfmt/issues/5974
1863macro_rules! nonzero_integer_signedness_dependent_methods {
1864    // Associated items for unsigned nonzero types only.
1865    (
1866        Primitive = unsigned $Int:ident,
1867        SignedPrimitive = $Sint:ty,
1868        UnsignedPrimitive = $Uint:ty,
1869    ) => {
1870        /// The smallest value that can be represented by this non-zero
1871        /// integer type, 1.
1872        ///
1873        /// # Examples
1874        ///
1875        /// ```
1876        /// # use std::num::NonZero;
1877        /// #
1878        #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::MIN.get(), 1", stringify!($Int), ");")]
1879        /// ```
1880        #[stable(feature = "nonzero_min_max", since = "1.70.0")]
1881        pub const MIN: Self = Self::new(1).unwrap();
1882
1883        /// The largest value that can be represented by this non-zero
1884        /// integer type,
1885        #[doc = concat!("equal to [`", stringify!($Int), "::MAX`].")]
1886        ///
1887        /// # Examples
1888        ///
1889        /// ```
1890        /// # use std::num::NonZero;
1891        /// #
1892        #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::MAX.get(), ", stringify!($Int), "::MAX);")]
1893        /// ```
1894        #[stable(feature = "nonzero_min_max", since = "1.70.0")]
1895        pub const MAX: Self = Self::new(<$Int>::MAX).unwrap();
1896
1897        /// Adds an unsigned integer to a non-zero value.
1898        /// Checks for overflow and returns [`None`] on overflow.
1899        /// As a consequence, the result cannot wrap to zero.
1900        ///
1901        ///
1902        /// # Examples
1903        ///
1904        /// ```
1905        /// # use std::num::NonZero;
1906        /// #
1907        /// # fn main() { test().unwrap(); }
1908        /// # fn test() -> Option<()> {
1909        #[doc = concat!("let one = NonZero::new(1", stringify!($Int), ")?;")]
1910        #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")]
1911        #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")]
1912        ///
1913        /// assert_eq!(Some(two), one.checked_add(1));
1914        /// assert_eq!(None, max.checked_add(1));
1915        /// # Some(())
1916        /// # }
1917        /// ```
1918        #[stable(feature = "nonzero_checked_ops", since = "1.64.0")]
1919        #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")]
1920        #[must_use = "this returns the result of the operation, \
1921                      without modifying the original"]
1922        #[inline]
1923        pub const fn checked_add(self, other: $Int) -> Option<Self> {
1924            if let Some(result) = self.get().checked_add(other) {
1925                // SAFETY:
1926                // - `checked_add` returns `None` on overflow
1927                // - `self` is non-zero
1928                // - the only way to get zero from an addition without overflow is for both
1929                //   sides to be zero
1930                //
1931                // So the result cannot be zero.
1932                Some(unsafe { Self::new_unchecked(result) })
1933            } else {
1934                None
1935            }
1936        }
1937
1938        /// Adds an unsigned integer to a non-zero value, panicking
1939        /// if overflow occurs.
1940        ///
1941        /// # Panics
1942        ///
1943        /// ## Overflow behavior
1944        ///
1945        /// This function always panics on overflow, regardless of whether
1946        /// overflow checks are enabled.
1947        ///
1948        /// # Examples
1949        ///
1950        /// ```
1951        /// #![feature(nonzero_strict_ops)]
1952        ///
1953        /// # use std::num::NonZero;
1954        /// #
1955        /// # fn main() { test().unwrap(); }
1956        /// # fn test() -> Option<()> {
1957        #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")]
1958        #[doc = concat!("let three = NonZero::new(3", stringify!($Int), ")?;")]
1959        ///
1960        /// assert_eq!(three, two.strict_add(1));
1961        /// # Some(())
1962        /// # }
1963        /// ```
1964        ///
1965        /// The following panics because of overflow:
1966        ///
1967        /// ```should_panic
1968        /// #![feature(nonzero_strict_ops)]
1969        ///
1970        /// # use std::num::NonZero;
1971        /// #
1972        /// # fn main() { test().unwrap(); }
1973        /// # fn test() -> Option<()> {
1974        #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")]
1975        ///
1976        /// let _ = max.strict_add(1);
1977        /// # Some(())
1978        /// # }
1979        /// ```
1980        #[unstable(feature = "nonzero_strict_ops", issue = "164850")]
1981        #[rustc_const_unstable(feature = "const_nonzero_strict_ops", issue = "164850")]
1982        #[must_use = "this returns the result of the operation, \
1983                      without modifying the original"]
1984        #[inline]
1985        #[track_caller]
1986        pub const fn strict_add(self, other: $Int) -> Self {
1987            // SAFETY:
1988            // - `$Int::strict_add` panics on overflow;
1989            // - `self` is nonzero;
1990            // - the only way to get zero from an unsigned addition without
1991            //   overflow is for both addends to be zero.
1992            //
1993            // So the result cannot be zero.
1994            unsafe { Self::new_unchecked(self.get().strict_add(other)) }
1995        }
1996
1997        /// Adds an unsigned integer to a non-zero value.
1998        #[doc = concat!("Return [`NonZero::<", stringify!($Int), ">::MAX`] on overflow.")]
1999        ///
2000        /// # Examples
2001        ///
2002        /// ```
2003        /// # use std::num::NonZero;
2004        /// #
2005        /// # fn main() { test().unwrap(); }
2006        /// # fn test() -> Option<()> {
2007        #[doc = concat!("let one = NonZero::new(1", stringify!($Int), ")?;")]
2008        #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")]
2009        #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")]
2010        ///
2011        /// assert_eq!(two, one.saturating_add(1));
2012        /// assert_eq!(max, max.saturating_add(1));
2013        /// # Some(())
2014        /// # }
2015        /// ```
2016        #[stable(feature = "nonzero_checked_ops", since = "1.64.0")]
2017        #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")]
2018        #[must_use = "this returns the result of the operation, \
2019                      without modifying the original"]
2020        #[inline]
2021        pub const fn saturating_add(self, other: $Int) -> Self {
2022            // SAFETY:
2023            // - `saturating_add` returns `u*::MAX` on overflow, which is non-zero
2024            // - `self` is non-zero
2025            // - the only way to get zero from an addition without overflow is for both
2026            //   sides to be zero
2027            //
2028            // So the result cannot be zero.
2029            unsafe { Self::new_unchecked(self.get().saturating_add(other)) }
2030        }
2031
2032        /// Adds an unsigned integer to a non-zero value,
2033        /// assuming overflow cannot occur.
2034        /// Overflow is unchecked, and it is undefined behavior to overflow
2035        /// *even if the result would wrap to a non-zero value*.
2036        ///
2037        /// # Safety
2038        ///
2039        /// This results in undefined behavior when overflow occurs, i.e. when
2040        /// [`checked_add`] would return `None`.
2041        ///
2042        /// # Examples
2043        ///
2044        /// ```
2045        /// #![feature(nonzero_ops)]
2046        ///
2047        /// # use std::num::NonZero;
2048        /// #
2049        /// # fn main() { test().unwrap(); }
2050        /// # fn test() -> Option<()> {
2051        #[doc = concat!("let one = NonZero::new(1", stringify!($Int), ")?;")]
2052        #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")]
2053        ///
2054        /// assert_eq!(two, unsafe { one.unchecked_add(1) });
2055        /// # Some(())
2056        /// # }
2057        /// ```
2058        ///
2059        /// [`checked_add`]: Self::checked_add
2060        #[unstable(feature = "nonzero_ops", issue = "84186")]
2061        #[must_use = "this returns the result of the operation, \
2062                      without modifying the original"]
2063        #[inline]
2064        pub const unsafe fn unchecked_add(self, other: $Int) -> Self {
2065            // SAFETY: The caller ensures there is no overflow.
2066            unsafe { Self::new_unchecked(self.get().unchecked_add(other)) }
2067        }
2068
2069        /// Calculates the quotient of `self` and `rhs`, rounding the result towards positive infinity.
2070        ///
2071        /// The result is guaranteed to be non-zero.
2072        ///
2073        /// # Examples
2074        ///
2075        /// ```
2076        /// # use std::num::NonZero;
2077        #[doc = concat!("let one = NonZero::new(1", stringify!($Int), ").unwrap();")]
2078        #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX).unwrap();")]
2079        /// assert_eq!(one.div_ceil(max), one);
2080        ///
2081        #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ").unwrap();")]
2082        #[doc = concat!("let three = NonZero::new(3", stringify!($Int), ").unwrap();")]
2083        /// assert_eq!(three.div_ceil(two), two);
2084        /// ```
2085        #[stable(feature = "unsigned_nonzero_div_ceil", since = "1.92.0")]
2086        #[rustc_const_stable(feature = "unsigned_nonzero_div_ceil", since = "1.92.0")]
2087        #[must_use = "this returns the result of the operation, \
2088                      without modifying the original"]
2089        #[inline]
2090        pub const fn div_ceil(self, rhs: Self) -> Self {
2091            // An implementation of the function without calculating the remainder.
2092            // It is better than the implementation for normal integers, but it can only
2093            // be used here because of the possibility to subtract by one without overflow.
2094            let v = (self.get() - 1) / rhs.get() + 1;
2095            // SAFETY: ceiled division of two positive integers can never be zero.
2096            unsafe { Self::new_unchecked(v) }
2097        }
2098
2099        /// Returns the smallest power of two greater than or equal to `self`.
2100        /// Checks for overflow and returns [`None`]
2101        /// if the next power of two is greater than the type’s maximum value.
2102        /// As a consequence, the result cannot wrap to zero.
2103        ///
2104        /// # Examples
2105        ///
2106        /// ```
2107        /// # use std::num::NonZero;
2108        /// #
2109        /// # fn main() { test().unwrap(); }
2110        /// # fn test() -> Option<()> {
2111        #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")]
2112        #[doc = concat!("let three = NonZero::new(3", stringify!($Int), ")?;")]
2113        #[doc = concat!("let four = NonZero::new(4", stringify!($Int), ")?;")]
2114        #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")]
2115        ///
2116        /// assert_eq!(Some(two), two.checked_next_power_of_two() );
2117        /// assert_eq!(Some(four), three.checked_next_power_of_two() );
2118        /// assert_eq!(None, max.checked_next_power_of_two() );
2119        /// # Some(())
2120        /// # }
2121        /// ```
2122        #[stable(feature = "nonzero_checked_ops", since = "1.64.0")]
2123        #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")]
2124        #[must_use = "this returns the result of the operation, \
2125                      without modifying the original"]
2126        #[inline]
2127        pub const fn checked_next_power_of_two(self) -> Option<Self> {
2128            if let Some(nz) = self.get().checked_next_power_of_two() {
2129                // SAFETY: The next power of two is positive
2130                // and overflow is checked.
2131                Some(unsafe { Self::new_unchecked(nz) })
2132            } else {
2133                None
2134            }
2135        }
2136
2137        /// Returns the base 2 logarithm of the number, rounded down.
2138        ///
2139        /// This is the same operation as
2140        #[doc = concat!("[`", stringify!($Int), "::ilog2`],")]
2141        /// except that it has no failure cases to worry about
2142        /// since this value can never be zero.
2143        ///
2144        /// Note that this is equivalent to [`highest_one`](Self::highest_one).
2145        ///
2146        /// # Examples
2147        ///
2148        /// ```
2149        /// # use std::num::NonZero;
2150        /// #
2151        /// # fn main() { test().unwrap(); }
2152        /// # fn test() -> Option<()> {
2153        #[doc = concat!("assert_eq!(NonZero::new(7", stringify!($Int), ")?.ilog2(), 2);")]
2154        #[doc = concat!("assert_eq!(NonZero::new(8", stringify!($Int), ")?.ilog2(), 3);")]
2155        #[doc = concat!("assert_eq!(NonZero::new(9", stringify!($Int), ")?.ilog2(), 3);")]
2156        /// # Some(())
2157        /// # }
2158        /// ```
2159        #[stable(feature = "int_log", since = "1.67.0")]
2160        #[rustc_const_stable(feature = "int_log", since = "1.67.0")]
2161        #[must_use = "this returns the result of the operation, \
2162                      without modifying the original"]
2163        #[inline]
2164        pub const fn ilog2(self) -> u32 {
2165            Self::BITS - 1 - self.leading_zeros()
2166        }
2167
2168        /// Returns the base 10 logarithm of the number, rounded down.
2169        ///
2170        /// This is the same operation as
2171        #[doc = concat!("[`", stringify!($Int), "::ilog10`],")]
2172        /// except that it has no failure cases to worry about
2173        /// since this value can never be zero.
2174        ///
2175        /// # Examples
2176        ///
2177        /// ```
2178        /// # use std::num::NonZero;
2179        /// #
2180        /// # fn main() { test().unwrap(); }
2181        /// # fn test() -> Option<()> {
2182        #[doc = concat!("assert_eq!(NonZero::new(99", stringify!($Int), ")?.ilog10(), 1);")]
2183        #[doc = concat!("assert_eq!(NonZero::new(100", stringify!($Int), ")?.ilog10(), 2);")]
2184        #[doc = concat!("assert_eq!(NonZero::new(101", stringify!($Int), ")?.ilog10(), 2);")]
2185        /// # Some(())
2186        /// # }
2187        /// ```
2188        #[stable(feature = "int_log", since = "1.67.0")]
2189        #[rustc_const_stable(feature = "int_log", since = "1.67.0")]
2190        #[must_use = "this returns the result of the operation, \
2191                      without modifying the original"]
2192        #[inline]
2193        pub const fn ilog10(self) -> u32 {
2194            imp::int_log10::$Int(self)
2195        }
2196
2197        /// Calculates the midpoint (average) between `self` and `rhs`.
2198        ///
2199        /// `midpoint(a, b)` is `(a + b) >> 1` as if it were performed in a
2200        /// sufficiently-large signed integral type. This implies that the result is
2201        /// always rounded towards negative infinity and that no overflow will ever occur.
2202        ///
2203        /// # Examples
2204        ///
2205        /// ```
2206        /// # use std::num::NonZero;
2207        /// #
2208        /// # fn main() { test().unwrap(); }
2209        /// # fn test() -> Option<()> {
2210        #[doc = concat!("let one = NonZero::new(1", stringify!($Int), ")?;")]
2211        #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")]
2212        #[doc = concat!("let four = NonZero::new(4", stringify!($Int), ")?;")]
2213        ///
2214        /// assert_eq!(one.midpoint(four), two);
2215        /// assert_eq!(four.midpoint(one), two);
2216        /// # Some(())
2217        /// # }
2218        /// ```
2219        #[stable(feature = "num_midpoint", since = "1.85.0")]
2220        #[rustc_const_stable(feature = "num_midpoint", since = "1.85.0")]
2221        #[must_use = "this returns the result of the operation, \
2222                      without modifying the original"]
2223        #[doc(alias = "average_floor")]
2224        #[doc(alias = "average")]
2225        #[inline]
2226        pub const fn midpoint(self, rhs: Self) -> Self {
2227            // SAFETY: The only way to get `0` with midpoint is to have two opposite or
2228            // near opposite numbers: (-5, 5), (0, 1), (0, 0) which is impossible because
2229            // of the unsignedness of this number and also because `Self` is guaranteed to
2230            // never being 0.
2231            unsafe { Self::new_unchecked(self.get().midpoint(rhs.get())) }
2232        }
2233
2234        /// Returns `true` if and only if `self == (1 << k)` for some `k`.
2235        ///
2236        /// On many architectures, this function can perform better than `is_power_of_two()`
2237        /// on the underlying integer type, as special handling of zero can be avoided.
2238        ///
2239        /// # Examples
2240        ///
2241        /// ```
2242        /// # use std::num::NonZero;
2243        /// #
2244        /// # fn main() { test().unwrap(); }
2245        /// # fn test() -> Option<()> {
2246        #[doc = concat!("let eight = NonZero::new(8", stringify!($Int), ")?;")]
2247        /// assert!(eight.is_power_of_two());
2248        #[doc = concat!("let ten = NonZero::new(10", stringify!($Int), ")?;")]
2249        /// assert!(!ten.is_power_of_two());
2250        /// # Some(())
2251        /// # }
2252        /// ```
2253        #[must_use]
2254        #[stable(feature = "nonzero_is_power_of_two", since = "1.59.0")]
2255        #[rustc_const_stable(feature = "nonzero_is_power_of_two", since = "1.59.0")]
2256        #[inline]
2257        pub const fn is_power_of_two(self) -> bool {
2258            // LLVM 11 normalizes `unchecked_sub(x, 1) & x == 0` to the implementation seen here.
2259            // On the basic x86-64 target, this saves 3 instructions for the zero check.
2260            // On x86_64 with BMI1, being nonzero lets it codegen to `BLSR`, which saves an instruction
2261            // compared to the `POPCNT` implementation on the underlying integer type.
2262
2263            intrinsics::ctpop(self.get()) < 2
2264        }
2265
2266        /// Returns the square root of the number, rounded down.
2267        ///
2268        /// # Examples
2269        ///
2270        /// ```
2271        /// # use std::num::NonZero;
2272        /// #
2273        /// # fn main() { test().unwrap(); }
2274        /// # fn test() -> Option<()> {
2275        #[doc = concat!("let ten = NonZero::new(10", stringify!($Int), ")?;")]
2276        #[doc = concat!("let three = NonZero::new(3", stringify!($Int), ")?;")]
2277        ///
2278        /// assert_eq!(ten.isqrt(), three);
2279        /// # Some(())
2280        /// # }
2281        /// ```
2282        #[stable(feature = "isqrt", since = "1.84.0")]
2283        #[rustc_const_stable(feature = "isqrt", since = "1.84.0")]
2284        #[must_use = "this returns the result of the operation, \
2285                      without modifying the original"]
2286        #[inline]
2287        pub const fn isqrt(self) -> Self {
2288            let result = self.get().isqrt();
2289
2290            // SAFETY: Integer square root is a monotonically nondecreasing
2291            // function, which means that increasing the input will never cause
2292            // the output to decrease. Thus, since the input for nonzero
2293            // unsigned integers has a lower bound of 1, the lower bound of the
2294            // results will be sqrt(1), which is 1, so a result can't be zero.
2295            unsafe { Self::new_unchecked(result) }
2296        }
2297
2298        /// Returns the bit pattern of `self` reinterpreted as a signed integer of the same size.
2299        ///
2300        /// # Examples
2301        ///
2302        /// ```
2303        /// # use std::num::NonZero;
2304        ///
2305        #[doc = concat!("let n = NonZero::<", stringify!($Int), ">::MAX;")]
2306        ///
2307        #[doc = concat!("assert_eq!(n.cast_signed(), NonZero::new(-1", stringify!($Sint), ").unwrap());")]
2308        /// ```
2309        #[stable(feature = "integer_sign_cast", since = "1.87.0")]
2310        #[rustc_const_stable(feature = "integer_sign_cast", since = "1.87.0")]
2311        #[must_use = "this returns the result of the operation, \
2312                      without modifying the original"]
2313        #[inline(always)]
2314        pub const fn cast_signed(self) -> NonZero<$Sint> {
2315            // SAFETY: `self.get()` can't be zero
2316            unsafe { NonZero::new_unchecked(self.get().cast_signed()) }
2317        }
2318
2319        /// Returns the minimum number of bits required to represent `self`.
2320        ///
2321        /// # Examples
2322        ///
2323        /// ```
2324        /// # use core::num::NonZero;
2325        /// #
2326        /// # fn main() { test().unwrap(); }
2327        /// # fn test() -> Option<()> {
2328        #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::new(0b1)?.bit_width(), NonZero::new(1)?);")]
2329        #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::new(0b111)?.bit_width(), NonZero::new(3)?);")]
2330        #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::new(0b1110)?.bit_width(), NonZero::new(4)?);")]
2331        /// # Some(())
2332        /// # }
2333        /// ```
2334        #[stable(feature = "uint_bit_width", since = "1.97.0")]
2335        #[rustc_const_stable(feature = "uint_bit_width", since = "1.97.0")]
2336        #[must_use = "this returns the result of the operation, \
2337                      without modifying the original"]
2338        #[inline(always)]
2339        pub const fn bit_width(self) -> NonZero<u32> {
2340            // SAFETY: Since `self.leading_zeros()` is always less than
2341            // `Self::BITS`, this subtraction can never be zero.
2342            unsafe { NonZero::new_unchecked(Self::BITS - self.leading_zeros()) }
2343        }
2344    };
2345
2346    // Associated items for signed nonzero types only.
2347    (
2348        Primitive = signed $Int:ident,
2349        SignedPrimitive = $Sint:ty,
2350        UnsignedPrimitive = $Uint:ty,
2351    ) => {
2352        /// The smallest value that can be represented by this non-zero
2353        /// integer type,
2354        #[doc = concat!("equal to [`", stringify!($Int), "::MIN`].")]
2355        ///
2356        /// Note: While most integer types are defined for every whole
2357        /// number between `MIN` and `MAX`, signed non-zero integers are
2358        /// a special case. They have a "gap" at 0.
2359        ///
2360        /// # Examples
2361        ///
2362        /// ```
2363        /// # use std::num::NonZero;
2364        /// #
2365        #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::MIN.get(), ", stringify!($Int), "::MIN);")]
2366        /// ```
2367        #[stable(feature = "nonzero_min_max", since = "1.70.0")]
2368        pub const MIN: Self = Self::new(<$Int>::MIN).unwrap();
2369
2370        /// The largest value that can be represented by this non-zero
2371        /// integer type,
2372        #[doc = concat!("equal to [`", stringify!($Int), "::MAX`].")]
2373        ///
2374        /// Note: While most integer types are defined for every whole
2375        /// number between `MIN` and `MAX`, signed non-zero integers are
2376        /// a special case. They have a "gap" at 0.
2377        ///
2378        /// # Examples
2379        ///
2380        /// ```
2381        /// # use std::num::NonZero;
2382        /// #
2383        #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::MAX.get(), ", stringify!($Int), "::MAX);")]
2384        /// ```
2385        #[stable(feature = "nonzero_min_max", since = "1.70.0")]
2386        pub const MAX: Self = Self::new(<$Int>::MAX).unwrap();
2387
2388        /// Computes the absolute value of self.
2389        #[doc = concat!("See [`", stringify!($Int), "::abs`]")]
2390        /// for documentation on overflow behavior.
2391        ///
2392        /// # Example
2393        ///
2394        /// ```
2395        /// # use std::num::NonZero;
2396        /// #
2397        /// # fn main() { test().unwrap(); }
2398        /// # fn test() -> Option<()> {
2399        #[doc = concat!("let pos = NonZero::new(1", stringify!($Int), ")?;")]
2400        #[doc = concat!("let neg = NonZero::new(-1", stringify!($Int), ")?;")]
2401        ///
2402        /// assert_eq!(pos, pos.abs());
2403        /// assert_eq!(pos, neg.abs());
2404        /// # Some(())
2405        /// # }
2406        /// ```
2407        #[stable(feature = "nonzero_checked_ops", since = "1.64.0")]
2408        #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")]
2409        #[must_use = "this returns the result of the operation, \
2410                      without modifying the original"]
2411        #[inline]
2412        pub const fn abs(self) -> Self {
2413            // SAFETY: This cannot overflow to zero.
2414            unsafe { Self::new_unchecked(self.get().abs()) }
2415        }
2416
2417        /// Checked absolute value.
2418        /// Checks for overflow and returns [`None`] if
2419        #[doc = concat!("`self == NonZero::<", stringify!($Int), ">::MIN`.")]
2420        /// The result cannot be zero.
2421        ///
2422        /// # Example
2423        ///
2424        /// ```
2425        /// # use std::num::NonZero;
2426        /// #
2427        /// # fn main() { test().unwrap(); }
2428        /// # fn test() -> Option<()> {
2429        #[doc = concat!("let pos = NonZero::new(1", stringify!($Int), ")?;")]
2430        #[doc = concat!("let neg = NonZero::new(-1", stringify!($Int), ")?;")]
2431        #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")]
2432        ///
2433        /// assert_eq!(Some(pos), neg.checked_abs());
2434        /// assert_eq!(None, min.checked_abs());
2435        /// # Some(())
2436        /// # }
2437        /// ```
2438        #[stable(feature = "nonzero_checked_ops", since = "1.64.0")]
2439        #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")]
2440        #[must_use = "this returns the result of the operation, \
2441                      without modifying the original"]
2442        #[inline]
2443        pub const fn checked_abs(self) -> Option<Self> {
2444            if let Some(nz) = self.get().checked_abs() {
2445                // SAFETY: absolute value of nonzero cannot yield zero values.
2446                Some(unsafe { Self::new_unchecked(nz) })
2447            } else {
2448                None
2449            }
2450        }
2451
2452        /// Computes the absolute value of self,
2453        /// with overflow information, see
2454        #[doc = concat!("[`", stringify!($Int), "::overflowing_abs`].")]
2455        ///
2456        /// # Example
2457        ///
2458        /// ```
2459        /// # use std::num::NonZero;
2460        /// #
2461        /// # fn main() { test().unwrap(); }
2462        /// # fn test() -> Option<()> {
2463        #[doc = concat!("let pos = NonZero::new(1", stringify!($Int), ")?;")]
2464        #[doc = concat!("let neg = NonZero::new(-1", stringify!($Int), ")?;")]
2465        #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")]
2466        ///
2467        /// assert_eq!((pos, false), pos.overflowing_abs());
2468        /// assert_eq!((pos, false), neg.overflowing_abs());
2469        /// assert_eq!((min, true), min.overflowing_abs());
2470        /// # Some(())
2471        /// # }
2472        /// ```
2473        #[stable(feature = "nonzero_checked_ops", since = "1.64.0")]
2474        #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")]
2475        #[must_use = "this returns the result of the operation, \
2476                      without modifying the original"]
2477        #[inline]
2478        pub const fn overflowing_abs(self) -> (Self, bool) {
2479            let (nz, flag) = self.get().overflowing_abs();
2480            (
2481                // SAFETY: absolute value of nonzero cannot yield zero values.
2482                unsafe { Self::new_unchecked(nz) },
2483                flag,
2484            )
2485        }
2486
2487        /// Saturating absolute value, see
2488        #[doc = concat!("[`", stringify!($Int), "::saturating_abs`].")]
2489        ///
2490        /// # Example
2491        ///
2492        /// ```
2493        /// # use std::num::NonZero;
2494        /// #
2495        /// # fn main() { test().unwrap(); }
2496        /// # fn test() -> Option<()> {
2497        #[doc = concat!("let pos = NonZero::new(1", stringify!($Int), ")?;")]
2498        #[doc = concat!("let neg = NonZero::new(-1", stringify!($Int), ")?;")]
2499        #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")]
2500        #[doc = concat!("let min_plus = NonZero::new(", stringify!($Int), "::MIN + 1)?;")]
2501        #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")]
2502        ///
2503        /// assert_eq!(pos, pos.saturating_abs());
2504        /// assert_eq!(pos, neg.saturating_abs());
2505        /// assert_eq!(max, min.saturating_abs());
2506        /// assert_eq!(max, min_plus.saturating_abs());
2507        /// # Some(())
2508        /// # }
2509        /// ```
2510        #[stable(feature = "nonzero_checked_ops", since = "1.64.0")]
2511        #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")]
2512        #[must_use = "this returns the result of the operation, \
2513                      without modifying the original"]
2514        #[inline]
2515        pub const fn saturating_abs(self) -> Self {
2516            // SAFETY: absolute value of nonzero cannot yield zero values.
2517            unsafe { Self::new_unchecked(self.get().saturating_abs()) }
2518        }
2519
2520        /// Wrapping absolute value, see
2521        #[doc = concat!("[`", stringify!($Int), "::wrapping_abs`].")]
2522        ///
2523        /// # Example
2524        ///
2525        /// ```
2526        /// # use std::num::NonZero;
2527        /// #
2528        /// # fn main() { test().unwrap(); }
2529        /// # fn test() -> Option<()> {
2530        #[doc = concat!("let pos = NonZero::new(1", stringify!($Int), ")?;")]
2531        #[doc = concat!("let neg = NonZero::new(-1", stringify!($Int), ")?;")]
2532        #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")]
2533        #[doc = concat!("# let max = NonZero::new(", stringify!($Int), "::MAX)?;")]
2534        ///
2535        /// assert_eq!(pos, pos.wrapping_abs());
2536        /// assert_eq!(pos, neg.wrapping_abs());
2537        /// assert_eq!(min, min.wrapping_abs());
2538        /// assert_eq!(max, (-max).wrapping_abs());
2539        /// # Some(())
2540        /// # }
2541        /// ```
2542        #[stable(feature = "nonzero_checked_ops", since = "1.64.0")]
2543        #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")]
2544        #[must_use = "this returns the result of the operation, \
2545                      without modifying the original"]
2546        #[inline]
2547        pub const fn wrapping_abs(self) -> Self {
2548            // SAFETY: absolute value of nonzero cannot yield zero values.
2549            unsafe { Self::new_unchecked(self.get().wrapping_abs()) }
2550        }
2551
2552        /// Computes the absolute value of self
2553        /// without any wrapping or panicking.
2554        ///
2555        /// # Example
2556        ///
2557        /// ```
2558        /// # use std::num::NonZero;
2559        /// #
2560        /// # fn main() { test().unwrap(); }
2561        /// # fn test() -> Option<()> {
2562        #[doc = concat!("let u_pos = NonZero::new(1", stringify!($Uint), ")?;")]
2563        #[doc = concat!("let i_pos = NonZero::new(1", stringify!($Int), ")?;")]
2564        #[doc = concat!("let i_neg = NonZero::new(-1", stringify!($Int), ")?;")]
2565        #[doc = concat!("let i_min = NonZero::new(", stringify!($Int), "::MIN)?;")]
2566        #[doc = concat!("let u_max = NonZero::new(", stringify!($Uint), "::MAX / 2 + 1)?;")]
2567        ///
2568        /// assert_eq!(u_pos, i_pos.unsigned_abs());
2569        /// assert_eq!(u_pos, i_neg.unsigned_abs());
2570        /// assert_eq!(u_max, i_min.unsigned_abs());
2571        /// # Some(())
2572        /// # }
2573        /// ```
2574        #[stable(feature = "nonzero_checked_ops", since = "1.64.0")]
2575        #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")]
2576        #[must_use = "this returns the result of the operation, \
2577                      without modifying the original"]
2578        #[inline]
2579        pub const fn unsigned_abs(self) -> NonZero<$Uint> {
2580            // SAFETY: absolute value of nonzero cannot yield zero values.
2581            unsafe { NonZero::new_unchecked(self.get().unsigned_abs()) }
2582        }
2583
2584        /// Returns `true` if `self` is positive and `false` if the
2585        /// number is negative.
2586        ///
2587        /// # Example
2588        ///
2589        /// ```
2590        /// # use std::num::NonZero;
2591        /// #
2592        /// # fn main() { test().unwrap(); }
2593        /// # fn test() -> Option<()> {
2594        #[doc = concat!("let pos_five = NonZero::new(5", stringify!($Int), ")?;")]
2595        #[doc = concat!("let neg_five = NonZero::new(-5", stringify!($Int), ")?;")]
2596        ///
2597        /// assert!(pos_five.is_positive());
2598        /// assert!(!neg_five.is_positive());
2599        /// # Some(())
2600        /// # }
2601        /// ```
2602        #[must_use]
2603        #[inline]
2604        #[stable(feature = "nonzero_negation_ops", since = "1.71.0")]
2605        #[rustc_const_stable(feature = "nonzero_negation_ops", since = "1.71.0")]
2606        pub const fn is_positive(self) -> bool {
2607            self.get().is_positive()
2608        }
2609
2610        /// Returns `true` if `self` is negative and `false` if the
2611        /// number is positive.
2612        ///
2613        /// # Example
2614        ///
2615        /// ```
2616        /// # use std::num::NonZero;
2617        /// #
2618        /// # fn main() { test().unwrap(); }
2619        /// # fn test() -> Option<()> {
2620        #[doc = concat!("let pos_five = NonZero::new(5", stringify!($Int), ")?;")]
2621        #[doc = concat!("let neg_five = NonZero::new(-5", stringify!($Int), ")?;")]
2622        ///
2623        /// assert!(neg_five.is_negative());
2624        /// assert!(!pos_five.is_negative());
2625        /// # Some(())
2626        /// # }
2627        /// ```
2628        #[must_use]
2629        #[inline]
2630        #[stable(feature = "nonzero_negation_ops", since = "1.71.0")]
2631        #[rustc_const_stable(feature = "nonzero_negation_ops", since = "1.71.0")]
2632        pub const fn is_negative(self) -> bool {
2633            self.get().is_negative()
2634        }
2635
2636        /// Checked negation. Computes `-self`,
2637        #[doc = concat!("returning `None` if `self == NonZero::<", stringify!($Int), ">::MIN`.")]
2638        ///
2639        /// # Example
2640        ///
2641        /// ```
2642        /// # use std::num::NonZero;
2643        /// #
2644        /// # fn main() { test().unwrap(); }
2645        /// # fn test() -> Option<()> {
2646        #[doc = concat!("let pos_five = NonZero::new(5", stringify!($Int), ")?;")]
2647        #[doc = concat!("let neg_five = NonZero::new(-5", stringify!($Int), ")?;")]
2648        #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")]
2649        ///
2650        /// assert_eq!(pos_five.checked_neg(), Some(neg_five));
2651        /// assert_eq!(min.checked_neg(), None);
2652        /// # Some(())
2653        /// # }
2654        /// ```
2655        #[inline]
2656        #[stable(feature = "nonzero_negation_ops", since = "1.71.0")]
2657        #[rustc_const_stable(feature = "nonzero_negation_ops", since = "1.71.0")]
2658        pub const fn checked_neg(self) -> Option<Self> {
2659            if let Some(result) = self.get().checked_neg() {
2660                // SAFETY: negation of nonzero cannot yield zero values.
2661                return Some(unsafe { Self::new_unchecked(result) });
2662            }
2663            None
2664        }
2665
2666        /// Checked negation. Computes `-self`, panicking if `self == MIN`.
2667        ///
2668        /// # Panics
2669        ///
2670        /// ## Overflow behavior
2671        ///
2672        /// This function always panics on overflow, regardless of whether
2673        /// overflow checks are enabled.
2674        ///
2675        /// # Examples
2676        ///
2677        /// ```
2678        /// #![feature(nonzero_strict_ops)]
2679        ///
2680        /// # use std::num::NonZero;
2681        /// #
2682        /// # fn main() { test().unwrap(); }
2683        /// # fn test() -> Option<()> {
2684        #[doc = concat!("let pos_six = NonZero::new(6", stringify!($Int), ")?;")]
2685        #[doc = concat!("let neg_six = NonZero::new(-6", stringify!($Int), ")?;")]
2686        ///
2687        /// assert_eq!(pos_six.strict_neg(), neg_six);
2688        /// # Some(())
2689        /// # }
2690        /// ```
2691        ///
2692        /// The following panics because of overflow:
2693        ///
2694        /// ```should_panic
2695        /// #![feature(nonzero_strict_ops)]
2696        ///
2697        /// # use std::num::NonZero;
2698        /// #
2699        /// # fn main() { test().unwrap(); }
2700        /// # fn test() -> Option<()> {
2701        #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")]
2702        ///
2703        /// let _ = min.strict_neg();
2704        /// # Some(())
2705        /// # }
2706        /// ```
2707        #[unstable(feature = "nonzero_strict_ops", issue = "164850")]
2708        #[rustc_const_unstable(feature = "const_nonzero_strict_ops", issue = "164850")]
2709        #[must_use = "this returns the result of the operation, \
2710                      without modifying the original"]
2711        #[inline]
2712        #[track_caller]
2713        pub const fn strict_neg(self) -> Self {
2714            // SAFETY:
2715            // - `$Int::strict_neg` panics on overflow;
2716            // - `self` is nonzero;
2717            // - the only way to get zero from a negation without overflow
2718            //   is for the input to be zero.
2719            //
2720            // So the result cannot be zero.
2721            unsafe { Self::new_unchecked(self.get().strict_neg()) }
2722        }
2723
2724        /// Negates self, overflowing if this is equal to the minimum value.
2725        ///
2726        #[doc = concat!("See [`", stringify!($Int), "::overflowing_neg`]")]
2727        /// for documentation on overflow behavior.
2728        ///
2729        /// # Example
2730        ///
2731        /// ```
2732        /// # use std::num::NonZero;
2733        /// #
2734        /// # fn main() { test().unwrap(); }
2735        /// # fn test() -> Option<()> {
2736        #[doc = concat!("let pos_five = NonZero::new(5", stringify!($Int), ")?;")]
2737        #[doc = concat!("let neg_five = NonZero::new(-5", stringify!($Int), ")?;")]
2738        #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")]
2739        ///
2740        /// assert_eq!(pos_five.overflowing_neg(), (neg_five, false));
2741        /// assert_eq!(min.overflowing_neg(), (min, true));
2742        /// # Some(())
2743        /// # }
2744        /// ```
2745        #[inline]
2746        #[stable(feature = "nonzero_negation_ops", since = "1.71.0")]
2747        #[rustc_const_stable(feature = "nonzero_negation_ops", since = "1.71.0")]
2748        pub const fn overflowing_neg(self) -> (Self, bool) {
2749            let (result, overflow) = self.get().overflowing_neg();
2750            // SAFETY: negation of nonzero cannot yield zero values.
2751            ((unsafe { Self::new_unchecked(result) }), overflow)
2752        }
2753
2754        /// Saturating negation. Computes `-self`,
2755        #[doc = concat!("returning [`NonZero::<", stringify!($Int), ">::MAX`]")]
2756        #[doc = concat!("if `self == NonZero::<", stringify!($Int), ">::MIN`")]
2757        /// instead of overflowing.
2758        ///
2759        /// # Example
2760        ///
2761        /// ```
2762        /// # use std::num::NonZero;
2763        /// #
2764        /// # fn main() { test().unwrap(); }
2765        /// # fn test() -> Option<()> {
2766        #[doc = concat!("let pos_five = NonZero::new(5", stringify!($Int), ")?;")]
2767        #[doc = concat!("let neg_five = NonZero::new(-5", stringify!($Int), ")?;")]
2768        #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")]
2769        #[doc = concat!("let min_plus_one = NonZero::new(", stringify!($Int), "::MIN + 1)?;")]
2770        #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")]
2771        ///
2772        /// assert_eq!(pos_five.saturating_neg(), neg_five);
2773        /// assert_eq!(min.saturating_neg(), max);
2774        /// assert_eq!(max.saturating_neg(), min_plus_one);
2775        /// # Some(())
2776        /// # }
2777        /// ```
2778        #[inline]
2779        #[stable(feature = "nonzero_negation_ops", since = "1.71.0")]
2780        #[rustc_const_stable(feature = "nonzero_negation_ops", since = "1.71.0")]
2781        pub const fn saturating_neg(self) -> Self {
2782            if let Some(result) = self.checked_neg() {
2783                return result;
2784            }
2785            Self::MAX
2786        }
2787
2788        /// Wrapping (modular) negation. Computes `-self`, wrapping around at the boundary
2789        /// of the type.
2790        ///
2791        #[doc = concat!("See [`", stringify!($Int), "::wrapping_neg`]")]
2792        /// for documentation on overflow behavior.
2793        ///
2794        /// # Example
2795        ///
2796        /// ```
2797        /// # use std::num::NonZero;
2798        /// #
2799        /// # fn main() { test().unwrap(); }
2800        /// # fn test() -> Option<()> {
2801        #[doc = concat!("let pos_five = NonZero::new(5", stringify!($Int), ")?;")]
2802        #[doc = concat!("let neg_five = NonZero::new(-5", stringify!($Int), ")?;")]
2803        #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")]
2804        ///
2805        /// assert_eq!(pos_five.wrapping_neg(), neg_five);
2806        /// assert_eq!(min.wrapping_neg(), min);
2807        /// # Some(())
2808        /// # }
2809        /// ```
2810        #[inline]
2811        #[stable(feature = "nonzero_negation_ops", since = "1.71.0")]
2812        #[rustc_const_stable(feature = "nonzero_negation_ops", since = "1.71.0")]
2813        pub const fn wrapping_neg(self) -> Self {
2814            let result = self.get().wrapping_neg();
2815            // SAFETY: negation of nonzero cannot yield zero values.
2816            unsafe { Self::new_unchecked(result) }
2817        }
2818
2819        /// Returns the bit pattern of `self` reinterpreted as an unsigned integer of the same size.
2820        ///
2821        /// # Examples
2822        ///
2823        /// ```
2824        /// # use std::num::NonZero;
2825        ///
2826        #[doc = concat!("let n = NonZero::new(-1", stringify!($Int), ").unwrap();")]
2827        ///
2828        #[doc = concat!("assert_eq!(n.cast_unsigned(), NonZero::<", stringify!($Uint), ">::MAX);")]
2829        /// ```
2830        #[stable(feature = "integer_sign_cast", since = "1.87.0")]
2831        #[rustc_const_stable(feature = "integer_sign_cast", since = "1.87.0")]
2832        #[must_use = "this returns the result of the operation, \
2833                      without modifying the original"]
2834        #[inline(always)]
2835        pub const fn cast_unsigned(self) -> NonZero<$Uint> {
2836            // SAFETY: `self.get()` can't be zero
2837            unsafe { NonZero::new_unchecked(self.get().cast_unsigned()) }
2838        }
2839
2840        /// Clamps this number to a symmetric range centred around zero.
2841        ///
2842        /// The method clamps the number's magnitude (absolute value) to be at most `limit`.
2843        ///
2844        /// This is functionally equivalent to `self.clamp(-limit, limit)`, but is more
2845        /// explicit about the intent.
2846        ///
2847        /// # Examples
2848        ///
2849        /// ```
2850        /// #![feature(clamp_magnitude)]
2851        /// # use std::num::NonZero;
2852        /// #
2853        #[doc = concat!("let limit = NonZero::<", stringify!($Uint), ">::new(100).unwrap();")]
2854        ///
2855        /// assert_eq!(
2856        #[doc = concat!("    NonZero::<", stringify!($Int), ">::new(120).unwrap().clamp_magnitude(limit),")]
2857        #[doc = concat!("    NonZero::<", stringify!($Int), ">::new(100).unwrap(),")]
2858        /// );
2859        ///
2860        /// assert_eq!(
2861        #[doc = concat!("    NonZero::<", stringify!($Int), ">::new(-120).unwrap().clamp_magnitude(limit),")]
2862        #[doc = concat!("    NonZero::<", stringify!($Int), ">::new(-100).unwrap(),")]
2863        /// );
2864        ///
2865        /// assert_eq!(
2866        #[doc = concat!("    NonZero::<", stringify!($Int), ">::new(80).unwrap().clamp_magnitude(limit),")]
2867        #[doc = concat!("    NonZero::<", stringify!($Int), ">::new(80).unwrap(),")]
2868        /// );
2869        ///
2870        /// assert_eq!(
2871        #[doc = concat!("    NonZero::<", stringify!($Int), ">::new(-80).unwrap().clamp_magnitude(limit),")]
2872        #[doc = concat!("    NonZero::<", stringify!($Int), ">::new(-80).unwrap(),")]
2873        /// );
2874        /// ```
2875        #[inline]
2876        #[must_use = "method returns a new number and does not mutate the original value"]
2877        #[rustc_const_unstable(feature = "const_cmp", issue = "143800")]
2878        #[unstable(feature = "clamp_magnitude", issue = "148519")]
2879        pub const fn clamp_magnitude(self, limit: NonZero<$Uint>) -> Self {
2880            // SAFETY: a non-zero value clamped to the magnitude of a non-zero value is still non-zero.
2881            unsafe { Self::new_unchecked(self.get().clamp_magnitude(limit.get())) }
2882        }
2883
2884    };
2885}
2886
2887nonzero_integer! {
2888    Self = NonZeroU8,
2889    Primitive = unsigned u8,
2890    SignedPrimitive = i8,
2891    rot = 2,
2892    rot_op = "0x82",
2893    rot_result = "0xa",
2894    swap_op = "0x12",
2895    swapped = "0x12",
2896    reversed = "0x48",
2897}
2898
2899nonzero_integer! {
2900    Self = NonZeroU16,
2901    Primitive = unsigned u16,
2902    SignedPrimitive = i16,
2903    rot = 4,
2904    rot_op = "0xa003",
2905    rot_result = "0x3a",
2906    swap_op = "0x1234",
2907    swapped = "0x3412",
2908    reversed = "0x2c48",
2909}
2910
2911nonzero_integer! {
2912    Self = NonZeroU32,
2913    Primitive = unsigned u32,
2914    SignedPrimitive = i32,
2915    rot = 8,
2916    rot_op = "0x10000b3",
2917    rot_result = "0xb301",
2918    swap_op = "0x12345678",
2919    swapped = "0x78563412",
2920    reversed = "0x1e6a2c48",
2921}
2922
2923nonzero_integer! {
2924    Self = NonZeroU64,
2925    Primitive = unsigned u64,
2926    SignedPrimitive = i64,
2927    rot = 12,
2928    rot_op = "0xaa00000000006e1",
2929    rot_result = "0x6e10aa",
2930    swap_op = "0x1234567890123456",
2931    swapped = "0x5634129078563412",
2932    reversed = "0x6a2c48091e6a2c48",
2933}
2934
2935nonzero_integer! {
2936    Self = NonZeroU128,
2937    Primitive = unsigned u128,
2938    SignedPrimitive = i128,
2939    rot = 16,
2940    rot_op = "0x13f40000000000000000000000004f76",
2941    rot_result = "0x4f7613f4",
2942    swap_op = "0x12345678901234567890123456789012",
2943    swapped = "0x12907856341290785634129078563412",
2944    reversed = "0x48091e6a2c48091e6a2c48091e6a2c48",
2945}
2946
2947#[cfg(target_pointer_width = "16")]
2948nonzero_integer! {
2949    Self = NonZeroUsize,
2950    Primitive = unsigned usize,
2951    SignedPrimitive = isize,
2952    rot = 4,
2953    rot_op = "0xa003",
2954    rot_result = "0x3a",
2955    swap_op = "0x1234",
2956    swapped = "0x3412",
2957    reversed = "0x2c48",
2958}
2959
2960#[cfg(target_pointer_width = "32")]
2961nonzero_integer! {
2962    Self = NonZeroUsize,
2963    Primitive = unsigned usize,
2964    SignedPrimitive = isize,
2965    rot = 8,
2966    rot_op = "0x10000b3",
2967    rot_result = "0xb301",
2968    swap_op = "0x12345678",
2969    swapped = "0x78563412",
2970    reversed = "0x1e6a2c48",
2971}
2972
2973#[cfg(target_pointer_width = "64")]
2974nonzero_integer! {
2975    Self = NonZeroUsize,
2976    Primitive = unsigned usize,
2977    SignedPrimitive = isize,
2978    rot = 12,
2979    rot_op = "0xaa00000000006e1",
2980    rot_result = "0x6e10aa",
2981    swap_op = "0x1234567890123456",
2982    swapped = "0x5634129078563412",
2983    reversed = "0x6a2c48091e6a2c48",
2984}
2985
2986nonzero_integer! {
2987    Self = NonZeroI8,
2988    Primitive = signed i8,
2989    UnsignedPrimitive = u8,
2990    rot = 2,
2991    rot_op = "-0x7e",
2992    rot_result = "0xa",
2993    swap_op = "0x12",
2994    swapped = "0x12",
2995    reversed = "0x48",
2996}
2997
2998nonzero_integer! {
2999    Self = NonZeroI16,
3000    Primitive = signed i16,
3001    UnsignedPrimitive = u16,
3002    rot = 4,
3003    rot_op = "-0x5ffd",
3004    rot_result = "0x3a",
3005    swap_op = "0x1234",
3006    swapped = "0x3412",
3007    reversed = "0x2c48",
3008}
3009
3010nonzero_integer! {
3011    Self = NonZeroI32,
3012    Primitive = signed i32,
3013    UnsignedPrimitive = u32,
3014    rot = 8,
3015    rot_op = "0x10000b3",
3016    rot_result = "0xb301",
3017    swap_op = "0x12345678",
3018    swapped = "0x78563412",
3019    reversed = "0x1e6a2c48",
3020}
3021
3022nonzero_integer! {
3023    Self = NonZeroI64,
3024    Primitive = signed i64,
3025    UnsignedPrimitive = u64,
3026    rot = 12,
3027    rot_op = "0xaa00000000006e1",
3028    rot_result = "0x6e10aa",
3029    swap_op = "0x1234567890123456",
3030    swapped = "0x5634129078563412",
3031    reversed = "0x6a2c48091e6a2c48",
3032}
3033
3034nonzero_integer! {
3035    Self = NonZeroI128,
3036    Primitive = signed i128,
3037    UnsignedPrimitive = u128,
3038    rot = 16,
3039    rot_op = "0x13f40000000000000000000000004f76",
3040    rot_result = "0x4f7613f4",
3041    swap_op = "0x12345678901234567890123456789012",
3042    swapped = "0x12907856341290785634129078563412",
3043    reversed = "0x48091e6a2c48091e6a2c48091e6a2c48",
3044}
3045
3046#[cfg(target_pointer_width = "16")]
3047nonzero_integer! {
3048    Self = NonZeroIsize,
3049    Primitive = signed isize,
3050    UnsignedPrimitive = usize,
3051    rot = 4,
3052    rot_op = "-0x5ffd",
3053    rot_result = "0x3a",
3054    swap_op = "0x1234",
3055    swapped = "0x3412",
3056    reversed = "0x2c48",
3057}
3058
3059#[cfg(target_pointer_width = "32")]
3060nonzero_integer! {
3061    Self = NonZeroIsize,
3062    Primitive = signed isize,
3063    UnsignedPrimitive = usize,
3064    rot = 8,
3065    rot_op = "0x10000b3",
3066    rot_result = "0xb301",
3067    swap_op = "0x12345678",
3068    swapped = "0x78563412",
3069    reversed = "0x1e6a2c48",
3070}
3071
3072#[cfg(target_pointer_width = "64")]
3073nonzero_integer! {
3074    Self = NonZeroIsize,
3075    Primitive = signed isize,
3076    UnsignedPrimitive = usize,
3077    rot = 12,
3078    rot_op = "0xaa00000000006e1",
3079    rot_result = "0x6e10aa",
3080    swap_op = "0x1234567890123456",
3081    swapped = "0x5634129078563412",
3082    reversed = "0x6a2c48091e6a2c48",
3083}