grit_bitvec/
lib.rs

1/*!
2# grit-bitvec
3This crate provides variants of `BitVec` data structure, a vector that can store data elements of fixed-size bit widths
4that do not fall into the 8/16/32/64/128 size categories. For example, rather than storing a vector of `bool`s in one
5byte each, you can store them each as one bit. Another example would be storing unsigned integers that are always in the
6range 0-3 as exactly 2 bits, 0-7 as 3 bits, 0-15 as 4 bits, or even a signed integer in the range -1024 to 1023 as 11 bits
7or a struct with 4 bools and 1 u8 in the range of 0-7 as a total of 7 bits.
8
9- [`RawBitVec`] : the base structure that all other variants wrap. Requires a [`BitProto`] to be passed to every function, and is UNSAFE if the same [`BitProto`] isnt used for all method calls on the same [`RawBitVec`] instance
10- [`CProtoBitVec<BIT_WIDTH>`] : a wrapper that takes the needed [`BitProto`] and stores it in a monomorphized constant for every separate `<BIT_WIDTH>`
11- [`SProtoBitVec`] : a wrapper that keeps a static reference to the needed [`BitProto`] in every instance
12- [`LProtoBitVec`] : a wrapper that keeps a full copy of the [`BitProto`] in every instance
13- [`TypedBitVec<T: TypedBitElem>`] : a wrapper that not only stores the [`BitProto`] in a monomorphized constant, but the needed functions to translate the raw returned bits into type `<T>`
14
15All versions use `usize` as the underlying data block type to take advantage of any possible arithmetic optimizations on
16native-size words, meaning that the maximum bit-width supported is the same as `usize::BITS`
17
18This allows considerable gains in memory usage for applications where the number of elements may be non-trivial, at the
19cost of processing time to access the elements.
20
21The additional processing cost is not terrible in most cases, as it is mostly performed with bitwise shifts and simple
22arithmetic, and is further reduced by using constant propogation when applcable to reduce many bitwise math functions
23to their easiest possible form. However they are not free, and operations that insert or remove elements in the middle
24of the `BitVec` may be even more costly due to the need to run those checks and shifts on every element rather than using
25`ptr::copy()` like `Vec` does internally
26
27By default the `small_int_impls` feature is enabled, providing simple `TypedBitElem` implementations for `bool` and
28integer types smaller than 16 bits (for example `u8_as_u3` or `i16_as_i11`), and the `large_int_impls` feature can
29be activated to get similar implementations for bit widths less than `usize::BITS`
30
31### Tested Functions
32- [x] new()  
33- [x] with_capacity()  
34- [x] len()  
35- [x] cap()  
36- [x] free()  
37- [x] clear()  
38- [x] grow_exact_for_total_elements_if_needed()  
39- [x] grow_exact_for_additional_elements_if_needed()  
40- [x] grow_for_total_elements_if_needed()  
41- [x] grow_for_additional_elements_if_needed  
42- [x] push()  
43- [x] pop()  
44- [x] insert()  
45- [x] remove()  
46- [x] insert_bitvec()  
47- [x] insert_iter()  
48- [x] remove_range()  
49- [x] trim_range()  
50- [x] swap()  
51- [x] swap_pop()  
52- [x] shrink_excess_capacity()  
53- [x] append_bitvec()  
54- [x] append_iter()  
55- [x] get()  
56- [x] set()  
57- [x] replace()  
58- [x] drain()  
59- [x] into_iter()  
60- [ ] discard_from_end()  
61
62This crate currently has incomplete documentation and is very much in the "unstable" phase. The API may change in the future
63*/
64
65pub(crate) use core::{
66    mem::{
67        size_of,
68        align_of,
69        ManuallyDrop
70    },
71    ptr::{
72        self,
73        NonNull,
74    },
75    marker::PhantomData,
76    cmp::Ordering,
77    ops::Range,
78};
79
80pub(crate) use std::alloc::{self, Layout, handle_alloc_error};
81
82mod proto_proxy;
83pub use proto_proxy::*;
84
85mod raw_bitvec;
86pub use raw_bitvec::*;
87mod raw_bitvec_iter;
88pub use raw_bitvec_iter::*;
89
90mod const_proto_bitvec;
91pub use const_proto_bitvec::*;
92mod const_proto_bitvec_iter;
93pub use const_proto_bitvec_iter::*;
94
95mod static_proto_bitvec;
96pub use static_proto_bitvec::*;
97mod static_proto_bitvec_iter;
98pub use static_proto_bitvec_iter::*;
99
100mod local_proto_bitvec;
101pub use local_proto_bitvec::*;
102mod local_proto_bitvec_iter;
103pub use local_proto_bitvec_iter::*;
104
105mod typed_bitvec;
106pub use typed_bitvec::*;
107mod typed_bitvec_iter;
108pub use typed_bitvec_iter::*;
109mod typed_bitvec_elem;
110pub use typed_bitvec_elem::*;
111
112mod utils;
113pub(crate) use utils::*;
114
115#[cfg(test)]
116mod testing;
117
118
119
grit_bitvec/lib.rs

grit_bitvec/
lib.rs
