Struct bitfield_layout::BitField

pub struct BitField<M, T> {
    pub value: T,
    // some fields omitted
}

Accessory struct for convinient type construction

This structure holds value of created bitfield type and may be used for types that doesn’t has own value field: enums and unit-like structs.

Enum wrapper

Using enumeration as bitfield type has the following advantage - you can bind bit (flag) to one of enum variants.

 
// Declare new bitfield type
enum EightFlags {
    One,
    Two,
    Three,
    Four,
    OemReserved(u8), // Reserved field referenced to multiple bits
    FutureReserved(u8), // Reserved field referenced to multiple bits
}
// Implement Dispaly trait for basic and alternative views
impl fmt::Display for EightFlags {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match (self, f.alternate()) {
            // Basic view
            (Self::One,   false) => write!(f, "one"),
            (Self::Two,   false) => write!(f, "two"),
            (Self::Three, false) => write!(f, "three"),
            (Self::Four,  false) => write!(f, "four"),
            // Alternative view
            (Self::One,   true)  => write!(f, "ONE"),
            (Self::Two,   true)  => write!(f, "TWO"),
            (Self::Three, true)  => write!(f, "THREE"),
            (Self::Four,  true)  => write!(f, "FOUR"),
            // Reserved fields
            (Self::OemReserved(v), _) => write!(f, "OEM reserved (#{})", v),
            (Self::FutureReserved(v), _) => write!(f, "Reserved for future usage (#{})", v),
        }
    }
}
// Implement constant bit layout for this type
impl EightFlags {
    const LAYOUT: [Self; 8] = [
        Self::One,
        Self::Two,
        Self::Three,
        Self::Four,
        Self::OemReserved(4),
        Self::OemReserved(5),
        Self::FutureReserved(6),
        Self::FutureReserved(7),
    ];
}
// Implement Layout for enum created early
impl Layout for EightFlags {
    type Layout = std::slice::Iter<'static, EightFlags>;
    fn layout() -> Self::Layout { EightFlags::LAYOUT.iter() }
}
 
// Now we can use wrapped bitfield enum
let bf: BitField<EightFlags, u8> = BitField::new(0b01100101);
 
// Get only setted flags
let result = bf.flags()
    .filter_map(|f| {
        if f.is_set {
            match f.value {
                EightFlags::OemReserved(v) =>
                    Some(format!("Reserved flag #{}", v)),
                EightFlags::FutureReserved(_) =>
                    Some(format!("{}", f.value)),
                v @ _ =>
                    Some(format!("Name: {}, Description: {:#}", v, v)),
            }
        } else {
            None
        }
    })
    .collect::<Vec<_>>();
 
let sample = vec![
    "Name: one, Description: ONE",
    "Name: three, Description: THREE",
    "Reserved flag #5",
    "Reserved for future usage (#6)",
];
assert_eq!(sample, result, "Wrapped enum");

Unit-like struct wrapper

We can use bitfield type defined as unit-like struct in the same way as for enum

 
// Unit-like struct without value
struct Status;
// Bind flags layout to this struct
impl Status {
    const LAYOUT: [&'static str; 8] = [
        "s0", "s1", "s2", "s3", "s4", "s5", "s6", "s7",
    ];
}
// Implement layout trait
impl Layout for Status {
    type Layout = core::slice::Iter<'static, &'static str>;
    fn layout() -> Self::Layout { Status::LAYOUT.iter() }
}
 
let bf: BitField<Status, u8> = BitField::new(42);
// Get formatted strings from flags iteartor
let result = bf.flags()
    .map(|f| format!("{:#}", f.value))
    .collect::<Vec<_>>();
let sample = vec!["s0", "s1", "s2", "s3", "s4", "s5", "s6", "s7"];
assert_eq!(sample, result, "Simple unit-like struct");
 

Unit-like struct with associated constants

Also we can use unit-like struct with associated constant flags. This will gave us feauture to has marked bits. This realisation somewhere in beetween enum and simple unit-like struct.

 
 
// Unit-like struct without value
struct Status;
// Implement layout. You can leave comments on every item. For example, you can use bit id as
// Status::ONE.
impl Status {
    const ONE: &'static str = "One";
    const TWO: &'static str = "Two";
    const THREE: &'static str = "Three";
    const FOUR: &'static str = "Four";
    const RESERVED: &'static str = "Reserved";
    const UNKNOWN: &'static str = "Unknown";
 
    const LAYOUT: [&'static str; 8] = [
        Self::ONE,
        Self::TWO,
        Self::THREE,
        Self::FOUR,
        Self::RESERVED,
        Self::RESERVED,
        Self::RESERVED,
        Self::UNKNOWN,
    ];
}
// Implement layout trait
impl Layout for Status {
    type Layout = core::slice::Iter<'static, &'static str>;
    fn layout() -> Self::Layout { Status::LAYOUT.iter() }
}
 
let bf: BitField<Status, u8> = BitField::new(0b00001000);
let result = bf.flags()
    .find(|f| f.is_set)
    .map(|f| f.value)
    .unwrap();
