Struct BitCount

pub struct BitCount<const MAX: u32> { /* private fields */ }

A number of bits to be consumed or written, with a known maximum

Implementations

impl<const MAX: u32> BitCount<MAX>

pub const fn new<const BITS: u32>() -> Self

Builds a bit count from a constant number of bits, which must not be greater than MAX or greater than the largest supported type.

Intended to be used for defining constants.

Use TryFrom to conditionally build counts from values at runtime.

Examples

use bitstream_io::{BitReader, BitRead, BigEndian, BitCount};
let data: &[u8] = &[0b111_00000];
let mut r = BitReader::endian(data, BigEndian);
// reading 3 bits from a stream out of a maximum of 8
// doesn't require checking that the bit count is larger
// than a u8 at runtime because specifying the maximum of 8
// guarantees our bit count will not be larger than 8
assert_eq!(r.read_counted::<8, u8>(BitCount::new::<3>()).unwrap(), 0b111);

use bitstream_io::BitCount;
// trying to build a count of 10 with a maximum of 8
// fails to compile at all
let count = BitCount::<8>::new::<10>();

use bitstream_io::BitCount;
// trying to build a count of 10 with a maximum of 129
// fails to compile at all
let count = BitCount::<129>::new::<10>();

pub const fn checked_add<const NEW_MAX: u32>( self, bits: u32, ) -> Option<BitCount<NEW_MAX>>

Add a number of bits to our count, returning a new count with a new maximum.

Returns None if the new count goes above our new maximum. A compile-time error occurs if NEW_MAX is larger than the largest supported type.

Examples

use bitstream_io::BitCount;

let count = BitCount::<2>::new::<1>();
// adding 2 to 1 and increasing the max to 3 yields a new count of 3
assert_eq!(count.checked_add::<3>(2), Some(BitCount::<3>::new::<3>()));
// adding 2 to 1 without increasing the max yields None
assert_eq!(count.checked_add::<2>(2), None);

use bitstream_io::BitCount;

let count = BitCount::<2>::new::<1>();
// a new maximum of 129 is larger than our largest supported type
let count2 = count.checked_add::<129>(1);

pub const fn checked_sub<const NEW_MAX: u32>(self, bits: u32) -> Option<Self>

Subtracts a number of bits from our count, returning a new count with a new maximum.

Returns None if the new count goes below 0 or below our new maximum. A compile-time error occurs if NEW_MAX is larger than the largest supported type.

Example

use bitstream_io::BitCount;
let count = BitCount::<5>::new::<5>();
// subtracting 1 from 5 yields a new count of 4
assert_eq!(count.checked_sub::<5>(1), Some(BitCount::<5>::new::<4>()));
// subtracting 6 from 5 yields None
assert!(count.checked_sub::<5>(6).is_none());
// subtracting 1 with a new maximum of 3 also yields None
// because 4 is larger than the maximum of 3
assert!(count.checked_sub::<3>(1).is_none());

pub fn try_map<const NEW_MAX: u32, F>(self, f: F) -> Option<BitCount<NEW_MAX>>

where F: FnOnce(u32) -> Option<u32>,

Attempt to convert our count to a count with a new bit count and new maximum.

Returns Some(count) if the updated number of bits is less than or equal to the new maximum. Returns None if not.

A compile-time error occurs if one tries to use a maximum bit count larger than the largest supported type.

Examples

use bitstream_io::BitCount;

let count = BitCount::<5>::new::<5>();
// muliplying 5 bits by 2 with a new max of 10 is ok
assert_eq!(
    count.try_map::<10, _>(|i| i.checked_mul(2)),
    Some(BitCount::<10>::new::<10>()),
);
// multiplying 5 bits by 3 with a new max of 10 overflows
assert_eq!(count.try_map::<10, _>(|i| i.checked_mul(3)), None);

use bitstream_io::BitCount;

// 129 bits is larger than the largest supported type
let count = BitCount::<5>::new::<5>();
let new_count = count.try_map::<129, _>(|i| i).unwrap();

impl BitCount<{ u128::BITS_SIZE }>

pub const fn unknown(bits: u32) -> Self

Builds a bit count where the maximum bits is unknown.

In this case, u128::BITS_SIZE is assumed, because that’s the largest type supported.

Example

use bitstream_io::BitCount;
assert_eq!(BitCount::unknown(5), BitCount::<128>::new::<5>());

Trait Implementations

impl<const MAX: u32> Clone for BitCount<MAX>

fn clone(&self) -> BitCount<MAX>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<const MAX: u32> Debug for BitCount<MAX>

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

Formats the value using the given formatter.

impl<const MAX: u32> From<BitCount<MAX>> for u32

fn from(_: BitCount<MAX>) -> u32

Converts to this type from the input type.

impl<const MAX: u32> Hash for BitCount<MAX>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<const MAX: u32> PartialEq for BitCount<MAX>

fn eq(&self, other: &BitCount<MAX>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<const MAX: u32> TryFrom<u32> for BitCount<MAX>

fn try_from(bits: u32) -> Result<Self, Self::Error>

Attempts to convert a u32 bit count to a BitCount

Attempting a bit maximum bit count larger than the largest supported type is a compile-time error

Examples

use bitstream_io::BitCount;
use std::convert::TryInto;

assert_eq!(8u32.try_into(), Ok(BitCount::<8>::new::<8>()));
assert_eq!(9u32.try_into(), Err::<BitCount<8>, _>(9));

use bitstream_io::BitCount;
use std::convert::TryInto;

// largest bit count is 128
assert_eq!(129u32.try_into(), Err::<BitCount<129>, _>(129));

type Error = u32

The type returned in the event of a conversion error.

impl<const MAX: u32> Copy for BitCount<MAX>

impl<const MAX: u32> Eq for BitCount<MAX>

impl<const MAX: u32> StructuralPartialEq for BitCount<MAX>