//! 已知不等于零的整数的定义。

use crate::fmt;
use crate::ops::{BitOr, BitOrAssign, Div, Rem};
use crate::str::FromStr;

use super::from_str_radix;
use super::{IntErrorKind, ParseIntError};
use crate::intrinsics;

macro_rules! impl_nonzero_fmt {
    ( #[$stability: meta] ( $( $Trait: ident ),+ ) for $Ty: ident ) => {
        $(
            #[$stability]
            impl fmt::$Trait for $Ty {
                #[inline]
                fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                    self.get().fmt(f)
                }
            }
        )+
    }
}

macro_rules! nonzero_integers {
    ( $( #[$stability: meta] #[$const_new_unchecked_stability: meta] $Ty: ident($Int: ty); )+ ) => {
        $(
            /// 已知不等于零的整数。
            ///
            /// 这样可以进行一些内存布局优化。
            #[doc = concat!("For example, `Option<", stringify!($Ty), ">` is the same size as `", stringify!($Int), "`:")]
            ///
            /// ```rust
            /// use std::mem::size_of;
            #[doc = concat!("assert_eq!(size_of::<Option<core::num::", stringify!($Ty), ">>(), size_of::<", stringify!($Int), ">());")]
            /// ```
            #[$stability]
            #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
            #[repr(transparent)]
            #[rustc_layout_scalar_valid_range_start(1)]
            #[rustc_nonnull_optimization_guaranteed]
            pub struct $Ty($Int);

            impl $Ty {
                /// 创建一个非零值而不检查该值是否为非零值。
                /// 如果该值为零，这将导致未定义的行为。
                ///
                /// # Safety
                ///
                /// 该值不能为零。
                #[$stability]
                #[$const_new_unchecked_stability]
                #[inline]
                pub const unsafe fn new_unchecked(n: $Int) -> Self {
                    // SAFETY: 调用者保证这是安全的。
                    unsafe { Self(n) }
                }

                /// 如果给定值不为零，则创建一个非零值。
                #[$stability]
                #[rustc_const_stable(feature = "const_nonzero_int_methods", since = "1.47.0")]
                #[inline]
                pub const fn new(n: $Int) -> Option<Self> {
                    if n != 0 {
                        // SAFETY: 我们只是检查了没有 `0`
                        Some(unsafe { Self(n) })
                    } else {
                        None
                    }
                }

                /// 以原始类型返回该值。
                #[$stability]
                #[inline]
                #[rustc_const_stable(feature = "nonzero", since = "1.34.0")]
                pub const fn get(self) -> $Int {
                    self.0
                }

            }

            #[stable(feature = "from_nonzero", since = "1.31.0")]
            impl From<$Ty> for $Int {
                #[doc = concat!("Converts a `", stringify!($Ty), "` into an `", stringify!($Int), "`")]
                #[inline]
                fn from(nonzero: $Ty) -> Self {
                    nonzero.0
                }
            }

            #[stable(feature = "nonzero_bitor", since = "1.45.0")]
            impl BitOr for $Ty {
                type Output = Self;
                #[inline]
                fn bitor(self, rhs: Self) -> Self::Output {
                    // SAFETY: 由于 `self` 和 `rhs` 都不为零，所以按位或的结果将为非零。
                    //
                    unsafe { $Ty::new_unchecked(self.get() | rhs.get()) }
                }
            }

            #[stable(feature = "nonzero_bitor", since = "1.45.0")]
            impl BitOr<$Int> for $Ty {
                type Output = Self;
                #[inline]
                fn bitor(self, rhs: $Int) -> Self::Output {
                    // SAFETY: 由于 `self` 为非零值，因此无论 `rhs` 的值如何，按位或运算的结果都将为非零值。
                    //
                    //
                    unsafe { $Ty::new_unchecked(self.get() | rhs) }
                }
            }

            #[stable(feature = "nonzero_bitor", since = "1.45.0")]
            impl BitOr<$Ty> for $Int {
                type Output = $Ty;
                #[inline]
                fn bitor(self, rhs: $Ty) -> Self::Output {
                    // SAFETY: 由于 `rhs` 为非零值，因此无论 `self` 的值如何，按位或运算的结果都将为非零值。
                    //
                    //
                    unsafe { $Ty::new_unchecked(self | rhs.get()) }
                }
            }

            #[stable(feature = "nonzero_bitor", since = "1.45.0")]
            impl BitOrAssign for $Ty {
                #[inline]
                fn bitor_assign(&mut self, rhs: Self) {
                    *self = *self | rhs;
                }
            }

            #[stable(feature = "nonzero_bitor", since = "1.45.0")]
            impl BitOrAssign<$Int> for $Ty {
                #[inline]
                fn bitor_assign(&mut self, rhs: $Int) {
                    *self = *self | rhs;
                }
            }

            impl_nonzero_fmt! {
                #[$stability] (Debug, Display, Binary, Octal, LowerHex, UpperHex) for $Ty
            }
        )+
    }
}

nonzero_integers! {
    #[stable(feature = "nonzero", since = "1.28.0")] #[rustc_const_stable(feature = "nonzero", since = "1.28.0")] NonZeroU8(u8);
    #[stable(feature = "nonzero", since = "1.28.0")] #[rustc_const_stable(feature = "nonzero", since = "1.28.0")] NonZeroU16(u16);
    #[stable(feature = "nonzero", since = "1.28.0")] #[rustc_const_stable(feature = "nonzero", since = "1.28.0")] NonZeroU32(u32);
    #[stable(feature = "nonzero", since = "1.28.0")] #[rustc_const_stable(feature = "nonzero", since = "1.28.0")] NonZeroU64(u64);
    #[stable(feature = "nonzero", since = "1.28.0")] #[rustc_const_stable(feature = "nonzero", since = "1.28.0")] NonZeroU128(u128);
    #[stable(feature = "nonzero", since = "1.28.0")] #[rustc_const_stable(feature = "nonzero", since = "1.28.0")] NonZeroUsize(usize);
    #[stable(feature = "signed_nonzero", since = "1.34.0")] #[rustc_const_stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI8(i8);
    #[stable(feature = "signed_nonzero", since = "1.34.0")] #[rustc_const_stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI16(i16);
    #[stable(feature = "signed_nonzero", since = "1.34.0")] #[rustc_const_stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI32(i32);
    #[stable(feature = "signed_nonzero", since = "1.34.0")] #[rustc_const_stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI64(i64);
    #[stable(feature = "signed_nonzero", since = "1.34.0")] #[rustc_const_stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI128(i128);
    #[stable(feature = "signed_nonzero", since = "1.34.0")] #[rustc_const_stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroIsize(isize);
}

macro_rules! from_str_radix_nzint_impl {
    ($($t:ty)*) => {$(
        #[stable(feature = "nonzero_parse", since = "1.35.0")]
        impl FromStr for $t {
            type Err = ParseIntError;
            fn from_str(src: &str) -> Result<Self, Self::Err> {
                Self::new(from_str_radix(src, 10)?)
                    .ok_or(ParseIntError {
                        kind: IntErrorKind::Zero
                    })
            }
        }
    )*}
}

from_str_radix_nzint_impl! { NonZeroU8 NonZeroU16 NonZeroU32 NonZeroU64 NonZeroU128 NonZeroUsize
NonZeroI8 NonZeroI16 NonZeroI32 NonZeroI64 NonZeroI128 NonZeroIsize }

macro_rules! nonzero_leading_trailing_zeros {
    ( $( $Ty: ident($Uint: ty) , $LeadingTestExpr:expr ;)+ ) => {
        $(
            impl $Ty {
                /// 返回 `self` 二进制表示形式中前导零的数目。
                ///
                /// 在许多体系结构上，此函数可以在基础整数类型上比 `leading_zeros()` 更好地执行，因为可以避免对零的特殊处理。
                ///
                /// # Examples
                ///
                /// 基本用法:
                ///
                /// ```
                #[doc = concat!("let n = std::num::", stringify!($Ty), "::new(", stringify!($LeadingTestExpr), ").unwrap();")]
                ///
                /// assert_eq!(n.leading_zeros(), 0);
                /// ```
                #[stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")]
                #[rustc_const_stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")]
                #[inline]
                pub const fn leading_zeros(self) -> u32 {
                    // SAFETY: 由于 `self` 不能为零，因此可以安全地调用 ctlz_nonzero
                    unsafe { intrinsics::ctlz_nonzero(self.0 as $Uint) as u32 }
                }

                /// 返回 `self` 二进制表示形式中的尾随零数。
                ///
                /// 在许多体系结构上，此函数可以在基础整数类型上比 `trailing_zeros()` 更好地执行，因为可以避免对零的特殊处理。
                ///
                ///
                /// # Examples
                ///
                /// 基本用法:
                ///
                /// ```
                #[doc = concat!("let n = std::num::", stringify!($Ty), "::new(0b0101000).unwrap();")]
                ///
                /// assert_eq!(n.trailing_zeros(), 3);
                /// ```
                #[stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")]
                #[rustc_const_stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")]
                #[inline]
                pub const fn trailing_zeros(self) -> u32 {
                    // SAFETY: 由于 `self` 不能为零，因此可以安全地调用 cttz_nonzero
                    unsafe { intrinsics::cttz_nonzero(self.0 as $Uint) as u32 }
                }

            }
        )+
    }
}

nonzero_leading_trailing_zeros! {
    NonZeroU8(u8), u8::MAX;
    NonZeroU16(u16), u16::MAX;
    NonZeroU32(u32), u32::MAX;
    NonZeroU64(u64), u64::MAX;
    NonZeroU128(u128), u128::MAX;
    NonZeroUsize(usize), usize::MAX;
    NonZeroI8(u8), -1i8;
    NonZeroI16(u16), -1i16;
    NonZeroI32(u32), -1i32;
    NonZeroI64(u64), -1i64;
    NonZeroI128(u128), -1i128;
    NonZeroIsize(usize), -1isize;
}

macro_rules! nonzero_integers_div {
    ( $( $Ty: ident($Int: ty); )+ ) => {
        $(
            #[stable(feature = "nonzero_div", since = "1.51.0")]
            impl Div<$Ty> for $Int {
                type Output = $Int;
                /// 此运算将舍入为零，舍去精确结果的任何小数部分，并且不能为 panic。
                ///
                #[inline]
                fn div(self, other: $Ty) -> $Int {
                    // SAFETY: 因为 `other` 是一个非零值，所以检查 div by 零，因为 `self` 是一个无符号整数，所以检查了 MIN/-1。
                    //
                    unsafe { crate::intrinsics::unchecked_div(self, other.get()) }
                }
            }

            #[stable(feature = "nonzero_div", since = "1.51.0")]
            impl Rem<$Ty> for $Int {
                type Output = $Int;
                /// 此操作满足 `n % d == n - (n / d) * d`，但不能为 panic。
                #[inline]
                fn rem(self, other: $Ty) -> $Int {
                    // SAFETY: 因为 `other` 是一个非零值，所以检查了 rem by zero，因为 `self` 是一个无符号 int，所以检查了 MIN/-1。
                    //
                    unsafe { crate::intrinsics::unchecked_rem(self, other.get()) }
                }
            }
        )+
    }
}

nonzero_integers_div! {
    NonZeroU8(u8);
    NonZeroU16(u16);
    NonZeroU32(u32);
    NonZeroU64(u64);
    NonZeroU128(u128);
    NonZeroUsize(usize);
}

// 一堆仅适用于无符号非零类型的方法。
macro_rules! nonzero_unsigned_operations {
    ( $( $Ty: ident($Int: ty); )+ ) => {
        $(
            impl $Ty {
                /// 将无符号整数添加到非零值。
                /// 检查溢出并在溢出时返回 [`None`] 因此，结果不能归零。
                ///
                ///
                /// # Examples
                ///
                /// ```
                /// #![feature(nonzero_ops)]
                #[doc = concat!("# use std::num::", stringify!($Ty), ";")]
                ///
                /// # fn main() { test().unwrap(); }
                ///
                /// # fn test() -> Option<()> {
                #[doc = concat!("let one = ", stringify!($Ty), "::new(1)?;")]
                #[doc = concat!("let two = ", stringify!($Ty), "::new(2)?;")]
                #[doc = concat!("let max = ", stringify!($Ty), "::new(",
                                stringify!($Int), "::MAX)?;")]
                ///
                /// assert_eq!(Some(two), one.checked_add(1));
                /// assert_eq!(None, max.checked_add(1));
                /// # Some(())
                /// # }
                /// ```
                #[unstable(feature = "nonzero_ops", issue = "84186")]
                #[inline]
                pub const fn checked_add(self, other: $Int) -> Option<$Ty> {
                    if let Some(result) = self.get().checked_add(other) {
                        // SAFETY: $Int::checked_add 在溢出时返回 None，因此结果不能为零。
                        //
                        Some(unsafe { $Ty::new_unchecked(result) })
                    } else {
                        None
                    }
                }

                /// 将无符号整数添加到非零值。
                #[doc = concat!("Return [`", stringify!($Int), "::MAX`] on overflow.")]
                ///
                /// # Examples
                ///
                /// ```
                /// #![feature(nonzero_ops)]
                #[doc = concat!("# use std::num::", stringify!($Ty), ";")]
                ///
                /// # fn main() { test().unwrap(); }
                /// # fn test() -> Option<()> {
                #[doc = concat!("let one = ", stringify!($Ty), "::new(1)?;")]
                #[doc = concat!("let two = ", stringify!($Ty), "::new(2)?;")]
                #[doc = concat!("let max = ", stringify!($Ty), "::new(",
                                stringify!($Int), "::MAX)?;")]
                ///
                /// assert_eq!(two, one.saturating_add(1));
                /// assert_eq!(max, max.saturating_add(1));
                /// # Some(())
                /// # }
                /// ```
                #[unstable(feature = "nonzero_ops", issue = "84186")]
                #[inline]
                pub const fn saturating_add(self, other: $Int) -> $Ty {
                    // SAFETY: $Int::saturating_add 在溢出时返回 $Int::MAX，因此结果不能为零。
                    //
                    unsafe { $Ty::new_unchecked(self.get().saturating_add(other)) }
                }

                /// 假设不会发生溢出，将无符号整数添加到非零值。
                /// 溢出未检查，如果结果将换行为非零值，则溢出 *even 是未定义的行为 *。
                ///
                /// 该行为是未定义的
                ///
                #[doc = concat!("`self + rhs > ", stringify!($Int), "::MAX`.")]
                ///
                /// # Examples
                ///
                /// ```
                /// #![feature(nonzero_ops)]
                #[doc = concat!("# use std::num::", stringify!($Ty), ";")]
                ///
                /// # fn main() { test().unwrap(); }
                /// # fn test() -> Option<()> {
                #[doc = concat!("let one = ", stringify!($Ty), "::new(1)?;")]
                #[doc = concat!("let two = ", stringify!($Ty), "::new(2)?;")]
                ///
                /// assert_eq!(two, unsafe { one.unchecked_add(1) });
                /// # Some(())
                /// # }
                /// ```
                #[unstable(feature = "nonzero_ops", issue = "84186")]
                #[inline]
                pub unsafe fn unchecked_add(self, other: $Int) -> $Ty {
                    // SAFETY: 调用者确保没有溢出。
                    unsafe { $Ty::new_unchecked(self.get().unchecked_add(other)) }
                }

                /// 返回大于或等于 n 的 2 的最小幂。
                /// 如果下一个 2 的幂大于类型的最大值，则检查是否溢出并返回 [`None`]。
                /// 因此，结果不能归零。
                ///
                /// # Examples
                ///
                /// ```
                /// #![feature(nonzero_ops)]
                #[doc = concat!("# use std::num::", stringify!($Ty), ";")]
                ///
                /// # fn main() { test().unwrap(); }
                ///
                /// # fn test() -> Option<()> {
                #[doc = concat!("let two = ", stringify!($Ty), "::new(2)?;")]
                #[doc = concat!("let three = ", stringify!($Ty), "::new(3)?;")]
                #[doc = concat!("let four = ", stringify!($Ty), "::new(4)?;")]
                #[doc = concat!("let max = ", stringify!($Ty), "::new(",
                                stringify!($Int), "::MAX)?;")]
                ///
                /// assert_eq!(Some(two), two.checked_next_power_of_two() );
                /// assert_eq!(Some(four), three.checked_next_power_of_two() );
                /// assert_eq!(None, max.checked_next_power_of_two() );
                /// # Some(())
                /// # }
                /// ```
                #[unstable(feature = "nonzero_ops", issue = "84186")]
                #[inline]
                pub const fn checked_next_power_of_two(self) -> Option<$Ty> {
                    if let Some(nz) = self.get().checked_next_power_of_two() {
                        // SAFETY: 下一个 2 的幂为正，并检查溢出。
                        //
                        Some(unsafe { $Ty::new_unchecked(nz) })
                    } else {
                        None
                    }
                }
            }
        )+
    }
}

