bitfielder 0.1.1

Yet another bitfield library
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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

# bitfielder

Yet another bitfield library to provide bitfield access functions to underlying types.

Supports base integer types, and byte arrays as the inner base type.

# But why?

One of the more common bitfield libraries, [rust-bitfield](https://docs.rs/bitfield) uses [proc-macros](https://doc.rust-lang.org/reference/procedural-macros.html) to define bitfield structs. This approach means higher compilation times, due to all of the build dependencies required for the `bitfield-macros` crate.

Also, [rust-bitfield](https://docs.rs/bitfield) does not provide `const` accessor functions because of the design choice of using traits for field access.

# Usage

A number of base types can be used for the inner representation of the bitfield.

## Primitive integers

```rust
    # use bitfielder::bitfield;

    bitfield! {
        /// U8 bitfield.
        pub BitfieldU8(u8): u8,
        mask: 0xff,
        default: 0,
        {
            pub range1: 7, 4;
            pub range0: 3, 1;
            pub bit0: 0;
        }
    }

    (0..=u8::MAX).for_each(|bits| {
        let field = BitfieldU8::from(bits);
        assert_eq!(field.bit0(), bits & 0x1 != 0);
        assert_eq!(field.range0(), (bits >> 1) & 0x7);
        assert_eq!(field.range1(), (bits >> 4) & 0xf);
    });
```

## Byte arrays

```rust
    # use bitfielder::bitfield;

    bitfield! {
        /// Test 24-bit array.
        pub TestU8x3(LSB0 [u8; 3]): u8 {
            pub range3: 23, 16;
            pub range2: 15, 8;
            pub range1: 7, 5;
            pub range0: 4, 2;
            pub bit1: 1;
            pub bit0: 0;
        }
    }

    (0..=24).map(|r| (1u32 << r) - 1).for_each(|bits| {
        let [b0, b1, b2, _] = bits.to_le_bytes();
        let test = TestU8x3([b0, b1, b2]);

        let [b0, b1, b2] = test.bytes();

        let exp_range1 = (b0 & (0x7 << 5)) >> 5;
        let exp_range0 = (b0 & (0x7 << 2)) >> 2;
        let exp_bit1 = ((b0 & 0x1 << 1) >> 1) != 0;
        let exp_bit0 = b0 & 0x1 != 0;

        assert_eq!(test.range3(), b2);
        assert_eq!(test.range2(), b1);
        assert_eq!(test.range1(), exp_range1);
        assert_eq!(test.range0(), exp_range0);
        assert_eq!(test.bit1(), exp_bit1);
        assert_eq!(test.bit0(), exp_bit0);
    })
```

## User defined type field accessors

Users can supply custom types for field accessor functions.

The main constraint is the type must have the following functions:

```rust
    # use bitfielder::bitfield;
    # use bitfielder::result::Result;

    #[derive(Debug, Eq, PartialEq)]
    pub struct CustomTy(u8);
    impl CustomTy {
        pub const fn try_from_inner(val: u8) -> Result<Self> {
            // example only, provide your own logic for type validation
            Ok(Self(val))
        }

        pub const fn into_inner(self) -> u8 {
            self.0
        }
    }

    // Use the library macro to define a custom field type.
    bitfield! {
        /// Custom macro field type.
        MacroTy: u8,
        mask: 0xf,
        default: 0,
        {
            ty_field: 3, 0;
        }
    }

    bitfield! {
        /// Test User defined fields.
        TestUser: u8,
        mask: 0xff,
        default: 0,
        {
            custom_ty: CustomTy, 7, 4;
            macro_ty: MacroTy, 3, 0;
        }
    }    

    (0..=u8::MAX).for_each(|bits| {
        let test = TestUser::try_from_inner(bits).unwrap();
        let custom_ty = CustomTy::try_from_inner(bits >> 4).unwrap();
        let macro_ty = MacroTy::try_from_inner(bits & MacroTy::MASK).unwrap();

        assert_eq!(test.custom_ty(), Ok(custom_ty));
        assert_eq!(test.macro_ty(), Ok(macro_ty));
    })
```

# License

This library is licensed under either [MIT](LICENSE-MIT) or [APACHE-2.0](LICENSE-APACHE).