Crate bitpiece

Expand description

§bitpiece

A powerful Rust crate for working with bitfields. Define compact, type-safe bitfield structures with automatic bit packing and extraction.

§Features

Const-compatible: All operations work in const contexts
no_std compatible: Works in embedded and bare-metal environments
Type-safe: Strong typing prevents mixing up different bitfield types
Flexible bit widths: Support for arbitrary bit widths from 1 to 64 bits
Signed and unsigned: Both signed (SB*) and unsigned (B*) arbitrary-width types
Nested bitfields: Compose complex structures from simpler bitfield types
Enum support: Use enums as bitfield members with automatic bit width calculation
Zero-cost abstractions: Compiles down to efficient bit manipulation operations

§Quick Start

use bitpiece::*;

// Define a 2-bit enum
#[bitpiece(2, all)]
#[derive(Debug, PartialEq, Eq)]
enum Priority {
    Low = 0,
    Medium = 1,
    High = 2,
    Critical = 3,
}

// Define an 8-bit struct containing multiple fields
#[bitpiece(8, all)]
#[derive(Debug, PartialEq, Eq)]
struct StatusByte {
    enabled: bool,      // 1 bit
    priority: Priority, // 2 bits
    count: B5,          // 5 bits (unsigned, 0-31)
}

fn main() {
    // Create from raw bits
    let status = StatusByte::from_bits(0b10101_01_1);
     
    assert_eq!(status.enabled(), true);
    assert_eq!(status.priority(), Priority::Medium);
    assert_eq!(status.count(), B5::new(21));
     
    // Modify fields
    let updated = status
        .with_priority(Priority::Critical)
        .with_count(B5::new(7));
     
    assert_eq!(updated.to_bits(), 0b00111_11_1);
}

§The `#[bitpiece]` Attribute

The #[bitpiece] attribute macro is the main entry point for defining bitfield types. It can be applied to structs and enums.

§Syntax

#[bitpiece]                    // Auto-calculate bit length, basic features
#[bitpiece(all)]               // Auto-calculate bit length, all features
#[bitpiece(32)]                // Explicit 32-bit length, basic features
#[bitpiece(32, all)]           // Explicit 32-bit length, all features
#[bitpiece(get, set)]          // Auto-calculate, specific features only
#[bitpiece(16, get, set, with)] // Explicit length with specific features

§Arguments

Bit length (optional): An integer specifying the exact bit length. If omitted, the bit length is calculated automatically from the fields (for structs) or variant values (for enums).
Feature flags (optional): Control which methods and types are generated. See Opt-in Features for details.

§Built-in Types

§Unsigned Arbitrary-Width Types (`B1` - `B64`)

Types for unsigned integers of specific bit widths:

let three_bits: B3 = B3::new(0b101);  // 3-bit value (0-7)
let five_bits: B5 = B5::new(31);       // 5-bit value (0-31)

assert_eq!(three_bits.get(), 5);
assert_eq!(B3::MAX.get(), 7);

// Validation
assert!(B3::try_new(7).is_some());   // Valid: fits in 3 bits
assert!(B3::try_new(8).is_none());   // Invalid: requires 4 bits

§Signed Arbitrary-Width Types (`SB1` - `SB64`)

Types for signed integers of specific bit widths using two’s complement:

let signed: SB5 = SB5::new(-10);  // 5-bit signed value (-16 to 15)

assert_eq!(signed.get(), -10);
assert_eq!(SB5::MIN.get(), -16);
assert_eq!(SB5::MAX.get(), 15);

// Validation
assert!(SB3::try_new(3).is_some());   // Valid: fits in 3 bits
assert!(SB3::try_new(-4).is_some());  // Valid: minimum for SB3
assert!(SB3::try_new(4).is_none());   // Invalid: too large
assert!(SB3::try_new(-5).is_none());  // Invalid: too small

§Standard Integer Types

All standard Rust integer types implement BitPiece:

Unsigned: u8, u16, u32, u64
Signed: i8, i16, i32, i64

#[bitpiece(48, all)]
struct MixedTypes {
    byte: u8,      // 8 bits
    word: u16,     // 16 bits
    flags: B8,     // 8 bits
    signed: i16,   // 16 bits
}

§Boolean Type

bool is a 1-bit type:

#[bitpiece(3, all)]
struct Flags {
    read: bool,    // 1 bit
    write: bool,   // 1 bit
    execute: bool, // 1 bit
}

§Defining Bitfield Structs

Structs are the primary way to define composite bitfields. Fields are packed in order from least significant bit (LSB) to most significant bit (MSB).

