fray 0.1.2

A type-safe and ergonomic Rust library for working with bitfields.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

pub mod iterable;

/// Provides typed storage and retrieval for a specific type `T` within a [`BitContainer`](crate::BitContainer).
///
/// `BitContainerFor<T>` defines how a value of type `T` is represented and manipulated
/// at the bit level inside a container. Each implementation specifies how to store
/// and retrieve `T` from the underlying bits.
///
/// Methods of this trait is typically **not used directly** by end-users. Instead, it is
/// used internally by [`BitContainer`].
///
/// # Usage
///
/// Implementers are responsible for:
/// - Defining how a value of type `T` is encoded into the underlying bits.
/// - Ensuring that `store_raw` and `retrieve_raw` are consistent, such that
///   storing a value and immediately retrieving it yields the original value.
pub trait BitContainerFor<T>: BitContainer {
    /// Store a value of type `T` at a given bit offset and size within the container.
    fn store_raw(&mut self, value: T, offset: usize, size: usize);

    /// Load a value of type `T` from a given bit offset and size within the container.
    fn retrieve_raw(&self, offset: usize, size: usize) -> T;
}

/// A bit container type used by a [`BitField`](crate::BitField),
/// abstracting how bits are stored and retrieved.
///
/// A `BitContainer` provides the low-level storage and access mechanisms
/// for bitfields. Implementers are responsible for:
/// Implementers are responsible for:
/// - Choosing an [`Inner`](Self::Inner) type. This is typically a primitive integer
///   type (e.g., `u8`, `u16`, `u32`), but the implementer is free to
///   decide what is valid.
/// - Defining the rules for storing and retrieving values. Typed storage is handled via [`BitContainerFor<T>`].
///
/// This trait defines how raw bits are represented and accessed, but
/// does not provide high-level methods; these are handled by [`BitField`](crate::BitField).
pub trait BitContainer: Sized {
    /// The underlying storage type, typically a primitive; the implementer decides what is valid.
    type Inner;

    /// The size of the container in **bits**.
    ///
    /// This constant is used internally by the bitfield machinery to
    /// calculate field offsets according to the chosen [`BitOrder`](crate::bitorder::BitOrder).
    /// It must accurately represent the total number of bits available
    /// in the container type.
    const SIZE: usize;

    /// Construct a new container with all bits cleared (zeroed).
    fn empty() -> Self;

    /// Extract the underlying primitive storage.
    fn into_inner(self) -> Self::Inner;

    ///   Store a typed value. Implementation is delegated to [`BitContainerFor<T>`].
    fn store<T>(&mut self, value: T, offset: usize, size: usize)
    where
        Self: BitContainerFor<T>,
    {
        self.store_raw(value, offset, size);
    }

    ///   Load a typed value. Implementation is delegated to [`BitContainerFor<T>`].
    fn retrieve<T>(&self, offset: usize, size: usize) -> T
    where
        Self: BitContainerFor<T>,
    {
        self.retrieve_raw(offset, size)
    }
}