To get started, add this to your Cargo.toml:
toml
[dependencies]
bitrange = { git = "https://github.com/trangar/bitrange" }
bitrange_plugin = { git = "https://github.com/trangar/bitrange" }
Then add the following code to your main.rs or lib.rs
``` rust
extern crate bitrange;
extern crate bitrange_plugin; ```
bitrange needs a nightly version of the compiler because it uses the feature proc_macro which is not stabilized yet
Because of an openstanding RFC 2320, stringify! can not be used in a proc-macro attribute. The code generated by this crate contains:
``` rust
``
where$formatand$structsizestringare from thebitrange` macro.
In this instance we'd like to use stringify!($format) and stringify($struct_size_string), however this does not work until RFC 2320 lands.
For this reason, the format needs to be quoted, and we need to annotate the type twice. e.g.
rust
bitrange! {
Test: u8, "u8",
"aaaa_bbbb",
a: first,
b: second
}
instead of the desired
rust
bitrange! {
Test: u8,
aaaa_bbbb,
a: first,
b: second
}
Bitrange helps you map bit fields to proper getters and setters.
Say you're trying to make an IP parser. The rfc will give you this:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Version| IHL |Type of Service| Total Length |
If you wanted to parse this in Rust, you'd have to make the following mapping:
* the first 4 bits are mapped to version
* The next 4 bits are mapped to ihl
* The next 8 bits are mapped to type_of_service
* The last 16 bits are mapped to total_length
With bitrange, you can easily map bytes to fields. To parse this part of the protocol, simply write
``` rust
extern crate bitrange;
bitrange! { IpHeader: u32, "u32", // struct name "aaaabbbbccccccccdddddddddddddddd", // pattern that we're matching against a: version, // map character 'a' to field 'version' b: ihl, // map character 'b' to field 'ihl' c: typeofservice, // map character 'c' to field 'typeofservice' d: totallength // map character 'd' to field 'total_length' }
fn main() { let header = IpHeader::from(0b00010010000000110000000000000100); asserteq!(header.version(), 0b0001); asserteq!(header.ihl(), 0b0010); asserteq!(header.typeofservice(), 0b0011); asserteq!(header.totallength(), 0b0100); } ```
If you wanted to make a field mutable, simply add a second ident to the field mapping, e.g.:
``` rust
bitrange! { IpHeader: u32, "u32", // struct name "aaaabbbbccccccccdddddddddddddddd", // pattern that we're matching against a: version setversion, // map character 'a' to field 'version', and create setter 'setversion' b: ihl, // map character 'b' to field 'ihl' c: typeofservice, // map character 'c' to field 'typeofservice' d: totallength // map character 'd' to field 'total_length' }
fn main() { let mut header = IpHeader::from(0b00010010000000110000000000000100); asserteq!(header.version(), 0b0001); asserteq!(header.ihl(), 0b0010); asserteq!(header.typeofservice(), 0b0011); asserteq!(header.totallength(), 0b0100);
header.set_version(0b0100);
assert_eq!(header.version(), 0b0100);
} ```
In addition, you can define constraints to bits that have to always be 0 or 1 ``` rust
bitrange! { Test: u8, "u8", // from left (highest) to right (lowest) // first 3 bits are mapped to a // the next bit is always 1 // the next bit is always 0 // the last 3 bits are mapped to b "aaa1_0bbb", a: first, b: second }
fn main() { // This panics at runtime // Because the 4th highest bit should always be 1 // Test::from(0);
// The enum also implements Default, so you can simply do:
let _test = Test::default();
// And this will have value 0b0001_0000
} ```
bitrange will also check fields at compile time to see if they exist
rust
bitrange! {
Test: u8, "u8",
"aaa1_0bbb",
a: first,
b: second,
c: third // this will panic with
// Token 'c' is not found in pattern "aaa10bbb"
}
However, this does not work for unmapped fields
rust
bitrange! {
Test: u8, "u8",
"aaa1_0bbb",
a: first,
// b is not mapped
// Does not give a warning
}