bitstructs/

lib.rs

#![cfg_attr(feature = "no_std", no_std)]
//! `bitstructs` is a library for defining type-safe bitfield structures
//! that can be used in both `std` and `no_std` environments.
//!
//! The library provides three macros, [`bitstruct_cow`], [`bitstruct_owned`],
//! and [`bitstruct_small`], for generating `BitStruct`. It also includes
//! the [`bitstruct_field_enum`] macro for safely generating enum types
//! for fields within `BitStruct`. Only [`bitstruct_cow`] is not supported
//! in `no_std` environments because it relies on [`std::borrow::Cow`].
//!
//!
//! `bitstructs`是一个可同时用于std和no_std 环境，定义类型安全的位域结构体的库。
//!
//! 该库提供了[`bitstruct_cow`]、[`bitstruct_owned`]、[`bitstruct_small`]三个宏，
//! 用于生成`BitStruct`。以及[`bitstruct_field_enum`]宏，用于安全的生成`BitStruct`中字段枚举类型。
//! 其中只有[`bitstruct_cow`] 因为需要使用[`std::borrow::Cow`] ，所以不支持 no_std 环境。
//!
//! ## Defining `BitStruct`
//!
//! The usage of the three macros, [bitstruct_cow], [bitstruct_owned],
//! and [bitstruct_small], is similar.
//!
//! The syntax is similar to Rust's struct definition, except that
//! a number is used after the field name to indicate the bit width
//! instead of the type. You can optionally use `=>` to specify
//! the corresponding enum type for the field. The field's enum type
//! can be declared inline or referenced from an external definition.
//!
//!
//! [`bitstruct_cow`]、[`bitstruct_owned`]、[`bitstruct_small`]三个宏的使用方法类似。
//!
//! 语法类似rust的结构体定义，只是在字段名后使用数字表示位宽而非类型，
//! 然后可以选择的使用`=>`设置字段的对应的枚举类型。字段枚举类型可以
//! 使用内联枚举声明，也可以使用外部定义的枚举类型。
//!
//! ```
//! use bitstructs::{bitstruct_owned};
//!
//! bitstruct_owned! {
//!     #[derive(Clone, Debug, PartialEq)]
//!     pub struct Foo {
//!         a: 1,
//!         b: 2,
//!         c: 2 =>
//!         pub enum C {
//!             C0 = 0,
//!             C1 = 1,
//!         },
//!     }
//! }
//! let mut value = Foo::new();
//! assert_eq!(value.as_bytes(), vec![0b0000_0000]);
//! value.set_a(true);
//! unsafe { value.set_b(1) };
//! value.set_c(C::C1);
//! assert_eq!(value.as_bytes(), vec![0b0000_1011]);
//! ```
//!
//! By default, the library uses LSB0 and little-endian mode.
//! To use MSB0 and big-endian mode, add `#[bitstruct_repr(MSB0)]` to the struct.
//!
//! 默认情况下，采取的是LSB0和小端模式。如果要使用MSB0和大端模式，
//! 可以在结构体上添加中添加`#[bitstruct_repr(MSB0)]`。
//!
//! ```
//! use bitstructs::{bitstruct_owned};
//!
//! /// MSB0 and big-endian mode
//! /// MSB0和大端模式
//! bitstruct_owned! {
//!     #[derive(Clone, Debug, PartialEq)]
//!     #[bitstruct_repr(MSB0)]
//!     pub struct Foo {
//!         a: 1,
//!         b: 2,
//!         c: 2 =>
//!         pub enum C {
//!             C0 = 0,
//!             C1 = 1,
//!         },
//!     }
//! }
//! let mut value = Foo::new();
//! assert_eq!(value.as_bytes(), vec![0b0000_0000]);
//! value.set_a(true);
//! unsafe { value.set_b(1) };
//! value.set_c(C::C1);
//! assert_eq!(value.as_bytes(), vec![0b1010_1000]);
//! ```
//!
//! The [`bitstruct_owned`] macro generates the following methods:
//! - `fn new() -> Self`: Creates a new `BitStruct`.
//! - `fn bytes_len() -> usize`: Gets the number of bytes occupied by the `BitStruct`.
//! - `fn from_bytes(bytes: &[u8]) -> Result<Self, BitStructError>`: Creates a `BitStruct` from a byte array.
//! - `fn as_bytes(&self) -> &[u8]`: Gets an immutable reference to the byte array of the `BitStruct`.
//! - `fn as_bytes_mut(&mut self) -> &mut [u8]`: Gets a mutable reference to the byte array of the `BitStruct`.
//! - Methods for reading and setting each field. For fields without a specified enum type, the type will be chosen from `bool`, `u8`, `u16`, `u32`, or `u128`. Fields exceeding 128 bits will cause a compilation failure.
//!     For example, `fn b(&self) -> u8` and `unsafe fn set_b(&mut self, value: u8)`,
//!         `fn c(&self) -> C` and `fn set_c(&mut self, value: C)`.
//!
//! The usage of [`bitstruct_cow`] is the same as [`bitstruct_owned`],
//! but the generated `BitStruct` uses `Cow` internally. Additionally,
//! `as_bytes` and `as_bytes_mut` are replaced with `to_bytes` and `to_bytes_mut`.
//!
//! The usage of [`bitstruct_small`] is similar to [`bitstruct_owned`],
//! but it restricts the size of `BitStruct` to a maximum of 128 bits.
//! It does not support `#[bitstruct_repr(MSB0)]` but allows `#[bitstruct_repr(u8)]`
//! to explicitly specify the internal storage type of `BitStruct`.
//!
//!
//! [`bitstruct_owned`]宏会生成以下方法：
//! - `fn new() -> Self`：创建一个新的`BitStruct`。
//! - `fn bytes_len() -> usize`：获取`BitStruct`占用的字节数。
//! - `fn from_bytes(bytes: &[u8]) -> Result<Self, BitStructError>`：从字节数组中创建`BitStruct`。
//! - `fn as_bytes(&self) -> &[u8]`：获取`BitStruct`的字节数组引用。
//! - `fn as_bytes_mut(&mut self) -> &mut [u8]`：获取`BitStruct`的字节数组可变引用。
//! - 各个字段的读取和设置方法，对于没有指定枚举类型的字段，类型将会使用`bool`,`u8`,`u16`,`u32`,`u128`中选择。超过128位，将会编译失败。
//!     例如`fn b(&self) -> u8`和`unsafe fn set_b(&mut self, value: u8)`，
//!         `fn c(&self) -> C`和`fn set_c(&mut self, value: C)`。
//!
//! [`bitstruct_cow`]的使用和[`bitstruct_owned`]相同，只是生成的`BitStruct`内部是`Cow`类型，
//! 以及将`as_bytes`,`as_bytes_mut`换成了`to_bytes`，`to_bytes_mut`。
//!
//! [`bitstruct_small`]的使用和[`bitstruct_owned`]类似。但是限制了`BitStruct`的大小，最大为128位。
//! 以及不支持使用`#[bitstruct_repr(MSB0)]`，但是支持`#[bitstruct_repr(u8)]`去显示指定`BitStruct`内部的实际存储类型。
//!
//! ```
//! use bitstructs::{bitstruct_small};
//!
//! /// Specifying the storage type as u32
//! /// 指定存储类型为u32
//! bitstruct_small! {
//!     #[derive(Clone, Debug, PartialEq)]
//!     #[bitstruct_repr(u32)]
//!     pub struct Foo {
//!         a: 1,
//!         b: 2,
//!         reserved: 2,
//!         c: 2 =>
//!         #[derive(Debug, PartialEq, Eq)]
//!         pub enum C {
//!             C0 = 0,
//!             C1 = 1,
//!         },
//!     }
//! }
//! let value: u32 = 0b0100_10_1;
//! let value = Foo::from_value(value);
//! assert_eq!(value.a(), true);
//! assert_eq!(value.b(), 2);
//! assert_eq!(value.c(), C::C1);
//! ```
//!
//! ## Defining Enum Types
//!
//! In addition to defining enum types within the `bitstruct_owned`, `bitstruct_cow`,
//! and `bitstruct_small` macros as shown in the example above, enum types can also
//! be defined externally. Unlike inline enums, externally defined enum types can be reused. Here is a simple example:
//!
//! 除了像上面例子那样，在`bitstruct_owned`、`bitstruct_cow`、`bitstruct_small`宏中定义枚举类型，还可以在外部定义枚举类型。
//! 在外部定义的枚举类型，不同于内联枚举，可以重复使用。下面是一个简单的例子：
//!
//! ```
//! use bitstructs::{bitstruct_field_enum, bitstruct_owned};
//!
//! /// This is an enum type suitable for 2 bits
//! /// 这是一个适用于 2 bit 的枚举类型
//! #[bitstruct_field_enum(2)]
//! pub enum TwoBitEnum {
//!     Zero = 0,
//!     One = 1,
//!     Two = 2,
//!     Three = 3,
//! }
//! bitstruct_owned! {
//!     pub struct Foo {
//!         a: 4,
//!         b: 2 => TwoBitEnum,
//!         c: 2 => TwoBitEnum,
//!     }
//! }
//! ```
//!
//! If the variants in the enum type do not cover all possible values,
//! variants with the prefix `__Reserved` will be automatically added.
//! This also applies to inline enum types.
//!
//!
//! 如果枚举类型中的变体（variants）没有覆盖所有可能的取值，
//! 会自动添加前缀为 `__Reserved` 的变体。这同样适用于内联枚举类型。
//!
//! ```
//! use bitstructs::{bitstruct_field_enum,bitstruct_owned};
//! #[bitstruct_field_enum(2)]
//! pub enum TwoBitEnum {
//!    Zero = 0,
//!    Two = 2,
//! }
//! bitstruct_owned! {
//!     pub struct Foo {
//!         a: 4,
//!         b: 2 =>
//!         enum B {
//!             Foo = 2,
//!             Bar = 3,
//!         },
//!     }
//! }
//! ```
//!
//! The code above is equivalent to:
//!
//! ```
//! use bitstructs::{bitstruct_field_enum,bitstruct_owned};
//! #[bitstruct_field_enum(2)]
//! pub enum TwoBitEnum {
//!     Zero = 0,
//!     Two = 2,
//!     __Reserved1 = 1,
//!     __Reserved3 = 3,
//! }
//! bitstruct_owned! {
//!     pub struct Foo {
//!         a: 4,
//!         b: 2 =>
//!         enum B {
//!             Foo = 2,
//!             Bar = 3,
//!             __Reserved0 = 0,
//!             __Reserved1 = 1,
//!         },
//!     }
//! }
//! ```
//!
//! ## Confusing Error Messages
//!
//! If the bit width of the enum type does not match the bit width of the field
//! in `BitStruct`, compilation will fail. However, since the current check
//! for non-inline enum types uses `const` to trigger a compilation error through overflow,
//! the error message may not be very friendly when the bit widths do not match.
//!
//! 如果枚举类型的位宽与 `BitStruct` 中字段的位宽不匹配，编译将会失败。
//! 然而，由于当前对非内联枚举类型的检查是通过使用 `const` 来触发编译错误（利用溢出），
//! 因此当位宽不匹配时，错误信息不够友好。
//!
//! ```compile_fail
//! use bitstructs::{bitstruct_field_enum,bitstruct_owned};
//! #[bitstruct_field_enum(2)]
//! pub enum TwoBitEnum {
//!    Zero = 0,
//!    One = 1,
//!    Two = 2,
//!    Three = 3,
//! }
//! bitstruct_owned! {
//!     pub struct Foo {
//!         a: 4,
//!         b: 3 => TwoBitEnum,
//!     }
//! }
//! ```
//!
//! The code above will fail to compile with an error message similar to:
//!
//! ```text
//! error[E0080]: evaluation of constant value failed
//!   --> bitstructs/src/main.rs:9:1
//!    |
//! 9  | / bitstruct_owned! {
//! 10 | |     pub struct Foo {
//! 11 | |         a: 4,
//! 12 | |         b: 3 => TwoBitEnum,
//! 13 | |     }
//! 14 | | }
//!    | |_^ attempt to compute `0_u32 - u32::MAX`, which would overflow
//! ```
//!
//! Declaring inline enum types is checked during macro expansion,
//! which results in more friendly error messages.
//!
//! ```compile_fail
//! use bitstructs::{bitstruct_small};
//! bitstruct_small! {
//!     pub struct Foo {
//!         a: 4,
//!         b: 2 =>
//!         enum B {
//!            Zero = 0,
//!            One = 1,
//!            Two = 2,
//!            Three = 3,
//!            Four = 4
//!        },
//!     }
//! }
//! ```
//! The code above will fail to compile with an error message similar to:
//!
//! ```text
//! error: enum type variant count must be less than or equal to 2^2
//!  --> bitstructs/src/main.rs:5:22
//!   |
//! 6 |         enum B {
//!   |              ^
//! ```
//!
macro_rules! with_doc {
    ($($tokens:tt)*) => {
        /// A trait that must be implemented for non-inline field enum types. 非内联的字段枚举类型必须实现的trait。
        ///
        /// It is recommended to use the [`bitstruct_field_enum`] macro to generate non-inline field enum types instead of implementing them manually.
        ///
        /// 推荐使用[`bitstruct_field_enum`]宏来生成非内联的字段枚举类型。而不是手动实现。
        ///
        /// ```
        /// use bitstructs::{bitstruct_field_enum};
        /// #[bitstruct_field_enum(2)]
        /// pub enum TwoBitEnum {
        ///     Zero = 0,
        ///     One = 1,
        ///     Two = 2,
        ///     Three = 3,
        /// }
        /// ``````
        ///
        /// # Safety
        ///
        /// 1. Must be able to handle all values from `0` to `2.pow(BIT_WIDTH) - 1`.
        /// 2. Must implement both [`BitstructToValue`] and [`BitstructFromValue`].
        /// 3. The `StoreType` must be the smallest unsigned integer type that can contain all possible values, which can be one of [`u8`], [`u16`], [`u32`], [`u64`], or [`u128`].
        /// 4. The operations of [`BitstructFromValue::from_value`] and [`BitstructToValue::to_value`] must be inverse of each other.
        /// 5. The `BIT_WIDTH` of [`BitstructFromValue`] and [`BitstructToValue`] must be the same.
        ///
        /// 1. 必须能处理 0 到 `2.pow(BIT_WIDTH) - 1` 的所有取值。
        /// 2. 必须同时实现[`BitstructToValue`]和[`BitstructFromValue`]。
        /// 3. `StoreType`必须是能包含所有可能取值范围的最小的无符号整数类型，可使用[`u8`],[`u16`],[`u32`],[`u64`],[`u128`]。
        /// 4. [`BitstructFromValue::from_value`]和[`BitstructToValue::to_value`]必须是互为逆操作。
        /// 5. [`BitstructFromValue`]和[`BitstructToValue`]的`BIT_WIDTH`必须相同。
        ///
        $($tokens)*
    };
}

