Crate bit_struct

source ·
Expand description

bit-struct

crates.io codecov Minimum rustc version

Bit struct is a crate which allows for ergonomic use of C-like bit fields without mediocre IDE support resulting from proc macros. In addition, everything is statically typed checked!

Take the following example

use bit_struct::*; 

enums! {
    // 2 bits, i.e., 0b00, 0b01, 0b10
    pub HouseKind { Urban, Suburban, Rural}
}

bit_struct! {
    // u8 is the base storage type. This can be any multiple of 8
    pub struct HouseConfig(u8) {
        // 2 bits
        kind: HouseKind,
        
        // two's compliment 3-bit signed number
        lowest_floor: i3,
        
        // 2 bit unsigned number
        highest_floor: u2,
    }
}

// We can create a new `HouseConfig` like such:
// where all numbers are statically checked to be in bounds.
let config = HouseConfig::new(HouseKind::Suburban, i3!(-2), u2!(1));

// We can get the raw `u8` which represents `config`:
let raw: u8 = config.raw();
assert_eq!(114_u8, raw);

// or we can get a `HouseConfig` from a `u8` like:
let mut config: HouseConfig = HouseConfig::try_from(114_u8).unwrap();
assert_eq!(config, HouseConfig::new(HouseKind::Suburban, i3!(-2), u2!(1)));
// We need to unwrap because `HouseConfig` is not valid for all numbers. For instance, if the
// most significant bits are `0b11`, it encodes an invalid `HouseKind`. However, 
// if all elements of a struct are always valid (suppose we removed the `kind` field), the struct will
// auto implement a trait which allows calling the non-panicking:
// let config: HouseConfig = HouseConfig::exact_from(123_u8);

// We can access values of `config` like so:
let kind: HouseKind = config.kind().get();

// And we can set values like so:
config.lowest_floor().set(i3!(0));

// We can also convert the new numeric types for alternate bit-widths into the 
// numeric types provided by the standard library:
let lowest_floor: i3 = config.lowest_floor().get();
let lowest_floor_std: i8 = lowest_floor.value();
assert_eq!(lowest_floor_std, 0_i8);

Benefits

  • No proc macros
  • Autocompletion fully works (tested in IntelliJ Rust)
  • Fast compile times
  • Statically checks that structs are not overfilled. For example, these overfilled structs will not compile:
    ⓘ
      bit_struct::bit_struct! {
      struct TooManyFieldsToFit(u16) {
          a: u8,
          b: u8,
          c: bit_struct::u1
      }
  }
    ⓘ
      bit_struct::bit_struct! {
      struct FieldIsTooBig(u16) {
          a: u32
      }
  }
  • Statically checked types

Further Documentation

Look at the integration tests in the tests folder for further insight.

Macros