#[bitpiece(16, all)]
#[derive(Debug, PartialEq, Eq)]
struct Instruction {
    opcode: B4,    // Bits 0-3 (LSB)
    reg_a: B3,     // Bits 4-6
    reg_b: B3,     // Bits 7-9
    immediate: B6, // Bits 10-15 (MSB)
}

// Bit layout:
// [immediate: 6 bits][reg_b: 3 bits][reg_a: 3 bits][opcode: 4 bits]
// MSB                                                          LSB

§Field Ordering

Fields are packed starting from bit 0:

#[bitpiece(8, all)]
struct Example {
    a: B2,  // Bits 0-1
    b: B3,  // Bits 2-4
    c: B3,  // Bits 5-7
}

let val = Example::from_bits(0b111_010_01);
assert_eq!(val.a(), B2::new(0b01));
assert_eq!(val.b(), B3::new(0b010));
assert_eq!(val.c(), B3::new(0b111));

§Defining Bitfield Enums

Enums can be used as bitfield types. The bit width is automatically calculated from the variant values, or can be specified explicitly.

§Exhaustive Enums

When all possible bit patterns map to valid variants:

#[bitpiece(2, all)]  // 2 bits = 4 possible values
#[derive(Debug, PartialEq, Eq)]
enum Direction {
    North = 0,
    East = 1,
    South = 2,
    West = 3,
}

// All 2-bit values (0-3) are valid
let dir = Direction::from_bits(2);
assert_eq!(dir, Direction::South);

§Non-Exhaustive Enums

When not all bit patterns are valid variants:

#[bitpiece(all)]  // Auto-calculated: 7 bits needed for value 100
#[derive(Debug, PartialEq, Eq)]
enum ErrorCode {
    Success = 0,
    NotFound = 10,
    PermissionDenied = 50,
    InternalError = 100,
}

// Valid variant
assert_eq!(ErrorCode::from_bits(10), ErrorCode::NotFound);

// Invalid bit pattern panics in from_bits
// Use try_from_bits for safe conversion
assert!(ErrorCode::try_from_bits(25).is_none());
assert!(ErrorCode::try_from_bits(50).is_some());

§Explicit Bit Length for Enums

You can specify a larger bit length than required:

#[bitpiece(16, all)]  // Use 16 bits even though values fit in fewer
#[derive(Debug, PartialEq, Eq)]
enum Command {
    Nop = 0,
    Load = 1,
    Store = 2,
}

// Can accept 16-bit values
assert!(Command::try_from_bits(1000).is_none());

§Generated Methods and Types

When you apply #[bitpiece] to a struct, several methods and types are generated.

§Generated Constants

#[bitpiece(16, all)]
struct MyStruct { /* ... */ }

// Generated constants:
const MY_STRUCT_BIT_LEN: usize = 16;
type MyStructStorageTy = u16;  // Smallest type that fits

§Field Constants

For each field, offset and length constants are generated:

#[bitpiece(8, all)]
struct Example {
    a: B3,
    b: B5,
}

// Generated:
// Example::A_OFFSET = 0
// Example::A_LEN = 3
// Example::B_OFFSET = 3
// Example::B_LEN = 5

§Core Methods

impl MyStruct {
    // Create from raw bits (panics if invalid for non-exhaustive types)
    pub const fn from_bits(bits: StorageTy) -> Self;
     
    // Try to create from raw bits (returns None if invalid)
    pub const fn try_from_bits(bits: StorageTy) -> Option<Self>;
     
    // Convert to raw bits
    pub const fn to_bits(self) -> StorageTy;
}

§Associated Constants

impl BitPiece for MyStruct {
    const BITS: usize;   // Total bit length
    const ZEROES: Self;  // All bits set to 0 (for structs: each field's ZEROES)
    const ONES: Self;    // All bits set to 1 (for structs: each field's ONES)
    const MIN: Self;     // The minimum value (for structs: each field's MIN)
    const MAX: Self;     // The maximum value (for structs: each field's MAX)
}

Important distinction between ONES/ZEROES and MAX/MIN:

ZEROES: All bits are 0. For unsigned types, this equals MIN. For signed types, this is 0 (not the minimum).
ONES: All bits are 1. For unsigned types, this equals MAX. For signed types like i8, this represents -1 (not the maximum).
MIN: The minimum representable value. For i8, this is -128.
MAX: The maximum representable value. For i8, this is 127.

