Derive Macro bondrewd_derive::Bitfields

#[derive(Bitfields)]
{
    // Attributes available to this derive:
    #[bondrewd]
}

Generates an implementation of the bondrewd::Bitfield trait, as well as peek and set functions for direct sized u8 arrays access.

Supported Field Types

• All primitives other than usize and isize (i believe ambiguous sizing is bad for this type of work).
  • Floats currently must be full sized.
  • Its important to know that there is a small runtime cost for signed numbers.
• Enums which implement the BitfieldEnum trait in bondrewd.
• Structs which implement the Bitfield trait in bondrewd.

Struct Attributes

• default_endianness = {"le" or "be"} describes a default endianness for primitive fields.
• read_from = {"msb0" or "lsb0"} defines bit positioning. which end of the byte array to start at.
• enforce_bytes = {BYTES} defines a required resulting BIT_SIZE divided by 8 of the structure in condensed form.
• enforce_bits = {BYTES} defines a required resulting BIT_SIZE of the structure in condensed form.
• enforce_full_bytes defines that the resulting BIT_SIZE is required to be a multiple of 8.
• reverse defines that the entire byte array should be reversed before reading. no runtime cost.

Field Attributes

• bit_length = {BITS} define the total amount of bits to use when condensed.
• byte_length = {BYTES} define the total amount of bytes to use when condensed.
• endianness = {"le" or "be"} define per field endianess.
• block_bit_length = {BITS} describes a bit length for the entire array dropping lower indexes first. (default array type)
• block_byte_length = {BYTES} describes a byte length for the entire array dropping lower indexes first. (default array type)
• element_bit_length = {BITS} describes a bit length for each element of an array.
• element_byte_length = {BYTES} describes a byte length for each element of an array.
• enum_primitive = "u8" defines the size of the enum. the BitfieldEnum currently only supports u8.
• struct_size = {SIZE} defines the field as a struct which implements the Bitfield trait and the BYTE_SIZE const defined in said trait.
• reserve defines that this field should be ignored in from and into bytes functions.
• /!Untested!\ bits = "RANGE" - define the bit indexes yourself rather than let the proc macro figure it out. using a rust range in quotes.

Bitfield Array Example

use bondrewd::*;
#[derive(Bitfields, Clone, PartialEq, Eq, Debug)]
#[bondrewd(default_endianness = "be")]
struct SimpleWithArray {
    // each u8 in the array contains 4 bits of useful information.
    #[bondrewd(element_bit_length = 4)]
    one: [u8; 4],
    // due to no attributes being present for field `two`, no bits are missing and the type of array
    // shouldn't matter bondrewd will use block array logic. also boolean values are assumed to be 1
    // bit so this will produce 5 bits in an output.
    two: [bool; 5],
    // the total amount bits in the array. [{4 bits},{8 bits},{8 bits}]
    #[bondrewd(block_bit_length = 20)]
    three: [u8; 3],
}

Bitfield Struct as Field Example

use bondrewd::*;
#[derive(Bitfields, Clone, PartialEq, Eq, Debug)]
#[bondrewd(default_endianness = "be")]
struct Simple {
    #[bondrewd(bit_length = 3)]
    one: u8,
    #[bondrewd(bit_length = 27)]
    two: char,
    #[bondrewd(bit_length = 14)]
    three: u16,
    four: i8,
}
 
#[derive(Bitfields, Clone, PartialEq, Eq, Debug)]
#[bondrewd(default_endianness = "be")]
struct SimpleWithStruct {
    #[bondrewd(struct_size = 7)]
    one: Simple,
    #[bondrewd(struct_size = 7)]
    two: [Simple; 2],
}

Enum Example

examples for enums are on the BitfieldEnum Derive page.