bit_struct
Create a bit struct.
create
Create a bit_struct
enums
Create enums with trait implementations necessary for use in a bit_struct field.
i2
Produce a value of type i2
i3
Produce a value of type i3
i4
Produce a value of type i4
i5
Produce a value of type i5
i6
Produce a value of type i6
i7
Produce a value of type i7
i9
Produce a value of type i9
i10
Produce a value of type i10
i11
Produce a value of type i11
i12
Produce a value of type i12
i13
Produce a value of type i13
i14
Produce a value of type i14
i15
Produce a value of type i15
i17
Produce a value of type i17
i18
Produce a value of type i18
i19
Produce a value of type i19
i20
Produce a value of type i20
i21
Produce a value of type i21
i22
Produce a value of type i22
i23
Produce a value of type i23
i24
Produce a value of type i24
i25
Produce a value of type i25
i26
Produce a value of type i26
i27
Produce a value of type i27
i28
Produce a value of type i28
i29
Produce a value of type i29
i30
Produce a value of type i30
i31
Produce a value of type i31
i33
Produce a value of type i33
i34
Produce a value of type i34
i35
Produce a value of type i35
i36
Produce a value of type i36
i37
Produce a value of type i37
i38
Produce a value of type i38
i39
Produce a value of type i39
i40
Produce a value of type i40
i41
Produce a value of type i41
i42
Produce a value of type i42
i43
Produce a value of type i43
i44
Produce a value of type i44
i45
Produce a value of type i45
i46
Produce a value of type i46
i47
Produce a value of type i47
i48
Produce a value of type i48
i49
Produce a value of type i49
i50
Produce a value of type i50
i51
Produce a value of type i51
i52
Produce a value of type i52
i53
Produce a value of type i53
i54
Produce a value of type i54
i55
Produce a value of type i55
i56
Produce a value of type i56
i57
Produce a value of type i57
i58
Produce a value of type i58
i59
Produce a value of type i59
i60
Produce a value of type i60
i61
Produce a value of type i61
i62
Produce a value of type i62
i63
Produce a value of type i63
u1
Produce a value of type u1
u2
Produce a value of type u2
u3
Produce a value of type u3
u4
Produce a value of type u4
u5
Produce a value of type u5
u6
Produce a value of type u6
u7
Produce a value of type u7
u9
Produce a value of type u9
u10
Produce a value of type u10
u11
Produce a value of type u11
u12
Produce a value of type u12
u13
Produce a value of type u13
u14
Produce a value of type u14
u15
Produce a value of type u15
u17
Produce a value of type u17
u18
Produce a value of type u18
u19
Produce a value of type u19
u20
Produce a value of type u20
u21
Produce a value of type u21
u22
Produce a value of type u22
u23
Produce a value of type u23
u24
Produce a value of type u24
u25
Produce a value of type u25
u26
Produce a value of type u26
u27
Produce a value of type u27
u28
Produce a value of type u28
u29
Produce a value of type u29
u30
Produce a value of type u30
u31
Produce a value of type u31
u33
Produce a value of type u33
u34
Produce a value of type u34
u35
Produce a value of type u35
u36
Produce a value of type u36
u37
Produce a value of type u37
u38
Produce a value of type u38
u39
Produce a value of type u39
u40
Produce a value of type u40
u41
Produce a value of type u41
u42
Produce a value of type u42
u43
Produce a value of type u43
u44
Produce a value of type u44
u45
Produce a value of type u45
u46
Produce a value of type u46
u47
Produce a value of type u47
u48
Produce a value of type u48
u49
Produce a value of type u49
u50
Produce a value of type u50
u51
Produce a value of type u51
u52
Produce a value of type u52
u53
Produce a value of type u53
u54
Produce a value of type u54
u55
Produce a value of type u55
u56
Produce a value of type u56
u57
Produce a value of type u57
u58
Produce a value of type u58
u59
Produce a value of type u59
u60
Produce a value of type u60
u61
Produce a value of type u61
u62
Produce a value of type u62
u63
Produce a value of type u63

Structs