// For unsigned types: ZEROES == MIN, ONES == MAX
assert_eq!(B8::ZEROES.get(), 0);
assert_eq!(B8::ONES.get(), 255);
assert_eq!(B8::MIN.get(), 0);
assert_eq!(B8::MAX.get(), 255);

// For signed types: ONES != MAX, ZEROES != MIN
assert_eq!(SB8::ZEROES.get(), 0);    // All bits 0 = 0
assert_eq!(SB8::ONES.get(), -1);     // All bits 1 = -1 in two's complement
assert_eq!(SB8::MIN.get(), -128);    // Minimum value
assert_eq!(SB8::MAX.get(), 127);     // Maximum value

Non-exhaustive enums: For enums where not all bit patterns are valid variants, ZEROES and ONES represent the closest valid variant to the all-zeros or all-ones bit pattern (i.e., MIN and MAX respectively). If an enum has no variant with value 0, ZEROES will be the variant with the smallest value, not a value with all bits set to zero.

#[bitpiece(all)]
#[derive(Debug, PartialEq, Eq)]
enum Sparse {
    A = 10,
    B = 50,
    C = 100,
}

// No variant has value 0, so ZEROES is the minimum variant
assert_eq!(Sparse::ZEROES, Sparse::A);  // Value 10, not 0
assert_eq!(Sparse::MIN, Sparse::A);
assert_eq!(Sparse::ONES, Sparse::C);    // Maximum variant
assert_eq!(Sparse::MAX, Sparse::C);

§Opt-in Features

Control which methods and types are generated using feature flags.

§Feature Flags

Flag	Description
`get`	Field getter methods: `field_name()`
`set`	Field setter methods: `set_field_name(value)`
`with`	Builder-style methods: `with_field_name(value)`
`get_noshift`	Raw bit access: `field_name_noshift()`
`get_mut`	Mutable field references: `field_name_mut()`
`const_eq`	Const equality comparison
`fields_struct`	Generate `TypeNameFields` struct
`mut_struct`	Generate `TypeNameMutRef` type
`mut_struct_field_get`	Getter methods on MutRef
`mut_struct_field_set`	Setter methods on MutRef
`mut_struct_field_get_noshift`	Noshift getters on MutRef
`mut_struct_field_mut`	Nested mutable references on MutRef

§Presets

Preset	Includes
`basic`	`get`, `set`, `with` (default if no flags specified)
`all`	All features
`mut_struct_all`	All `mut_struct*` features

§Examples

// Only getters
#[bitpiece(8, get)]
struct ReadOnly { /* ... */ }

// Getters and setters, no builder pattern
#[bitpiece(8, get, set)]
struct Mutable { /* ... */ }

// Everything
#[bitpiece(8, all)]
struct Full { /* ... */ }

// Custom combination
#[bitpiece(8, get, with, fields_struct)]
struct Custom { /* ... */ }

§Attributes and Derives

When you apply #[bitpiece] to a type, any attributes you place on the type (such as #[derive(...)]) are applied to both the main generated type and the generated fields struct (if fields_struct is enabled).

§Automatic Clone and Copy

The Clone and Copy traits are automatically derived on all bitpiece types. You do not need to (and should not) manually derive these traits:

// Clone and Copy are automatically derived - don't include them!
#[bitpiece(8, all)]
#[derive(Debug, PartialEq, Eq)]  // No Clone, Copy needed
struct MyStruct {
    a: B4,
    b: B4,
}

// Same for enums
#[bitpiece(2, all)]
#[derive(Debug, PartialEq, Eq)]  // No Clone, Copy needed
enum MyEnum {
    A = 0,
    B = 1,
    C = 2,
    D = 3,
}

This automatic derivation ensures that all bitpiece types satisfy the Copy bound required by the BitPiece trait.

§Deriving Additional Traits

You can derive additional traits like Debug, PartialEq, Eq, Hash, or even third-party traits like serde::Serialize and serde::Deserialize:

#[bitpiece(16, all)]
#[derive(Debug, PartialEq, Eq, Hash)]
struct Packet {
    version: B4,
    flags: B4,
    length: u8,
}

// With serde (requires serde feature/dependency)
// #[bitpiece(8, all)]
// #[derive(Debug, serde::Serialize, serde::Deserialize)]
// struct Config {
//     mode: B4,
//     level: B4,
// }

These attributes are applied to both the main Packet type and the PacketFields struct, allowing you to serialize/deserialize both types consistently.

§Working with Fields

§Getting Field Values

#[bitpiece(8, all)]
struct Packet {
    version: B2,
    flags: B3,
    length: B3,
}

let packet = Packet::from_bits(0b101_110_01);