nonzero_unsigned_operations! {
    NonZeroU8(u8);
    NonZeroU16(u16);
    NonZeroU32(u32);
    NonZeroU64(u64);
    NonZeroU128(u128);
    NonZeroUsize(usize);
}

// 一堆仅用于有符号非零类型的方法。
macro_rules! nonzero_signed_operations {
    ( $( $Ty: ident($Int: ty) -> $Uty: ident($Uint: ty); )+ ) => {
        $(
            impl $Ty {
                /// 计算 self 的绝对值。
                #[doc = concat!("See [`", stringify!($Int), "::abs`]")]
                /// 有关溢出行为的文档。
                ///
                /// # Example
                ///
                /// ```
                /// #![feature(nonzero_ops)]
                #[doc = concat!("# use std::num::", stringify!($Ty), ";")]
                ///
                /// # fn main() { test().unwrap(); }
                /// # fn test() -> Option<()> {
                #[doc = concat!("let pos = ", stringify!($Ty), "::new(1)?;")]
                #[doc = concat!("let neg = ", stringify!($Ty), "::new(-1)?;")]
                ///
                /// assert_eq!(pos, pos.abs());
                /// assert_eq!(pos, neg.abs());
                /// # Some(())
                /// # }
                /// ```
                #[unstable(feature = "nonzero_ops", issue = "84186")]
                #[inline]
                pub const fn abs(self) -> $Ty {
                    // SAFETY: 这不能溢出到零。
                    unsafe { $Ty::new_unchecked(self.get().abs()) }
                }

                /// 检查的绝对值。
                /// 检查溢出并返回 [`None`] 如果
                #[doc = concat!("`self == ", stringify!($Int), "::MIN`.")]
                /// 结果不能为零。
                ///
                /// # Example
                ///
                /// ```
                /// #![feature(nonzero_ops)]
                #[doc = concat!("# use std::num::", stringify!($Ty), ";")]
                ///
                /// # fn main() { test().unwrap(); }
                /// # fn test() -> Option<()> {
                #[doc = concat!("let pos = ", stringify!($Ty), "::new(1)?;")]
                #[doc = concat!("let neg = ", stringify!($Ty), "::new(-1)?;")]
                #[doc = concat!("let min = ", stringify!($Ty), "::new(",
                                stringify!($Int), "::MIN)?;")]
                ///
                /// assert_eq!(Some(pos), neg.checked_abs());
                /// assert_eq!(None, min.checked_abs());
                /// # Some(())
                /// # }
                /// ```
                #[unstable(feature = "nonzero_ops", issue = "84186")]
                #[inline]
                pub const fn checked_abs(self) -> Option<$Ty> {
                    if let Some(nz) = self.get().checked_abs() {
                        // SAFETY: 非零的绝对值不能产生零值。
                        Some(unsafe { $Ty::new_unchecked(nz) })
                    } else {
                        None
                    }
                }

                /// 计算 self 的绝对值，带有溢出信息，请参见
                ///
                #[doc = concat!("[`", stringify!($Int), "::overflowing_abs`].")]
                ///
                /// # Example
                ///
                /// ```
                /// #![feature(nonzero_ops)]
                #[doc = concat!("# use std::num::", stringify!($Ty), ";")]
                ///
                /// # fn main() { test().unwrap(); }
                /// # fn test() -> Option<()> {
                #[doc = concat!("let pos = ", stringify!($Ty), "::new(1)?;")]
                #[doc = concat!("let neg = ", stringify!($Ty), "::new(-1)?;")]
                #[doc = concat!("let min = ", stringify!($Ty), "::new(",
                                stringify!($Int), "::MIN)?;")]
                ///
                /// assert_eq!((pos, false), pos.overflowing_abs());
                /// assert_eq!((pos, false), neg.overflowing_abs());
                /// assert_eq!((min, true), min.overflowing_abs());
                /// # Some(())
                /// # }
                /// ```
                #[unstable(feature = "nonzero_ops", issue = "84186")]
                #[inline]
                pub const fn overflowing_abs(self) -> ($Ty, bool) {
                    let (nz, flag) = self.get().overflowing_abs();
                    (
                        // SAFETY: 非零的绝对值不能产生零值。
                        unsafe { $Ty::new_unchecked(nz) },
                        flag,
                    )
                }

                /// 饱和绝对值，请参见
                #[doc = concat!("[`", stringify!($Int), "::saturating_abs`].")]
                ///
                /// # Example
                ///
                /// ```
                /// #![feature(nonzero_ops)]
                #[doc = concat!("# use std::num::", stringify!($Ty), ";")]
                ///
                /// # fn main() { test().unwrap(); }
                /// # fn test() -> Option<()> {
                #[doc = concat!("let pos = ", stringify!($Ty), "::new(1)?;")]
                #[doc = concat!("let neg = ", stringify!($Ty), "::new(-1)?;")]
                #[doc = concat!("let min = ", stringify!($Ty), "::new(",
                                stringify!($Int), "::MIN)?;")]
                #[doc = concat!("let min_plus = ", stringify!($Ty), "::new(",
                                stringify!($Int), "::MIN + 1)?;")]
                #[doc = concat!("let max = ", stringify!($Ty), "::new(",
                                stringify!($Int), "::MAX)?;")]
                ///
                /// assert_eq!(pos, pos.saturating_abs());
                /// assert_eq!(pos, neg.saturating_abs());
                /// assert_eq!(max, min.saturating_abs());
                /// assert_eq!(max, min_plus.saturating_abs());
                /// # Some(())
                /// # }
                /// ```
                #[unstable(feature = "nonzero_ops", issue = "84186")]
                #[inline]
                pub const fn saturating_abs(self) -> $Ty {
                    // SAFETY: 非零的绝对值不能产生零值。
                    unsafe { $Ty::new_unchecked(self.get().saturating_abs()) }
                }

                /// 包装绝对值，请参见
                #[doc = concat!("[`", stringify!($Int), "::wrapping_abs`].")]
                ///
                /// # Example
                ///
                /// ```
                /// #![feature(nonzero_ops)]
                #[doc = concat!("# use std::num::", stringify!($Ty), ";")]
                ///
                /// # fn main() { test().unwrap(); }
                /// # fn test() -> Option<()> {
                #[doc = concat!("let pos = ", stringify!($Ty), "::new(1)?;")]
                #[doc = concat!("let neg = ", stringify!($Ty), "::new(-1)?;")]
                #[doc = concat!("let min = ", stringify!($Ty), "::new(",
                                stringify!($Int), "::MIN)?;")]
                #[doc = concat!("let max = ", stringify!($Ty), "::new(",
                                stringify!($Int), "::MAX)?;")]
                ///
                /// assert_eq!(pos, pos.wrapping_abs());
                /// assert_eq!(pos, neg.wrapping_abs());
                /// assert_eq!(min, min.wrapping_abs());
                /// # // FIXME: 添加一次 Neg 实现?
                /// # // assert_eq!(max, (-max).wrapping_abs());
                /// # Some(())
                /// # }
                /// ```
                #[unstable(feature = "nonzero_ops", issue = "84186")]
                #[inline]
                pub const fn wrapping_abs(self) -> $Ty {
                    // SAFETY: 非零的绝对值不能产生零值。
                    unsafe { $Ty::new_unchecked(self.get().wrapping_abs()) }
                }

                /// 在没有任何包装或 panicking 的情况下计算 self 的绝对值。
                ///
                /// # Example
                ///
                /// ```
                /// #![feature(nonzero_ops)]
                #[doc = concat!("# use std::num::", stringify!($Ty), ";")]
                #[doc = concat!("# use std::num::", stringify!($Uty), ";")]
                ///
                /// # fn main() { test().unwrap(); }
                ///
                /// # fn test() -> Option<()> {
                #[doc = concat!("let u_pos = ", stringify!($Uty), "::new(1)?;")]
                #[doc = concat!("let i_pos = ", stringify!($Ty), "::new(1)?;")]
                #[doc = concat!("let i_neg = ", stringify!($Ty), "::new(-1)?;")]
                #[doc = concat!("let i_min = ", stringify!($Ty), "::new(",
                                stringify!($Int), "::MIN)?;")]
                #[doc = concat!("let u_max = ", stringify!($Uty), "::new(",
                                stringify!($Uint), "::MAX / 2 + 1)?;")]
                ///
                /// assert_eq!(u_pos, i_pos.unsigned_abs());
                /// assert_eq!(u_pos, i_neg.unsigned_abs());
                /// assert_eq!(u_max, i_min.unsigned_abs());
                /// # Some(())
                /// # }
                /// ```
                #[unstable(feature = "nonzero_ops", issue = "84186")]
                #[inline]
                pub const fn unsigned_abs(self) -> $Uty {
                    // SAFETY: 非零的绝对值不能产生零值。
                    unsafe { $Uty::new_unchecked(self.get().unsigned_abs()) }
                }
            }
        )+
    }
}

