Struct NonZero 

pub struct NonZero<T: ZeroablePrimitive>(/* private fields */);

A value that is known not to equal zero.

This enables some memory layout optimization. For example, Option<NonZero<u32>> is the same size as u32:

use core::{num::NonZero};

assert_eq!(size_of::<Option<NonZero<u32>>>(), size_of::<u32>());

Layout

NonZero<T> is guaranteed to have the same layout and bit validity as T with the exception that the all-zero bit pattern is invalid. Option<NonZero<T>> is guaranteed to be compatible with T, including in FFI.

Thanks to the null pointer optimization, NonZero<T> and Option<NonZero<T>> are guaranteed to have the same size and alignment:

use std::num::NonZero;

assert_eq!(size_of::<NonZero<u32>>(), size_of::<Option<NonZero<u32>>>());
assert_eq!(align_of::<NonZero<u32>>(), align_of::<Option<NonZero<u32>>>());

Note on generic usage

NonZero<T> can only be used with some standard library primitive types (such as u8, i32, and etc.). The type parameter T must implement the internal trait [ZeroablePrimitive], which is currently permanently unstable and cannot be implemented by users. Therefore, you cannot use NonZero<T> with your own types, nor can you implement traits for all NonZero<T>, only for concrete types.

Implementations

impl<T> NonZero<T>

where T: ZeroablePrimitive,

pub const fn new(n: T) -> Option<Self>

Creates a non-zero if the given value is not zero.

pub const unsafe fn new_unchecked(n: T) -> Self

Creates a non-zero without checking whether the value is non-zero. This results in undefined behavior if the value is zero.

Safety

The value must not be zero.

pub const fn get(self) -> T

Returns the contained value as a primitive type.

impl NonZero<u8>

pub const BITS: u32 = 8u32

The size of this non-zero integer type in bits.

This value is equal to u8::BITS.

Examples

assert_eq!(NonZero::<u8>::BITS, u8::BITS);

pub const fn leading_zeros(self) -> u32

Returns the number of leading zeros in the binary representation of self.

On many architectures, this function can perform better than leading_zeros() on the underlying integer type, as special handling of zero can be avoided.

Examples

let n = NonZero::<u8>::new(u8::MAX)?;

assert_eq!(n.leading_zeros(), 0);

pub const fn ilog2(self) -> u32

Returns the base 2 logarithm of the number, rounded down.

This is the same operation as u8::ilog2, except that it has no failure cases to worry about since this value can never be zero.

Examples

assert_eq!(NonZero::new(7u8)?.ilog2(), 2);
assert_eq!(NonZero::new(8u8)?.ilog2(), 3);
assert_eq!(NonZero::new(9u8)?.ilog2(), 3);

impl NonZero<u16>

pub const BITS: u32 = 16u32

The size of this non-zero integer type in bits.

This value is equal to u16::BITS.

Examples

assert_eq!(NonZero::<u16>::BITS, u16::BITS);

pub const fn leading_zeros(self) -> u32

Returns the number of leading zeros in the binary representation of self.

On many architectures, this function can perform better than leading_zeros() on the underlying integer type, as special handling of zero can be avoided.

Examples

let n = NonZero::<u16>::new(u16::MAX)?;

assert_eq!(n.leading_zeros(), 0);

pub const fn ilog2(self) -> u32

Returns the base 2 logarithm of the number, rounded down.

This is the same operation as u16::ilog2, except that it has no failure cases to worry about since this value can never be zero.

Examples

assert_eq!(NonZero::new(7u16)?.ilog2(), 2);
assert_eq!(NonZero::new(8u16)?.ilog2(), 3);
assert_eq!(NonZero::new(9u16)?.ilog2(), 3);

impl NonZero<u32>

pub const BITS: u32 = 32u32

The size of this non-zero integer type in bits.

This value is equal to u32::BITS.

Examples

assert_eq!(NonZero::<u32>::BITS, u32::BITS);

pub const fn leading_zeros(self) -> u32

Returns the number of leading zeros in the binary representation of self.

On many architectures, this function can perform better than leading_zeros() on the underlying integer type, as special handling of zero can be avoided.

Examples

let n = NonZero::<u32>::new(u32::MAX)?;

assert_eq!(n.leading_zeros(), 0);

pub const fn ilog2(self) -> u32

Returns the base 2 logarithm of the number, rounded down.

This is the same operation as u32::ilog2, except that it has no failure cases to worry about since this value can never be zero.

Examples

assert_eq!(NonZero::new(7u32)?.ilog2(), 2);
assert_eq!(NonZero::new(8u32)?.ilog2(), 3);
assert_eq!(NonZero::new(9u32)?.ilog2(), 3);

impl NonZero<u64>

pub const BITS: u32 = 64u32

The size of this non-zero integer type in bits.

This value is equal to u64::BITS.

Examples

assert_eq!(NonZero::<u64>::BITS, u64::BITS);

pub const fn leading_zeros(self) -> u32

