Struct canadensis_bit_length_set::BitLengthSet

pub struct BitLengthSet { /* private fields */ }

A non-empty set of possible lengths (in bits) for a data type

This is based on the Python version: https://github.com/UAVCAN/pydsdl/blob/master/pydsdl/_bit_length_set/_bit_length_set.py

Implementations

impl BitLengthSet

pub fn single(length: u64) -> BitLengthSet

Creates a bit length set with one length value in bits

pub fn from_lengths<I>(values: I) -> Option<BitLengthSet> where
    I: IntoIterator<Item = u64>, 

Creates a bit length set from an iterator of possible length values

If the provided iterator does not yield any elements, this function returns None.

pub fn from_length_set(values: BTreeSet<u64>) -> Option<BitLengthSet>

Creates a bit length set from a set of possible length values

If the provided set is empty, this function returns None.

pub fn min_value(&self) -> u64

Returns the minimum length value in this set

Examples

let lengths = BitLengthSet::single(37);
assert_eq!(37, lengths.min_value());

let lengths = BitLengthSet::from_lengths([1, 10, 30]).unwrap();
assert_eq!(1, lengths.min_value());

pub fn max_value(&self) -> u64

Returns the maximum length value in this set

Examples

let lengths = BitLengthSet::single(37);
assert_eq!(37, lengths.max_value());

let lengths = BitLengthSet::from_lengths([1, 10, 30]).unwrap();
assert_eq!(30, lengths.max_value());

pub fn is_fixed_size(&self) -> bool

Returns true if this set’s minimum and maximum values are equal

Examples

let lengths = BitLengthSet::single(37);
assert!(lengths.is_fixed_size());

let lengths = BitLengthSet::from_lengths([1, 10, 30]).unwrap();
assert!(!lengths.is_fixed_size());

pub fn is_byte_aligned(&self) -> bool

Returns true if all values in this set are aligned to multiples of 8 bits

Examples

assert!(BitLengthSet::single(0).is_byte_aligned());
assert!(BitLengthSet::single(8).is_byte_aligned());
assert!(BitLengthSet::single(16).is_byte_aligned());

assert!(!BitLengthSet::single(1).is_byte_aligned());
assert!(!BitLengthSet::single(2).is_byte_aligned());
assert!(!BitLengthSet::single(4).is_byte_aligned());
assert!(!BitLengthSet::single(7).is_byte_aligned());

assert!(!BitLengthSet::from_lengths([0, 1, 8, 16, 24]).unwrap().is_byte_aligned());
assert!(!BitLengthSet::from_lengths([8, 9]).unwrap().is_byte_aligned());

assert!(BitLengthSet::from_lengths([0, 8, 16, 24]).unwrap().is_byte_aligned());
assert!(BitLengthSet::from_lengths([8, 16]).unwrap().is_byte_aligned());

pub fn is_aligned(&self, bit_length: u64) -> bool

Returns true if all values in this set are aligned to multiples of the specified number of bits

Examples

assert!(BitLengthSet::from_lengths([0, 3, 6, 15]).unwrap().is_aligned(3));
assert!(!BitLengthSet::from_lengths([0, 3, 6, 16]).unwrap().is_aligned(3));

assert!(BitLengthSet::from_lengths([0, 17, 34, 68]).unwrap().is_aligned(17));
assert!(!BitLengthSet::from_lengths([0, 17, 34, 64]).unwrap().is_aligned(17));

pub fn expand(&self) -> BTreeSet<u64>

Expands this bit length set and returns a set with all enclosed values

For some bit length sets, especially when large sets are concatenated, this may be slow.

Examples

let lengths1 = BitLengthSet::from_lengths([0, 8, 24, 96]).unwrap();
let lengths2 = BitLengthSet::from_lengths([1, 2, 8]).unwrap();

let union = lengths1.unite([lengths2]);
let expanded_union = union.expand();

let expected: BTreeSet<u64> = [0, 1, 2, 8, 24, 96].iter().copied().collect();
assert_eq!(expected, expanded_union);

pub fn pad_to_alignment(self, alignment: u32) -> BitLengthSet

Converts this bit length set into a new set that aligns up all its values to a multiple of the given alignment

Examples

let lengths = BitLengthSet::from_lengths([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]).unwrap();
let padded = lengths.pad_to_alignment(8);

