Crate itybity 

An itty bitty crate providing bit iterators and bit iterator accessories.

No dependencies, no unsafe, and #![no_std] compatible.

Summary

This crate provides iterators for iterating over the bits of various types, including integers, slices, and strings. These iterators can be conveniently accessed via the provided extension traits, eg ToBits, IntoBits, and StrToBits.

The FromBitIterator trait provides implementations for parsing types from bit iterators.

Performance

This crate was not designed with performance in mind, but rather simplicity. For a more performant and memory efficient alternative, see bitvec.

That being said, the iterators in this crate are still reasonably fast and compact.

Bit Order

Be careful not to confuse bit order with byte order (endianness). Bit order refers to the order in which bits are positioned within a container. See this wiki for more information.

Conventionally, bits are written with the least-significant bit on the right. However, when dealing with bit vectors it is often more intuitive to have the least-significant bit reside at index 0, ie left-most or Lsb0 order.

For example, the number 69 in binary is 01000101, which translates to the following bit vector in Lsb0:

[1, 0, 1, 0, 0, 0, 1, 0]

And the following in Msb0:

[0, 1, 0, 0, 0, 1, 0, 1]

Usage

First, add the following to your Cargo.toml:

[dependencies]
itybity = "0.1"

Examples

use itybity::{ToBits, IntoBits, FromBitIterator, StrToBits};

let byte = 0b1010_1010u8;

// Convert to a Vec<bool> in Lsb0 order.
let bits = byte.to_lsb0_vec();

assert_eq!(bits, vec![false, true, false, true, false, true, false, true]);

// Writing a bit vector using bools is a pain, use a string instead!
//
// Notice that the string is written in Msb0 order, and we reverse it to Lsb0.
let expected_bits = "10101010".iter_bits().rev().collect::<Vec<bool>>();

assert_eq!(bits, expected_bits);

// Convert back to a u8.
let new_byte = u8::from_lsb0_iter(bits);
assert_eq!(byte, new_byte);

// We can work with slices too!
let bytes = vec![0u8, 1u8, 2u8, 3u8];

// Create an iterator over the bits in Msb0 order.
let bits = bytes.iter_msb0();

assert_eq!(bits.len(), 32);

// Convert back to a different type
let data = u32::from_msb0_iter(bits);

// If we have an iterator of values, we can map it to an iterator of bits.
let iter = vec![0u8, 1u8, 2u8, 3u8].into_iter();

let bit_iter = iter.flat_map(IntoBits::into_iter_lsb0);

// And we can parse it back
let values = Vec::<u8>::from_lsb0_iter(bit_iter);

assert_eq!(values, vec![0u8, 1u8, 2u8, 3u8]);

// We can do the same with arrays. Notice that the array is longer, so the last element
// will be 0.
let values = <[u8; 5]>::from_lsb0_iter(values.iter_lsb0());

assert_eq!(values, [0u8, 1u8, 2u8, 3u8, 0u8]);

Features

itybity supports #[no_std] by disabling the default features.

• std: Enables alloc, for use of Vec and String types.

License

Licensed under either of

• Apache License, Version 2.0
• MIT license

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Structs

BitIter

Iterator over bits.

IntoBitIter

A wrapper that converts an iterator over values to an iterator over bits.

Lsb0

Lsb0 bit order.

Msb0

Msb0 bit order.

StrBitIter

Iterator over a bit string.

Traits

BitIterable

A type whose bits can be iterated over.

BitLength

Trait for types with a const bit length.

BitOrder

Marker trait for bit order.

FromBitIterator

Trait used for parsing a value from a bit iterator.

GetBit

Trait for getting a bit at a given index.

IntoBitIterator

Trait for converting iterators over values into iterators over bits.

IntoBits

Trait for converting types into a bit iterator.

StrToBits

Trait for converting bit strings into a bit iterator.

ToBits

Trait for converting types into a borrowing bit iterator.