android/vendor/bitvec-1.0.1/README.md - toolchain/cargo-deny - Git at Google

 <div style="text-align: center;" align="center">

 # `bitvec`

 ## A Magnifying Glass for Memory <!-- omit in toc -->

 [![Crate][crate_img]][crate]
 [![Documentation][docs_img]][docs]
 [![License][license_img]][license_file]

 [![Crate Downloads][downloads_img]][crate]
 [![Project Size][loc_img]][loc]

 </div>

 1. [Summary](#summary)
 1. [Introduction](#introduction)
 1. [Highlights](#highlights)
 1. [Usage](#usage)
 1. [Examples](#examples)
 1. [User Stories](#user-stories)
    1. [Bit Collections](#bit-collections)
    1. [Bit-Field Memory Access](#bit-field-memory-access)
    1. [Transport Protocols](#transport-protocols)
 1. [Feature Flags](#feature-flags)
 1. [Deeper Reading](#deeper-reading)

 ## Summary

 `bitvec` provides a foundational API for bitfields in Rust. It specializes
 standard-library data structures (slices, arrays, and vectors of `bool`) to use
 one-bit-per-`bool` storage, similar to [`std::bitset<N>`] and
 [`std::vector<bool>`] in C++.

 Additionally, it allows a memory region to be divided into arbitrary regions of
 integer storage, like [binaries][erl_bit] in Erlang.

 If you need to view memory as bit-addressed instead of byte-addressed, then
 `bitvec` is the fastest, most complete, and Rust-idiomatic crate for you.

 ## Introduction

 Computers do not operate on bits. The memory bus is byte-addressed, and
 processors operate on register words, which are typically four to eight bytes,
 or even wider. This means that when programmers wish to operate on individual
 bits within a byte of memory or a word of register, they have to do so manually,
 using shift and mask operations that are likely familiar to anyone who has done
 this before.

 `bitvec` brings the capabilities of C++’s compact `bool` storage and Erlang’s
 decomposable bit-streams to Rust, in a package that fits in with your existing
 Rust idioms and in the most capable, performant, implementation possible. The
 bit-stream behavior provides the logic necessary for C-style structural
 bitfields, and syntax sugar for it can be found in [`deku`].

 `bitvec` enables you to write code for bit-addressed memory that is simple,
 easy, and fast. It compiles to the same, or even better, object code than you
 would get from writing shift/mask instructions manually. It leverages Rust’s
 powerful reference and type systems to create a system that seamlessly bridges
 single-bit addressing, precise control of in-memory layout, and Rust-native
 ownership and borrowing mechanisms.

 ## Highlights

 `bitvec` has a number of unique capabilities related to its place as a Rust
 library and as a bit-addressing system.

 - It supports arbitrary bit-addressing, and its bit slices can be munched from
   the front.
 - `BitSlice` is a region type equivalent to `[bool]`, and can be described by
   Rust references and thus fit into reference-based APIs.
 - Type parameters enable users to select the precise memory representation they
   desire.
 - A memory model accounts for element-level aliasing and is safe for concurrent
   use. In particular, the “Beware Bitfields” bug described in
   [this Mozilla report][moz] is simply impossible to produce.
 - Native support for atomic integers as bit-field storage.
 - Users can supply their own translation layer for memory representation if the
   built-in translations are insufficient.

 However, it does also have some small costs associated with its capabilities:

 - `BitSlice` cannot be used as a referent type in pointers, such as `Box`, `Rc`,
   or `Arc`.
 - `BitSlice` cannot implement `IndexMut`, so `bitslice[index] = true;` does not
   work.

 ## Usage

 **Minimum Supported Rust Version**: 1.56.0

 `bitvec` strives to follow the sequence APIs in the standard library. However,
 as most of its functionality is a reïmplementation that does not require the
 standard library to actually have the symbols present, doing so may not require
 an MSRV raise.

 Now that `bitvec` is at 1.0, it will only raise MSRV in minor-edition releases.
 If you have a pinned Rust toolchain, you should depend on `bitvec` with a
 limiting minor-version constraint like `"~1.0"`.

 First, depend on it in your Cargo manifest:

 ```toml
 [dependencies]
 bitvec = "1"
 ```

 > Note: `bitvec` supports `#![no_std]` targets. If you do not have `std`,
 > disable the default features, and explicitly restore any features that you do
 > have:
 >
 > ```toml
 > [dependencies.bitvec]
 > version = "1"
 > default-features = false
 > features = ["atomic", "alloc"]
 > ```

 Once Cargo knows about it, bring its prelude into scope:

 ```rust
 use bitvec::prelude::*;
 ```

 You can read the [prelude reëxports][prelude] to see exactly which symbols are
 being imported. The prelude brings in many symbols, and while name collisions
 are not likely, you may wish to instead import the prelude *module* rather than
 its contents:

 ```rust
 use bitvec::prelude as bv;
 ```

 You should almost certainly use type aliases to make names for specific
 instantiations of `bitvec` type parameters, and use that rather than attempting
 to remain generic over an `<T: BitStore, O: BitOrder>` pair throughout your
 project.

 ## Examples

 ```rust
 use bitvec::prelude::*;

 // All data-types have macro
 // constructors.
 let arr = bitarr![u32, Lsb0; 0; 80];
 let bits = bits![u16, Msb0; 0; 40];

 // Unsigned integers (scalar, array,
 // and slice) can be borrowed.
 let data = 0x2021u16;
 let bits = data.view_bits::<Msb0>();
 let data = [0xA5u8, 0x3C];
 let bits = data.view_bits::<Lsb0>();

 // Bit-slices can split anywhere.
 let (head, rest) = bits.split_at(4);
 assert_eq!(head, bits[.. 4]);
 assert_eq!(rest, bits[4 ..]);

 // And they are writable!
 let mut data = [0u8; 2];
 let bits = data.view_bits_mut::<Lsb0>();
 // l and r each own one byte.
 let (l, r) = bits.split_at_mut(8);

 // but now a, b, c, and d own a nibble!
 let ((a, b), (c, d)) = (
   l.split_at_mut(4),
   r.split_at_mut(4),
 );

 // and all four of them are writable.
 a.set(0, true);
 b.set(1, true);
 c.set(2, true);
 d.set(3, true);

 assert!(bits[0]);  // a[0]
 assert!(bits[5]);  // b[1]
 assert!(bits[10]); // c[2]
 assert!(bits[15]); // d[3]

 // `BitSlice` is accessed by reference,
 // which means it respects NLL styles.
 assert_eq!(data, [0x21u8, 0x84]);

 // Furthermore, bit-slices can store
 // ordinary integers:
 let eight = [0u8, 4, 8, 12, 16, 20, 24, 28];
 //           a    b  c  d   e   f   g   h
 let mut five = [0u8; 5];
 for (slot, byte) in five
   .view_bits_mut::<Msb0>()
   .chunks_mut(5)
   .zip(eight.iter().copied())
 {
   slot.store_be(byte);
   assert_eq!(slot.load_be::<u8>(), byte);
 }

 assert_eq!(five, [
   0b00000_001,
 //  aaaaa bbb
   0b00_01000_0,
 //  bb ccccc d
   0b1100_1000,
 //  dddd eeee
   0b0_10100_11,
 //  e fffff gg
   0b000_11100,
 //  ggg hhhhh
 ]);
 ```

 The `BitSlice` type is a view that alters the behavior of a borrowed memory
 region. It is never held directly, but only by references (created by borrowing
 integer memory) or the `BitArray` value type. In addition, the presence of a
 dynamic allocator enables the `BitBox` and `BitVec` buffer types, which can be
 used for more advanced buffer manipulation:

 ```rust
 #[cfg(feature = "alloc")]
 fn main() {

 use bitvec::prelude::*;

 let mut bv = bitvec![u8, Msb0;];
 bv.push(false);
 bv.push(true);
 bv.extend([false; 4].iter());
 bv.extend(&15u8.view_bits::<Lsb0>()[.. 4]);

 assert_eq!(bv.as_raw_slice(), &[
   0b01_0000_11, 0b11_000000
 //                   ^ dead
 ]);

 }
 ```

 While place expressions like `bits[index] = value;` are not available, `bitvec`
 instead provides a proxy structure that can be used as *nearly* an `&mut bit`
 reference:

 ```rust
 use bitvec::prelude::*;

 let bits = bits![mut 0];
 // `bit` is not a reference, so
 // it must be bound with `mut`.
 let mut bit = bits.get_mut(0).unwrap();
 assert!(!*bit);
 *bit = true;
 assert!(*bit);
 // `bit` is not a reference,
 // so NLL rules do not apply.
 drop(bit);
 assert!(bits[0]);
 ```

 The `bitvec` data types implement a complete replacement for their
 standard-library counterparts, including all of the inherent methods, traits,
 and operator behaviors.

 ## User Stories

 Uses of `bitvec` generally fall into three major genres.

 - compact, fast, `usize => bit` collections
 - truncated integer storage
 - precise control of memory layout

 ### Bit Collections

 At its most basic, `bitvec` provides sequence types analogous to the standard
 library’s `bool` collections. The default behavior is optimized for fast memory
 access and simple codegen, and can compact `[bool]` or `Vec<bool>` with minimal
 overhead.

 While `bitvec` does not attempt to take advantage of SIMD or other vectorized
 instructions in its default work, its codegen should be a good candidate for
 autovectorization in LLVM. If explicit vectorization is important to you, please
 [file an issue][issue].

 Example uses might be implementing a Sieve of Eratosthenes to store primes, or
 other collections that test a yes/no property of a number; or replacing
 `Vec<Option<T>>` with `(BitVec, Vec<MaybeUninit<T>>`).

 To get started, you can perform basic text replacement on your project.
 Translate any existing types as follows:

 - `[bool; N]` becomes `BitArray`
 - `[bool]` becomes `BitSlice`
 - `Vec<bool>` becomes `BitVec`
 - `Box<[bool]>` becomes `BitBox`

 and then follow any compiler errors that arise.

 ### Bit-Field Memory Access

 A single bit of information has very few uses. `bitvec` also enables you to
 store integers wider than a single bit, by selecting a bit-slice and using the
 [`BitField`] trait on it. You can store and retrieve both unsigned and signed
 integers, as long as the ordering type parameter is [`Lsb0`] or [`Msb0`].

 If your bit-field storage buffers are never serialized for exchange between
 machines, then you can get away with using the default type parameters and
 unadorned load/store methods. While the in-memory layout of stored integers may
 be surprising if directly inspected, the overall behavior should be optimal for
 your target.

 Remember: `bitvec` only provides array place expressions, using integer start
 and end points. You can use [`deku`] if you want C-style named structural fields
 with bit-field memory storage.

 However, if you are de/serializing buffers for transport, then you fall into the
 third category.

 ### Transport Protocols

 Many protocols use sub-element fields in order to save space in transport; for
 example, TCP headers have single-bit and 4-bit fields in order to pack all the
 needed information into a desirable amount of space. In C or Erlang, these TCP
 protocol fields could be mapped by record fields in the language. In Rust, they
 can be mapped by indexing into a bit-slice.

 When using `bitvec` to manage protocol buffers, you will need to select the
 exact type parameters that match your memory layout. For instance, TCP uses
 `<u8, Msb0>`, while IPv6 on a little-endian machine uses `<u32, Lsb0>`. Once you
 have done this, you can replace all of your `(memory & mask) >> shift` or
 `memory |= (value & mask) << shift` expressions with `memory[start .. end]`.

 As a direct example, the Itanium instruction set IA-64 uses very-long
 instruction words containing three 41-bit fields in a `[u8; 16]`. One IA-64
 disassembler replaced its manual shift/mask implementation with `bitvec` range
 indexing, taking the bit numbers directly from the datasheet, and observed that
 their code was both easier to maintain and also had better performance as a
 result!

 ## Feature Flags

 `bitvec` has a few Cargo features that govern its API surface. The default
 feature set is:

 ```toml
 [dependencies.bitvec]
 version = "1"
 features = [
   "alloc",
   "atomic",
   # "serde",
   "std",
 ]
 ```

 Use `default-features = false` to disable all of them, then `features = []` to
 restore the ones you need.

 - `alloc`: This links against the `alloc` distribution crate, and provides the
   `BitVec` and `BitBox` types. It can be used on `#![no_std]` targets that
   possess a dynamic allocator but not an operating system.

 - `atomic`: This controls whether atomic instructions can be used for aliased
   memory. `bitvec` uses the [`radium`] crate to perform automatic detection of
   atomic capability, and targets that do not possess atomic instructions can
   still function with this feature *enabled*. Its only effect is that targets
   which do have atomic instructions may choose to disable it and enforce
   single-threaded behavior that never incurs atomic synchronization.

 - `serde`: This enables the de/serialization of `bitvec` buffers through the
   `serde` system. This can be useful if you need to transmit `usize => bool`
   collections.

 - `std`: This provides some `std::io::{Read,Write}` implementations, as well as
   `std::error::Error` for the various error types. It is otherwise unnecessary.

 ## Deeper Reading

 The [API Documentation][docsrs] explores `bitvec`’s usage and implementation in
 great detail. In particular, you should read the documentation for the
 [`order`], [`store`], and [`field`] modules, as well as the [`BitSlice`] and
 [`BitArray`] types.

 In addition, the [user guide][guide] explores the philosophical and academic
 concepts behind `bitvec`’s construction, its goals, and the more intricate parts
 of its behavior.

 While you should be able to get started with `bitvec` with only dropping it into
 your code and using the same habits you have with the standard library, both of
 these resources contain all of the information needed to understand what it
 does, how it works, and how it can be useful to you.

 <!-- Badges -->
 [crate]: https://crates.io/crates/bitvec "Crate listing"
 [crate_img]: https://img.shields.io/crates/v/bitvec.svg?logo=rust&style=for-the-badge "Crate badge"
 [docs]: https://docs.rs/bitvec/latest/bitvec "Crate documentation"
 [docs_img]: https://img.shields.io/docsrs/bitvec/latest.svg?style=for-the-badge "Documentation badge"
 [downloads_img]: https://img.shields.io/crates/dv/bitvec.svg?logo=rust&style=for-the-badge "Crate downloads"
 [license_file]: https://github.com/bitvecto-rs/bitvec/blob/main/LICENSE.txt "Project license"
 [license_img]: https://img.shields.io/crates/l/bitvec.svg?style=for-the-badge "License badge"
 [loc]: https://github.com/bitvecto-rs/bitvec "Project repository"
 [loc_img]: https://img.shields.io/tokei/lines/github/bitvecto-rs/bitvec?category=code&style=for-the-badge "Project size"

 <!-- Documentation -->
 [`BitArray`]: https://docs.rs/bitvec/latest/bitvec/array/struct.BitArray.html
 [`BitField`]: https://docs.rs/bitvec/latest/bitvec/field/trait.BitField.html
 [`BitSlice`]: https://docs.rs/bitvec/latest/bitvec/slice/struct.BitSlice.html
 [`Lsb0`]: https://docs.rs/bitvec/latest/bitvec/order/struct.Lsb0.html
 [`Msb0`]: https://docs.rs/bitvec/latest/bitvec/order/struct.Msb0.html
 [`field`]: https://docs.rs/bitvec/latest/bitvec/field/index.html
 [`order`]: https://docs.rs/bitvec/latest/bitvec/order/index.html
 [`store`]: https://docs.rs/bitvec/latest/bitvec/store/index.html
 [layout]: https://bitvecto-rs.github.io/bitvec/memory-representation
 [prelude]: https://docs.rs/bitvec/latest/bitvec/prelude

 <!-- External References -->
 [`deku`]: https://crates.io/crates/deku
 [docsrs]: https://docs.rs/bitvec/latest/bitvec
 [erl_bit]: https://www.erlang.org/doc/programming_examples/bit_syntax.html
 [guide]: https://bitvecto-rs.github.io/bitvec/
 [issue]: https://github.com/bitvecto-rs/bitvec/issues/new
 [moz]: https://hacks.mozilla.org/2021/04/eliminating-data-races-in-firefox-a-technical-report/ "Mozilla Hacks article describing various concurrency bugs in FireFox"
 [`radium`]: https://crates.io/crates/radium
 [`std::bitset<N>`]: https://en.cppreference.com/w/cpp/utility/bitset
 [`std::vector<bool>`]: https://en.cppreference.com/w/cpp/container/vector_bool
	<div style="text-align: center;" align="center">

	# `bitvec`

	## A Magnifying Glass for Memory <!-- omit in toc -->

	[![Crate][crate_img]][crate]
	[![Documentation][docs_img]][docs]
	[![License][license_img]][license_file]

	[![Crate Downloads][downloads_img]][crate]
	[![Project Size][loc_img]][loc]

	</div>

	1. [Summary](#summary)
	1. [Introduction](#introduction)
	1. [Highlights](#highlights)
	1. [Usage](#usage)
	1. [Examples](#examples)
	1. [User Stories](#user-stories)
	1. [Bit Collections](#bit-collections)
	1. [Bit-Field Memory Access](#bit-field-memory-access)
	1. [Transport Protocols](#transport-protocols)
	1. [Feature Flags](#feature-flags)
	1. [Deeper Reading](#deeper-reading)

	## Summary

	`bitvec` provides a foundational API for bitfields in Rust. It specializes
	standard-library data structures (slices, arrays, and vectors of `bool`) to use
	one-bit-per-`bool` storage, similar to [`std::bitset<N>`] and
	[`std::vector<bool>`] in C++.

	Additionally, it allows a memory region to be divided into arbitrary regions of
	integer storage, like [binaries][erl_bit] in Erlang.

	If you need to view memory as bit-addressed instead of byte-addressed, then
	`bitvec` is the fastest, most complete, and Rust-idiomatic crate for you.

	## Introduction

	Computers do not operate on bits. The memory bus is byte-addressed, and
	processors operate on register words, which are typically four to eight bytes,
	or even wider. This means that when programmers wish to operate on individual
	bits within a byte of memory or a word of register, they have to do so manually,
	using shift and mask operations that are likely familiar to anyone who has done
	this before.

	`bitvec` brings the capabilities of C++’s compact `bool` storage and Erlang’s
	decomposable bit-streams to Rust, in a package that fits in with your existing
	Rust idioms and in the most capable, performant, implementation possible. The
	bit-stream behavior provides the logic necessary for C-style structural
	bitfields, and syntax sugar for it can be found in [`deku`].

	`bitvec` enables you to write code for bit-addressed memory that is simple,
	easy, and fast. It compiles to the same, or even better, object code than you
	would get from writing shift/mask instructions manually. It leverages Rust’s
	powerful reference and type systems to create a system that seamlessly bridges
	single-bit addressing, precise control of in-memory layout, and Rust-native
	ownership and borrowing mechanisms.

	## Highlights

	`bitvec` has a number of unique capabilities related to its place as a Rust
	library and as a bit-addressing system.

	- It supports arbitrary bit-addressing, and its bit slices can be munched from
	the front.
	- `BitSlice` is a region type equivalent to `[bool]`, and can be described by
	Rust references and thus fit into reference-based APIs.
	- Type parameters enable users to select the precise memory representation they
	desire.
	- A memory model accounts for element-level aliasing and is safe for concurrent
	use. In particular, the “Beware Bitfields” bug described in
	[this Mozilla report][moz] is simply impossible to produce.
	- Native support for atomic integers as bit-field storage.
	- Users can supply their own translation layer for memory representation if the
	built-in translations are insufficient.

	However, it does also have some small costs associated with its capabilities:

	- `BitSlice` cannot be used as a referent type in pointers, such as `Box`, `Rc`,
	or `Arc`.
	- `BitSlice` cannot implement `IndexMut`, so `bitslice[index] = true;` does not
	work.

	## Usage

	Minimum Supported Rust Version: 1.56.0

	`bitvec` strives to follow the sequence APIs in the standard library. However,
	as most of its functionality is a reïmplementation that does not require the
	standard library to actually have the symbols present, doing so may not require
	an MSRV raise.

	Now that `bitvec` is at 1.0, it will only raise MSRV in minor-edition releases.
	If you have a pinned Rust toolchain, you should depend on `bitvec` with a
	limiting minor-version constraint like `"~1.0"`.

	First, depend on it in your Cargo manifest:

	```toml
	[dependencies]
	bitvec = "1"
	```

	> Note: `bitvec` supports `#![no_std]` targets. If you do not have `std`,
	> disable the default features, and explicitly restore any features that you do
	> have:
	>
	> ```toml
	> [dependencies.bitvec]
	> version = "1"
	> default-features = false
	> features = ["atomic", "alloc"]
	> ```

	Once Cargo knows about it, bring its prelude into scope:

	```rust
	use bitvec::prelude::*;
	```

	You can read the [prelude reëxports][prelude] to see exactly which symbols are
	being imported. The prelude brings in many symbols, and while name collisions
	are not likely, you may wish to instead import the prelude module rather than
	its contents:

	```rust
	use bitvec::prelude as bv;
	```

	You should almost certainly use type aliases to make names for specific
	instantiations of `bitvec` type parameters, and use that rather than attempting
	to remain generic over an `<T: BitStore, O: BitOrder>` pair throughout your
	project.

	## Examples

	```rust
	use bitvec::prelude::*;

	// All data-types have macro
	// constructors.
	let arr = bitarr![u32, Lsb0; 0; 80];
	let bits = bits![u16, Msb0; 0; 40];

	// Unsigned integers (scalar, array,
	// and slice) can be borrowed.
	let data = 0x2021u16;
	let bits = data.view_bits::<Msb0>();
	let data = [0xA5u8, 0x3C];
	let bits = data.view_bits::<Lsb0>();

	// Bit-slices can split anywhere.
	let (head, rest) = bits.split_at(4);
	assert_eq!(head, bits[.. 4]);
	assert_eq!(rest, bits[4 ..]);

	// And they are writable!
	let mut data = [0u8; 2];
	let bits = data.view_bits_mut::<Lsb0>();
	// l and r each own one byte.
	let (l, r) = bits.split_at_mut(8);

	// but now a, b, c, and d own a nibble!
	let ((a, b), (c, d)) = (
	l.split_at_mut(4),
	r.split_at_mut(4),
	);

	// and all four of them are writable.
	a.set(0, true);
	b.set(1, true);
	c.set(2, true);
	d.set(3, true);

	assert!(bits[0]); // a[0]
	assert!(bits[5]); // b[1]
	assert!(bits[10]); // c[2]
	assert!(bits[15]); // d[3]

	// `BitSlice` is accessed by reference,
	// which means it respects NLL styles.
	assert_eq!(data, [0x21u8, 0x84]);

	// Furthermore, bit-slices can store
	// ordinary integers:
	let eight = [0u8, 4, 8, 12, 16, 20, 24, 28];
	// a b c d e f g h
	let mut five = [0u8; 5];
	for (slot, byte) in five
	.view_bits_mut::<Msb0>()
	.chunks_mut(5)
	.zip(eight.iter().copied())
	{
	slot.store_be(byte);
	assert_eq!(slot.load_be::<u8>(), byte);
	}

	assert_eq!(five, [
	0b00000_001,
	// aaaaa bbb
	0b00_01000_0,
	// bb ccccc d
	0b1100_1000,
	// dddd eeee
	0b0_10100_11,
	// e fffff gg
	0b000_11100,
	// ggg hhhhh
	]);
	```

	The `BitSlice` type is a view that alters the behavior of a borrowed memory
	region. It is never held directly, but only by references (created by borrowing
	integer memory) or the `BitArray` value type. In addition, the presence of a
	dynamic allocator enables the `BitBox` and `BitVec` buffer types, which can be
	used for more advanced buffer manipulation:

	```rust
	#[cfg(feature = "alloc")]
	fn main() {

	use bitvec::prelude::*;

	let mut bv = bitvec![u8, Msb0;];
	bv.push(false);
	bv.push(true);
	bv.extend([false; 4].iter());
	bv.extend(&15u8.view_bits::<Lsb0>()[.. 4]);

	assert_eq!(bv.as_raw_slice(), &[
	0b01_0000_11, 0b11_000000
	// ^ dead
	]);

	}
	```

	While place expressions like `bits[index] = value;` are not available, `bitvec`
	instead provides a proxy structure that can be used as nearly an `&mut bit`
	reference:

	```rust
	use bitvec::prelude::*;

	let bits = bits![mut 0];
	// `bit` is not a reference, so
	// it must be bound with `mut`.
	let mut bit = bits.get_mut(0).unwrap();
	assert!(!*bit);
	*bit = true;
	assert!(*bit);
	// `bit` is not a reference,
	// so NLL rules do not apply.
	drop(bit);
	assert!(bits[0]);
	```

	The `bitvec` data types implement a complete replacement for their
	standard-library counterparts, including all of the inherent methods, traits,
	and operator behaviors.

	## User Stories

	Uses of `bitvec` generally fall into three major genres.

	- compact, fast, `usize => bit` collections
	- truncated integer storage
	- precise control of memory layout

	### Bit Collections

	At its most basic, `bitvec` provides sequence types analogous to the standard
	library’s `bool` collections. The default behavior is optimized for fast memory
	access and simple codegen, and can compact `[bool]` or `Vec<bool>` with minimal
	overhead.

	While `bitvec` does not attempt to take advantage of SIMD or other vectorized
	instructions in its default work, its codegen should be a good candidate for
	autovectorization in LLVM. If explicit vectorization is important to you, please
	[file an issue][issue].

	Example uses might be implementing a Sieve of Eratosthenes to store primes, or
	other collections that test a yes/no property of a number; or replacing
	`Vec<Option<T>>` with `(BitVec, Vec<MaybeUninit<T>>`).

	To get started, you can perform basic text replacement on your project.
	Translate any existing types as follows:

	- `[bool; N]` becomes `BitArray`
	- `[bool]` becomes `BitSlice`
	- `Vec<bool>` becomes `BitVec`
	- `Box<[bool]>` becomes `BitBox`

	and then follow any compiler errors that arise.

	### Bit-Field Memory Access

	A single bit of information has very few uses. `bitvec` also enables you to
	store integers wider than a single bit, by selecting a bit-slice and using the
	[`BitField`] trait on it. You can store and retrieve both unsigned and signed
	integers, as long as the ordering type parameter is [`Lsb0`] or [`Msb0`].

	If your bit-field storage buffers are never serialized for exchange between
	machines, then you can get away with using the default type parameters and
	unadorned load/store methods. While the in-memory layout of stored integers may
	be surprising if directly inspected, the overall behavior should be optimal for
	your target.

	Remember: `bitvec` only provides array place expressions, using integer start
	and end points. You can use [`deku`] if you want C-style named structural fields
	with bit-field memory storage.

	However, if you are de/serializing buffers for transport, then you fall into the
	third category.

	### Transport Protocols

	Many protocols use sub-element fields in order to save space in transport; for
	example, TCP headers have single-bit and 4-bit fields in order to pack all the
	needed information into a desirable amount of space. In C or Erlang, these TCP
	protocol fields could be mapped by record fields in the language. In Rust, they
	can be mapped by indexing into a bit-slice.

	When using `bitvec` to manage protocol buffers, you will need to select the
	exact type parameters that match your memory layout. For instance, TCP uses
	`<u8, Msb0>`, while IPv6 on a little-endian machine uses `<u32, Lsb0>`. Once you
	have done this, you can replace all of your `(memory & mask) >> shift` or
	`memory \|= (value & mask) << shift` expressions with `memory[start .. end]`.

	As a direct example, the Itanium instruction set IA-64 uses very-long
	instruction words containing three 41-bit fields in a `[u8; 16]`. One IA-64
	disassembler replaced its manual shift/mask implementation with `bitvec` range
	indexing, taking the bit numbers directly from the datasheet, and observed that
	their code was both easier to maintain and also had better performance as a
	result!

	## Feature Flags

	`bitvec` has a few Cargo features that govern its API surface. The default
	feature set is:

	```toml
	[dependencies.bitvec]
	version = "1"
	features = [
	"alloc",
	"atomic",
	# "serde",
	"std",
	]
	```

	Use `default-features = false` to disable all of them, then `features = []` to
	restore the ones you need.

	- `alloc`: This links against the `alloc` distribution crate, and provides the
	`BitVec` and `BitBox` types. It can be used on `#![no_std]` targets that
	possess a dynamic allocator but not an operating system.

	- `atomic`: This controls whether atomic instructions can be used for aliased
	memory. `bitvec` uses the [`radium`] crate to perform automatic detection of
	atomic capability, and targets that do not possess atomic instructions can
	still function with this feature enabled. Its only effect is that targets
	which do have atomic instructions may choose to disable it and enforce
	single-threaded behavior that never incurs atomic synchronization.

	- `serde`: This enables the de/serialization of `bitvec` buffers through the
	`serde` system. This can be useful if you need to transmit `usize => bool`
	collections.

	- `std`: This provides some `std::io::{Read,Write}` implementations, as well as
	`std::error::Error` for the various error types. It is otherwise unnecessary.

	## Deeper Reading

	The [API Documentation][docsrs] explores `bitvec`’s usage and implementation in
	great detail. In particular, you should read the documentation for the
	[`order`], [`store`], and [`field`] modules, as well as the [`BitSlice`] and
	[`BitArray`] types.

	In addition, the [user guide][guide] explores the philosophical and academic
	concepts behind `bitvec`’s construction, its goals, and the more intricate parts
	of its behavior.

	While you should be able to get started with `bitvec` with only dropping it into
	your code and using the same habits you have with the standard library, both of
	these resources contain all of the information needed to understand what it
	does, how it works, and how it can be useful to you.

	<!-- Badges -->
	[crate]: https://crates.io/crates/bitvec "Crate listing"
	[crate_img]: https://img.shields.io/crates/v/bitvec.svg?logo=rust&style=for-the-badge "Crate badge"
	[docs]: https://docs.rs/bitvec/latest/bitvec "Crate documentation"
	[docs_img]: https://img.shields.io/docsrs/bitvec/latest.svg?style=for-the-badge "Documentation badge"
	[downloads_img]: https://img.shields.io/crates/dv/bitvec.svg?logo=rust&style=for-the-badge "Crate downloads"
	[license_file]: https://github.com/bitvecto-rs/bitvec/blob/main/LICENSE.txt "Project license"
	[license_img]: https://img.shields.io/crates/l/bitvec.svg?style=for-the-badge "License badge"
	[loc]: https://github.com/bitvecto-rs/bitvec "Project repository"
	[loc_img]: https://img.shields.io/tokei/lines/github/bitvecto-rs/bitvec?category=code&style=for-the-badge "Project size"

	<!-- Documentation -->
	[`BitArray`]: https://docs.rs/bitvec/latest/bitvec/array/struct.BitArray.html
	[`BitField`]: https://docs.rs/bitvec/latest/bitvec/field/trait.BitField.html
	[`BitSlice`]: https://docs.rs/bitvec/latest/bitvec/slice/struct.BitSlice.html
	[`Lsb0`]: https://docs.rs/bitvec/latest/bitvec/order/struct.Lsb0.html
	[`Msb0`]: https://docs.rs/bitvec/latest/bitvec/order/struct.Msb0.html
	[`field`]: https://docs.rs/bitvec/latest/bitvec/field/index.html
	[`order`]: https://docs.rs/bitvec/latest/bitvec/order/index.html
	[`store`]: https://docs.rs/bitvec/latest/bitvec/store/index.html
	[layout]: https://bitvecto-rs.github.io/bitvec/memory-representation
	[prelude]: https://docs.rs/bitvec/latest/bitvec/prelude

	<!-- External References -->
	[`deku`]: https://crates.io/crates/deku
	[docsrs]: https://docs.rs/bitvec/latest/bitvec
	[erl_bit]: https://www.erlang.org/doc/programming_examples/bit_syntax.html
	[guide]: https://bitvecto-rs.github.io/bitvec/
	[issue]: https://github.com/bitvecto-rs/bitvec/issues/new
	[moz]: https://hacks.mozilla.org/2021/04/eliminating-data-races-in-firefox-a-technical-report/ "Mozilla Hacks article describing various concurrency bugs in FireFox"
	[`radium`]: https://crates.io/crates/radium
	[`std::bitset<N>`]: https://en.cppreference.com/w/cpp/utility/bitset
	[`std::vector<bool>`]: https://en.cppreference.com/w/cpp/container/vector_bool