# Type Alias core::num::NonZeroU128

1.28.0 · source · `pub type NonZeroU128 = NonZero<u128>;`

## Expand description

An integer that is known not to equal zero.

This enables some memory layout optimization.
For example, `Option<NonZeroU128>`

is the same size as `u128`

:

```
use std::mem::size_of;
assert_eq!(size_of::<Option<core::num::NonZeroU128>>(), size_of::<u128>());
```

Run## §Layout

`NonZeroU128`

is guaranteed to have the same layout and bit validity as `u128`

with the exception that `0`

is not a valid instance.
`Option<NonZeroU128>`

is guaranteed to be compatible with `u128`

,
including in FFI.

Thanks to the null pointer optimization,
`NonZeroU128`

and `Option<NonZeroU128>`

are guaranteed to have the same size and alignment:

```
use std::num::NonZeroU128;
assert_eq!(size_of::<NonZeroU128>(), size_of::<Option<NonZeroU128>>());
assert_eq!(align_of::<NonZeroU128>(), align_of::<Option<NonZeroU128>>());
```

Run## Aliased Type§

`struct NonZeroU128(/* private fields */);`

## Implementations§

source§### impl NonZeroU128

### impl NonZeroU128

1.67.0 · source#### pub const BITS: u32 = 128u32

#### 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!(NonZeroU128::BITS, u128::BITS);
```

Run1.53.0 (const: 1.53.0) · source#### pub const fn leading_zeros(self) -> u32

#### 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

Basic usage:

```
let n = std::num::NonZeroU128::new(u128::MAX).unwrap();
assert_eq!(n.leading_zeros(), 0);
```

Run1.53.0 (const: 1.53.0) · source#### pub const fn trailing_zeros(self) -> u32

#### pub const fn trailing_zeros(self) -> u32

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::NonZeroU128::new(0b0101000).unwrap();
assert_eq!(n.trailing_zeros(), 3);
```

Runconst: unstable · source#### pub fn count_ones(self) -> NonZero<u32>

