The smallest value that can be represented by this integer type.

§Examples

assert_eq!(usize::MIN,0);

The largest value that can be represented by this integer type(2⁶⁴ − 1 on 64-bit targets).

§Examples

assert_eq!(usize::MAX,18446744073709551615);

The size of this integer type in bits.

§Examples

assert_eq!(usize::BITS,64);

Returns the number of ones in the binary representation ofself.

§Examples

letn =0b01001100usize;assert_eq!(n.count_ones(),3);letmax = usize::MAX;assert_eq!(max.count_ones(),64);letzero =0usize;assert_eq!(zero.count_ones(),0);

Returns the number of zeros in the binary representation ofself.

§Examples

letzero =0usize;assert_eq!(zero.count_zeros(),64);letmax = usize::MAX;assert_eq!(max.count_zeros(),0);

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

Depending on what you’re doing with the value, you might also be interested in theilog2 function which returns a consistent number, even if the type widens.

§Examples

letn = usize::MAX >>2;assert_eq!(n.leading_zeros(),2);letzero =0usize;assert_eq!(zero.leading_zeros(),64);letmax = usize::MAX;assert_eq!(max.leading_zeros(),0);

Returns the number of trailing zeros in the binary representationofself.

§Examples

letn =0b0101000usize;assert_eq!(n.trailing_zeros(),3);letzero =0usize;assert_eq!(zero.trailing_zeros(),64);letmax = usize::MAX;assert_eq!(max.trailing_zeros(),0);

Returns the number of leading ones in the binary representation ofself.

§Examples

letn = !(usize::MAX >>2);assert_eq!(n.leading_ones(),2);letzero =0usize;assert_eq!(zero.leading_ones(),0);letmax = usize::MAX;assert_eq!(max.leading_ones(),64);

Returns the number of trailing ones in the binary representationofself.

§Examples

letn =0b1010111usize;assert_eq!(n.trailing_ones(),3);letzero =0usize;assert_eq!(zero.trailing_ones(),0);letmax = usize::MAX;assert_eq!(max.trailing_ones(),64);

Returns the minimum number of bits required to representself.

This method returns zero ifself is zero.

§Examples

#![feature(uint_bit_width)]assert_eq!(0_usize.bit_width(),0);assert_eq!(0b111_usize.bit_width(),3);assert_eq!(0b1110_usize.bit_width(),4);assert_eq!(usize::MAX.bit_width(),64);

Returnsself with only the most significant bit set, or0 ifthe input is0.

§Examples

#![feature(isolate_most_least_significant_one)]letn: usize =0b_01100100;assert_eq!(n.isolate_highest_one(),0b_01000000);assert_eq!(0_usize.isolate_highest_one(),0);

Returnsself with only the least significant bit set, or0 ifthe input is0.

§Examples

#![feature(isolate_most_least_significant_one)]letn: usize =0b_01100100;assert_eq!(n.isolate_lowest_one(),0b_00000100);assert_eq!(0_usize.isolate_lowest_one(),0);

Returns the index of the highest bit set to one inself, orNoneifself is0.

§Examples

#![feature(int_lowest_highest_one)]assert_eq!(0b0_usize.highest_one(),None);assert_eq!(0b1_usize.highest_one(),Some(0));assert_eq!(0b1_0000_usize.highest_one(),Some(4));assert_eq!(0b1_1111_usize.highest_one(),Some(4));

Returns the index of the lowest bit set to one inself, orNoneifself is0.

§Examples

#![feature(int_lowest_highest_one)]assert_eq!(0b0_usize.lowest_one(),None);assert_eq!(0b1_usize.lowest_one(),Some(0));assert_eq!(0b1_0000_usize.lowest_one(),Some(4));assert_eq!(0b1_1111_usize.lowest_one(),Some(0));

Returns the bit pattern ofself reinterpreted as a signed integer of the same size.

This produces the same result as anas cast, but ensures that the bit-width remainsthe same.

§Examples

letn = usize::MAX;assert_eq!(n.cast_signed(), -1isize);

Shifts the bits to the left by a specified amount,n,wrapping the truncated bits to the end of the resulting integer.

rotate_left(n) is equivalent to applyingrotate_left(1) a total ofn times. Inparticular, a rotation by the number of bits inself returns the input valueunchanged.

Please note this isn’t the same operation as the<< shifting operator!

§Examples

letn =0xaa00000000006e1usize;letm =0x6e10aa;assert_eq!(n.rotate_left(12), m);assert_eq!(n.rotate_left(1024), n);

Shifts the bits to the right by a specified amount,n,wrapping the truncated bits to the beginning of the resultinginteger.

rotate_right(n) is equivalent to applyingrotate_right(1) a total ofn times. Inparticular, a rotation by the number of bits inself returns the input valueunchanged.

Please note this isn’t the same operation as the>> shifting operator!

§Examples

letn =0x6e10aausize;letm =0xaa00000000006e1;assert_eq!(n.rotate_right(12), m);assert_eq!(n.rotate_right(1024), n);

Performs a left funnel shift (concatenatesself withrhs, withselfmaking up the most significant half, then shifts the combined value leftbyn, and most significant half is extracted to produce the result).

Please note this isn’t the same operation as the<< shifting operator orrotate_left, althougha.funnel_shl(a, n) isequivalenttoa.rotate_left(n).

§Panics

Ifn is greater than or equal to the number of bits inself

§Examples

Basic usage:

#![feature(funnel_shifts)]leta =0xaa00000000006e1usize;letb =0x2fe78e45983acd98usize;letm =0x6e12fe;assert_eq!(a.funnel_shl(b,12), m);

Performs a right funnel shift (concatenatesself andrhs, withselfmaking up the most significant half, then shifts the combined value rightbyn, and least significant half is extracted to produce the result).

Please note this isn’t the same operation as the>> shifting operator orrotate_right, althougha.funnel_shr(a, n) isequivalenttoa.rotate_right(n).

§Panics

Ifn is greater than or equal to the number of bits inself

§Examples

Basic usage:

#![feature(funnel_shifts)]leta =0xaa00000000006e1usize;letb =0x2fe78e45983acd98usize;letm =0x6e12fe78e45983ac;assert_eq!(a.funnel_shr(b,12), m);

Reverses the byte order of the integer.

§Examples

letn =0x1234567890123456usize;letm = n.swap_bytes();assert_eq!(m,0x5634129078563412);

Returns an integer with the bit locations specified bymask packedcontiguously into the least significant bits of the result.

#![feature(uint_gather_scatter_bits)]letn: usize =0b1011_1100;assert_eq!(n.gather_bits(0b0010_0100),0b0000_0011);assert_eq!(n.gather_bits(0xF0),0b0000_1011);

Returns an integer with the least significant bits ofselfdistributed to the bit locations specified bymask.