// Get individual fields
let version = packet.version();  // B2
let flags = packet.flags();      // B3
let length = packet.length();    // B3

assert_eq!(version.get(), 1);
assert_eq!(flags.get(), 6);
assert_eq!(length.get(), 5);

§Setting Field Values (Immutable)

The with_* methods return a new instance with the field modified:

let packet = Packet::ZEROES;

// Chain modifications
let updated = packet
    .with_version(B2::new(2))
    .with_flags(B3::new(7))
    .with_length(B3::new(4));

// Original unchanged
assert_eq!(packet.to_bits(), 0);

§Setting Field Values (Mutable)

The set_* methods modify the instance in place:

let mut packet = Packet::ZEROES;

packet.set_version(B2::new(2));
packet.set_flags(B3::new(7));
packet.set_length(B3::new(4));

§Raw Bit Access (Noshift)

Get field bits at their original position without shifting:

#[bitpiece(8, all)]
struct Example {
    a: B3,  // Bits 0-2
    b: B5,  // Bits 3-7
}

let val = Example::from_bits(0b11111_010);

// Normal getter: shifts to bit 0
assert_eq!(val.b().get(), 0b11111);

// Noshift: keeps original position
assert_eq!(val.b_noshift(), 0b11111_000);

§Mutable References

Get a mutable reference to a field within the bitfield:

#[bitpiece(8, all)]
struct Container {
    inner: B4,
    outer: B4,
}

let mut container = Container::ZEROES;
{
    let mut inner_ref = container.inner_mut();
    inner_ref.set(B4::new(15));
}
assert_eq!(container.inner().get(), 15);

§Nested Bitfields

Bitfield types can be nested within other bitfields:

#[bitpiece(4, all)]
#[derive(Debug, PartialEq, Eq)]
struct Inner {
    x: B2,
    y: B2,
}

#[bitpiece(12, all)]
#[derive(Debug, PartialEq, Eq)]
struct Outer {
    a: Inner,    // 4 bits
    b: Inner,    // 4 bits
    c: B4,       // 4 bits
}

let outer = Outer::from_bits(0b1010_0110_0011);

// Access nested fields
assert_eq!(outer.a().x(), B2::new(3));
assert_eq!(outer.a().y(), B2::new(0));
assert_eq!(outer.b().x(), B2::new(2));
assert_eq!(outer.b().y(), B2::new(1));
assert_eq!(outer.c(), B4::new(10));

§Deep Nesting

#[bitpiece(8, all)]
struct Level1 {
    data: B4,
    flags: B4,
}

#[bitpiece(16, all)]
struct Level2 {
    l1_a: Level1,
    l1_b: Level1,
}

#[bitpiece(32, all)]
struct Level3 {
    l2: Level2,
    extra: u16,
}

let l3 = Level3::from_bits(0x12345678);
let nested_data = l3.l2().l1_a().data();

§Signed Types

§Using Standard Signed Integers

#[bitpiece(24, all)]
struct SignedExample {
    small: i8,   // 8-bit signed
    large: i16,  // 16-bit signed
}

let val = SignedExample::from_fields(SignedExampleFields {
    small: -50,
    large: -1000,
});

assert_eq!(val.small(), -50i8);
assert_eq!(val.large(), -1000i16);

§Using Arbitrary-Width Signed Types

#[bitpiece(16, all)]
struct CustomSigned {
    a: SB5,   // 5-bit signed (-16 to 15)
    b: bool,
    c: SB7,   // 7-bit signed (-64 to 63)
    d: B3,
}

let val = CustomSigned::from_bits(0b101_0101010_1_11111);

assert_eq!(val.a(), SB5::new(-1));
assert_eq!(val.b(), true);
assert_eq!(val.c(), SB7::new(42));
assert_eq!(val.d(), B3::new(5));

§Const Context Usage

All operations work in const contexts:

#[bitpiece(8, all)]
struct Config {
    mode: B2,
    speed: B3,
    enabled: bool,
    reserved: B2,
}

// Const construction
const DEFAULT_CONFIG: Config = Config::from_bits(0b00_1_101_01);

// Const field access
const DEFAULT_MODE: B2 = DEFAULT_CONFIG.mode();
const DEFAULT_SPEED: B3 = DEFAULT_CONFIG.speed();
const IS_ENABLED: bool = DEFAULT_CONFIG.enabled();

// Const modification
const DISABLED_CONFIG: Config = DEFAULT_CONFIG.with_enabled(false);

