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

Safety

The value must not be zero.

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

Returns the value as a primitive type.

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

Basic usage:

let n = std::num::NonZeroUsize::new(usize::MAX).unwrap();

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

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

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

Examples

Basic usage:

let n = std::num::NonZeroUsize::new(0b0101000).unwrap();

assert_eq!(n.trailing_zeros(), 3);

Adds an unsigned integer to a non-zero value. Checks for overflow and returns None on overflow. As a consequence, the result cannot wrap to zero.

Examples

let one = NonZeroUsize::new(1)?;
let two = NonZeroUsize::new(2)?;
let max = NonZeroUsize::new(usize::MAX)?;

assert_eq!(Some(two), one.checked_add(1));
assert_eq!(None, max.checked_add(1));

Adds an unsigned integer to a non-zero value. Return NonZeroUsize::MAX on overflow.

Examples

let one = NonZeroUsize::new(1)?;
let two = NonZeroUsize::new(2)?;
let max = NonZeroUsize::new(usize::MAX)?;

assert_eq!(two, one.saturating_add(1));
assert_eq!(max, max.saturating_add(1));

Adds an unsigned integer to a non-zero value, assuming overflow cannot occur. Overflow is unchecked, and it is undefined behaviour to overflow even if the result would wrap to a non-zero value. The behaviour is undefined as soon as self + rhs > usize::MAX.

Examples

#![feature(nonzero_ops)]

let one = NonZeroUsize::new(1)?;
let two = NonZeroUsize::new(2)?;

assert_eq!(two, unsafe { one.unchecked_add(1) });

Returns the smallest power of two greater than or equal to n. Checks for overflow and returns None if the next power of two is greater than the type’s maximum value. As a consequence, the result cannot wrap to zero.

Examples

let two = NonZeroUsize::new(2)?;
let three = NonZeroUsize::new(3)?;
let four = NonZeroUsize::new(4)?;
let max = NonZeroUsize::new(usize::MAX)?;

assert_eq!(Some(two), two.checked_next_power_of_two() );
assert_eq!(Some(four), three.checked_next_power_of_two() );
assert_eq!(None, max.checked_next_power_of_two() );

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!(NonZeroUsize::new(7).unwrap().ilog2(), 2);
assert_eq!(NonZeroUsize::new(8).unwrap().ilog2(), 3);
assert_eq!(NonZeroUsize::new(9).unwrap().ilog2(), 3);

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

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

Examples

assert_eq!(NonZeroUsize::new(99).unwrap().ilog10(), 1);
assert_eq!(NonZeroUsize::new(100).unwrap().ilog10(), 2);
assert_eq!(NonZeroUsize::new(101).unwrap().ilog10(), 2);

Calculates the middle point of self and rhs.

midpoint(a, b) is (a + b) >> 1 as if it were performed in a sufficiently-large signed integral type. This implies that the result is always rounded towards negative infinity and that no overflow will ever occur.

Examples

#![feature(num_midpoint)]

let one = NonZeroUsize::new(1)?;
let two = NonZeroUsize::new(2)?;
let four = NonZeroUsize::new(4)?;

assert_eq!(one.midpoint(four), two);
assert_eq!(four.midpoint(one), two);

Multiplies two non-zero integers together. Checks for overflow and returns None on overflow. As a consequence, the result cannot wrap to zero.

Examples

let two = NonZeroUsize::new(2)?;
let four = NonZeroUsize::new(4)?;
let max = NonZeroUsize::new(usize::MAX)?;

assert_eq!(Some(four), two.checked_mul(two));
assert_eq!(None, max.checked_mul(two));

Multiplies two non-zero integers together. Return NonZeroUsize::MAX on overflow.

Examples

let two = NonZeroUsize::new(2)?;
let four = NonZeroUsize::new(4)?;
let max = NonZeroUsize::new(usize::MAX)?;

assert_eq!(four, two.saturating_mul(two));
assert_eq!(max, four.saturating_mul(max));

Multiplies two non-zero integers together, assuming overflow cannot occur. Overflow is unchecked, and it is undefined behaviour to overflow even if the result would wrap to a non-zero value. The behaviour is undefined as soon as self * rhs > usize::MAX.

Examples

#![feature(nonzero_ops)]

let two = NonZeroUsize::new(2)?;
let four = NonZeroUsize::new(4)?;

assert_eq!(four, unsafe { two.unchecked_mul(two) });

Raises non-zero value to an integer power. Checks for overflow and returns None on overflow. As a consequence, the result cannot wrap to zero.

Examples

let three = NonZeroUsize::new(3)?;
let twenty_seven = NonZeroUsize::new(27)?;
let half_max = NonZeroUsize::new(usize::MAX / 2)?;

assert_eq!(Some(twenty_seven), three.checked_pow(3));
assert_eq!(None, half_max.checked_pow(3));

Raise non-zero value to an integer power. Return NonZeroUsize::MAX on overflow.

Examples

let three = NonZeroUsize::new(3)?;
let twenty_seven = NonZeroUsize::new(27)?;
let max = NonZeroUsize::new(usize::MAX)?;

assert_eq!(twenty_seven, three.saturating_pow(3));
assert_eq!(max, max.saturating_pow(3));

Returns true if and only if self == (1 << k) for some k.

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

Examples

Basic usage:

let eight = std::num::NonZeroUsize::new(8).unwrap();
assert!(eight.is_power_of_two());
let ten = std::num::NonZeroUsize::new(10).unwrap();
assert!(!ten.is_power_of_two());

The smallest value that can be represented by this non-zero integer type, 1.

Examples

assert_eq!(NonZeroUsize::MIN.get(), 1usize);

The largest value that can be represented by this non-zero integer type, equal to usize::MAX.

Examples

assert_eq!(NonZeroUsize::MAX.get(), usize::MAX);

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

This value is equal to usize::BITS.

Examples

assert_eq!(NonZeroUsize::BITS, usize::BITS);

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

Converts NonZeroU16 to NonZeroUsize losslessly.

Converts NonZeroU8 to NonZeroUsize losslessly.

Converts a NonZeroUsize into an usize

This operation satisfies n % d == n - (n / d) * d, and cannot panic.

Attempts to convert NonZeroI128 to NonZeroUsize.

Attempts to convert NonZeroI16 to NonZeroUsize.

Attempts to convert NonZeroI32 to NonZeroUsize.

Attempts to convert NonZeroI64 to NonZeroUsize.

Attempts to convert NonZeroI8 to NonZeroUsize.

Attempts to convert NonZeroIsize to NonZeroUsize.

Attempts to convert NonZeroU128 to NonZeroUsize.

Attempts to convert NonZeroU32 to NonZeroUsize.

Attempts to convert NonZeroU64 to NonZeroUsize.

Attempts to convert NonZeroUsize to NonZeroI128.

Attempts to convert NonZeroUsize to NonZeroI16.

Attempts to convert NonZeroUsize to NonZeroI32.

Attempts to convert NonZeroUsize to NonZeroI64.

Attempts to convert NonZeroUsize to NonZeroI8.

Attempts to convert NonZeroUsize to NonZeroIsize.

Attempts to convert NonZeroUsize to NonZeroU128.

Attempts to convert NonZeroUsize to NonZeroU16.

Attempts to convert NonZeroUsize to NonZeroU32.

Attempts to convert NonZeroUsize to NonZeroU64.

Attempts to convert NonZeroUsize to NonZeroU8.

Attempts to convert usize to NonZeroUsize.

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.