let expected = BitLengthSet::from_lengths([0, 8, 16]).unwrap();
assert_eq!(padded.expand(), expected.expand());

pub fn repeat(self, count: u64) -> BitLengthSet

Converts this bit length set into a new set that represents a repetition of these values a fixed number of times

Examples

Single length

let length = BitLengthSet::single(12);
let repeated = length.repeat(4);

let expected = BitLengthSet::single(12 * 4);
assert_eq!(repeated.expand(), expected.expand());

Multiple lengths

let lengths = BitLengthSet::from_lengths([0, 1, 8]).unwrap();
let repeated = lengths.repeat(4);

let expected = BitLengthSet::from_lengths(
    [0, 1, 2, 3, 4, 8, 9, 10, 11, 16, 17, 18, 24, 25, 32]
).unwrap();
assert_eq!(repeated.expand(), expected.expand());

pub fn repeat_range(self, count: RangeToInclusive<u64>) -> BitLengthSet

Converts this bit length set into a new set that represents a repetition of these values zero times up to an inclusive maximum count

Examples

Single length

let lengths = BitLengthSet::single(3);
let repeated = lengths.repeat_range(..=8);

let expected = BitLengthSet::from_lengths([0, 3, 6, 9, 12, 15, 18, 21, 24]).unwrap();
assert_eq!(repeated.expand(), expected.expand());

Multiple lengths

let lengths = BitLengthSet::from_lengths([1, 2, 4]).unwrap();
let repeated = lengths.repeat_range(..=2);

let expected = BitLengthSet::from_lengths([0, 1, 2, 3, 4, 5, 6, 8]).unwrap();
assert_eq!(repeated.expand(), expected.expand());

pub fn concatenate<I>(self, others: I) -> BitLengthSet where
    I: IntoIterator<Item = BitLengthSet>, 

Extends this bit length set, so that this set represents a concatenation of this set followed by other sets

Examples

let combined = bit_length![0, 8].concatenate([bit_length![12]]);
let expected = bit_length![12, 20];
assert_eq!(combined.expand(), expected.expand());

let combined = bit_length![0, 1, 3].concatenate([bit_length![5, 13]]);
let expected = bit_length![5, 6, 8, 13, 14, 16];
assert_eq!(combined.expand(), expected.expand());

pub fn unite<I>(self, others: I) -> BitLengthSet where
    I: IntoIterator<Item = BitLengthSet>, 

Converts this bit length set into a new set that is the union of this set and the provided other sets

This is uses to represent a union (or enum in Rust)

Examples

let combined = bit_length![0, 1, 3, 24].unite([bit_length![3, 8]]);
let expected = bit_length![0, 1, 3, 8, 24];
assert_eq!(combined.expand(), expected.expand());

pub fn validate_numerically(&self)

Checks that the expanded form of this set has the same properties as calculated based on the internal representation of this set

Trait Implementations

impl Clone for BitLengthSet

fn clone(&self) -> BitLengthSet

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for BitLengthSet

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

Formats the value using the given formatter.

impl Default for BitLengthSet

fn default() -> Self

Returns the default bit length set, which contains the value 0

impl Extend<BitLengthSet> for BitLengthSet

fn extend<T: IntoIterator<Item = BitLengthSet>>(&mut self, iter: T)

Extends this bit length set, so that this set represents a concatenation of this set followed by other sets

This is equivalent to concatenate.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl Ord for BitLengthSet

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<BitLengthSet> for BitLengthSet

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialOrd<BitLengthSet> for BitLengthSet

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Rem<u64> for BitLengthSet

fn rem(self, rhs: u64) -> Self::Output

Calculates the elementwise modulo of each value in this set

type Output = BitLengthSet

The resulting type after applying the % operator.

impl Rem<u64> for &BitLengthSet

fn rem(self, rhs: u64) -> Self::Output

Calculates the elementwise modulo of each value in this set

Examples

assert_eq!((bit_length![0] % 12345).expand(), bit_length![0].expand());
assert_eq!((bit_length![34] % 17).expand(), bit_length![0].expand());
assert_eq!((bit_length![8, 12, 16] % 8).expand(), bit_length![0, 4].expand());
assert_eq!((bit_length![0, 3, 8, 9, 27] % 8).expand(), bit_length![0, 1, 3].expand());

type Output = BitLengthSet

The resulting type after applying the % operator.

impl Eq for BitLengthSet