// Const assertions
const _: () = assert!(DEFAULT_MODE.get() == 1);
const _: () = assert!(DEFAULT_SPEED.get() == 5);
const _: () = assert!(IS_ENABLED == true);

§Const Functions

const fn create_packet(version: u8, flags: u8) -> Packet {
    Packet::ZEROES
        .with_version(B2::new(version))
        .with_flags(B3::new(flags))
}

const PACKET: Packet = create_packet(2, 5);

§The BitPiece Trait

All bitfield types implement the BitPiece trait:

pub trait BitPiece: Copy {
    /// The length in bits of this type
    const BITS: usize;
     
    /// A value with all bits set to 0 (see note below for enums)
    const ZEROES: Self;
     
    /// A value with all bits set to 1 (see note below for enums)
    const ONES: Self;
     
    /// The minimum representable value
    const MIN: Self;
     
    /// The maximum representable value
    const MAX: Self;
     
    /// The storage type used internally
    type Bits: BitStorage;
     
    /// Try to create from raw bits
    fn try_from_bits(bits: Self::Bits) -> Option<Self>;
     
    /// Create from raw bits (may panic)
    fn from_bits(bits: Self::Bits) -> Self;
     
    /// Convert to raw bits
    fn to_bits(self) -> Self::Bits;
}

§Using the Trait Generically

fn print_bitpiece_info<T: BitPiece + core::fmt::Debug>(value: T)
{
    println!("Bits: {}", T::BITS);
    println!("Value: {:?}", value);
}

§Error Handling

§Safe Conversion with `try_from_bits`

#[bitpiece(all)]
#[derive(Debug, PartialEq, Eq)]
enum Status {
    Ok = 0,
    Error = 1,
    Pending = 2,
}

// Safe conversion
match Status::try_from_bits(1) {
    Some(status) => println!("Status: {:?}", status),
    None => println!("Invalid status code"),
}

// For exhaustive enums, try_from_bits still validates range
assert!(Status::try_from_bits(3).is_none());

§Validation for B* and SB* Types

// B types validate that value fits in bit width
assert!(B4::try_new(15).is_some());  // Max for 4 bits
assert!(B4::try_new(16).is_none());  // Too large

// SB types validate signed range
assert!(SB4::try_new(7).is_some());   // Max for 4-bit signed
assert!(SB4::try_new(-8).is_some());  // Min for 4-bit signed
assert!(SB4::try_new(8).is_none());   // Too large
assert!(SB4::try_new(-9).is_none());  // Too small

§Panicking Constructors

The new and from_bits methods panic on invalid input:

// These will panic:
let _ = B3::new(8);           // Value doesn't fit
let _ = Status::from_bits(5); // Invalid variant

§Fields Struct

When fields_struct is enabled, a companion struct is generated for convenient construction:

#[bitpiece(8, all)]
#[derive(Debug, PartialEq, Eq)]
struct Packet {
    version: B2,
    flags: B3,
    length: B3,
}

// Generated: PacketFields struct
let fields = PacketFields {
    version: B2::new(1),
    flags: B3::new(5),
    length: B3::new(7),
};

let packet = Packet::from_fields(fields);

// Convert back to fields
let extracted: PacketFields = packet.to_fields();
assert_eq!(fields, extracted);

// From/Into implementations
let packet2: Packet = fields.into();
let fields2: PacketFields = packet2.into();

§Nested Fields

For nested bitfields, the fields struct uses the direct bitfield type (not its *Fields type):

#[bitpiece(4, all)]
struct Inner {
    x: B2,
    y: B2,
}

#[bitpiece(8, all)]
struct Outer {
    a: Inner,
    b: B4,
}

// OuterFields uses Inner directly for field 'a'
let fields = OuterFields {
    a: Inner::from_bits(0b1001),  // or use InnerFields and convert
    b: B4::new(15),
};

let outer = Outer::from_fields(fields);

// You can also construct the inner type from its fields and convert:
let fields2 = OuterFields {
    a: InnerFields {
        x: B2::new(1),
        y: B2::new(2),
    }.into(),  // Convert InnerFields to Inner
    b: B4::new(15),
};

§Storage Types

The crate automatically selects the smallest storage type that fits the bit length:

Bit Length	Storage Type
1-8	`u8`
9-16	`u16`
17-32	`u32`
33-64	`u64`

Access the storage directly:

#[bitpiece(12, all)]
struct Example {
    a: B6,
    b: B6,
}

let val = Example::from_bits(0xABC);

// Direct storage access
assert_eq!(val.storage, 0xABC);

// Storage type is u16 for 12 bits
let storage: u16 = val.storage;

