bitmaps/lib.rs
1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at http://mozilla.org/MPL/2.0/.
4
5#![forbid(rust_2018_idioms)]
6#![deny(nonstandard_style)]
7#![warn(unreachable_pub)]
8#![allow(clippy::missing_safety_doc)]
9#![cfg_attr(not(feature = "std"), no_std)]
10
11//! This crate provides the [`Bitmap`][Bitmap] type as a convenient and
12//! efficient way of declaring and working with fixed size bitmaps in Rust.
13//!
14//! # Examples
15//!
16//! ```rust
17//! # #[macro_use] extern crate bitmaps;
18//! # use bitmaps::Bitmap;
19//! let mut bitmap: Bitmap<10> = Bitmap::new();
20//! assert_eq!(bitmap.set(5, true), false);
21//! assert_eq!(bitmap.set(5, true), true);
22//! assert_eq!(bitmap.get(5), true);
23//! assert_eq!(bitmap.get(6), false);
24//! assert_eq!(bitmap.len(), 1);
25//! assert_eq!(bitmap.set(3, true), false);
26//! assert_eq!(bitmap.len(), 2);
27//! assert_eq!(bitmap.first_index(), Some(3));
28//! ```
29//!
30//! # X86 Arch Support
31//!
32//! On `x86` and `x86_64` architectures, [`Bitmap`][Bitmap]s of size 256, 512,
33//! 768 and 1024 gain the [`load_m256i()`][load_m256i] method, which reads the
34//! bitmap into an [`__m256i`][m256i] or an array of [`__m256i`][m256i] using
35//! [`_mm256_loadu_si256()`][loadu_si256]. [`Bitmap`][Bitmap]s of size 128 as
36//! well as the previous gain the [`load_m128i()`][load_m128i] method, which
37//! does the same for [`__m128i`][m128i].
38//!
39//! In addition, [`Bitmap<U128>`][Bitmap] and [`Bitmap<U256>`][Bitmap] will have
40//! `From` and `Into` implementations for [`__m128i`][m128i] and
41//! [`__m256i`][m256i] respectively.
42//!
43//! Note that alignment is unaffected - your bitmaps will be aligned
44//! appropriately for `u128`, not [`__m128i`][m128i] or [`__m256i`][m256i],
45//! unless you arrange for it to be otherwise. This may affect the performance
46//! of SIMD instructions.
47//!
48//! [Bitmap]: struct.Bitmap.html
49//! [load_m128i]: struct.Bitmap.html#method.load_m128i
50//! [load_m256i]: struct.Bitmap.html#method.load_m256i
51//! [m128i]: https://doc.rust-lang.org/core/arch/x86_64/struct.__m128i.html
52//! [m256i]: https://doc.rust-lang.org/core/arch/x86_64/struct.__m256i.html
53//! [loadu_si256]: https://doc.rust-lang.org/core/arch/x86_64/fn._mm256_loadu_si256.html
54
55mod bitmap;
56mod types;
57
58#[doc(inline)]
59pub use crate::bitmap::{Bitmap, Iter};
60#[doc(inline)]
61pub use crate::types::{BitOps, Bits, BitsImpl};