Struct NumberWithBase

pub struct NumberWithBase {
    number: U256,
    is_nonnegative: bool,
    base: Base,
}

Utility struct for parsing numbers and formatting them into different bases.

Example

use cast::base::NumberWithBase;
use alloy_primitives::U256;

let number: NumberWithBase = U256::from(12345).into();
assert_eq!(number.format(), "12345");

// Debug uses number.base() to determine which base to format to, which defaults to Base::Decimal
assert_eq!(format!("{:?}", number), "12345");

// Display uses Base::Decimal
assert_eq!(format!("{}", number), "12345");

// The alternate formatter ("#") prepends the base's prefix
assert_eq!(format!("{:x}", number), "3039");
assert_eq!(format!("{:#x}", number), "0x3039");

assert_eq!(format!("{:b}", number), "11000000111001");
assert_eq!(format!("{:#b}", number), "0b11000000111001");

assert_eq!(format!("{:o}", number), "30071");
assert_eq!(format!("{:#o}", number), "0o30071");

Fields

number: U256

The number.

is_nonnegative: bool

Whether the number is positive or zero.

base: Base

The base to format to.

Implementations

impl NumberWithBase

pub fn new(number: impl Into<U256>, is_nonnegative: bool, base: Base) -> Self

pub fn with_base(&self, base: Base) -> Self

Creates a copy of the number with the provided base.

pub fn parse_int(s: &str, base: Option<&str>) -> Result<Self>

Parses a string slice into a signed integer. If base is None then it tries to determine base from the prefix, otherwise defaults to Decimal.

pub fn parse_uint(s: &str, base: Option<&str>) -> Result<Self>

Parses a string slice into an unsigned integer. If base is None then it tries to determine base from the prefix, otherwise defaults to Decimal.

pub fn number(&self) -> U256

Returns a copy of the underlying number as an unsigned integer. If the value is negative then the two’s complement of its absolute value will be returned.

pub fn is_nonnegative(&self) -> bool

Returns whether the underlying number is positive or zero.

pub fn base(&self) -> Base

Returns the underlying base. Defaults to Decimal.

pub const fn prefix(&self) -> &str

Returns the Rust standard prefix for the base.

pub fn set_base(&mut self, base: Base) -> &mut Self

Sets the number’s base to format to.

pub fn format(&self) -> String

Formats the number into the specified base.

Note: this method only formats the number into the base, without adding any prefixes, signs or padding. Refer to the std::fmt module documentation on how to format this number with the aforementioned properties.

fn _parse_int(s: &str, base: Base) -> Result<(U256, bool)>

fn _parse_uint(s: &str, base: Base) -> Result<U256>

Methods from Deref<Target = U256>

pub fn to_base_le(&self, base: u64) -> impl Iterator<Item = u64>

Returns an iterator over the base base digits of the number in little-endian order.

Pro tip: instead of setting base = 10, set it to the highest power of 10 that still fits u64. This way much fewer iterations are required to extract all the digits.

Panics

Panics if the base is less than 2.

pub fn to_base_be(&self, base: u64) -> impl Iterator<Item = u64>

Available on crate feature alloc only.

Returns an iterator over the base base digits of the number in big-endian order.

Pro tip: instead of setting base = 10, set it to the highest power of 10 that still fits u64. This way much fewer iterations are required to extract all the digits.

Panics

Panics if the base is less than 2.

pub fn bit(&self, index: usize) -> bool

Returns whether a specific bit is set.

Returns false if index exceeds the bit width of the number.

pub fn byte(&self, index: usize) -> u8

Returns a specific byte. The byte at index 0 is the least significant byte (little endian).

Panics

Panics if index exceeds the byte width of the number.

Examples

let x = uint!(0x1234567890_U64);
let bytes = [
    x.byte(0), // 0x90
    x.byte(1), // 0x78
    x.byte(2), // 0x56
    x.byte(3), // 0x34
    x.byte(4), // 0x12
    x.byte(5), // 0x00
    x.byte(6), // 0x00
    x.byte(7), // 0x00
];
assert_eq!(bytes, x.to_le_bytes());

Panics if out of range.

let x = uint!(0x1234567890_U64);
let _ = x.byte(8);

pub fn leading_zeros(&self) -> usize

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

pub fn leading_ones(&self) -> usize

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

pub fn trailing_zeros(&self) -> usize

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

pub fn trailing_ones(&self) -> usize

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

pub fn count_ones(&self) -> usize

Returns the number of ones in the binary representation of self.

pub fn count_zeros(&self) -> usize

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

pub fn bit_len(&self) -> usize

Length of the number in bits ignoring leading zeros.

pub fn byte_len(&self) -> usize

Length of the number in bytes ignoring leading zeros.

pub fn most_significant_bits(&self) -> (u64, usize)

Returns the most significant 64 bits of the number and the exponent.

Given return value $(\mathtt{bits}, \mathtt{exponent})$, the self can be approximated as

$$ \mathtt{self} ≈ \mathtt{bits} ⋅ 2^\mathtt{exponent} $$

If self is $<≥> 2^{63}$, then exponent will be zero and bits will have leading zeros.

pub const BYTES: usize = _

pub fn as_le_slice(&self) -> &[u8]