assert_eq!(Status::FOUR, *result, "Enumeration");

Fields

value: T

Implementations

impl<M, T> BitField<M, T>

pub fn new(value: T) -> Self

Trait Implementations

impl<M, T> BitAnd<BitField<M, T>> for BitField<M, T> where
    M: Layout,
    T: Copy + IntoBits + FromBits + BitAnd<Output = T>, 

type Output = Self

The resulting type after applying the & operator.

fn bitand(self, rhs: Self) -> Self::Output

Performs the & operation.

impl<M, T> BitAndAssign<BitField<M, T>> for BitField<M, T> where
    M: Layout,
    T: Copy + IntoBits + FromBits + BitAnd<Output = T>, 

fn bitand_assign(&mut self, rhs: Self)

Performs the &= operation.

impl<M: Layout, T: Copy + IntoBits + FromBits> BitFieldLayout for BitField<M, T>

type Value = T

fn get(&self) -> Self::Value

Returns a copy of the contained value.

fn set(&mut self, new: Self::Value)

Sets the contained value.

fn replace(&mut self, new: Self::Value) -> Self::Value

Replaces the contained value with val, and returns the old contained value.

fn swap(&mut self, other: &mut Self)

Swaps the values of two bitfields.

fn update<F>(&mut self, f: F) -> Self::Value where
    F: FnOnce(Self::Value) -> Self::Value, 

Updates the contained value using a function and returns the new value.

fn insert_flag(&mut self, position: usize, b: bool) -> bool

Set the specified bit (flag) in-place. Returns current state

fn toggle_flag(&mut self, position: usize)

The specified bit (flag) will be inverted

fn bits(&self) -> Bits<<Self::Value as IntoBits>::Bytes>

Return iterator through bitfield value bits. Every bit represents as bool value.

fn flags(&self) -> Flags<Self::Layout, Bits<<Self::Value as IntoBits>::Bytes>>

Return iterator through bitfield value flags. Every flag contains bit state (set or unset) and item (record) value - string in simple case.

fn diff(
    &self,
    other: Self
) -> Diff<Self::Layout, Bits<<Self::Value as IntoBits>::Bytes>> where
    Self: Sized, 

Helps to find difference between two bitfield values.

impl<M, T> BitOr<BitField<M, T>> for BitField<M, T> where
    M: Layout,
    T: Copy + IntoBits + FromBits + BitOr<Output = T>, 

type Output = Self

The resulting type after applying the | operator.

fn bitor(self, rhs: Self) -> Self::Output

Performs the | operation.

impl<M, T> BitOrAssign<BitField<M, T>> for BitField<M, T> where
    M: Layout,
    T: Copy + IntoBits + FromBits + BitOr<Output = T>, 

fn bitor_assign(&mut self, rhs: Self)

Performs the |= operation.

impl<M, T> BitXor<BitField<M, T>> for BitField<M, T> where
    M: Layout,
    T: Copy + IntoBits + FromBits + BitXor<Output = T>, 

type Output = Self

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: Self) -> Self::Output

Performs the ^ operation.

impl<M, T> BitXorAssign<BitField<M, T>> for BitField<M, T> where
    M: Layout,
    T: Copy + IntoBits + FromBits + BitXor<Output = T>, 

fn bitxor_assign(&mut self, rhs: Self)

Performs the ^= operation.

impl<M: Clone, T: Clone> Clone for BitField<M, T>

fn clone(&self) -> BitField<M, T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<M: Debug, T: Debug> Debug for BitField<M, T>

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

Formats the value using the given formatter.

impl<M: Hash, T: Hash> Hash for BitField<M, T>

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, 

Feeds a slice of this type into the given Hasher.

impl<M: Layout, T> Layout for BitField<M, T>

type Layout = M::Layout

Layout iterator. Typically constant array or slice

fn layout() -> Self::Layout

Return iterator through layout items. Actual layout may be implemented inside this function or be a associated constant of bitfield type

impl<M: Ord, T: Ord> Ord for BitField<M, T>

fn cmp(&self, other: &BitField<M, T>) -> Ordering

This method returns an Ordering between self and other.

#[must_use]

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

Compares and returns the maximum of two values.

#[must_use]

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

Compares and returns the minimum of two values.

#[must_use]

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

Restrict a value to a certain interval.

impl<M: PartialEq, T: PartialEq> PartialEq<BitField<M, T>> for BitField<M, T>

fn eq(&self, other: &BitField<M, T>) -> bool

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

fn ne(&self, other: &BitField<M, T>) -> bool

This method tests for !=.

impl<M: PartialOrd, T: PartialOrd> PartialOrd<BitField<M, T>> for BitField<M, T>

fn partial_cmp(&self, other: &BitField<M, T>) -> Option<Ordering>

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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<M: Eq, T: Eq> Eq for BitField<M, T>

impl<M, T> StructuralEq for BitField<M, T>

impl<M, T> StructuralPartialEq for BitField<M, T>