with_doc! {
    pub unsafe trait BitstructFromValue {
        const BIT_WIDTH: u32;
        type StoreType;
        unsafe fn from_value(value: Self::StoreType) -> Self;
    }
}

with_doc! {
    pub unsafe trait BitstructToValue {
        const BIT_WIDTH: u32;
        type StoreType;
        unsafe fn to_value(self) -> Self::StoreType;
    }
}

#[cfg(not(feature = "no_std"))]
pub use bitstructs_macro::bitstruct_cow;
pub use bitstructs_macro::bitstruct_field_enum;
pub use bitstructs_macro::bitstruct_owned;
pub use bitstructs_macro::bitstruct_repr;
pub use bitstructs_macro::bitstruct_small;

/// ```compile_fail
/// use bitstructs::{bitstruct_field_enum,bitstruct_owned};
/// #[bitstruct_field_enum(2)]
/// pub enum TwoBitEnum {
///    Zero = 0,
///    One = 1,
///    Two = 2,
///    Three = 3,
/// }
/// bitstruct_owned! {
///     pub struct Foo {
///         a: 4,
///         b: 3 => TwoBitEnum,
///     }
/// }
/// ```
///
/// ```compile_fail
/// use bitstructs::{bitstruct_field_enum,bitstruct_cow};
/// #[bitstruct_field_enum(2)]
/// pub enum TwoBitEnum {
///    Zero = 0,
///    One = 1,
///    Two = 2,
///    Three = 3,
/// }
/// bitstruct_cow! {
///     pub struct Foo {
///         a: 4,
///         b: 3 => TwoBitEnum,
///     }
/// }
/// ```
///
/// ```compile_fail
/// use bitstructs::{bitstruct_field_enum,bitstruct_small};
/// #[bitstruct_field_enum(2)]
/// pub enum TwoBitEnum {
///    Zero = 0,
///    One = 1,
///    Two = 2,
///    Three = 3,
/// }
/// bitstruct_small! {
///     pub struct Foo {
///         a: 4,
///         b: 3 => TwoBitEnum,
///     }
/// }
/// ```
#[doc(hidden)]
#[allow(dead_code)]
fn test_should_compile_fail() {
    unreachable!("This function should not be called.");
}