Available on little-endian only.

Access the underlying store as a little-endian slice of bytes.

Only available on little-endian targets.

If BITS does not evenly divide 8, it is padded with zero bits in the most significant position.

pub fn as_le_bytes(&self) -> Cow<'_, [u8]>

Available on crate feature alloc only.

Access the underlying store as a little-endian bytes.

Uses an optimized implementation on little-endian targets.

pub fn as_le_bytes_trimmed(&self) -> Cow<'_, [u8]>

Available on crate feature alloc only.

Access the underlying store as a little-endian bytes with trailing zeros removed.

Uses an optimized implementation on little-endian targets.

pub fn to_le_bytes<const BYTES: usize>(&self) -> [u8; BYTES]

Converts the Uint to a little-endian byte array of size exactly Self::BYTES.

Panics

Panics if the generic parameter BYTES is not exactly Self::BYTES. Ideally this would be a compile time error, but this is blocked by Rust issue #60551.

pub fn to_le_bytes_vec(&self) -> Vec<u8>

Available on crate feature alloc only.

Converts the Uint to a little-endian byte vector of size exactly Self::BYTES.

This method is useful when Self::to_le_bytes can not be used because byte size is not known compile time.

pub fn to_le_bytes_trimmed_vec(&self) -> Vec<u8>

Available on crate feature alloc only.

Converts the Uint to a little-endian byte vector with trailing zeros bytes removed.

pub fn to_be_bytes<const BYTES: usize>(&self) -> [u8; BYTES]

Converts the Uint to a big-endian byte array of size exactly Self::BYTES.

Panics

Panics if the generic parameter BYTES is not exactly Self::BYTES. Ideally this would be a compile time error, but this is blocked by Rust issue #60551.

pub fn to_be_bytes_vec(&self) -> Vec<u8>

Available on crate feature alloc only.

Converts the Uint to a big-endian byte vector of size exactly Self::BYTES.

This method is useful when Self::to_be_bytes can not be used because byte size is not known compile time.

pub fn to_be_bytes_trimmed_vec(&self) -> Vec<u8>

Available on crate feature alloc only.

Converts the Uint to a big-endian byte vector with leading zeros bytes removed.

pub fn is_zero(&self) -> bool

Returns true if the value is zero.

pub fn to<T>(&self) -> T

where Uint<BITS, LIMBS>: UintTryTo<T>, T: Debug,

Panics

Panics if the conversion fails, for example if the value is too large for the bit-size of the target type.

Examples

assert_eq!(300_U12.to::<i16>(), 300_i16);
assert_eq!(300_U12.to::<U256>(), 300_U256);

pub fn wrapping_to<T>(&self) -> T

where Uint<BITS, LIMBS>: UintTryTo<T>,

Examples

assert_eq!(300_U12.wrapping_to::<i8>(), 44_i8);
assert_eq!(255_U32.wrapping_to::<i8>(), -1_i8);
assert_eq!(0x1337cafec0d3_U256.wrapping_to::<U32>(), 0xcafec0d3_U32);

pub fn saturating_to<T>(&self) -> T

where Uint<BITS, LIMBS>: UintTryTo<T>,

Examples

assert_eq!(300_U12.saturating_to::<i16>(), 300_i16);
assert_eq!(255_U32.saturating_to::<i8>(), 127);
assert_eq!(0x1337cafec0d3_U256.saturating_to::<U32>(), U32::MAX);

pub const LIMBS: usize = _

pub const MASK: u64 = _

pub const BITS: usize = BITS

pub const ZERO: Uint<BITS, LIMBS> = _

pub const MIN: Uint<BITS, LIMBS> = Self::ZERO

pub const MAX: Uint<BITS, LIMBS> = _

pub fn as_limbs(&self) -> &[u64; LIMBS]

View the array of limbs.

Trait Implementations

impl Binary for NumberWithBase

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl Clone for NumberWithBase

fn clone(&self) -> NumberWithBase

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for NumberWithBase

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl Deref for NumberWithBase

type Target = Uint<256, 4>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Display for NumberWithBase

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl From<NumberWithBase> for I256

fn from(n: NumberWithBase) -> Self

Converts to this type from the input type.

impl From<NumberWithBase> for String

fn from(n: NumberWithBase) -> Self

Formats the number into the specified base. See NumberWithBase::format.

impl From<NumberWithBase> for U256

fn from(n: NumberWithBase) -> Self

Converts to this type from the input type.

impl From<ParseUnits> for NumberWithBase

fn from(value: ParseUnits) -> Self

Converts to this type from the input type.

impl From<Signed<256, 4>> for NumberWithBase

fn from(number: I256) -> Self

Converts to this type from the input type.

impl From<Uint<256, 4>> for NumberWithBase

fn from(number: U256) -> Self

Converts to this type from the input type.

impl FromStr for NumberWithBase

type Err = Report

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl LowerHex for NumberWithBase

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl Octal for NumberWithBase

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl ToBase for NumberWithBase

type Err = Infallible

fn to_base(&self, base: Base, add_prefix: bool) -> Result<String, Self::Err>

Formats self into a base, specifying whether to add the base prefix or not.

impl UpperHex for NumberWithBase

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl Copy for NumberWithBase

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 40 bytes