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//! # use typenum::U10;
20//! let mut bitmap: Bitmap<U10> = Bitmap::new();
21//! assert_eq!(bitmap.set(5, true), false);
22//! assert_eq!(bitmap.set(5, true), true);
23//! assert_eq!(bitmap.get(5), true);
24//! assert_eq!(bitmap.get(6), false);
25//! assert_eq!(bitmap.len(), 1);
26//! assert_eq!(bitmap.set(3, true), false);
27//! assert_eq!(bitmap.len(), 2);
28//! assert_eq!(bitmap.first_index(), Some(3));
29//! ```
30//!
31//! # X86 Arch Support
32//!
33//! On `x86` and `x86_64` architectures, [`Bitmap`][Bitmap]s of size 256, 512,
34//! 768 and 1024 gain the [`load_m256i()`][load_m256i] method, which reads the
35//! bitmap into an [`__m256i`][m256i] or an array of [`__m256i`][m256i] using
36//! [`_mm256_loadu_si256()`][loadu_si256]. [`Bitmap`][Bitmap]s of size 128 as
37//! well as the previous gain the [`load_m128i()`][load_m128i] method, which
38//! does the same for [`__m128i`][m128i].
39//!
40//! In addition, [`Bitmap<U128>`][Bitmap] and [`Bitmap<U256>`][Bitmap] will have
41//! `From` and `Into` implementations for [`__m128i`][m128i] and
42//! [`__m256i`][m256i] respectively.
43//!
44//! Note that alignment is unaffected - your bitmaps will be aligned
45//! appropriately for `u128`, not [`__m128i`][m128i] or [`__m256i`][m256i],
46//! unless you arrange for it to be otherwise. This may affect the performance
47//! of SIMD instructions.
48//!
49//! [Bitmap]: struct.Bitmap.html
50//! [load_m128i]: struct.Bitmap.html#method.load_m128i
51//! [load_m256i]: struct.Bitmap.html#method.load_m256i
52//! [m128i]: https://doc.rust-lang.org/core/arch/x86_64/struct.__m128i.html
53//! [m256i]: https://doc.rust-lang.org/core/arch/x86_64/struct.__m256i.html
54//! [loadu_si256]: https://doc.rust-lang.org/core/arch/x86_64/fn._mm256_loadu_si256.html
55
56mod bitmap;
57mod types;
58
59#[doc(inline)]
60pub use crate::bitmap::{Bitmap, Iter};
61#[doc(inline)]
62pub use crate::types::{BitOps, Bits};