Struct Checked

pub struct Checked<C, T> { /* private fields */ }

A type for eliminating redundant validation when writing

Normally, when writing a value, not only must the number of bits must be checked against the type being written (e.g. writing 9 bits from a u8 is always an error), but the value must also be checked against the number of bits (e.g. writing a value of 2 in 1 bit is always an error).

But when the value’s range can be checked in advance, the write-time check can be skipped through the use of the BitWrite::write_checked method.

Implementations

impl<C, T> Checked<C, T>

pub fn into_count_value(self) -> (C, T)

Returns our bit count and value

pub fn into_value(self) -> T

Returns our value

impl<const MAX: u32, U: UnsignedInteger> Checked<BitCount<MAX>, U>

pub fn new( count: impl TryInto<BitCount<MAX>>, value: U, ) -> Result<Self, CheckedError>

Returns our value if it fits in the given number of bits

Example

use bitstream_io::{BitCount, CheckedUnsigned, CheckedError};

// a value of 7 fits into a 3 bit count
assert!(CheckedUnsigned::<8, u8>::new(3, 0b111).is_ok());

// a value of 8 does not fit into a 3 bit count
assert!(matches!(
    CheckedUnsigned::<8, u8>::new(3, 0b1000),
    Err(CheckedError::ExcessiveValue),
));

// a bit count of 9 is too large for u8
assert!(matches!(
    CheckedUnsigned::<9, _>::new(9, 1u8),
    Err(CheckedError::ExcessiveBits),
));

pub fn new_fixed<const BITS: u32>(value: U) -> Result<Self, CheckedError>

Returns our value if it fits in the given number of const bits

Examples

use bitstream_io::{CheckedUnsigned, CheckedError};

// a value of 7 fits into a 3 bit count
assert!(CheckedUnsigned::<8, u8>::new_fixed::<3>(0b111).is_ok());

// a value of 8 does not fit into a 3 bit count
assert!(matches!(
    CheckedUnsigned::<8, u8>::new_fixed::<3>(0b1000),
    Err(CheckedError::ExcessiveValue),
));

use bitstream_io::{BitCount, CheckedUnsigned};

// a bit count of 9 is too large for u8

// because this is checked at compile-time,
// it does not compile at all
let c = CheckedUnsigned::<16, u8>::new_fixed::<9>(1);

impl<const MAX: u32, S: SignedInteger> Checked<SignedBitCount<MAX>, S>

pub fn new( count: impl TryInto<SignedBitCount<MAX>>, value: S, ) -> Result<Self, CheckedError>

Returns our value if it fits in the given number of bits

Example

use bitstream_io::{SignedBitCount, CheckedSigned, CheckedError};

// a value of 3 fits into a 3 bit count
assert!(CheckedSigned::<8, _>::new(3, 3i8).is_ok());

// a value of 4 does not fit into a 3 bit count
assert!(matches!(
    CheckedSigned::<8, _>::new(3, 4i8),
    Err(CheckedError::ExcessiveValue),
));

// a bit count of 9 is too large for i8
assert!(matches!(
    CheckedSigned::<9, _>::new(9, 1i8),
    Err(CheckedError::ExcessiveBits),
));

pub fn new_fixed<const BITS: u32>(value: S) -> Result<Self, CheckedError>

Returns our value if it fits in the given number of const bits

Examples

use bitstream_io::{CheckedSigned, CheckedError};

// a value of 3 fits into a 3 bit count
assert!(CheckedSigned::<8, i8>::new_fixed::<3>(3).is_ok());

// a value of 4 does not fit into a 3 bit count
assert!(matches!(
    CheckedSigned::<8, i8>::new_fixed::<3>(4),
    Err(CheckedError::ExcessiveValue),
));

use bitstream_io::{BitCount, CheckedSigned};

// a bit count of 9 is too large for i8

// because this is checked at compile-time,
// it does not compile at all
let c = CheckedSigned::<16, i8>::new_fixed::<9>(1);

Trait Implementations

impl<C, T> AsRef<T> for Checked<C, T>

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<C: Clone, T: Clone> Clone for Checked<C, T>

fn clone(&self) -> Checked<C, T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<C: Debug, T: Debug> Debug for Checked<C, T>

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

Formats the value using the given formatter.

impl<C: Copy, T: Copy> Copy for Checked<C, T>