#![feature(uint_gather_scatter_bits)]letn: usize =0b1010_1101;assert_eq!(n.scatter_bits(0b0101_0101),0b0101_0001);assert_eq!(n.scatter_bits(0xF0),0b1101_0000);

Reverses the order of bits in the integer. The least significant bit becomes the most significant bit,second least-significant bit becomes second most-significant bit, etc.

§Examples

letn =0x1234567890123456usize;letm = n.reverse_bits();assert_eq!(m,0x6a2c48091e6a2c48);assert_eq!(0,0usize.reverse_bits());

Converts an integer from big endian to the target’s endianness.

On big endian this is a no-op. On little endian the bytes areswapped.

§Examples

letn =0x1Ausize;ifcfg!(target_endian ="big") {assert_eq!(usize::from_be(n), n)}else{assert_eq!(usize::from_be(n), n.swap_bytes())}

Converts an integer from little endian to the target’s endianness.

On little endian this is a no-op. On big endian the bytes areswapped.

§Examples

letn =0x1Ausize;ifcfg!(target_endian ="little") {assert_eq!(usize::from_le(n), n)}else{assert_eq!(usize::from_le(n), n.swap_bytes())}

Convertsself to big endian from the target’s endianness.

On big endian this is a no-op. On little endian the bytes areswapped.

§Examples

letn =0x1Ausize;ifcfg!(target_endian ="big") {assert_eq!(n.to_be(), n)}else{assert_eq!(n.to_be(), n.swap_bytes())}

Convertsself to little endian from the target’s endianness.

On little endian this is a no-op. On big endian the bytes areswapped.

§Examples

letn =0x1Ausize;ifcfg!(target_endian ="little") {assert_eq!(n.to_le(), n)}else{assert_eq!(n.to_le(), n.swap_bytes())}

Checked integer addition. Computesself + rhs, returningNoneif overflow occurred.

§Examples

assert_eq!((usize::MAX -2).checked_add(1),Some(usize::MAX -1));assert_eq!((usize::MAX -2).checked_add(3),None);

Strict integer addition. Computesself + rhs, panickingif overflow occurred.

§Panics

§Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

§Examples

assert_eq!((usize::MAX -2).strict_add(1), usize::MAX -1);

The following panics because of overflow:

let _= (usize::MAX -2).strict_add(3);

Unchecked integer addition. Computesself + rhs, assuming overflowcannot occur.

Callingx.unchecked_add(y) is semantically equivalent to callingx.checked_add(y).unwrap_unchecked().

If you’re just trying to avoid the panic in debug mode, thendo notuse this. Instead, you’re looking forwrapping_add.

§Safety

This results in undefined behavior whenself + rhs > usize::MAX orself + rhs < usize::MIN,i.e. whenchecked_add would returnNone.

Checked addition with a signed integer. Computesself + rhs,returningNone if overflow occurred.

§Examples

assert_eq!(1usize.checked_add_signed(2),Some(3));assert_eq!(1usize.checked_add_signed(-2),None);assert_eq!((usize::MAX -2).checked_add_signed(3),None);

Strict addition with a signed integer. Computesself + rhs,panicking if overflow occurred.

§Panics

§Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

§Examples

assert_eq!(1usize.strict_add_signed(2),3);

The following panic because of overflow:

let _=1usize.strict_add_signed(-2);

let _= (usize::MAX -2).strict_add_signed(3);

Checked integer subtraction. Computesself - rhs, returningNone if overflow occurred.

§Examples

assert_eq!(1usize.checked_sub(1),Some(0));assert_eq!(0usize.checked_sub(1),None);

Strict integer subtraction. Computesself - rhs, panicking ifoverflow occurred.

§Panics

§Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

§Examples

assert_eq!(1usize.strict_sub(1),0);

The following panics because of overflow:

let _=0usize.strict_sub(1);

Unchecked integer subtraction. Computesself - rhs, assuming overflowcannot occur.

Callingx.unchecked_sub(y) is semantically equivalent to callingx.checked_sub(y).unwrap_unchecked().

If you’re just trying to avoid the panic in debug mode, thendo notuse this. Instead, you’re looking forwrapping_sub.

If you find yourself writing code like this:

iffoo >= bar {// SAFETY: just checked it will not overflowletdiff =unsafe{ foo.unchecked_sub(bar) };// ... use diff ...}

Consider changing it to

if letSome(diff) = foo.checked_sub(bar) {// ... use diff ...}

As that does exactly the same thing – including telling the optimizerthat the subtraction cannot overflow – but avoids needingunsafe.

§Safety

This results in undefined behavior whenself - rhs > usize::MAX orself - rhs < usize::MIN,i.e. whenchecked_sub would returnNone.

Checked subtraction with a signed integer. Computesself - rhs,returningNone if overflow occurred.

§Examples

assert_eq!(1usize.checked_sub_signed(2),None);assert_eq!(1usize.checked_sub_signed(-2),Some(3));assert_eq!((usize::MAX -2).checked_sub_signed(-4),None);

Strict subtraction with a signed integer. Computesself - rhs,panicking if overflow occurred.

§Panics

§Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

§Examples

assert_eq!(3usize.strict_sub_signed(2),1);

The following panic because of overflow:

let _=1usize.strict_sub_signed(2);

let _= (usize::MAX).strict_sub_signed(-1);

Checked integer subtraction. Computesself - rhs and checks if the result fits into anisize, returningNone if overflow occurred.

§Examples

assert_eq!(10usize.checked_signed_diff(2),Some(8));assert_eq!(2usize.checked_signed_diff(10),Some(-8));assert_eq!(usize::MAX.checked_signed_diff(isize::MAXasusize),None);assert_eq!((isize::MAXasusize).checked_signed_diff(usize::MAX),Some(isize::MIN));assert_eq!((isize::MAXasusize +1).checked_signed_diff(0),None);assert_eq!(usize::MAX.checked_signed_diff(usize::MAX),Some(0));

Checked integer multiplication. Computesself * rhs, returningNone if overflow occurred.

§Examples

assert_eq!(5usize.checked_mul(1),Some(5));assert_eq!(usize::MAX.checked_mul(2),None);

Strict integer multiplication. Computesself * rhs, panicking ifoverflow occurred.

§Panics

§Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

§Examples

assert_eq!(5usize.strict_mul(1),5);

The following panics because of overflow:

let _= usize::MAX.strict_mul(2);

Unchecked integer multiplication. Computesself * rhs, assuming overflowcannot occur.

Callingx.unchecked_mul(y) is semantically equivalent to callingx.checked_mul(y).unwrap_unchecked().

If you’re just trying to avoid the panic in debug mode, thendo notuse this. Instead, you’re looking forwrapping_mul.

§Safety

This results in undefined behavior whenself * rhs > usize::MAX orself * rhs < usize::MIN,i.e. whenchecked_mul would returnNone.

Checked integer division. Computesself / rhs, returningNoneifrhs == 0.

§Examples

assert_eq!(128usize.checked_div(2),Some(64));assert_eq!(1usize.checked_div(0),None);

Strict integer division. Computesself / rhs.

Strict division on unsigned types is just normal division. There’s noway overflow could ever happen. This function exists so that alloperations are accounted for in the strict operations.

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(100usize.strict_div(10),10);

The following panics because of division by zero:

let _= (1usize).strict_div(0);

Checked Euclidean division. Computesself.div_euclid(rhs), returningNoneifrhs == 0.

§Examples

assert_eq!(128usize.checked_div_euclid(2),Some(64));assert_eq!(1usize.checked_div_euclid(0),None);

Strict Euclidean division. Computesself.div_euclid(rhs).

Strict division on unsigned types is just normal division. There’s noway overflow could ever happen. This function exists so that alloperations are accounted for in the strict operations. Since, for thepositive integers, all common definitions of division are equal, thisis exactly equal toself.strict_div(rhs).

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(100usize.strict_div_euclid(10),10);

The following panics because of division by zero:

let _= (1usize).strict_div_euclid(0);

Checked integer division without remainder. Computesself / rhs,returningNone ifrhs == 0 or ifself % rhs != 0.

§Examples

#![feature(exact_div)]assert_eq!(64usize.checked_div_exact(2),Some(32));assert_eq!(64usize.checked_div_exact(32),Some(2));assert_eq!(64usize.checked_div_exact(0),None);assert_eq!(65usize.checked_div_exact(2),None);

Integer division without remainder. Computesself / rhs, returningNone ifself % rhs != 0.

§Panics

This function will panic ifrhs == 0.

§Examples

#![feature(exact_div)]assert_eq!(64usize.div_exact(2),Some(32));assert_eq!(64usize.div_exact(32),Some(2));assert_eq!(65usize.div_exact(2),None);

Unchecked integer division without remainder. Computesself / rhs.

§Safety

This results in undefined behavior whenrhs == 0 orself % rhs != 0,i.e. whenchecked_div_exact would returnNone.

Checked integer remainder. Computesself % rhs, returningNoneifrhs == 0.

§Examples

assert_eq!(5usize.checked_rem(2),Some(1));assert_eq!(5usize.checked_rem(0),None);

Strict integer remainder. Computesself % rhs.

Strict remainder calculation on unsigned types is just the regularremainder calculation. There’s no way overflow could ever happen.This function exists so that all operations are accounted for in thestrict operations.

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(100usize.strict_rem(10),0);

The following panics because of division by zero:

let _=5usize.strict_rem(0);

Checked Euclidean modulo. Computesself.rem_euclid(rhs), returningNoneifrhs == 0.

§Examples

assert_eq!(5usize.checked_rem_euclid(2),Some(1));assert_eq!(5usize.checked_rem_euclid(0),None);

Strict Euclidean modulo. Computesself.rem_euclid(rhs).

Strict modulo calculation on unsigned types is just the regularremainder calculation. There’s no way overflow could ever happen.This function exists so that all operations are accounted for in thestrict operations. Since, for the positive integers, all commondefinitions of division are equal, this is exactly equal toself.strict_rem(rhs).

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(100usize.strict_rem_euclid(10),0);

The following panics because of division by zero:

let _=5usize.strict_rem_euclid(0);

Same value asself | other, but UB if any bit position is set in both inputs.

This is a situational micro-optimization for places where you’d ratheruse addition on some platforms and bitwise or on other platforms, basedon exactly which instructions combine better with whatever else you’redoing. Note that there’s no reason to bother using this for placeswhere it’s clear from the operations involved that they can’t overlap.For example, if you’re combiningu16s into au32 with((a as u32) << 16) | (b as u32), that’s fine, as the backend willknow those sides of the| are disjoint without needing help.

§Examples

#![feature(disjoint_bitor)]// SAFETY: `1` and `4` have no bits in common.unsafe{assert_eq!(1_usize.unchecked_disjoint_bitor(4),5);}

§Safety

Requires that(self & other) == 0, otherwise it’s immediate UB.

Equivalently, requires that(self | other) == (self + other).

Returns the logarithm of the number with respect to an arbitrary base,rounded down.

This method might not be optimized owing to implementation details;ilog2 can produce results more efficiently for base 2, andilog10can produce results more efficiently for base 10.

§Panics

This function will panic ifself is zero, or ifbase is less than 2.

§Examples

assert_eq!(5usize.ilog(5),1);

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

§Panics

This function will panic ifself is zero.

§Examples

assert_eq!(2usize.ilog2(),1);

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

§Panics

This function will panic ifself is zero.

§Example

assert_eq!(10usize.ilog10(),1);

Returns the logarithm of the number with respect to an arbitrary base,rounded down.

ReturnsNone if the number is zero, or if the base is not at least 2.

This method might not be optimized owing to implementation details;checked_ilog2 can produce results more efficiently for base 2, andchecked_ilog10 can produce results more efficiently for base 10.

§Examples

assert_eq!(5usize.checked_ilog(5),Some(1));

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

ReturnsNone if the number is zero.

§Examples

assert_eq!(2usize.checked_ilog2(),Some(1));

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

ReturnsNone if the number is zero.

§Examples

assert_eq!(10usize.checked_ilog10(),Some(1));

Checked negation. Computes-self, returningNone unlessself == 0.

Note that negating any positive integer will overflow.

§Examples

assert_eq!(0usize.checked_neg(),Some(0));assert_eq!(1usize.checked_neg(),None);

Strict negation. Computes-self, panicking unlessself == 0.

Note that negating any positive integer will overflow.

§Panics

§Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

§Examples

assert_eq!(0usize.strict_neg(),0);

The following panics because of overflow:

let _=1usize.strict_neg();

Checked shift left. Computesself << rhs, returningNoneifrhs is larger than or equal to the number of bits inself.

§Examples

assert_eq!(0x1usize.checked_shl(4),Some(0x10));assert_eq!(0x10usize.checked_shl(129),None);assert_eq!(0x10usize.checked_shl(63),Some(0));

Strict shift left. Computesself << rhs, panicking ifrhs is largerthan or equal to the number of bits inself.

§Panics

§Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

§Examples

assert_eq!(0x1usize.strict_shl(4),0x10);

The following panics because of overflow:

let _=0x10usize.strict_shl(129);

Unchecked shift left. Computesself << rhs, assuming thatrhs is less than the number of bits inself.

§Safety

This results in undefined behavior ifrhs is larger thanor equal to the number of bits inself,i.e. whenchecked_shl would returnNone.

Unbounded shift left. Computesself << rhs, without bounding the value ofrhs.

Ifrhs is larger or equal to the number of bits inself,the entire value is shifted out, and0 is returned.

§Examples

assert_eq!(0x1usize.unbounded_shl(4),0x10);assert_eq!(0x1usize.unbounded_shl(129),0);

Exact shift left. Computesself << rhs as long as it can be reversed losslessly.

ReturnsNone if any non-zero bits would be shifted out or ifrhs >=usize::BITS.Otherwise, returnsSome(self << rhs).

§Examples

#![feature(exact_bitshifts)]assert_eq!(0x1usize.shl_exact(4),Some(0x10));assert_eq!(0x1usize.shl_exact(129),None);

Unchecked exact shift left. Computesself << rhs, assuming the operation can belosslessly reversedrhs cannot be larger thanusize::BITS.

§Safety

This results in undefined behavior whenrhs > self.leading_zeros() || rhs >= usize::BITSi.e. whenusize::shl_exactwould returnNone.

Checked shift right. Computesself >> rhs, returningNoneifrhs is larger than or equal to the number of bits inself.

§Examples

assert_eq!(0x10usize.checked_shr(4),Some(0x1));assert_eq!(0x10usize.checked_shr(129),None);

Strict shift right. Computesself >> rhs, panicking ifrhs islarger than or equal to the number of bits inself.

§Panics

§Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

§Examples

assert_eq!(0x10usize.strict_shr(4),0x1);

The following panics because of overflow:

let _=0x10usize.strict_shr(129);

Unchecked shift right. Computesself >> rhs, assuming thatrhs is less than the number of bits inself.

§Safety

This results in undefined behavior ifrhs is larger thanor equal to the number of bits inself,i.e. whenchecked_shr would returnNone.

Unbounded shift right. Computesself >> rhs, without bounding the value ofrhs.

Ifrhs is larger or equal to the number of bits inself,the entire value is shifted out, and0 is returned.

§Examples

assert_eq!(0x10usize.unbounded_shr(4),0x1);assert_eq!(0x10usize.unbounded_shr(129),0);

Exact shift right. Computesself >> rhs as long as it can be reversed losslessly.

ReturnsNone if any non-zero bits would be shifted out or ifrhs >=usize::BITS.Otherwise, returnsSome(self >> rhs).

§Examples

#![feature(exact_bitshifts)]assert_eq!(0x10usize.shr_exact(4),Some(0x1));assert_eq!(0x10usize.shr_exact(5),None);

Unchecked exact shift right. Computesself >> rhs, assuming the operation can belosslessly reversed andrhs cannot be larger thanusize::BITS.

§Safety

This results in undefined behavior whenrhs > self.trailing_zeros() || rhs >= usize::BITSi.e. whenusize::shr_exactwould returnNone.

Checked exponentiation. Computesself.pow(exp), returningNone ifoverflow occurred.

§Examples

assert_eq!(2usize.checked_pow(5),Some(32));assert_eq!(0_usize.checked_pow(0),Some(1));assert_eq!(usize::MAX.checked_pow(2),None);

Strict exponentiation. Computesself.pow(exp), panicking ifoverflow occurred.

§Panics

§Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

§Examples

assert_eq!(2usize.strict_pow(5),32);assert_eq!(0_usize.strict_pow(0),1);

The following panics because of overflow:

let _= usize::MAX.strict_pow(2);

Saturating integer addition. Computesself + rhs, saturating atthe numeric bounds instead of overflowing.

§Examples

assert_eq!(100usize.saturating_add(1),101);assert_eq!(usize::MAX.saturating_add(127), usize::MAX);

Saturating addition with a signed integer. Computesself + rhs,saturating at the numeric bounds instead of overflowing.

§Examples

assert_eq!(1usize.saturating_add_signed(2),3);assert_eq!(1usize.saturating_add_signed(-2),0);assert_eq!((usize::MAX -2).saturating_add_signed(4), usize::MAX);

Saturating integer subtraction. Computesself - rhs, saturatingat the numeric bounds instead of overflowing.

§Examples

assert_eq!(100usize.saturating_sub(27),73);assert_eq!(13usize.saturating_sub(127),0);

Saturating integer subtraction. Computesself -rhs, saturating atthe numeric bounds instead of overflowing.

§Examples

assert_eq!(1usize.saturating_sub_signed(2),0);assert_eq!(1usize.saturating_sub_signed(-2),3);assert_eq!((usize::MAX -2).saturating_sub_signed(-4), usize::MAX);

Saturating integer multiplication. Computesself * rhs,saturating at the numeric bounds instead of overflowing.

§Examples

assert_eq!(2usize.saturating_mul(10),20);assert_eq!((usize::MAX).saturating_mul(10), usize::MAX);

Saturating integer division. Computesself / rhs, saturating at thenumeric bounds instead of overflowing.

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(5usize.saturating_div(2),2);

Saturating integer exponentiation. Computesself.pow(exp),saturating at the numeric bounds instead of overflowing.

§Examples

assert_eq!(4usize.saturating_pow(3),64);assert_eq!(0_usize.saturating_pow(0),1);assert_eq!(usize::MAX.saturating_pow(2), usize::MAX);

Wrapping (modular) addition. Computesself + rhs,wrapping around at the boundary of the type.

§Examples

assert_eq!(200usize.wrapping_add(55),255);assert_eq!(200usize.wrapping_add(usize::MAX),199);

Wrapping (modular) addition with a signed integer. Computesself + rhs, wrapping around at the boundary of the type.

§Examples

assert_eq!(1usize.wrapping_add_signed(2),3);assert_eq!(1usize.wrapping_add_signed(-2), usize::MAX);assert_eq!((usize::MAX -2).wrapping_add_signed(4),1);

Wrapping (modular) subtraction. Computesself - rhs,wrapping around at the boundary of the type.

§Examples

assert_eq!(100usize.wrapping_sub(100),0);assert_eq!(100usize.wrapping_sub(usize::MAX),101);

Wrapping (modular) subtraction with a signed integer. Computesself - rhs, wrapping around at the boundary of the type.

§Examples

assert_eq!(1usize.wrapping_sub_signed(2), usize::MAX);assert_eq!(1usize.wrapping_sub_signed(-2),3);assert_eq!((usize::MAX -2).wrapping_sub_signed(-4),1);

Wrapping (modular) multiplication. Computesself * rhs, wrapping around at the boundary of the type.

§Examples

Please note that this example is shared among integer types, which is whyu8 is used.

assert_eq!(10u8.wrapping_mul(12),120);assert_eq!(25u8.wrapping_mul(12),44);

Wrapping (modular) division. Computesself / rhs.

Wrapped division on unsigned types is just normal division. There’sno way wrapping could ever happen. This function exists so that alloperations are accounted for in the wrapping operations.

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(100usize.wrapping_div(10),10);

Wrapping Euclidean division. Computesself.div_euclid(rhs).

Wrapped division on unsigned types is just normal division. There’sno way wrapping could ever happen. This function exists so that alloperations are accounted for in the wrapping operations. Since, forthe positive integers, all common definitions of division are equal,this is exactly equal toself.wrapping_div(rhs).

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(100usize.wrapping_div_euclid(10),10);

Wrapping (modular) remainder. Computesself % rhs.

Wrapped remainder calculation on unsigned types is just the regularremainder calculation. There’s no way wrapping could ever happen.This function exists so that all operations are accounted for in thewrapping operations.

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(100usize.wrapping_rem(10),0);

Wrapping Euclidean modulo. Computesself.rem_euclid(rhs).

Wrapped modulo calculation on unsigned types is just the regularremainder calculation. There’s no way wrapping could ever happen.This function exists so that all operations are accounted for in thewrapping operations. Since, for the positive integers, all commondefinitions of division are equal, this is exactly equal toself.wrapping_rem(rhs).

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(100usize.wrapping_rem_euclid(10),0);

Wrapping (modular) negation. Computes-self,wrapping around at the boundary of the type.

Since unsigned types do not have negative equivalentsall applications of this function will wrap (except for-0).For values smaller than the corresponding signed type’s maximumthe result is the same as casting the corresponding signed value.Any larger values are equivalent toMAX + 1 - (val - MAX - 1) whereMAX is the corresponding signed type’s maximum.

§Examples

assert_eq!(0_usize.wrapping_neg(),0);assert_eq!(usize::MAX.wrapping_neg(),1);assert_eq!(13_usize.wrapping_neg(), (!13) +1);assert_eq!(42_usize.wrapping_neg(), !(42-1));

Panic-free bitwise shift-left; yieldsself << mask(rhs),wheremask removes any high-order bits ofrhs thatwould cause the shift to exceed the bitwidth of the type.

Note that this isnot the same as a rotate-left; theRHS of a wrapping shift-left is restricted to the rangeof the type, rather than the bits shifted out of the LHSbeing returned to the other end. The primitive integertypes all implement arotate_left function,which may be what you want instead.

§Examples

assert_eq!(1usize.wrapping_shl(7),128);assert_eq!(1usize.wrapping_shl(128),1);

Panic-free bitwise shift-right; yieldsself >> mask(rhs),wheremask removes any high-order bits ofrhs thatwould cause the shift to exceed the bitwidth of the type.

Note that this isnot the same as a rotate-right; theRHS of a wrapping shift-right is restricted to the rangeof the type, rather than the bits shifted out of the LHSbeing returned to the other end. The primitive integertypes all implement arotate_right function,which may be what you want instead.

§Examples

assert_eq!(128usize.wrapping_shr(7),1);assert_eq!(128usize.wrapping_shr(128),128);

Wrapping (modular) exponentiation. Computesself.pow(exp),wrapping around at the boundary of the type.

§Examples

assert_eq!(3usize.wrapping_pow(5),243);assert_eq!(3u8.wrapping_pow(6),217);assert_eq!(0_usize.wrapping_pow(0),1);

Calculatesself +rhs.

Returns a tuple of the addition along with a boolean indicatingwhether an arithmetic overflow would occur. If an overflow wouldhave occurred then the wrapped value is returned.

§Examples

assert_eq!(5usize.overflowing_add(2), (7,false));assert_eq!(usize::MAX.overflowing_add(1), (0,true));

Calculatesself +rhs +carry and returns a tuple containingthe sum and the output carry (in that order).

Performs “ternary addition” of two integer operands and a carry-inbit, and returns an output integer and a carry-out bit. This allowschaining together multiple additions to create a wider addition, andcan be useful for bignum addition.

This can be thought of as a 64-bit “full adder”, in the electronics sense.

If the input carry is false, this method is equivalent tooverflowing_add, and the output carry isequal to the overflow flag. Note that although carry and overflowflags are similar for unsigned integers, they are different forsigned integers.

§Examples

//    3  MAX    (a = 3 × 2^64 + 2^64 - 1)// +  5    7    (b = 5 × 2^64 + 7)// ---------//    9    6    (sum = 9 × 2^64 + 6)let(a1, a0): (usize, usize) = (3, usize::MAX);let(b1, b0): (usize, usize) = (5,7);letcarry0 =false;let(sum0, carry1) = a0.carrying_add(b0, carry0);assert_eq!(carry1,true);let(sum1, carry2) = a1.carrying_add(b1, carry1);assert_eq!(carry2,false);assert_eq!((sum1, sum0), (9,6));

Calculatesself +rhs with a signedrhs.

Returns a tuple of the addition along with a boolean indicatingwhether an arithmetic overflow would occur. If an overflow wouldhave occurred then the wrapped value is returned.

§Examples

assert_eq!(1usize.overflowing_add_signed(2), (3,false));assert_eq!(1usize.overflowing_add_signed(-2), (usize::MAX,true));assert_eq!((usize::MAX -2).overflowing_add_signed(4), (1,true));

Calculatesself -rhs.

Returns a tuple of the subtraction along with a boolean indicatingwhether an arithmetic overflow would occur. If an overflow wouldhave occurred then the wrapped value is returned.

§Examples

assert_eq!(5usize.overflowing_sub(2), (3,false));assert_eq!(0usize.overflowing_sub(1), (usize::MAX,true));

Calculatesself −rhs −borrow and returns a tuplecontaining the difference and the output borrow.

Performs “ternary subtraction” by subtracting both an integeroperand and a borrow-in bit fromself, and returns an outputinteger and a borrow-out bit. This allows chaining together multiplesubtractions to create a wider subtraction, and can be useful forbignum subtraction.

§Examples

//    9    6    (a = 9 × 2^64 + 6)// -  5    7    (b = 5 × 2^64 + 7)// ---------//    3  MAX    (diff = 3 × 2^64 + 2^64 - 1)let(a1, a0): (usize, usize) = (9,6);let(b1, b0): (usize, usize) = (5,7);letborrow0 =false;let(diff0, borrow1) = a0.borrowing_sub(b0, borrow0);assert_eq!(borrow1,true);let(diff1, borrow2) = a1.borrowing_sub(b1, borrow1);assert_eq!(borrow2,false);assert_eq!((diff1, diff0), (3, usize::MAX));

Calculatesself -rhs with a signedrhs

Returns a tuple of the subtraction along with a boolean indicatingwhether an arithmetic overflow would occur. If an overflow wouldhave occurred then the wrapped value is returned.

§Examples

assert_eq!(1usize.overflowing_sub_signed(2), (usize::MAX,true));assert_eq!(1usize.overflowing_sub_signed(-2), (3,false));assert_eq!((usize::MAX -2).overflowing_sub_signed(-4), (1,true));

Computes the absolute difference betweenself andother.

§Examples

assert_eq!(100usize.abs_diff(80),20usize);assert_eq!(100usize.abs_diff(110),10usize);

Calculates the multiplication ofself andrhs.

Returns a tuple of the multiplication along with a booleanindicating whether an arithmetic overflow would occur. If anoverflow would have occurred then the wrapped value is returned.

If you want thevalue of the overflow, rather than justwhetheran overflow occurred, seeSelf::carrying_mul.

§Examples

Please note that this example is shared among integer types, which is whyu32 is used.

assert_eq!(5u32.overflowing_mul(2), (10,false));assert_eq!(1_000_000_000u32.overflowing_mul(10), (1410065408,true));

Calculates the complete double-width productself * rhs.

This returns the low-order (wrapping) bits and the high-order (overflow) bitsof the result as two separate values, in that order. As such,a.widening_mul(b).0 produces the same result asa.wrapping_mul(b).

If you also need to add a value and carry to the wide result, then you wantSelf::carrying_mul_add instead.

If you also need to add a carry to the wide result, then you wantSelf::carrying_mul instead.

If you just want to knowwhether the multiplication overflowed, then youwantSelf::overflowing_mul instead.

§Examples

#![feature(bigint_helper_methods)]assert_eq!(5_usize.widening_mul(7), (35,0));assert_eq!(usize::MAX.widening_mul(usize::MAX), (1, usize::MAX -1));

Compared to other*_mul methods:

#![feature(bigint_helper_methods)]assert_eq!(usize::widening_mul(1<<63,6), (0,3));assert_eq!(usize::overflowing_mul(1<<63,6), (0,true));assert_eq!(usize::wrapping_mul(1<<63,6),0);assert_eq!(usize::checked_mul(1<<63,6),None);

Please note that this example is shared among integer types, which is whyu32 is used.

#![feature(bigint_helper_methods)]assert_eq!(5u32.widening_mul(2), (10,0));assert_eq!(1_000_000_000u32.widening_mul(10), (1410065408,2));

Calculates the “full multiplication”self * rhs + carrywithout the possibility to overflow.

This returns the low-order (wrapping) bits and the high-order (overflow) bitsof the result as two separate values, in that order.

Performs “long multiplication” which takes in an extra amount to add, and may return anadditional amount of overflow. This allows for chaining together multiplemultiplications to create “big integers” which represent larger values.

If you also need to add a value, then useSelf::carrying_mul_add.

§Examples

Please note that this example is shared among integer types, which is whyu32 is used.

assert_eq!(5u32.carrying_mul(2,0), (10,0));assert_eq!(5u32.carrying_mul(2,10), (20,0));assert_eq!(1_000_000_000u32.carrying_mul(10,0), (1410065408,2));assert_eq!(1_000_000_000u32.carrying_mul(10,10), (1410065418,2));assert_eq!(usize::MAX.carrying_mul(usize::MAX, usize::MAX), (0, usize::MAX));

This is the core operation needed for scalar multiplication whenimplementing it for wider-than-native types.

#![feature(bigint_helper_methods)]fnscalar_mul_eq(little_endian_digits:&mutVec<u16>, multiplicand: u16) {letmutcarry =0;fordinlittle_endian_digits.iter_mut() {        (*d, carry) = d.carrying_mul(multiplicand, carry);    }ifcarry !=0{        little_endian_digits.push(carry);    }}letmutv =vec![10,20];scalar_mul_eq(&mutv,3);assert_eq!(v, [30,60]);assert_eq!(0x87654321_u64*0xFEED,0x86D3D159E38D);letmutv =vec![0x4321,0x8765];scalar_mul_eq(&mutv,0xFEED);assert_eq!(v, [0xE38D,0xD159,0x86D3]);

Ifcarry is zero, this is similar tooverflowing_mul,except that it gives the value of the overflow instead of just whether one happened:

#![feature(bigint_helper_methods)]letr = u8::carrying_mul(7,13,0);assert_eq!((r.0, r.1!=0), u8::overflowing_mul(7,13));letr = u8::carrying_mul(13,42,0);assert_eq!((r.0, r.1!=0), u8::overflowing_mul(13,42));

The value of the first field in the returned tuple matches what you’d getby combining thewrapping_mul andwrapping_add methods:

#![feature(bigint_helper_methods)]assert_eq!(789_u16.carrying_mul(456,123).0,789_u16.wrapping_mul(456).wrapping_add(123),);

Calculates the “full multiplication”self * rhs + carry + add.

This returns the low-order (wrapping) bits and the high-order (overflow) bitsof the result as two separate values, in that order.

This cannot overflow, as the double-width result has exactly enoughspace for the largest possible result. This is equivalent to how, indecimal, 9 × 9 + 9 + 9 = 81 + 18 = 99 = 9×10⁰ + 9×10¹ = 10² - 1.

Performs “long multiplication” which takes in an extra amount to add, and may return anadditional amount of overflow. This allows for chaining together multiplemultiplications to create “big integers” which represent larger values.

If you don’t need theadd part, then you can useSelf::carrying_mul instead.

§Examples

Please note that this example is shared between integer types,which explains whyu32 is used here.

assert_eq!(5u32.carrying_mul_add(2,0,0), (10,0));assert_eq!(5u32.carrying_mul_add(2,10,10), (30,0));assert_eq!(1_000_000_000u32.carrying_mul_add(10,0,0), (1410065408,2));assert_eq!(1_000_000_000u32.carrying_mul_add(10,10,10), (1410065428,2));assert_eq!(usize::MAX.carrying_mul_add(usize::MAX, usize::MAX, usize::MAX), (usize::MAX, usize::MAX));

This is the core per-digit operation for “grade school” O(n²) multiplication.

Please note that this example is shared between integer types,usingu8 for simplicity of the demonstration.

fnquadratic_mul<constN: usize>(a: [u8; N], b: [u8; N]) -> [u8; N] {letmutout = [0; N];forjin0..N {letmutcarry =0;foriin0..(N - j) {            (out[j + i], carry) = u8::carrying_mul_add(a[i], b[j], out[j + i], carry);        }    }    out}// -1 * -1 == 1assert_eq!(quadratic_mul([0xFF;3], [0xFF;3]), [1,0,0]);assert_eq!(u32::wrapping_mul(0x9e3779b9,0x7f4a7c15),0xcffc982d);assert_eq!(    quadratic_mul(u32::to_le_bytes(0x9e3779b9), u32::to_le_bytes(0x7f4a7c15)),    u32::to_le_bytes(0xcffc982d));

Calculates the divisor whenself is divided byrhs.

Returns a tuple of the divisor along with a boolean indicatingwhether an arithmetic overflow would occur. Note that for unsignedintegers overflow never occurs, so the second value is alwaysfalse.

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(5usize.overflowing_div(2), (2,false));

Calculates the quotient of Euclidean divisionself.div_euclid(rhs).

Returns a tuple of the divisor along with a boolean indicatingwhether an arithmetic overflow would occur. Note that for unsignedintegers overflow never occurs, so the second value is alwaysfalse.Since, for the positive integers, all commondefinitions of division are equal, thisis exactly equal toself.overflowing_div(rhs).

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(5usize.overflowing_div_euclid(2), (2,false));

Calculates the remainder whenself is divided byrhs.

Returns a tuple of the remainder after dividing along with a booleanindicating whether an arithmetic overflow would occur. Note that forunsigned integers overflow never occurs, so the second value isalwaysfalse.

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(5usize.overflowing_rem(2), (1,false));

Calculates the remainderself.rem_euclid(rhs) as if by Euclidean division.

Returns a tuple of the modulo after dividing along with a booleanindicating whether an arithmetic overflow would occur. Note that forunsigned integers overflow never occurs, so the second value isalwaysfalse.Since, for the positive integers, all commondefinitions of division are equal, this operationis exactly equal toself.overflowing_rem(rhs).

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(5usize.overflowing_rem_euclid(2), (1,false));

Negates self in an overflowing fashion.

Returns!self + 1 using wrapping operations to return the valuethat represents the negation of this unsigned value. Note that forpositive unsigned values overflow always occurs, but negating 0 doesnot overflow.

§Examples

assert_eq!(0usize.overflowing_neg(), (0,false));assert_eq!(2usize.overflowing_neg(), (-2i32asusize,true));

Shifts self left byrhs bits.

Returns a tuple of the shifted version of self along with a booleanindicating whether the shift value was larger than or equal to thenumber of bits. If the shift value is too large, then value ismasked (N-1) where N is the number of bits, and this value is thenused to perform the shift.

§Examples

assert_eq!(0x1usize.overflowing_shl(4), (0x10,false));assert_eq!(0x1usize.overflowing_shl(132), (0x10,true));assert_eq!(0x10usize.overflowing_shl(63), (0,false));

Shifts self right byrhs bits.

Returns a tuple of the shifted version of self along with a booleanindicating whether the shift value was larger than or equal to thenumber of bits. If the shift value is too large, then value ismasked (N-1) where N is the number of bits, and this value is thenused to perform the shift.

§Examples

assert_eq!(0x10usize.overflowing_shr(4), (0x1,false));assert_eq!(0x10usize.overflowing_shr(132), (0x1,true));

Raises self to the power ofexp, using exponentiation by squaring.

Returns a tuple of the exponentiation along with a bool indicatingwhether an overflow happened.

§Examples

assert_eq!(3usize.overflowing_pow(5), (243,false));assert_eq!(0_usize.overflowing_pow(0), (1,false));assert_eq!(3u8.overflowing_pow(6), (217,true));

Raises self to the power ofexp, using exponentiation by squaring.

§Examples

assert_eq!(2usize.pow(5),32);assert_eq!(0_usize.pow(0),1);

Returns the square root of the number, rounded down.

§Examples

assert_eq!(10usize.isqrt(),3);

Performs Euclidean division.

Since, for the positive integers, all commondefinitions of division are equal, thisis exactly equal toself / rhs.

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(7usize.div_euclid(4),1);// or any other integer type

Calculates the least remainder ofself (mod rhs).

Since, for the positive integers, all commondefinitions of division are equal, thisis exactly equal toself % rhs.

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(7usize.rem_euclid(4),3);// or any other integer type

Calculates the quotient ofself andrhs, rounding the result towards negative infinity.

This is the same as performingself / rhs for all unsigned integers.

§Panics

This function will panic ifrhs is zero.

§Examples

#![feature(int_roundings)]assert_eq!(7_usize.div_floor(4),1);

Calculates the quotient ofself andrhs, rounding the result towards positive infinity.

§Panics

This function will panic ifrhs is zero.

§Examples

assert_eq!(7_usize.div_ceil(4),2);

Calculates the smallest value greater than or equal toself thatis a multiple ofrhs.

§Panics

This function will panic ifrhs is zero.

§Overflow behavior

On overflow, this function will panic if overflow checks are enabled (default in debugmode) and wrap if overflow checks are disabled (default in release mode).

§Examples

assert_eq!(16_usize.next_multiple_of(8),16);assert_eq!(23_usize.next_multiple_of(8),24);

Calculates the smallest value greater than or equal toself thatis a multiple ofrhs. ReturnsNone ifrhs is zero or theoperation would result in overflow.

§Examples

assert_eq!(16_usize.checked_next_multiple_of(8),Some(16));assert_eq!(23_usize.checked_next_multiple_of(8),Some(24));assert_eq!(1_usize.checked_next_multiple_of(0),None);assert_eq!(usize::MAX.checked_next_multiple_of(2),None);

Returnstrue ifself is an integer multiple ofrhs, and false otherwise.

This function is equivalent toself % rhs == 0, except that it will not panicforrhs == 0. Instead,0.is_multiple_of(0) == true, and for any non-zeron,n.is_multiple_of(0) == false.

§Examples

assert!(6_usize.is_multiple_of(2));assert!(!5_usize.is_multiple_of(2));assert!(0_usize.is_multiple_of(0));assert!(!6_usize.is_multiple_of(0));

Returnstrue if and only ifself == 2^k for some unsigned integerk.

§Examples

assert!(16usize.is_power_of_two());assert!(!10usize.is_power_of_two());

Returns the smallest power of two greater than or equal toself.

When return value overflows (i.e.,self > (1 << (N-1)) for typeuN), it panics in debug mode and the return value is wrapped to 0 inrelease mode (the only situation in which this method can return 0).

§Examples

assert_eq!(2usize.next_power_of_two(),2);assert_eq!(3usize.next_power_of_two(),4);assert_eq!(0usize.next_power_of_two(),1);

Returns the smallest power of two greater than or equal toself. Ifthe next power of two is greater than the type’s maximum value,None is returned, otherwise the power of two is wrapped inSome.

§Examples

assert_eq!(2usize.checked_next_power_of_two(),Some(2));assert_eq!(3usize.checked_next_power_of_two(),Some(4));assert_eq!(usize::MAX.checked_next_power_of_two(),None);

Returns the smallest power of two greater than or equal ton. Ifthe next power of two is greater than the type’s maximum value,the return value is wrapped to0.

§Examples

#![feature(wrapping_next_power_of_two)]assert_eq!(2usize.wrapping_next_power_of_two(),2);assert_eq!(3usize.wrapping_next_power_of_two(),4);assert_eq!(usize::MAX.wrapping_next_power_of_two(),0);

Returns the memory representation of this integer as a byte array inbig-endian (network) byte order.

Note: This function returns an array of length 2, 4 or 8 bytesdepending on the target pointer size.

§Examples

letbytes =0x1234567890123456usize.to_be_bytes();assert_eq!(bytes, [0x12,0x34,0x56,0x78,0x90,0x12,0x34,0x56]);

Returns the memory representation of this integer as a byte array inlittle-endian byte order.

Note: This function returns an array of length 2, 4 or 8 bytesdepending on the target pointer size.

§Examples

letbytes =0x1234567890123456usize.to_le_bytes();assert_eq!(bytes, [0x56,0x34,0x12,0x90,0x78,0x56,0x34,0x12]);

Returns the memory representation of this integer as a byte array innative byte order.

As the target platform’s native endianness is used, portable codeshould useto_be_bytes orto_le_bytes, as appropriate,instead.

Note: This function returns an array of length 2, 4 or 8 bytesdepending on the target pointer size.

§Examples

letbytes =0x1234567890123456usize.to_ne_bytes();assert_eq!(    bytes,ifcfg!(target_endian ="big") {        [0x12,0x34,0x56,0x78,0x90,0x12,0x34,0x56]    }else{        [0x56,0x34,0x12,0x90,0x78,0x56,0x34,0x12]    });

Creates a native endian integer value from its representationas a byte array in big endian.

Note: This function takes an array of length 2, 4 or 8 bytesdepending on the target pointer size.

§Examples

letvalue = usize::from_be_bytes([0x12,0x34,0x56,0x78,0x90,0x12,0x34,0x56]);assert_eq!(value,0x1234567890123456);

When starting from a slice rather than an array, fallible conversion APIs can be used:

fnread_be_usize(input:&mut &[u8]) -> usize {let(int_bytes, rest) = input.split_at(size_of::<usize>());*input = rest;    usize::from_be_bytes(int_bytes.try_into().unwrap())}

Creates a native endian integer value from its representationas a byte array in little endian.

Note: This function takes an array of length 2, 4 or 8 bytesdepending on the target pointer size.

§Examples

letvalue = usize::from_le_bytes([0x56,0x34,0x12,0x90,0x78,0x56,0x34,0x12]);assert_eq!(value,0x1234567890123456);

When starting from a slice rather than an array, fallible conversion APIs can be used:

fnread_le_usize(input:&mut &[u8]) -> usize {let(int_bytes, rest) = input.split_at(size_of::<usize>());*input = rest;    usize::from_le_bytes(int_bytes.try_into().unwrap())}

Creates a native endian integer value from its memory representationas a byte array in native endianness.

As the target platform’s native endianness is used, portable codelikely wants to usefrom_be_bytes orfrom_le_bytes, asappropriate instead.

Note: This function takes an array of length 2, 4 or 8 bytesdepending on the target pointer size.

§Examples

letvalue = usize::from_ne_bytes(ifcfg!(target_endian ="big") {    [0x12,0x34,0x56,0x78,0x90,0x12,0x34,0x56]}else{    [0x56,0x34,0x12,0x90,0x78,0x56,0x34,0x12]});assert_eq!(value,0x1234567890123456);

When starting from a slice rather than an array, fallible conversion APIs can be used:

fnread_ne_usize(input:&mut &[u8]) -> usize {let(int_bytes, rest) = input.split_at(size_of::<usize>());*input = rest;    usize::from_ne_bytes(int_bytes.try_into().unwrap())}

New code should prefer to useusize::MIN instead.

Returns the smallest value that can be represented by this integer type.

New code should prefer to useusize::MAX instead.

Returns the largest value that can be represented by this integer type.

Calculates the midpoint (average) betweenself andrhs.

midpoint(a, b) is(a + b) / 2 as if it were performed in asufficiently-large unsigned integral type. This implies that the result isalways rounded towards zero and that no overflow will ever occur.

§Examples

assert_eq!(0usize.midpoint(4),2);assert_eq!(1usize.midpoint(4),2);

Parses an integer from a string slice with digits in a given base.

The string is expected to be an optional+sign followed by only digits. Leading and trailing non-digit characters (includingwhitespace) represent an error. Underscores (which are accepted in Rust literals)also represent an error.

Digits are a subset of these characters, depending onradix:

• 0-9
• a-z
• A-Z

§Panics

This function panics ifradix is not in the range from 2 to 36.

§See also

If the string to be parsed is in base 10 (decimal),from_str orstr::parse can also be used.

§Examples

assert_eq!(usize::from_str_radix("A",16),Ok(10));

Trailing space returns error:

assert!(usize::from_str_radix("1 ",10).is_err());

Parses an integer from an ASCII-byte slice with decimal digits.

The characters are expected to be an optional+sign followed by only digits. Leading and trailing non-digit characters (includingwhitespace) represent an error. Underscores (which are accepted in Rust literals)also represent an error.

§Examples

#![feature(int_from_ascii)]assert_eq!(usize::from_ascii(b"+10"),Ok(10));

Trailing space returns error:

assert!(usize::from_ascii(b"1 ").is_err());

Parses an integer from an ASCII-byte slice with digits in a given base.

The characters are expected to be an optional+sign followed by only digits. Leading and trailing non-digit characters (includingwhitespace) represent an error. Underscores (which are accepted in Rust literals)also represent an error.

Digits are a subset of these characters, depending onradix:

• 0-9
• a-z
• A-Z

§Panics

This function panics ifradix is not in the range from 2 to 36.

§Examples

#![feature(int_from_ascii)]assert_eq!(usize::from_ascii_radix(b"A",16),Ok(10));

Trailing space returns error:

assert!(usize::from_ascii_radix(b"1 ",10).is_err());

Allows users to write an integer (in signed decimal format) into a variablebuf oftypeNumBuffer that is passed by the caller by mutable reference.

§Examples

#![feature(int_format_into)]usecore::fmt::NumBuffer;letn =0usize;letmutbuf = NumBuffer::new();assert_eq!(n.format_into(&mutbuf),"0");letn1 =32usize;assert_eq!(n1.format_into(&mutbuf),"32");letn2 = usize :: MAX;assert_eq!(n2.format_into(&mutbuf), usize :: MAX.to_string());

Format unsigned integers in the radix.

Returns the default value of0

Same asself / other.get(), but becauseother is aNonZero<_>,there’s never a runtime check for division-by-zero.

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

Same asself /= other.get(), but becauseother is aNonZero<_>,there’s never a runtime check for division-by-zero.

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

Converts abool tousize losslessly.The resulting value is0 forfalse and1 fortrue values.

§Examples

assert_eq!(usize::from(true),1);assert_eq!(usize::from(false),0);

Convertsu16 tousize losslessly.

Convertsu8 tousize losslessly.

Converts anusize into anAtomicUsize.

Parses an integer from a string slice with decimal digits.

The characters are expected to be an optional+sign followed by only digits. Leading and trailing non-digit characters (includingwhitespace) represent an error. Underscores (which are accepted in Rust literals)also represent an error.

§See also

For parsing numbers in other bases, such as binary or hexadecimal,seefrom_str_radix.

§Examples

usestd::str::FromStr;assert_eq!(usize::from_str("+10"),Ok(10));

Trailing space returns error:

assert!(usize::from_str("1 ").is_err());

Format unsigned integers in the radix.

Format unsigned integers in the radix.