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}