GetSet
A struct which allows for getting/setting a given property
UnsafeStorage
UnsafeStorage is used to mark that there are some arbitrary invariants which must be maintained in storing its inner value. Therefore, creation and modifying of the inner value is an “unsafe” behavior. Although it might not be unsafe in traditional Rust terms (no memory unsafety), behavior might be “undefined”—or at least undocumented, because invariants are expected to be upheld.
i2
An unsigned integer which contains 2 bits
i3
An unsigned integer which contains 3 bits
i4
An unsigned integer which contains 4 bits
i5
An unsigned integer which contains 5 bits
i6
An unsigned integer which contains 6 bits
i7
An unsigned integer which contains 7 bits
i9
An unsigned integer which contains 9 bits
i10
An unsigned integer which contains 10 bits
i11
An unsigned integer which contains 11 bits
i12
An unsigned integer which contains 12 bits
i13
An unsigned integer which contains 13 bits
i14
An unsigned integer which contains 14 bits
i15
An unsigned integer which contains 15 bits
i17
An unsigned integer which contains 17 bits
i18
An unsigned integer which contains 18 bits
i19
An unsigned integer which contains 19 bits
i20
An unsigned integer which contains 20 bits
i21
An unsigned integer which contains 21 bits
i22
An unsigned integer which contains 22 bits
i23
An unsigned integer which contains 23 bits
i24
An unsigned integer which contains 24 bits
i25
An unsigned integer which contains 25 bits
i26
An unsigned integer which contains 26 bits
i27
An unsigned integer which contains 27 bits
i28
An unsigned integer which contains 28 bits
i29
An unsigned integer which contains 29 bits
i30
An unsigned integer which contains 30 bits
i31
An unsigned integer which contains 31 bits
i33
An unsigned integer which contains 33 bits
i34
An unsigned integer which contains 34 bits
i35
An unsigned integer which contains 35 bits
i36
An unsigned integer which contains 36 bits
i37
An unsigned integer which contains 37 bits
i38
An unsigned integer which contains 38 bits
i39
An unsigned integer which contains 39 bits
i40
An unsigned integer which contains 40 bits
i41
An unsigned integer which contains 41 bits
i42
An unsigned integer which contains 42 bits
i43
An unsigned integer which contains 43 bits
i44
An unsigned integer which contains 44 bits
i45
An unsigned integer which contains 45 bits
i46
An unsigned integer which contains 46 bits
i47
An unsigned integer which contains 47 bits
i48
An unsigned integer which contains 48 bits
i49
An unsigned integer which contains 49 bits
i50
An unsigned integer which contains 50 bits
i51
An unsigned integer which contains 51 bits
i52
An unsigned integer which contains 52 bits
i53
An unsigned integer which contains 53 bits
i54
An unsigned integer which contains 54 bits
i55
An unsigned integer which contains 55 bits
i56
An unsigned integer which contains 56 bits
i57
An unsigned integer which contains 57 bits
i58
An unsigned integer which contains 58 bits
i59
An unsigned integer which contains 59 bits
i60
An unsigned integer which contains 60 bits
i61
An unsigned integer which contains 61 bits
i62
An unsigned integer which contains 62 bits
i63
An unsigned integer which contains 63 bits
u1
An unsigned integer which contains 1 bits
u2
An unsigned integer which contains 2 bits
u3
An unsigned integer which contains 3 bits
u4
An unsigned integer which contains 4 bits
u5
An unsigned integer which contains 5 bits
u6
An unsigned integer which contains 6 bits
u7
An unsigned integer which contains 7 bits
u9
An unsigned integer which contains 9 bits
u10
An unsigned integer which contains 10 bits
u11
An unsigned integer which contains 11 bits
u12
An unsigned integer which contains 12 bits
u13
An unsigned integer which contains 13 bits
u14
An unsigned integer which contains 14 bits
u15
An unsigned integer which contains 15 bits
u17
An unsigned integer which contains 17 bits
u18
An unsigned integer which contains 18 bits
u19
An unsigned integer which contains 19 bits
u20
An unsigned integer which contains 20 bits
u21
An unsigned integer which contains 21 bits
u22
An unsigned integer which contains 22 bits
u23
An unsigned integer which contains 23 bits
u24
An unsigned integer which contains 24 bits
u25
An unsigned integer which contains 25 bits
u26
An unsigned integer which contains 26 bits
u27
An unsigned integer which contains 27 bits
u28
An unsigned integer which contains 28 bits
u29
An unsigned integer which contains 29 bits
u30
An unsigned integer which contains 30 bits
u31
An unsigned integer which contains 31 bits
u33
An unsigned integer which contains 33 bits
u34
An unsigned integer which contains 34 bits
u35
An unsigned integer which contains 35 bits
u36
An unsigned integer which contains 36 bits
u37
An unsigned integer which contains 37 bits
u38
An unsigned integer which contains 38 bits
u39
An unsigned integer which contains 39 bits
u40
An unsigned integer which contains 40 bits
u41
An unsigned integer which contains 41 bits
u42
An unsigned integer which contains 42 bits
u43
An unsigned integer which contains 43 bits
u44
An unsigned integer which contains 44 bits
u45
An unsigned integer which contains 45 bits
u46
An unsigned integer which contains 46 bits
u47
An unsigned integer which contains 47 bits
u48
An unsigned integer which contains 48 bits
u49
An unsigned integer which contains 49 bits
u50
An unsigned integer which contains 50 bits
u51
An unsigned integer which contains 51 bits
u52
An unsigned integer which contains 52 bits
u53
An unsigned integer which contains 53 bits
u54
An unsigned integer which contains 54 bits
u55
An unsigned integer which contains 55 bits
u56
An unsigned integer which contains 56 bits
u57
An unsigned integer which contains 57 bits
u58
An unsigned integer which contains 58 bits
u59
An unsigned integer which contains 59 bits
u60
An unsigned integer which contains 60 bits
u61
An unsigned integer which contains 61 bits
u62
An unsigned integer which contains 62 bits
u63
An unsigned integer which contains 63 bits

Traits

BitCount
A trait which defines how many bits are needed to store a struct.
BitStruct
A trait that all bit structs implement
BitStructExt
An extension trait for bit structs which can be safely made from any value in their underlying storage type.
BitStructZero
A bit struct which has a zero value we can get
BitsFitIn
A conversion type for fitting the bits of one type into the bits of another type
FieldStorage
A type which can be a field of a bit_struct
ValidCheck
Check whether the underlying bits are valid

Functions

bits
Returns the index of the leading 1 in num