nonzero_signed_operations! {
    NonZeroI8(i8) -> NonZeroU8(u8);
    NonZeroI16(i16) -> NonZeroU16(u16);
    NonZeroI32(i32) -> NonZeroU32(u32);
    NonZeroI64(i64) -> NonZeroU64(u64);
    NonZeroI128(i128) -> NonZeroU128(u128);
    NonZeroIsize(isize) -> NonZeroUsize(usize);
}

// 有符号和无符号非零类型的一堆方法。
macro_rules! nonzero_unsigned_signed_operations {
    ( $( $signedness:ident $Ty: ident($Int: ty); )+ ) => {
        $(
            impl $Ty {
                /// 将两个非零整数相乘。
                /// 检查溢出并在溢出时返回 [`None`]。
                /// 因此，结果不能归零。
                ///
                /// # Examples
                ///
                /// ```
                /// #![feature(nonzero_ops)]
                #[doc = concat!("# use std::num::", stringify!($Ty), ";")]
                ///
                /// # fn main() { test().unwrap(); }
                /// # fn test() -> Option<()> {
                #[doc = concat!("let two = ", stringify!($Ty), "::new(2)?;")]
                #[doc = concat!("let four = ", stringify!($Ty), "::new(4)?;")]
                #[doc = concat!("let max = ", stringify!($Ty), "::new(",
                                stringify!($Int), "::MAX)?;")]
                ///
                /// assert_eq!(Some(four), two.checked_mul(two));
                /// assert_eq!(None, max.checked_mul(two));
                /// # Some(())
                /// # }
                /// ```
                #[unstable(feature = "nonzero_ops", issue = "84186")]
                #[inline]
                pub const fn checked_mul(self, other: $Ty) -> Option<$Ty> {
                    if let Some(result) = self.get().checked_mul(other.get()) {
                        // SAFETY: Checked_mul 在溢出时返回 None 并且 `other` 也是非空的，因此结果不能为零。
                        //
                        //
                        Some(unsafe { $Ty::new_unchecked(result) })
                    } else {
                        None
                    }
                }

                /// 将两个非零整数相乘。
                #[doc = concat!("Return [`", stringify!($Int), "::MAX`] on overflow.")]
                ///
                /// # Examples
                ///
                /// ```
                /// #![feature(nonzero_ops)]
                #[doc = concat!("# use std::num::", stringify!($Ty), ";")]
                ///
                /// # fn main() { test().unwrap(); }
                /// # fn test() -> Option<()> {
                #[doc = concat!("let two = ", stringify!($Ty), "::new(2)?;")]
                #[doc = concat!("let four = ", stringify!($Ty), "::new(4)?;")]
                #[doc = concat!("let max = ", stringify!($Ty), "::new(",
                                stringify!($Int), "::MAX)?;")]
                ///
                /// assert_eq!(four, two.saturating_mul(two));
                /// assert_eq!(max, four.saturating_mul(max));
                /// # Some(())
                /// # }
                /// ```
                #[unstable(feature = "nonzero_ops", issue = "84186")]
                #[inline]
                pub const fn saturating_mul(self, other: $Ty) -> $Ty {
                    // SAFETY: saturating_mul 在溢出时返回 u*::MAX 并且 `other` 也是非空的，因此结果不能为零。
                    //
                    //
                    unsafe { $Ty::new_unchecked(self.get().saturating_mul(other.get())) }
                }

                /// 假设不会发生溢出，将两个非零整数相乘。
                /// 溢出未检查，如果结果将换行为非零值，则溢出 *even 是未定义的行为 *。
                ///
                /// 该行为是未定义的
                ///
                #[doc = sign_dependent_expr!{
                    $signedness ?
                    if signed {
                        concat!("`self * rhs > ", stringify!($Int), "::MAX`, ",
                                "or `self * rhs < ", stringify!($Int), "::MIN`.")
                    }
                    if unsigned {
                        concat!("`self * rhs > ", stringify!($Int), "::MAX`.")
                    }
                }]
                ///
                /// # Examples
                ///
                /// ```
                /// #![feature(nonzero_ops)]
                #[doc = concat!("# use std::num::", stringify!($Ty), ";")]
                ///
                /// # fn main() { test().unwrap(); }
                /// # fn test() -> Option<()> {
                #[doc = concat!("let two = ", stringify!($Ty), "::new(2)?;")]
                #[doc = concat!("let four = ", stringify!($Ty), "::new(4)?;")]
                ///
                /// assert_eq!(four, unsafe { two.unchecked_mul(two) });
                /// # Some(())
                /// # }
                /// ```
                #[unstable(feature = "nonzero_ops", issue = "84186")]
                #[inline]
                pub unsafe fn unchecked_mul(self, other: $Ty) -> $Ty {
                    // SAFETY: 调用者确保没有溢出。
                    unsafe { $Ty::new_unchecked(self.get().unchecked_mul(other.get())) }
                }

                /// 将非零值提高到整数幂。
                /// 检查溢出并在溢出时返回 [`None`]。
                /// 因此，结果不能归零。
                ///
                /// # Examples
                ///
                /// ```
                /// #![feature(nonzero_ops)]
                #[doc = concat!("# use std::num::", stringify!($Ty), ";")]
                ///
                /// # fn main() { test().unwrap(); }
                /// # fn test() -> Option<()> {
                #[doc = concat!("let three = ", stringify!($Ty), "::new(3)?;")]
                #[doc = concat!("let twenty_seven = ", stringify!($Ty), "::new(27)?;")]
                #[doc = concat!("let half_max = ", stringify!($Ty), "::new(",
                                stringify!($Int), "::MAX / 2)?;")]
                ///
                /// assert_eq!(Some(twenty_seven), three.checked_pow(3));
                /// assert_eq!(None, half_max.checked_pow(3));
                /// # Some(())
                /// # }
                /// ```
                #[unstable(feature = "nonzero_ops", issue = "84186")]
                #[inline]
                pub const fn checked_pow(self, other: u32) -> Option<$Ty> {
                    if let Some(result) = self.get().checked_pow(other) {
                        // SAFETY: Checked_pow 在溢出时返回 None，因此结果不能为零。
                        //
                        Some(unsafe { $Ty::new_unchecked(result) })
                    } else {
                        None
                    }
                }

                /// 将非零值提高到整数幂。
                #[doc = sign_dependent_expr!{
                    $signedness ?
                    if signed {
                        concat!("Return [`", stringify!($Int), "::MIN`] ",
                                    "or [`", stringify!($Int), "::MAX`] on overflow.")
                    }
                    if unsigned {
                        concat!("Return [`", stringify!($Int), "::MAX`] on overflow.")
                    }
                }]
                ///
                /// # Examples
                ///
                /// ```
                /// #![feature(nonzero_ops)]
                #[doc = concat!("# use std::num::", stringify!($Ty), ";")]
                ///
                /// # fn main() { test().unwrap(); }
                /// # fn test() -> Option<()> {
                #[doc = concat!("let three = ", stringify!($Ty), "::new(3)?;")]
                #[doc = concat!("let twenty_seven = ", stringify!($Ty), "::new(27)?;")]
                #[doc = concat!("let max = ", stringify!($Ty), "::new(",
                                stringify!($Int), "::MAX)?;")]
                ///
                /// assert_eq!(twenty_seven, three.saturating_pow(3));
                /// assert_eq!(max, max.saturating_pow(3));
                /// # Some(())
                /// # }
                /// ```
                #[unstable(feature = "nonzero_ops", issue = "84186")]
                #[inline]
                pub const fn saturating_pow(self, other: u32) -> $Ty {
                    // SAFETY: saturating_pow 在溢出时返回 u*::MAX，因此结果不能为零。
                    //
                    unsafe { $Ty::new_unchecked(self.get().saturating_pow(other)) }
                }
            }
        )+
    }
}