Macros§

bitpiece_check_base_impl
bitpiece_check_const_assert_bits_eq
bitpiece_check_do_for_each_value
bitpiece_check_fields_impl
bitpiece_check_full_impl
bitpiece_check_gen_values_to_check
bitpiece_check_mut_impl
bitpiece_define_mut_ref_type
const_for: A for loop that is usable in const contexts.
paste

Structs§

B1: a type used to represent a field with a specific amount of bits.
B2: a type used to represent a field with a specific amount of bits.
B3: a type used to represent a field with a specific amount of bits.
B4: a type used to represent a field with a specific amount of bits.
B5: a type used to represent a field with a specific amount of bits.
B6: a type used to represent a field with a specific amount of bits.
B7: a type used to represent a field with a specific amount of bits.
B8: a type used to represent a field with a specific amount of bits.
B9: a type used to represent a field with a specific amount of bits.
B1MutRef
B2MutRef
B3MutRef
B4MutRef
B5MutRef
B6MutRef
B7MutRef
B8MutRef
B9MutRef
B10: a type used to represent a field with a specific amount of bits.
B11: a type used to represent a field with a specific amount of bits.
B12: a type used to represent a field with a specific amount of bits.
B13: a type used to represent a field with a specific amount of bits.
B14: a type used to represent a field with a specific amount of bits.
B15: a type used to represent a field with a specific amount of bits.
B16: a type used to represent a field with a specific amount of bits.
B17: a type used to represent a field with a specific amount of bits.
B18: a type used to represent a field with a specific amount of bits.
B19: a type used to represent a field with a specific amount of bits.
B20: a type used to represent a field with a specific amount of bits.
B21: a type used to represent a field with a specific amount of bits.
B22: a type used to represent a field with a specific amount of bits.
B23: a type used to represent a field with a specific amount of bits.
B24: a type used to represent a field with a specific amount of bits.
B25: a type used to represent a field with a specific amount of bits.
B26: a type used to represent a field with a specific amount of bits.
B27: a type used to represent a field with a specific amount of bits.
B28: a type used to represent a field with a specific amount of bits.
B29: a type used to represent a field with a specific amount of bits.
B30: a type used to represent a field with a specific amount of bits.
B31: a type used to represent a field with a specific amount of bits.
B32: a type used to represent a field with a specific amount of bits.
B33: a type used to represent a field with a specific amount of bits.
B34: a type used to represent a field with a specific amount of bits.
B35: a type used to represent a field with a specific amount of bits.
B36: a type used to represent a field with a specific amount of bits.
B37: a type used to represent a field with a specific amount of bits.
B38: a type used to represent a field with a specific amount of bits.
B39: a type used to represent a field with a specific amount of bits.
B40: a type used to represent a field with a specific amount of bits.
B41: a type used to represent a field with a specific amount of bits.
B42: a type used to represent a field with a specific amount of bits.
B43: a type used to represent a field with a specific amount of bits.
B44: a type used to represent a field with a specific amount of bits.
B45: a type used to represent a field with a specific amount of bits.
B46: a type used to represent a field with a specific amount of bits.
B47: a type used to represent a field with a specific amount of bits.
B48: a type used to represent a field with a specific amount of bits.
B49: a type used to represent a field with a specific amount of bits.
B50: a type used to represent a field with a specific amount of bits.
B51: a type used to represent a field with a specific amount of bits.
B52: a type used to represent a field with a specific amount of bits.
B53: a type used to represent a field with a specific amount of bits.
B54: a type used to represent a field with a specific amount of bits.
B55: a type used to represent a field with a specific amount of bits.
B56: a type used to represent a field with a specific amount of bits.
B57: a type used to represent a field with a specific amount of bits.
B58: a type used to represent a field with a specific amount of bits.
B59: a type used to represent a field with a specific amount of bits.
B60: a type used to represent a field with a specific amount of bits.
B61: a type used to represent a field with a specific amount of bits.
B62: a type used to represent a field with a specific amount of bits.
B63: a type used to represent a field with a specific amount of bits.
B64: a type used to represent a field with a specific amount of bits.
B10MutRef
B11MutRef
B12MutRef
B13MutRef
B14MutRef
B15MutRef
B16MutRef
B17MutRef
B18MutRef
B19MutRef
B20MutRef
B21MutRef
B22MutRef
B23MutRef
B24MutRef
B25MutRef
B26MutRef
B27MutRef
B28MutRef
B29MutRef
B30MutRef
B31MutRef
B32MutRef
B33MutRef
B34MutRef
B35MutRef
B36MutRef
B37MutRef
B38MutRef
B39MutRef
B40MutRef
B41MutRef
B42MutRef
B43MutRef
B44MutRef
B45MutRef
B46MutRef
B47MutRef
B48MutRef
B49MutRef
B50MutRef
B51MutRef
B52MutRef
B53MutRef
B54MutRef
B55MutRef
B56MutRef
B57MutRef
B58MutRef
B59MutRef
B60MutRef
B61MutRef
B62MutRef
B63MutRef
B64MutRef
BitLength: an empty struct used to represent a specific bit length. this is then combined with some traits (ExactAssociatedStorage, AssociatedStorage) to perform operations on the specified bit length.
BitPieceBoolConverter
BitPieceBoolMutRef
BitPieceI8Converter
BitPieceI8MutRef
BitPieceI16Converter
BitPieceI16MutRef
BitPieceI32Converter
BitPieceI32MutRef
BitPieceI64Converter
BitPieceI64MutRef
BitPieceU8Converter
BitPieceU8MutRef
BitPieceU16Converter
BitPieceU16MutRef
BitPieceU32Converter
BitPieceU32MutRef
BitPieceU64Converter
BitPieceU64MutRef
BitsMut: a convenience type for interacting with the bits of an underlying storage type, starting at a specific bit index. this is useful for implementing mutable references to bitpieces.
SB1: a type used to represent a field with a specific amount of bits.
SB2: a type used to represent a field with a specific amount of bits.
SB3: a type used to represent a field with a specific amount of bits.
SB4: a type used to represent a field with a specific amount of bits.
SB5: a type used to represent a field with a specific amount of bits.
SB6: a type used to represent a field with a specific amount of bits.
SB7: a type used to represent a field with a specific amount of bits.
SB8: a type used to represent a field with a specific amount of bits.
SB9: a type used to represent a field with a specific amount of bits.
SB1MutRef
SB2MutRef
SB3MutRef
SB4MutRef
SB5MutRef
SB6MutRef
SB7MutRef
SB8MutRef
SB9MutRef
SB10: a type used to represent a field with a specific amount of bits.
SB11: a type used to represent a field with a specific amount of bits.
SB12: a type used to represent a field with a specific amount of bits.
SB13: a type used to represent a field with a specific amount of bits.
SB14: a type used to represent a field with a specific amount of bits.
SB15: a type used to represent a field with a specific amount of bits.
SB16: a type used to represent a field with a specific amount of bits.
SB17: a type used to represent a field with a specific amount of bits.
SB18: a type used to represent a field with a specific amount of bits.
SB19: a type used to represent a field with a specific amount of bits.
SB20: a type used to represent a field with a specific amount of bits.
SB21: a type used to represent a field with a specific amount of bits.
SB22: a type used to represent a field with a specific amount of bits.
SB23: a type used to represent a field with a specific amount of bits.
SB24: a type used to represent a field with a specific amount of bits.
SB25: a type used to represent a field with a specific amount of bits.
SB26: a type used to represent a field with a specific amount of bits.
SB27: a type used to represent a field with a specific amount of bits.
SB28: a type used to represent a field with a specific amount of bits.
SB29: a type used to represent a field with a specific amount of bits.
SB30: a type used to represent a field with a specific amount of bits.
SB31: a type used to represent a field with a specific amount of bits.
SB32: a type used to represent a field with a specific amount of bits.
SB33: a type used to represent a field with a specific amount of bits.
SB34: a type used to represent a field with a specific amount of bits.
SB35: a type used to represent a field with a specific amount of bits.
SB36: a type used to represent a field with a specific amount of bits.
SB37: a type used to represent a field with a specific amount of bits.
SB38: a type used to represent a field with a specific amount of bits.
SB39: a type used to represent a field with a specific amount of bits.
SB40: a type used to represent a field with a specific amount of bits.
SB41: a type used to represent a field with a specific amount of bits.
SB42: a type used to represent a field with a specific amount of bits.
SB43: a type used to represent a field with a specific amount of bits.
SB44: a type used to represent a field with a specific amount of bits.
SB45: a type used to represent a field with a specific amount of bits.
SB46: a type used to represent a field with a specific amount of bits.
SB47: a type used to represent a field with a specific amount of bits.
SB48: a type used to represent a field with a specific amount of bits.
SB49: a type used to represent a field with a specific amount of bits.
SB50: a type used to represent a field with a specific amount of bits.
SB51: a type used to represent a field with a specific amount of bits.
SB52: a type used to represent a field with a specific amount of bits.
SB53: a type used to represent a field with a specific amount of bits.
SB54: a type used to represent a field with a specific amount of bits.
SB55: a type used to represent a field with a specific amount of bits.
SB56: a type used to represent a field with a specific amount of bits.
SB57: a type used to represent a field with a specific amount of bits.
SB58: a type used to represent a field with a specific amount of bits.
SB59: a type used to represent a field with a specific amount of bits.
SB60: a type used to represent a field with a specific amount of bits.
SB61: a type used to represent a field with a specific amount of bits.
SB62: a type used to represent a field with a specific amount of bits.
SB63: a type used to represent a field with a specific amount of bits.
SB64: a type used to represent a field with a specific amount of bits.
SB10MutRef
SB11MutRef
SB12MutRef
SB13MutRef
SB14MutRef
SB15MutRef
SB16MutRef
SB17MutRef
SB18MutRef
SB19MutRef
SB20MutRef
SB21MutRef
SB22MutRef
SB23MutRef
SB24MutRef
SB25MutRef
SB26MutRef
SB27MutRef
SB28MutRef
SB29MutRef
SB30MutRef
SB31MutRef
SB32MutRef
SB33MutRef
SB34MutRef
SB35MutRef
SB36MutRef
SB37MutRef
SB38MutRef
SB39MutRef
SB40MutRef
SB41MutRef
SB42MutRef
SB43MutRef
SB44MutRef
SB45MutRef
SB46MutRef
SB47MutRef
SB48MutRef
SB49MutRef
SB50MutRef
SB51MutRef
SB52MutRef
SB53MutRef
SB54MutRef
SB55MutRef
SB56MutRef
SB57MutRef
SB58MutRef
SB59MutRef
SB60MutRef
SB61MutRef
SB62MutRef
SB63MutRef
SB64MutRef

