Struct PaddedNumber

Source

pub struct PaddedNumber<const A: u8 = 1, const B: u8 = { u8::MAX }> { /* private fields */ }

Expand description

Newtype encapsulating the padded number invariants

Consists only of an u8 and an u64 which keep track of the leading zeros count and the remaining number value respectively.

Check out the crate-level documentation for an introduction.

PaddedNumber uses const generic parameters for setting lower (inclusive) and upper (inclusive) length bounds. These parameters are by default set to 1 and 255 (u8::MAX) respectively.

MIN < MAX allows for variable digit length.
MIN == MAX requires the digit to be exactly of length MIN/MAX.
MIN == 0 results in empty values (“”) being allowed as valid numbers.
MIN > MAX, where MIN, MAX > 0 is technically declarable, but any attempts at constructing such a padded number will fail.

Implementations§

Source §

impl<const A: u8, const B: u8> PaddedNumber<A, B>

Source

pub const fn try_new(str: &str) -> Result<Self, ParsePaddedNumberError>

Create a new PaddedNumber

Source

pub const fn len(&self) -> u8

Calculate the length of the padded number, including any leading zeros

assert_eq!(2, padded_number!("01").len());
assert_eq!(3, padded_number!("123").len());

Source

pub const fn is_empty(&self) -> bool

Check if the number if empty, e.g. if and only if it is "".

assert!(bound_padded_number!(0, 1, "").is_empty());
assert!(!padded_number!("01").is_empty());

Source §

impl<const A: u8, const B: u8> PaddedNumber<A, B>

Source

pub fn wrapping_add(self, rhs: u64) -> Self

Wrapping addition with u64 as right-hand side

Used within the impl Add<u64> for PaddedNumber implementation.

assert_eq!(padded_number!("0") + 1, padded_number!("0").wrapping_add(1));

// Within bounds
assert_eq!(padded_number!("9") + 1, padded_number!("00"));
assert_eq!(padded_number!("80") + 11, padded_number!("91"));

// Wrapped
assert_eq!(
    bound_padded_number!(2, 3, "999") + 2,
    bound_padded_number!(2, 3, "01")
);

Source

pub fn saturating_add(self, rhs: u64) -> Self

Saturating addition with u64 as right-hand side

assert_eq!(
    bound_padded_number!(2, 3, "990").saturating_add(1000),
    bound_padded_number!(2, 3, "999") // saturated
);

Addition within bounds behaves the same as in Self::wrapping_add.

Source

pub fn wrapping_sub(self, rhs: u64) -> Self

Wrapping subtraction with u64 as right-hand side

Used within the impl Sub<u64> for PaddedNumber implementation.

assert_eq!(padded_number!("9") - 1, padded_number!("9").wrapping_sub(1));

// Within bounds
assert_eq!(padded_number!("9") + 1, padded_number!("00"));
assert_eq!(padded_number!("80") + 11, padded_number!("91"));

// Wrapped
assert_eq!(
    bound_padded_number!(2, 3, "999") + 2,
    bound_padded_number!(2, 3, "01")
);

Source

pub fn saturating_sub(self, rhs: u64) -> Self

Saturating subtraction with u64 as right-hand side

assert_eq!(
    bound_padded_number!(1, 2, "99").saturating_sub(1000),
    bound_padded_number!(1, 2, "0") // saturated
);

Subtraction within bounds behaves the same as in Self::wrapping_sub.

Source §

impl<const MIN_LENGTH: u8, const MAX_LENGTH: u8> PaddedNumber<MIN_LENGTH, MAX_LENGTH>

Source

pub fn section<const START_INDEX: u8, const END_INDEX: u8>( &self, ) -> Option<PaddedNumber<{ _ }, { _ }>>
where [(); { _ }]:,

Get a section of a padded number

First generic parameter is the start index, inclusive. Second parameter denotes the end index, exclusive. Remaining bound checks are enforced by the type system. E.g. end >= start and end <= max length.

Returns None if the end index overflowed for a padded whose length is is not equal to it’s max length.

§Examples

#![feature(generic_const_exprs)]

let section = padded_number!("00123")
    .section::<2, 5>()
    .expect("section should not have overflowed");

assert_eq!(section, bound_padded_number!(3, 3, "123"));

let section = bound_padded_number!(1, 3, "0").section::<1, 3>();
// overflowed, missing two digits after "0"
assert!(section.is_none());

#![feature(generic_const_exprs)]

let section = bound_padded_number!(3, 3, "123");
section.section::<0, 4>(); // <-- END_INDEX '4' > MAX_LENGTH '3'

#![feature(generic_const_exprs)]

let section = bound_padded_number!(3, 3, "123");
section.section::<2, 1>(); // <-- END_INDEX '1' < START_INDEX '2'

Source

pub fn expected_section<const START_INDEX: u8, const END_INDEX: u8>( &self, ) -> PaddedNumber<{ _ }, { _ }>
where [(); { _ }]:,

Get a section from the minimum length of a padded number

Unlike PaddedNumber::section, this does not need to return an option. Type system ensures that END_INDEX <= MIN_LENGTH.

§Examples

#![feature(generic_const_exprs)]

let section = bound_padded_number!(3, 5, "00123").expected_section::<0, 3>();
assert_eq!(section, bound_padded_number!(3, 3, "001"));

#![feature(generic_const_exprs)]

let section = bound_padded_number!(3, 5, "00123");
section.expected_section::<0, 4>(); // <-- END_INDEX '4' > MIN_LENGTH '3'