Returns the number of leading zeros in the binary representation of self.

On many architectures, this function can perform better than leading_zeros() on the underlying integer type, as special handling of zero can be avoided.

Examples

let n = NonZero::<u64>::new(u64::MAX)?;

assert_eq!(n.leading_zeros(), 0);

pub const fn ilog2(self) -> u32

Returns the base 2 logarithm of the number, rounded down.

This is the same operation as u64::ilog2, except that it has no failure cases to worry about since this value can never be zero.

Examples

assert_eq!(NonZero::new(7u64)?.ilog2(), 2);
assert_eq!(NonZero::new(8u64)?.ilog2(), 3);
assert_eq!(NonZero::new(9u64)?.ilog2(), 3);

impl NonZero<u128>

pub const BITS: u32 = 128u32

The size of this non-zero integer type in bits.

This value is equal to u128::BITS.

Examples

assert_eq!(NonZero::<u128>::BITS, u128::BITS);

pub const fn leading_zeros(self) -> u32

Returns the number of leading zeros in the binary representation of self.

On many architectures, this function can perform better than leading_zeros() on the underlying integer type, as special handling of zero can be avoided.

Examples

let n = NonZero::<u128>::new(u128::MAX)?;

assert_eq!(n.leading_zeros(), 0);

pub const fn ilog2(self) -> u32

Returns the base 2 logarithm of the number, rounded down.

This is the same operation as u128::ilog2, except that it has no failure cases to worry about since this value can never be zero.

Examples

assert_eq!(NonZero::new(7u128)?.ilog2(), 2);
assert_eq!(NonZero::new(8u128)?.ilog2(), 3);
assert_eq!(NonZero::new(9u128)?.ilog2(), 3);

impl NonZero<usize>

pub const BITS: u32 = 64u32

The size of this non-zero integer type in bits.

This value is equal to usize::BITS.

Examples

assert_eq!(NonZero::<usize>::BITS, usize::BITS);

pub const fn leading_zeros(self) -> u32

Returns the number of leading zeros in the binary representation of self.

On many architectures, this function can perform better than leading_zeros() on the underlying integer type, as special handling of zero can be avoided.

Examples

let n = NonZero::<usize>::new(usize::MAX)?;

assert_eq!(n.leading_zeros(), 0);

pub const fn ilog2(self) -> u32

Returns the base 2 logarithm of the number, rounded down.

This is the same operation as usize::ilog2, except that it has no failure cases to worry about since this value can never be zero.

Examples

assert_eq!(NonZero::new(7usize)?.ilog2(), 2);
assert_eq!(NonZero::new(8usize)?.ilog2(), 3);
assert_eq!(NonZero::new(9usize)?.ilog2(), 3);

Trait Implementations

impl<T> Clone for NonZero<T>

where T: ZeroablePrimitive,

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

where Self:,

Performs copy-assignment from source.

impl Div<NonZero<u128>> for u128

fn div(self, other: NonZero<u128>) -> u128

Same as self / other.get(), but because other is a NonZero<_>, there’s never a runtime check for division-by-zero.

This operation rounds towards zero, truncating any fractional part of the exact result, and cannot panic.

type Output = u128

The resulting type after applying the / operator.

impl Div<NonZero<u16>> for u16

fn div(self, other: NonZero<u16>) -> u16

Same as self / other.get(), but because other is a NonZero<_>, there’s never a runtime check for division-by-zero.

This operation rounds towards zero, truncating any fractional part of the exact result, and cannot panic.

type Output = u16

The resulting type after applying the / operator.

impl Div<NonZero<u32>> for u32

fn div(self, other: NonZero<u32>) -> u32

Same as self / other.get(), but because other is a NonZero<_>, there’s never a runtime check for division-by-zero.

This operation rounds towards zero, truncating any fractional part of the exact result, and cannot panic.

type Output = u32

The resulting type after applying the / operator.

impl Div<NonZero<u64>> for u64

fn div(self, other: NonZero<u64>) -> u64

Same as self / other.get(), but because other is a NonZero<_>, there’s never a runtime check for division-by-zero.

This operation rounds towards zero, truncating any fractional part of the exact result, and cannot panic.

type Output = u64

The resulting type after applying the / operator.

impl Div<NonZero<u8>> for u8

fn div(self, other: NonZero<u8>) -> u8

Same as self / other.get(), but because other is a NonZero<_>, there’s never a runtime check for division-by-zero.

This operation rounds towards zero, truncating any fractional part of the exact result, and cannot panic.

type Output = u8

The resulting type after applying the / operator.

impl Div<NonZero<usize>> for usize

fn div(self, other: NonZero<usize>) -> usize

Same as self / other.get(), but because other is a NonZero<_>, there’s never a runtime check for division-by-zero.

This operation rounds towards zero, truncating any fractional part of the exact result, and cannot panic.

type Output = usize

The resulting type after applying the / operator.

impl<T> Copy for NonZero<T>

where T: ZeroablePrimitive,