modular-bitfield 0.13.1

Easily define bitfield types with modular building blocks.
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

Derive macro generating an impl of the trait [`Specifier`].

This macro can be used on all unit enums and structs annotated with
`#[bitfield]`. The enum or struct can be up to 128 bits in size; anything larger
will cause a compilation error.

# Options

* `#[bits = N]`: Explicitly specifies the number of bits used by a unit enum.
  This attribute is required when an enum does not have a power-of-two number of
  variants, but can be used for extra validation no matter what.

# Examples

## Basic usage

In this example, an extra variant (`Invalid`) is required because otherwise the
enum would not contain a power-of-two number of variants. The power-of-two
requirement ensures conversion from raw bits is infallible.

```
use modular_bitfield::prelude::*;

#[derive(Specifier)]
pub enum Weekday {
    Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday, Invalid
}
```

## Using `#[bits = N]`

To eliminate the power-of-two requirement, add the `#[bits]` attribute:

```
# use modular_bitfield::prelude::*;
#
#[derive(Specifier)]
#[bits = 3]
pub enum Weekday {
    Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday
}
```

## Discriminants

Discriminants can be used normally to explicitly override certain values:

```
# use modular_bitfield::prelude::*;
#
#[derive(Specifier)]
#[bits = 3]
pub enum Weekday {
    Monday = 1,
    Tuesday /* 2 … */,
    Wednesday,
    Thursday,
    Friday,
    Saturday,
    Sunday = 0,
}
```

## With `#[bitfield]`

An enum that implements `Specifier` can be used normally as a field type in a
`#[bitfield]` struct:

```
# use modular_bitfield::prelude::*;
#
# #[derive(Debug, Eq, PartialEq, Specifier)]
# #[bits = 3]
# pub enum Weekday {
#     Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday
# }
#[bitfield]
pub struct MeetingTimeSlot {
    day: Weekday,
    from: B6,
    to: B6,
    expired: bool,
}

let mut slot = MeetingTimeSlot::new()
    .with_day(Weekday::Friday)
    .with_from(14) // 14:00
    .with_to(15); // 15:00
assert_eq!(slot.day(), Weekday::Friday);
assert_eq!(slot.from(), 14);
assert_eq!(slot.to(), 15);
assert!(!slot.expired());
```