Enums§

BitPieceStorageMutRef: a mutable reference to the storage type of some bitpiece.

Traits§

AssociatedStorage: a trait implemented for all BitLength types that are small enough and provides the minimal storage type required for storing that amount of bits. for example for bit lengths 0..8 this will be u8.
BitPiece
BitPieceHasFields
BitPieceHasMutRef
BitPieceMutRef: a mutable reference to a bitpiece inside another bitpiece.
BitStorage: a type which can be used as the internal storage of a bitpiece.
ExactAssociatedStorage: a trait implemented for BitLength types that have an exact associated storage type, for example u8 or u16.

Functions§

const_array_max_u64
const_array_min_u64
extract_bits: extracts some bits from a value
extract_bits_noshift: extracts some bits (mask only, no shift) from a value
modify_bits: returns a new value with the specified bit range modified to the new value

Attribute Macros§

bitpiece: an attribute for defining bitfields.

Crate bitpiece

Crate bitpiece Copy item path

§bitpiece

§Features

§Quick Start

§Table of Contents

§The #[bitpiece] Attribute

§Syntax

§Arguments

§Built-in Types

§Unsigned Arbitrary-Width Types (B1 - B64)

§Signed Arbitrary-Width Types (SB1 - SB64)

§Standard Integer Types

§Boolean Type