// 当生成的代码在有符号和无符号类型之间应该不同时使用它。
macro_rules! sign_dependent_expr {
    (signed ? if signed { $signed_case:expr } if unsigned { $unsigned_case:expr } ) => {
        $signed_case
    };
    (unsigned ? if signed { $signed_case:expr } if unsigned { $unsigned_case:expr } ) => {
        $unsigned_case
    };
}

nonzero_unsigned_signed_operations! {
    unsigned NonZeroU8(u8);
    unsigned NonZeroU16(u16);
    unsigned NonZeroU32(u32);
    unsigned NonZeroU64(u64);
    unsigned NonZeroU128(u128);
    unsigned NonZeroUsize(usize);
    signed NonZeroI8(i8);
    signed NonZeroI16(i16);
    signed NonZeroI32(i32);
    signed NonZeroI64(i64);
    signed NonZeroI128(i128);
    signed NonZeroIsize(isize);
}

macro_rules! nonzero_unsigned_is_power_of_two {
    ( $( $Ty: ident )+ ) => {
        $(
            impl $Ty {

                /// 当且仅当某些 `k` 的 `self == (1 << k)` 时，才返回 `true`。
                ///
                /// 在许多体系结构上，此函数可以在基础整数类型上比 `is_power_of_two()` 更好地执行，因为可以避免对零的特殊处理。
                ///
                ///
                /// # Examples
                ///
                /// 基本用法:
                ///
                /// ```
                /// #![feature(nonzero_is_power_of_two)]
                ///
                #[doc = concat!("let eight = std::num::", stringify!($Ty), "::new(8).unwrap();")]
                /// assert!(eight.is_power_of_two());
                #[doc = concat!("let ten = std::num::", stringify!($Ty), "::new(10).unwrap();")]
                /// assert!(!ten.is_power_of_two());
                /// ```
                #[unstable(feature = "nonzero_is_power_of_two", issue = "81106")]
                #[inline]
                pub const fn is_power_of_two(self) -> bool {
                    // LLVM 11 将 `unchecked_sub(x, 1) & x == 0` 标准化为此处看到的实现。
                    // 在基本的 x86-64 目标上，这会保存 3 条用于零位检查的指令。
                    // 在带有 BMI1 的 x86_64 上，非零值使其代码生成到 `BLSR`，与在底层整数类型上的 `POPCNT` 实现相比，它节省了一条指令。
                    //

                    intrinsics::ctpop(self.get()) < 2
                }

            }
        )+
    }
}

nonzero_unsigned_is_power_of_two! { NonZeroU8 NonZeroU16 NonZeroU32 NonZeroU64 NonZeroU128 NonZeroUsize }