🔬This is a nightly-only experimental API. (`non_zero_count_ones`

#120287)

#### pub fn count_ones(self) -> NonZero<u32>

`non_zero_count_ones`

#120287)Returns the number of ones in the binary representation of `self`

.

##### §Examples

Basic usage:

```
#![feature(generic_nonzero, non_zero_count_ones)]
let a = NonZero::<u128>::new(0b100_0000)?;
let b = NonZero::<u128>::new(0b100_0011)?;
assert_eq!(a.count_ones(), NonZero::new(1)?);
assert_eq!(b.count_ones(), NonZero::new(3)?);
```

Run1.64.0 (const: 1.64.0) · source#### pub const fn checked_add(self, other: u128) -> Option<Self>

#### pub const fn checked_add(self, other: u128) -> Option<Self>

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 = NonZeroU128::new(1)?;
let two = NonZeroU128::new(2)?;
let max = NonZeroU128::new(u128::MAX)?;
assert_eq!(Some(two), one.checked_add(1));
assert_eq!(None, max.checked_add(1));
```

Run1.64.0 (const: 1.64.0) · source#### pub const fn saturating_add(self, other: u128) -> Self

#### pub const fn saturating_add(self, other: u128) -> Self

Adds an unsigned integer to a non-zero value.
Return `NonZeroU128::MAX`

on overflow.

##### §Examples

```
let one = NonZeroU128::new(1)?;
let two = NonZeroU128::new(2)?;
let max = NonZeroU128::new(u128::MAX)?;
assert_eq!(two, one.saturating_add(1));
assert_eq!(max, max.saturating_add(1));
```

Runsource#### pub const unsafe fn unchecked_add(self, other: u128) -> Self

🔬This is a nightly-only experimental API. (`nonzero_ops`

#84186)

#### pub const unsafe fn unchecked_add(self, other: u128) -> Self

`nonzero_ops`

#84186)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 > u128::MAX`

.

##### §Examples

```
#![feature(nonzero_ops)]
let one = NonZeroU128::new(1)?;
let two = NonZeroU128::new(2)?;
assert_eq!(two, unsafe { one.unchecked_add(1) });
```

Run1.64.0 (const: 1.64.0) · source#### pub const fn checked_next_power_of_two(self) -> Option<Self>

#### pub const fn checked_next_power_of_two(self) -> Option<Self>

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 = NonZeroU128::new(2)?;
let three = NonZeroU128::new(3)?;
let four = NonZeroU128::new(4)?;
let max = NonZeroU128::new(u128::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() );
```

Run1.67.0 (const: 1.67.0) · source#### pub const fn ilog2(self) -> u32

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

Run1.67.0 (const: 1.67.0) · source#### pub const fn ilog10(self) -> u32

#### pub const fn ilog10(self) -> u32

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

This is the same operation as
`u128::ilog10`

,
except that it has no failure cases to worry about
since this value can never be zero.

##### §Examples

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

Runconst: unstable · source#### pub fn midpoint(self, rhs: Self) -> Self

🔬This is a nightly-only experimental API. (`num_midpoint`

#110840)

#### pub fn midpoint(self, rhs: Self) -> Self

`num_midpoint`

#110840)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 = NonZeroU128::new(1)?;
let two = NonZeroU128::new(2)?;
let four = NonZeroU128::new(4)?;
assert_eq!(one.midpoint(four), two);
assert_eq!(four.midpoint(one), two);
```

Run1.59.0 (const: 1.59.0) · source#### pub const fn is_power_of_two(self) -> bool

#### pub const fn is_power_of_two(self) -> bool

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::NonZeroU128::new(8).unwrap();
assert!(eight.is_power_of_two());
let ten = std::num::NonZeroU128::new(10).unwrap();
assert!(!ten.is_power_of_two());
```

Run1.64.0 (const: 1.64.0) · source#### pub const fn checked_mul(self, other: Self) -> Option<Self>

#### pub const fn checked_mul(self, other: Self) -> Option<Self>

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 = NonZeroU128::new(2)?;
let four = NonZeroU128::new(4)?;
let max = NonZeroU128::new(u128::MAX)?;
assert_eq!(Some(four), two.checked_mul(two));
assert_eq!(None, max.checked_mul(two));
```

Run1.64.0 (const: 1.64.0) · source#### pub const fn saturating_mul(self, other: Self) -> Self

#### pub const fn saturating_mul(self, other: Self) -> Self

Multiplies two non-zero integers together.
Return `NonZeroU128::MAX`

on overflow.

##### §Examples

```
let two = NonZeroU128::new(2)?;
let four = NonZeroU128::new(4)?;
let max = NonZeroU128::new(u128::MAX)?;
assert_eq!(four, two.saturating_mul(two));
assert_eq!(max, four.saturating_mul(max));
```

Runsource#### pub const unsafe fn unchecked_mul(self, other: Self) -> Self

🔬This is a nightly-only experimental API. (`nonzero_ops`

#84186)

#### pub const unsafe fn unchecked_mul(self, other: Self) -> Self

`nonzero_ops`

#84186)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 > u128::MAX`

.

##### §Examples

```
#![feature(nonzero_ops)]
let two = NonZeroU128::new(2)?;
let four = NonZeroU128::new(4)?;
assert_eq!(four, unsafe { two.unchecked_mul(two) });
```

Run1.64.0 (const: 1.64.0) · source#### pub const fn checked_pow(self, other: u32) -> Option<Self>

#### pub const fn checked_pow(self, other: u32) -> Option<Self>

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 = NonZeroU128::new(3)?;
let twenty_seven = NonZeroU128::new(27)?;
let half_max = NonZeroU128::new(u128::MAX / 2)?;
assert_eq!(Some(twenty_seven), three.checked_pow(3));
assert_eq!(None, half_max.checked_pow(3));
```

Run1.64.0 (const: 1.64.0) · source#### pub const fn saturating_pow(self, other: u32) -> Self

#### pub const fn saturating_pow(self, other: u32) -> Self

Raise non-zero value to an integer power.
Return `NonZeroU128::MAX`

on overflow.

##### §Examples

```
let three = NonZeroU128::new(3)?;
let twenty_seven = NonZeroU128::new(27)?;
let max = NonZeroU128::new(u128::MAX)?;
assert_eq!(twenty_seven, three.saturating_pow(3));
assert_eq!(max, max.saturating_pow(3));
```

Run