§Defining Bitfield Structs

§Field Ordering

§Defining Bitfield Enums

§Exhaustive Enums

§Non-Exhaustive Enums

§Explicit Bit Length for Enums

§Generated Methods and Types

§Generated Constants

§Field Constants

§Core Methods

§Associated Constants

§Opt-in Features

§Feature Flags

§Presets

§Examples

§Attributes and Derives

§Automatic Clone and Copy

§Deriving Additional Traits

§Working with Fields

§Getting Field Values

§Setting Field Values (Immutable)

§Setting Field Values (Mutable)

§Raw Bit Access (Noshift)

§Mutable References

§Nested Bitfields

§Deep Nesting

§Signed Types

§Using Standard Signed Integers

§Using Arbitrary-Width Signed Types

§Const Context Usage

§Const Functions

§The BitPiece Trait

§Using the Trait Generically

§Error Handling

§Safe Conversion with try_from_bits

§Validation for B* and SB* Types

§Panicking Constructors

§Fields Struct

§Nested Fields

§Storage Types

Macros§

Structs§

Enums§

Traits§

Functions§

Attribute Macros§

Crate bitpiece

§The `#[bitpiece]` Attribute

§Unsigned Arbitrary-Width Types (`B1` - `B64`)

§Signed Arbitrary-Width Types (`SB1` - `SB64`)

§Safe Conversion with `try_from_bits`