fixed_bitmaps/
lib.rs

1//! # Fixed Bitmaps
2//!
3//! This is a crate whose aim is to create the simplest bitmap structures to work with. This crate provides wrappings for Rust unsigned
4//! integers from `u8` up to `u128`, along with `usize`.
5//!
6//! Note that indexing for bit access starts at 0, which allows you to know what the effect of setting a bit will be, by putting 2 to
7//! the power of the index. For example, the following example sets the 5th bit to true in an otherwise empty bitmap. This is equivalent
8//! to adding 2<sup>5</sup> to the underlying value:
9//! ```rust
10//! use fixed_bitmaps::Bitmap64;
11//!
12//! let mut bitmap = Bitmap64::default();
13//!
14//! // Set the 5th index (the 6th bit) to true.
15//! // Can simply unwrap the result to remove the warning, as we know
16//! // for certain that 5 < 64
17//! bitmap.set(5, true).unwrap();
18//!
19//! // The following will throw an error however, as the 64th index is out of bounds
20//! // (the highest index in a `Bitmap64` is 63)
21//!
22//! // Will print out the error thrown when trying to set an index out of bounds
23//! match bitmap.set(64, true) {
24//!     Ok(_) => println!("That wasn't meant to happen... something's up with my implementation!"),
25//!     Err(error) => {
26//!         println!("Yep, threw an error as expected. Error message is as follows:");
27//!         eprintln!("{}", error);
28//!     }
29//! }
30//! ```
31//!
32//!
33//! # Contributing
34//!
35//! When making changes, only do so in the following two files (unless of course you plan to add a new module or something of the sort):
36//!
37//! - `fixed_bitmaps/src/primitives/bitmap128.rs`
38//! - `fixed_bitmaps/tests/primitives/bitmap128.rs`
39//!
40//! You can then run `cargo run` on this project, and it will propogate changes to those files through to all of the other files in their
41//! respective directories, adapting the changes to match the particular primitive each module aims to support.
42//!
43//! # More Examples
44//!
45//! ```rust
46//! use fixed_bitmaps::Bitmap64;
47//!
48//! // Multiple ways to create a new bitmap
49//! let _empty = Bitmap64::default();
50//! let _full = Bitmap64::from(u64::MAX);
51//!
52//! // Equivalent ways to create a bitmap with last bits 1001
53//! let bitmap = Bitmap64::from(9);
54//! let bitmap = Bitmap64::from(0b1001);
55//!
56//! // Sets the 7th least significant bit when creating a new
57//! // bitmap (indexing starts at 0)
58//! let mut bitmap = Bitmap64::from_set(6).unwrap();
59//!
60//! // Use the set() method to work with specific bits
61//! bitmap.set(6, false).unwrap();
62//! bitmap.set(42, true).unwrap();
63//!
64//! // Use get() to know the value of a specific bit
65//! println!("Bit at index 42: {}", bitmap.get(42).unwrap());
66//!
67//! // Freely use boolean operators &, |, and ^
68//! let bitmap1 = Bitmap64::from(0b1001);
69//! let bitmap2 = Bitmap64::from(0b1010);
70//!
71//! let _and = bitmap1 & bitmap2;
72//! let _or = bitmap1 | bitmap2;
73//! let _xor = bitmap1 ^ bitmap2;
74//!
75//! // The following also works exactly the same
76//! let _and = bitmap1 & 0b1010;
77//! let _or = bitmap1 | 0b1010;
78//! let _xor = bitmap1 ^ 0b1010;
79//!
80//! // Aritmetic operators are currently used as exactly that, the following is
81//! // guarunteed to continue working as it does
82//! let _add = bitmap1 + 10;
83//! let _sub = bitmap1 - 4;
84//! let _mul = bitmap2 * 2;
85//! let _div = bitmap2 / 2;
86//!
87//! // The following work exactly as above, but are likely to change in favour of
88//! // set operations in the major update to 1.0.0
89//! let _add = bitmap1 + Bitmap64::from(10);
90//! let _sub = bitmap1 - Bitmap64::from(4);
91//! let _mul = bitmap2 * Bitmap64::from(2);
92//! let _div = bitmap2 / Bitmap64::from(2);
93//!
94//! // Left and right shifts work exactly as they do with integers
95//! let _lsh = bitmap1 << 3;
96//! let _rsh = bitmap2 >> 1;
97//! ```
98//!
99//! Note that all of the various `Bitmap` types are exactly the same in
100//! the operations they can perform, the only difference is the integer type they wrap.
101
102mod oversized;
103mod primitives;
104
105pub use oversized::Bitmap1024;
106pub use oversized::Bitmap2048;
107pub use oversized::Bitmap256;
108pub use oversized::Bitmap4096;
109pub use oversized::Bitmap512;
110pub use oversized::BitmapKB;
111pub use primitives::Bitmap128;
112pub use primitives::Bitmap16;
113pub use primitives::Bitmap32;
114pub use primitives::Bitmap64;
115pub use primitives::Bitmap8;
116pub use primitives::BitmapArch;
117pub use primitives::BitmapSize;
fixed_bitmaps/lib.rs

fixed_bitmaps/
lib.rs
