Struct bitvec::slice::BitSlice

#[repr(transparent)]pub struct BitSlice<O = Local, T = usize> where
    O: BitOrder,
    T: BitStore,  { /* fields omitted */ }

A compact slice of bits, whose order and storage types can be customized.

BitSlice is a specialized slice type, which can only ever be held by reference or specialized owning pointers provided by this crate. The value patterns of its handles are opaque binary structures, which cannot be meaningfully inspected by user code.

BitSlice can only be dynamically allocated by this library. Creation of any other BitSlice collections will result in severely incorrect behavior.

A BitSlice reference can be created through the bitvec! macro, from a BitVec collection, or from most common Rust types (fundamentals, slices of them, and small arrays) using the Bits and BitsMut traits.

BitSlices are a view into a block of memory at bit-level resolution. They are represented by a crate-internal pointer structure that cannot be used with other Rust code except through the provided conversion APIs.

use bitvec::prelude::*;

let bv = bitvec![0, 1, 0, 1];
//  slicing a bitvec
let bslice: &BitSlice = &bv[..];

//  coercing an array to a bitslice
let bslice: &BitSlice<_, _> = [1u8, 254u8].bits::<Msb0>();

Bit slices are either mutable or shared. The shared slice type is &BitSlice<O, T>, while the mutable slice type is &mut BitSlice<O, T>. For example, you can mutate bits in the memory to which a mutable BitSlice points:

use bitvec::prelude::*;

let mut base = [0u8, 0, 0, 0];
{
 let bs: &mut BitSlice<_, _> = base.bits_mut::<Msb0>();
 bs.set(13, true);
 eprintln!("{:?}", bs.as_ref());
 assert!(bs[13]);
}
assert_eq!(base[1], 4);

Type Parameters

• O: An implementor of the BitOrder trait. This type is used to convert semantic indices into concrete bit positions in elements, and store or retrieve bit values from the storage type.
• T: An implementor of the BitStore trait: u8, u16, u32, or u64 (64-bit systems only). This is the actual type in memory that the slice will use to store data.

Safety

The &BitSlice reference handle has the same size as standard Rust slice handles, but it is extremely value-incompatible with them. Attempting to treat &BitSlice<_, T> as &[T] in any manner except through the provided APIs is catastrophically unsafe and unsound.

Implementations

impl<O, T> BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

Reimplementation of the [T] inherent-method API.

pub fn len(&self) -> usize

Returns the number of bits in the slice.

Original

slice::len

Examples

let bits = 0u8.bits::<Local>();
assert_eq!(bits.len(), 8);

pub fn is_empty(&self) -> bool

Returns true if the slice has a length of 0.

Original

slice::is_empty

Examples

let bits = 0u8.bits::<Local>();
assert!(!bits.is_empty());

assert!(BitSlice::<Local, usize>::empty().is_empty())

pub fn first(&self) -> Option<&bool>

Returns the first bit of the slice, or None if it is empty.

Original

slice::first

Examples

let bits = 1u8.bits::<Lsb0>();
assert_eq!(bits.first(), Some(&true));

assert!(BitSlice::<Local, usize>::empty().first().is_none());

pub fn first_mut(&mut self) -> Option<BitMut<'_, O, T>>

Returns a mutable pointer to the first bit of the slice, or None if it is empty.

Original

slice::first_mut

Examples

let mut data = 0u8;
let bits = data.bits_mut::<Lsb0>();
if let Some(mut first) = bits.first_mut() {
    *first = true;
}
assert_eq!(data, 1u8);

pub fn split_first(&self) -> Option<(&bool, &Self)>

Returns the first and all the rest of the bits of the slice, or None if it is empty.

Examples

let bits = 1u8.bits::<Lsb0>();
if let Some((first, rest)) = bits.split_first() {
    assert_eq!(first, &true);
    assert_eq!(rest, &bits[1 ..]);
}

pub fn split_first_mut(&mut self) -> Option<(BitMut<'_, O, T>, &mut Self)>

Returns the first and all the rest of the bits of the slice, or None if it is empty.

Examples

let mut data = 0u8;
let bits = data.bits_mut::<Lsb0>();
if let Some((mut first, rest)) = bits.split_first_mut() {
    *first = true;
    *rest.at(0) = true;
    *rest.at(1) = true;
}
assert_eq!(data, 7);

pub fn split_last(&self) -> Option<(&bool, &Self)>

Returns the last and all the rest of the bits of the slice, or None if it is empty.

Examples

let bits = 1u8.bits::<Msb0>();
if let Some((last, rest)) = bits.split_last() {
    assert_eq!(last, &true);
    assert_eq!(rest, &bits[.. 7]);
}

pub fn split_last_mut(&mut self) -> Option<(BitMut<'_, O, T>, &mut Self)>

Returns the last and all the rest of the bits of the slice, or None if it is empty.

Examples

let mut data = 0u8;
let bits = data.bits_mut::<Msb0>();
if let Some((mut last, rest)) = bits.split_last_mut() {
    *last = true;
    *rest.at(0) = true;
    *rest.at(1) = true;
}
assert_eq!(data, 128 | 64 | 1);

pub fn last(&self) -> Option<&bool>

Returns the last bit of the slice, or None if it is empty.

Examples

let bits = 1u8.bits::<Msb0>();
assert_eq!(Some(&true), bits.last());
assert!(BitSlice::<Local, usize>::empty().last().is_none());

pub fn last_mut(&mut self) -> Option<BitMut<'_, O, T>>

Returns a mutable pointer to the last bit in the slice.

Examples

let mut data = 0u8;
let bits = data.bits_mut::<Msb0>();
if let Some(mut last) = bits.last_mut() {
    *last = true;
}
assert!(bits[7]);

pub fn get<'a, I>(&'a self, index: I) -> Option<I::Immut> where
    I: BitSliceIndex<'a, O, T>, 

Returns a reference to a bit or subslice depending on the type of index.

• If given a position, returns a reference to the bit at that position or None if out of bounds.
• If given a range, returns the subslice corresponding to that range, or None if out of bounds.

Examples

let data = 1u8;
let bits = data.bits::<Lsb0>();
assert_eq!(Some(&true), bits.get(0));
assert!(bits.get(8).is_none());
assert!(bits.get(1 ..).expect("in bounds").not_any());
assert!(bits.get(.. 12).is_none());

pub fn get_mut<'a, I>(&'a mut self, index: I) -> Option<I::Mut> where
    I: BitSliceIndex<'a, O, T>, 

Returns a mutable reference to a bit or subslice depending on the type of index (see get) or None if the index is out of bounds.

Examples

let mut data = 0u8;
let bits = data.bits_mut::<Lsb0>();
if let Some(mut bit) = bits.get_mut(1) {
    *bit = true;
}
if let Some(bits) = bits.get_mut(5 .. 7) {
    bits.set_all(true);
}
assert_eq!(data, 64 | 32 | 2);

pub unsafe fn get_unchecked<'a, I>(&'a self, index: I) -> I::Immut where
    I: BitSliceIndex<'a, O, T>, 

Returns a reference to a bit or subslice, without doing bounds checking.

This is generally not recommended; use with caution! For a safe alternative, see get.

Safety

As this function does not perform boundary checking, the caller must ensure that self is an index within the boundaries of slice before calling in order to avoid boundary escapes and ensuing safety violations.

Examples

let data = 4u8;
let bits = data.bits::<Lsb0>();
unsafe {
    assert!(bits.get_unchecked(2));
    assert!(!bits.get_unchecked(1));
}

pub unsafe fn get_unchecked_mut<'a, I>(&'a mut self, index: I) -> I::Mut where
    I: BitSliceIndex<'a, O, T>, 

Returns a mutable reference to a bit or subslice, without doing bounds checking.

This is generally not recommended; use with caution! For a safe alternative, see get_mut.

Safety

As this function does not perform boundary checking, the caller must ensure that self is an index within the boundaries of slice before calling in order to avoid boundary escapes and ensuing safety violations.

Examples

let mut data = 0u8;
let bits = data.bits_mut::<Msb0>();
unsafe {
    let mut bit = bits.get_unchecked_mut(0);
    *bit = true;
    drop(bit); // release the borrow immediately
    let bits = bits.get_unchecked_mut(6 ..);
    bits.set_all(true);
}
assert_eq!(data, 1 | 2 | 128);

pub fn as_ptr(&self) -> *const T

Returns a raw pointer to the slice’s buffer.

The caller must ensure that the slice outlives the pointer this function returns, or else it will end up pointing to garbage.

The caller must also ensure that the memory the pointer (non-transitively) points to is never written to (except inside an UnsafeCell) using this pointer or any pointer derived from it. If you need to mutate the contents of the buffer, use as_mut_ptr.

Modifying the container referenced by this slice may cause its buffer to be reallocated, which would also make any pointers to it invalid.

Notes

This pointer is always to the first T element in the backing storage, even if that element is only partially used by the self slice. Multiple separate BitSlice handles may produce the same pointer with this method.

Examples

let data = [0u8; 2];
let bits = data.bits::<Msb0>();
let (head, rest) = bits.split_at(4);
assert_eq!(head.as_ptr(), rest.as_ptr());

pub fn as_mut_ptr(&mut self) -> *mut T

Returns an unsafe mutable pointer to the slice’s buffer.

The caller must ensure thath the slice outlives the pointer this function returns, or else it will end up pointing to garbage.

Modifying the container referenced by this slice may couse its buffer to be reallocated, which would also make any pointers to it invalid.

Notes

This pointer is always to the first T element in the backing storage, even if that element is only partially used by the self slice. Multiple separate BitSlice handles may produce the same pointer with this method.

Examples

let mut data = [0u8; 2];
let bits = data.bits_mut::<Msb0>();
let (head, rest) = bits.split_at_mut(4);
assert_eq!(head.as_mut_ptr(), rest.as_mut_ptr());
unsafe { *head.as_mut_ptr() = 2; }
assert!(rest[2]);

pub fn swap(&mut self, a: usize, b: usize)

Swaps two bits in the slice.

Arguments

• a: The index of the first bit
• b: The index of the second bit

Panics

Panics if a or b are out of bounds.

Examples

let mut data = 2u8;
let bits = data.bits_mut::<Lsb0>();
bits.swap(0, 1);
assert_eq!(data, 1);

pub fn reverse(&mut self)

Reverses the order of bits in the slice, in place.

Examples

use bitvec::prelude::*;
let mut data = 0b1_1001100u8;
let bits = data.bits_mut::<Msb0>();
bits[1 ..].reverse();
assert_eq!(data, 0b1_0011001);

pub fn iter(&self) -> Iter<'_, O, T>

Returns an iterator over the slice.

Examples

let data = 3u8;
let bits = data.bits::<Lsb0>();
let mut iter = bits[.. 4].iter();
assert_eq!(iter.next(), Some(&true));
assert_eq!(iter.next(), Some(&true));
assert_eq!(iter.next(), Some(&false));
assert_eq!(iter.next(), Some(&false));
assert!(iter.next().is_none());

pub fn iter_mut(&mut self) -> IterMut<'_, O, T>

Returns an iterator that allows modifying each bit.

Examples

let mut data = 0u8;
let bits = &mut data.bits_mut::<Lsb0>()[.. 2];
for mut bit in bits.iter_mut() {
    *bit = true;
}
assert_eq!(data, 3);

pub fn windows(&self, width: usize) -> Windows<'_, O, T>

Returns an iterator over all contiguous windows of width width.

The windows overlap. If the slice is shorter than width, the iterator returns no values.

Panics

Panics if width is 0.

Examples

let data = 0b100_010_01u8;
let bits = data.bits::<Msb0>();
let mut iter = bits[.. 5].windows(3);
assert_eq!(iter.next().unwrap(), &bits[0 .. 3]);
assert_eq!(iter.next().unwrap(), &bits[1 .. 4]);
assert_eq!(iter.next().unwrap(), &bits[2 .. 5]);
assert!(iter.next().is_none());

If the slice is shorter than width:

let data = 0u8;
let bits = data.bits::<Local>();
let mut iter = bits[.. 3].windows(4);
assert!(iter.next().is_none());

pub fn chunks(&self, chunk_size: usize) -> Chunks<'_, O, T>

Returns an iterator over chunk_size bits of the slice at a time, starting at the beginning of the slice.

The chunks are slices and do not overlap. If chunk_size does not divide the length of the slice, then the last chunk will not have length chunk_size.

See chunks_exact for a variant of this iterator that returns chunks of always exactly chunk_size elements, and rchunks for the same iterator but starting at the end of the slice.

Panics

Panics if chunk_size is 0.

Examples

let data = 0b001_010_10u8;
let bits = data.bits::<Msb0>();
let mut iter = bits.chunks(3);
assert_eq!(iter.next().unwrap(), &bits[0 .. 3]);
assert_eq!(iter.next().unwrap(), &bits[3 .. 6]);
assert_eq!(iter.next().unwrap(), &bits[6 .. 8]);
assert!(iter.next().is_none());

pub fn chunks_mut(&mut self, chunk_size: usize) -> ChunksMut<'_, O, T>

Returns an iterator over chunk_size bits of the slice at a time, starting at the beginning of the slice.

The chunks are mutable slices, and do not overlap. If chunk_size does not divide the length of the slice, then the last chunk will not have length chunk_size.

See chunks_exact_mut for a variant of this iterator that returns chunks of always exactly chunk_size bits, and rchunks_mut for the same iterator but starting at the end of the slice.

Panics

Panics if chunk_size is 0.

Examples

let mut data = 0u8;
let bits = data.bits_mut::<Msb0>();
let mut count = 0;

for chunk in bits.chunks_mut(3) {
    chunk.store(4u8 >> count);
    count += 1;
}
assert_eq!(count, 3);
assert_eq!(data, 0b100_010_01);

pub fn chunks_exact(&self, chunk_size: usize) -> ChunksExact<'_, O, T>

Returns an iterator over chunk_size elements of the slice at a time, starting at the beginning of the slice.

The chunks are slices and do not overlap. If chunk_size does not divide the length of the slice, then the last up to chunk_size - 1 elements will be omitted and can be retrieved from the remainder function of the iterator.

Due to each chunk having exactly chunk_size elements, the compiler can often optimize the resulting code better than in the case of chunks.

See chunks for a variant of this iterator that also returns the remainder as a smaller chunk, and rchunks_exact for the same iterator but starting at the end of the slice.

Panics

Panics if chunk_size is 0.

Examples

let data = 0b100_010_01u8;
let bits = data.bits::<Msb0>();
let mut iter = bits.chunks_exact(3);
assert_eq!(iter.next().unwrap(), &bits[0 .. 3]);
assert_eq!(iter.next().unwrap(), &bits[3 .. 6]);
assert!(iter.next().is_none());
assert_eq!(iter.remainder(), &bits[6 .. 8]);

pub fn chunks_exact_mut(
    &mut self,
    chunk_size: usize
) -> ChunksExactMut<'_, O, T>

Returns an iterator over chunk_size elements of the slice at a time, starting at the beginning of the slice.

The chunks are mutable slices, and do not overlap. If chunk_size does not divide the length of the slice, then the last up to chunk_size - 1 elements will be omitted and can be retrieved from the into_remainder function of the iterator.

Due to each chunk having exactly chunk_size elements, the compiler can often optimize the resulting code better than in the case of chunks_mut.

See chunks_mut for a variant of this iterator that also returns the remainder as a smaller chunk, and rchunks_exact_mut for the same iterator but starting at the end of the slice of the slice.

Panics

Panics if chunk_size is 0.

Examples

let mut data = 0u8;
let bits = data.bits_mut::<Msb0>();
let mut count = 0u8;

let mut iter = bits.chunks_exact_mut(3);
for chunk in &mut iter {
    chunk.store(4u8 >> count);
    count += 1;
}
iter.into_remainder().store(1u8);
assert_eq!(count, 2);
assert_eq!(data, 0b100_010_01);

pub fn rchunks(&self, chunk_size: usize) -> RChunks<'_, O, T>

Returns an iterator over chunk_size bits of the slice at a time, starting at the end of the slice.

The chunks are slices and do not overlap. If chunk_size does not divide the length of the slice, then the last chunk will not have length of the slice, then the last chunk will not have length chunk_size.

See rchunks_exact for a variant of this iterator that returns chunks of always exactly chunk_size bits, and chunks for the same iterator but starting at the beginning of the slice.

Panics

Panics if chunk_size is 0.

Examples

let data = 0b01_010_100u8;
let bits = data.bits::<Msb0>();
let mut iter = bits.rchunks(3);
assert_eq!(iter.next().unwrap(), &bits[5 .. 8]);
assert_eq!(iter.next().unwrap(), &bits[2 .. 5]);
assert_eq!(iter.next().unwrap(), &bits[0 .. 2]);
assert!(iter.next().is_none());

pub fn rchunks_mut(&mut self, chunk_size: usize) -> RChunksMut<'_, O, T>

Returns an iterator over chunk_size bits of the slice at a time, starting at the end of the slice.

The chunks are mutable slices and do not overlap. If chunk_size does not divide the length of the slice, then the last chunk will not have length of the slice, then the last chunk will not have length chunk_size.

See rchunks_exact_mut for a variant of this iterator that returns chunks of always exactly chunk_size bits, and chunks_mut for the same iterator but starting at the beginning of the slice.

Panics

Panics if chunk_size is 0.

Examples

let mut data = 0u8;
let bits = data.bits_mut::<Lsb0>();
let mut count = 0;

for chunk in bits.rchunks_mut(3) {
    chunk.store(4u8 >> count);
    count += 1;
}
assert_eq!(count, 3);
assert_eq!(data, 0b100_010_01);

pub fn rchunks_exact(&self, chunk_size: usize) -> RChunksExact<'_, O, T>

Returns an iterator over chunk_size bits of the slice at a time, starting at the end of the slice.

The chunks are slices and do not overlap. If chunk_size does not divide the length of the slice, then the last up to chunk_size - 1 bits will be omitted and can be retrieved from the remainder function of the iterator.

Due to each chunk having exactly chunk_size bits, the compiler can often optimize the resulting code better than in the case of chunks.

See rchunks for a variant of this iterator that also returns the remainder as a smaller chunk, and chunks_exact for the same iterator but starting at the beginning of the slice.

Panics

Panics if chunk_size is 0.

Examples

let data = 0b100_010_01u8;
let bits = data.bits::<Lsb0>();
let mut iter = bits.rchunks_exact(3);
assert_eq!(iter.next().unwrap(), &bits[5 .. 8]);
assert_eq!(iter.next().unwrap(), &bits[2 .. 5]);
assert!(iter.next().is_none());
assert_eq!(iter.remainder(), &bits[0 ..2]);

pub fn rchunks_exact_mut(
    &mut self,
    chunk_size: usize
) -> RChunksExactMut<'_, O, T>

Returns an iterator over chunk_size bits of the slice at a time, starting at the end of the slice.

The chunks are mutable slices, and do not overlap. If chunk_size does not divide the length of the slice, then the last up to chunk_size - 1 bits will be omitted and can be retrieved from the into_remainder function of the iterator.

Due to each chunk having exactly chunk_size bits, the compiler can often optimize the resulting code better than in the case of chunks_mut.

See rchunks_mut for a variant of this iterator that also returns the remainder as a smaller chunk, and chunks_exact_mut for the same iterator but starting at the beginning of the slice.

Panics

Panics if chunk_size is 0.

Examples

let mut data = 0u8;
let bits = data.bits_mut::<Lsb0>();
let mut count = 0;
let mut iter = bits.rchunks_exact_mut(3);

for chunk in &mut iter {
    chunk.store(4u8 >> count);
    count += 1;
}
iter.into_remainder().store(1u8);
assert_eq!(data, 0b100_010_01);
assert_eq!(count, 2);

pub fn split_at(&self, mid: usize) -> (&Self, &Self)

Divides one slice into two at an index.

The first will contain all indices from [0, mid) (excluding the index mid itself) and the second will contain all indices from [mid, len) (excluding the index len itself).

Panics

Panics if mid > len.

Examples

let data = 0x0Fu8;
let bits = data.bits::<Msb0>();

{
    let (left, right) = bits.split_at(0);
    assert!(left.is_empty());
    assert_eq!(right, bits);
}

{
    let (left, right) = bits.split_at(4);
    assert!(left.not_any());
    assert!(right.all());
}

{
    let (left, right) = bits.split_at(8);
    assert_eq!(left, bits);
    assert!(right.is_empty());
}

pub fn split_at_mut(&mut self, mid: usize) -> (&mut Self, &mut Self)

Divides one mutable slice into two at an index.

The first will contain all indices from [0, mid) (excluding the index mid itself) and the second will contain all indices from [mid, len) (excluding the index len itself).

Panics

Panics if mid > len.

Examples

let mut data = 0x0Fu8;
let bits = data.bits_mut::<Msb0>();

let (left, right) = bits.split_at_mut(4);
assert!(left.not_any());
assert!(right.all());
*left.at(1) = true;
*right.at(2) = false;

assert_eq!(data, 0b0100_1101);

pub fn split<F>(&self, func: F) -> Split<'_, O, T, F> where
    F: FnMut(usize, &bool) -> bool, 

Returns an iterator over subslices separated by indexed bits that satisfy the predicate function. The matched position is not contained in the subslices.

API Differences

The slice::split method takes a predicate function with signature (&T) -> bool, whereas this method’s predicate function has signature (usize, &T) -> bool. This difference is in place because BitSlice by definition has only one bit of information per slice item, and including the index allows the callback function to make more informed choices.

Examples

let data = 0b01_001_000u8;
let bits = data.bits::<Msb0>();
let mut iter = bits.split(|pos, bit| *bit);

assert_eq!(iter.next().unwrap(), &bits[0 .. 1]);
assert_eq!(iter.next().unwrap(), &bits[2 .. 4]);
assert_eq!(iter.next().unwrap(), &bits[5 .. 8]);
assert!(iter.next().is_none());

If the first position is matched, an empty slice will be the first item returned by the iterator. Similarly, if the last position in the slice is matched, an empty slice will be the last item returned by the iterator:

let data = 1u8;
let bits = data.bits::<Msb0>();
let mut iter = bits.split(|pos, bit| *bit);

assert_eq!(iter.next().unwrap(), &bits[0 .. 7]);
assert_eq!(iter.next().unwrap(), BitSlice::<Local, usize>::empty());
assert!(iter.next().is_none());

If two matched positions are directly adjacent, an empty slice will be present between them.

let data = 0b001_100_00u8;
let bits = data.bits::<Msb0>();
let mut iter = bits.split(|pos, bit| *bit);

assert_eq!(iter.next().unwrap(), &bits[0 .. 2]);
assert_eq!(iter.next().unwrap(), BitSlice::<Local, usize>::empty());
assert_eq!(iter.next().unwrap(), &bits[4 .. 8]);
assert!(iter.next().is_none());

pub fn split_mut<F>(&mut self, func: F) -> SplitMut<'_, O, T, F> where
    F: FnMut(usize, &bool) -> bool, 

Returns an iterator over mutable subslices separated by indexed bits that satisfy the predicate function. The matched position is not contained in the subslices.

API Differences

The slice::split_mut method takes a predicate function with signature (&T) -> bool, whereas this method’s predicate function has signature (usize, &T) -> bool. This difference is in place because BitSlice by definition has only one bit of information per slice item, and including the index allows the callback function to make more informed choices.

Examples

let mut data = 0b001_000_10u8;
let bits = data.bits_mut::<Msb0>();

for group in bits.split_mut(|pos, bit| *bit) {
    *group.at(0) = true;
}
assert_eq!(data, 0b101_1001_1u8);

pub fn rsplit<F>(&self, func: F) -> RSplit<'_, O, T, F> where
    F: FnMut(usize, &bool) -> bool, 

Returns an iterator over subslices separated by indexed bits that satisfy a predicate function, starting at the end of the slice and working backwards. The matched position is not contained in the subslices.

API Differences

The slice::rsplit method takes a predicate function with signature (&T) -> bool, whereas this method’s predicate function has signature (usize, &T) -> bool. This difference is in place because BitSlice by definition has only one bit of information per slice item, and including the index allows the callback function to make more informed choices.

Examples

let data = 0b0001_0000u8;
let bits = data.bits::<Msb0>();
let mut iter = bits.rsplit(|pos, bit| *bit);

assert_eq!(iter.next().unwrap(), &bits[4 .. 8]);
assert_eq!(iter.next().unwrap(), &bits[0 .. 3]);
assert!(iter.next().is_none());

As with split(), if the first or last position is matched, an empty slice will be the first (or last) item returned by the iterator.

let data = 0b1001_0001u8;
let bits = data.bits::<Msb0>();
let mut iter = bits.rsplit(|pos, bit| *bit);
assert!(iter.next().unwrap().is_empty());
assert_eq!(iter.next().unwrap(), &bits[4 .. 7]);
assert_eq!(iter.next().unwrap(), &bits[1 .. 3]);
assert!(iter.next().unwrap().is_empty());
assert!(iter.next().is_none());

pub fn rsplit_mut<F>(&mut self, func: F) -> RSplitMut<'_, O, T, F> where
    F: FnMut(usize, &bool) -> bool, 

Returns an iterator over mutable subslices separated by indexed bits that satisfy a predicate function, starting at the end of the slice and working backwards. The matched position is not contained in the subslices.

API Differences

The slice::rsplit_mut method takes a predicate function with signature (&T) -> bool, whereas this method’s predicate function has signature (usize, &T) -> bool. This difference is in place because BitSlice by definition has only one bit of information per slice item, and including the index allows the callback function to make more informed choices.

Examples

let mut data = 0u8;
let bits = data.bits_mut::<Msb0>();

let mut count = 0u8;
for group in bits.rsplit_mut(|pos, bit| pos % 3 == 2) {
    count += 1;
    group.store(count);
}
assert_eq!(data, 0b11_0_10_0_01);

pub fn splitn<F>(&self, n: usize, func: F) -> SplitN<'_, O, T, F> where
    F: FnMut(usize, &bool) -> bool, 

Returns an iterator over subslices separated by indexed bits that satisfy the predicate function, limited to returning at most n items. The matched position is not contained in the subslices.

The last element returned, if any, will contain the remainder of the slice.

API Differences

The slice::splitn method takes a predicate function with signature (&T) -> bool, whereas this method’s predicate function has signature (usize, &T) -> bool. This difference is in place because BitSlice by definition has only one bit of information per slice item, and including the index allows the callback function to make more informed choices.

Examples

Print the slice split once by indices divisible by 3:

let data = 0xA5u8;
let bits = data.bits::<Msb0>();

for group in bits.splitn(2, |pos, bit| pos % 3 == 2) {
    println!("{}", group);
}
//  [10]
//  [00101]

pub fn splitn_mut<F>(&mut self, n: usize, func: F) -> SplitNMut<'_, O, T, F> where
    F: FnMut(usize, &bool) -> bool, 

Returns an iterator over mutable subslices separated by indexed bits that satisfy the predicate function, limited to returning at most n items. The matched position is not contained in the subslices.

The last element returned, if any, will contain the remainder of the slice.

API Differences

The slice::splitn_mut method takes a predicate function with signature (&T) -> bool, whereas this method’s predicate function has signature (usize, &T) -> bool. This difference is in place because BitSlice by definition has only one bit of information per slice item, and including the index allows the callback function to make more informed choices.

Examples

let mut data = 0u8;
let bits = data.bits_mut::<Msb0>();
let mut counter = 0u8;

for group in bits.splitn_mut(2, |pos, bit| pos % 4 == 3) {
    counter += 1;
    group.store(counter);
}
assert_eq!(data, 0b001_0_0010);

pub fn rsplitn<F>(&self, n: usize, func: F) -> RSplitN<'_, O, T, F> where
    F: FnMut(usize, &bool) -> bool, 

Returns an iterator over subslices separated by indexed bits that satisfy a predicate function, limited to returning at most n items. This starts at the end of the slice and works backwards. The matched position is not contained in the subslices.

The last element returned, if any, will contain the remainder of the slice.

API Differences

The slice::rsplitn method takes a predicate function with signature (&T) -> bool, whereas this method’s predicate function has signature (usize, &T) -> bool. This difference is in place because BitSlice by definition has only one bit of information per slice item, and including the index allows the callback function to make more informed choices.

Examples

Print the slice split once, starting from the end, by indices divisible by 3:

let data = 0xA5u8;
let bits = data.bits::<Msb0>();

for group in bits.rsplitn(2, |pos, bit| pos % 3 == 2) {
    println!("{}", group);
}
//  [01]
//  [10100]

pub fn rsplitn_mut<F>(&mut self, n: usize, func: F) -> RSplitNMut<'_, O, T, F> where
    F: FnMut(usize, &bool) -> bool, 

Returns an iterator over mutable subslices separated by indexed bits that satisfy a predicate function, limited to returning at most n items. This starts at the end of the slice and works backwards. The matched position is not contained in the subslices.

The last element returned, if any, will contain the remainder of the slice.

API Differences

The slice::rsplitn_mut method takes a predicate function with signature (&T) -> bool, whereas this method’s predicate function has signature (usize, &T) -> bool. This difference is in place because BitSlice by definition has only one bit of information per slice item, and including the index allows the callback function to make more informed choices.

Examples

let mut data = 0u8;
let bits = data.bits_mut::<Msb0>();
let mut counter = 0u8;

for group in bits.rsplitn_mut(2, |pos, bit| pos % 3 == 2) {
    counter += 1;
    group.store(counter);
}
assert_eq!(data, 0b00010_0_01);

pub fn contains<P, U>(&self, query: &BitSlice<P, U>) -> bool where
    P: BitOrder,
    U: BitStore, 

Returns true if the slice contains a region that matches the given span.

API Differences

The slice::contains method tests for a single slice element. Because this is a slice of single bits, testing for the presence of one bool value is not very informative. This instead searches for a subslice, which may be one or more bits.

Examples

let data = 0b0101_1010u8;
let bits_be = data.bits::<Msb0>();
let bits_le = data.bits::<Lsb0>();
assert!(bits_be.contains(&bits_le[1 .. 5]));

This example uses a palindrome pattern to demonstrate that the query does not need to have the same type parameters as the searched slice.

pub fn starts_with<P, U>(&self, prefix: &BitSlice<P, U>) -> bool where
    P: BitOrder,
    U: BitStore, 

Returns true if prefix is a prefix of the slice.

Examples

let data = 0b0110_1110u8;
let bits = data.bits::<Msb0>();
assert!(bits.starts_with(&data.bits::<Lsb0>()[.. 2]));

pub fn ends_with<P, U>(&self, suffix: &BitSlice<P, U>) -> bool where
    P: BitOrder,
    U: BitStore, 

Returns true if suffix is a suffix of the slice.

Examples

let data = 0b0111_1010u8;
let bits = data.bits::<Msb0>();
assert!(bits.ends_with(&data.bits::<Lsb0>()[6 ..]));

pub fn rotate_left(&mut self, by: usize)

Rotates the slice in-place such that the first by bits of the slice move to the end while the last self.len() - by bits move to the front. After calling rotate_left, the bit previously at index by will become the first bit in the slice.

Panics

This function will panic if by is greater than the length of the slice. Note that by == self.len() does not panic and is a noöp rotation.

Complexity

Takes linear (in self.len()) time.

Examples

let mut data = 0xF0u8;
let bits = data.bits_mut::<Msb0>();
bits.rotate_left(2);
assert_eq!(data, 0xC3);

Rotating a subslice:

let mut data = 0xF0u8;
let bits = data.bits_mut::<Msb0>();
bits[1 .. 5].rotate_left(1);
assert_eq!(data, 0b1_1101_000);

pub fn rotate_right(&mut self, by: usize)

Rotates the slice in-place such that the first self.len() - by bits of the slice move to the end while the last by bits move to the front. After calling rotate_right, the bit previously at index self.len() - by will become the first bit in the slice.

Panics

This function will panic if by is greater than the length of the slice. Note that by == self.len() does not panic and is a noöp rotation.

Complexity

Takes linear (in self.len()) time.

Examples

let mut data = 0xF0u8;
let bits = data.bits_mut::<Msb0>();
bits.rotate_right(2);
assert_eq!(data, 0x3C);

Rotate a subslice:

let mut data = 0xF0u8;
let bits = data.bits_mut::<Msb0>();
bits[1 .. 5].rotate_right(1);
assert_eq!(data, 0b1_0111_000);

pub fn clone_from_slice<P, U>(&mut self, src: &BitSlice<P, U>) where
    P: BitOrder,
    U: BitStore, 

Copies the elements from src into self.

The length of src must be the same as self.

This is equivalent to copy_from_slice; this function is only included for API surface equivalence.

Panics

This function will panic if the two slices have different lengths.

Examples

let mut data = 0u8;
let bits = data.bits_mut::<Msb0>();
let src = 0x0Fu16.bits::<Lsb0>();
bits.clone_from_slice(&src[.. 8]);
assert_eq!(data, 0xF0);

Rust enforces that there can only be one mutable reference with no immutable references to a particular piece of data in a particular scope. Because of this, attempting to use clone_from_slice on a single slice will result in a compile failure:

let mut data = 3u8;
let bits = data.bits_mut::<Msb0>();
bits[.. 2].clone_from_slice(&bits[6 ..]);

To work around this, we can use [split_at_mut] to create two distinct sub-slices from a slice:

let mut data = 3u8;
let bits = data.bits_mut::<Msb0>();
let (head, tail) = bits.split_at_mut(4);
head.clone_from_slice(tail);
assert_eq!(data, 0x33);

pub fn copy_from_slice(&mut self, src: &Self)

Copies the elements from src into self.

The length of src must be the same as self.

This is restricted to take exactly the same type of bit slice as the source slice, so that the implementation has the chace to use faster memcpy if possible.

Panics

This function will panic if the two slices have different lengths.

Examples

let mut data = 0u8;
let bits = data.bits_mut::<Msb0>();
let src = 0x0Fu8.bits::<Msb0>();
bits.copy_from_slice(src);
assert_eq!(data, 0x0F);

Rust enforces that there can only be one mutable reference with no immutable references to a particular piece of data in a particular scope. Because of this, attempting to use copy_from_slice on a single slice will result in a compile failure:

let mut data = 3u8;
let bits = data.bits_mut::<Msb0>();
bits[.. 2].copy_from_slice(&bits[6 ..]);

To work around this, we can use [split_at_mut] to create two distinct sub-slices from a slice:

let mut data = 3u8;
let bits = data.bits_mut::<Msb0>();
let (head, tail) = bits.split_at_mut(4);
head.copy_from_slice(tail);
assert_eq!(data, 0x33);

pub fn swap_with_slice<P, U>(&mut self, other: &mut BitSlice<P, U>) where
    P: BitOrder,
    U: BitStore, 

Swaps all bits in self with those in other.

The length of other must be the same as self.

Panics

This function will panic if the two slices hav different lengths.

Example

Swapping two elements across slices:

let mut a = 0u8;
let mut b = 0x96A5u16;
let bits_a = a.bits_mut::<Lsb0>();
let bits_b = b.bits_mut::<Msb0>();

bits_a.swap_with_slice(&mut bits_b[4 .. 12]);

assert_eq!(a, 0x56);
assert_eq!(b, 0x9005);

Rust enforces that there can only be one mutable reference to a particular piece of data in a particular scope. Because of this, attempting to use swap_with_slice on a single slice will result in a compile failure:

let mut data = 15u8;
let bits = data.bits_mut::<Msb0>();
bits[.. 3].swap_with_slice(&mut bits[5 ..]);

To work around this, we can use [split_at_mut] to create two distinct mutable sub-slices from a slice:

let mut data = 15u8;
let bits = data.bits_mut::<Msb0>();

{
    let (left, right) = bits.split_at_mut(4);
    left[.. 2].swap_with_slice(&mut right[2 ..]);
}

assert_eq!(data, 0xCC);

pub unsafe fn align_to<U>(&self) -> (&Self, &BitSlice<O, U>, &Self) where
    U: BitStore, 

Transmute the slice to a slice with a different backing store, ensuring alignment of the types is maintained.

This method splits the slice into three distinct slices: prefix, correctly aligned middle slice of a new backing type, and the suffix slice. The method does a best effort to make the middle slice the greatest length possible for a given type and input slice, but only your algorithm’s performance should depend on that, not its correctness.

Safety

This method is essentially a transmute with respect to the elements in the returned middle slice, so all the usual caveats pertaining to transmute::<T, U> also apply here.

Examples

Basic usage:

unsafe {
    let bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7];
    let bits = bytes.bits::<Local>();
    let (prefix, shorts, suffix) = bits.align_to::<u16>();
    match prefix.len() {
        0 => {
            assert_eq!(shorts, bits[.. 48]);
            assert_eq!(suffix, bits[48 ..]);
        },
        8 => {
            assert_eq!(prefix, bits[.. 8]);
            assert_eq!(shorts, bits[8 ..]);
        },
        _ => unreachable!("This case will not occur")
    }
}

pub unsafe fn align_to_mut<U>(
    &mut self
) -> (&mut Self, &mut BitSlice<O, U>, &mut Self) where
    U: BitStore, 

Transmute the slice to a slice with a different backing store, ensuring alignment of the types is maintained.

This method splits the slice into three distinct slices: prefix, correctly aligned middle slice of a new backing type, and the suffix slice. The method does a best effort to make the middle slice the greatest length possible for a given type and input slice, but only your algorithm’s performance should depend on that, not its correctness.

Safety

This method is essentially a transmute with respect to the elements in the returned middle slice, so all the usual caveats pertaining to transmute::<T, U> also apply here.

Examples

Basic usage:

unsafe {
    let mut bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7];
    let bits = bytes.bits_mut::<Local>();
    let (prefix, shorts, suffix) = bits.align_to_mut::<u16>();
    //  same access and behavior as in `align_to`
}

pub fn to_vec(&self) -> BitVec<O, T>

Copies self into a new BitVec.

Examples

let data = [0u8, !0u8];
let bits = data.bits::<Local>();
let vec = bits.to_vec();
assert_eq!(bits, vec);

impl<O, T> BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

pub fn empty<'a>() -> &'a Self

Produces the empty slice. This is equivalent to &[] for Rust slices.

Returns

An empty &BitSlice handle.

Examples

use bitvec::prelude::*;

let bits: &BitSlice = BitSlice::empty();

pub fn empty_mut<'a>() -> &'a mut Self

Produces the empty mutable slice. This is equivalent to &mut [] for Rust slices.

Returns

An empty &mut BitSlice handle.

Examples

use bitvec::prelude::*;

let bits: &mut BitSlice = BitSlice::empty_mut();

pub fn from_element(elt: &T) -> &Self

Produces an immutable BitSlice over a single element.

Parameters

• elt: A reference to an element over which the BitSlice will be created.

Returns

A BitSlice over the provided element.

Examples

use bitvec::prelude::*;

let elt: u8 = !0;
let bs: &BitSlice<Local, _> = BitSlice::from_element(&elt);
assert!(bs.all());

pub fn from_element_mut(elt: &mut T) -> &mut Self

Produces a mutable BitSlice over a single element.

Parameters

• elt: A reference to an element over which the BitSlice will be created.

Returns

A BitSlice over the provided element.

Examples

use bitvec::prelude::*;

let mut elt: u8 = !0;
let bs: &mut BitSlice<Local, _> = BitSlice::from_element_mut(&mut elt);
bs.set(0, false);
assert!(!bs.all());

pub fn from_slice(slice: &[T]) -> &Self

Wraps a &[T: BitStore] in a &BitSlice<O: BitOrder, T>. The order must be specified at the call site. The element type cannot be changed.

Parameters

• src: The elements over which the new BitSlice will operate.

Returns

A BitSlice representing the original element slice.

Panics

The source slice must not exceed the maximum number of elements that a BitSlice can contain. This value is documented in BitPtr.

Examples

use bitvec::prelude::*;

let src = [1, 2, 3];
let bits = BitSlice::<Msb0, u8>::from_slice(&src[..]);
assert_eq!(bits.len(), 24);
assert_eq!(bits.as_ref().len(), 3);
assert!(bits[7]);  // src[0] == 0b0000_0001
assert!(bits[14]); // src[1] == 0b0000_0010
assert!(bits[22]); // src[2] == 0b0000_0011
assert!(bits[23]);

pub fn from_slice_mut(slice: &mut [T]) -> &mut Self

Wraps a &mut [T: BitStore] in a &mut BitSlice<O: BitOrder, T>. The order must be specified by the call site. The element type cannot be changed.

Parameters

• src: The elements over which the new BitSlice will operate.

Returns

A BitSlice representing the original element slice.

Panics

The source slice must not exceed the maximum number of elements that a BitSlice can contain. This value is documented in BitPtr.

Examples

use bitvec::prelude::*;

let mut src = [1, 2, 3];
let bits = BitSlice::<Lsb0, u8>::from_slice_mut(&mut src[..]);
//  The first bit is the LSb of the first element.
assert!(bits[0]);
bits.set(0, false);
assert!(!bits[0]);
assert_eq!(bits.as_ref(), &[0, 2, 3]);

pub fn set(&mut self, index: usize, value: bool)

Sets the bit value at the given position.

Parameters

• &mut self
• index: The bit index to set. It must be in the domain 0 .. self.len().
• value: The value to be set, true for 1 and false for 0.

Panics

This method panics if index is outside the slice domain.

Examples

use bitvec::prelude::*;

let mut store = 8u8;
let bits = store.bits_mut::<Msb0>();
assert!(!bits[3]);
bits.set(3, true);
assert!(bits[3]);

pub unsafe fn set_unchecked(&mut self, index: usize, value: bool)

Sets a bit at an index, without doing bounds checking.

This is generally not recommended; use with caution! For a safe alternative, see set.

Parameters

• &mut self
• index: The bit index to retrieve. This index is not checked against the length of self.

Effects

The bit at index is set to value.

Safety

This method is not safe. It performs raw pointer arithmetic to seek from the start of the slice to the requested index, and set the bit there. It does not inspect the length of self, and it is free to perform out-of-bounds memory write access.

Use this method only when you have already performed the bounds check, and can guarantee that the call occurs with a safely in-bounds index.

Examples

This example uses a bit slice of length 2, and demonstrates out-of-bounds access to the last bit in the element.

use bitvec::prelude::*;

let mut src = 0u8;
{
 let bits = &mut src.bits_mut::<Msb0>()[2 .. 4];
 assert_eq!(bits.len(), 2);
 unsafe { bits.set_unchecked(5, true); }
}
assert_eq!(src, 1);

pub fn at<'a, I>(&'a mut self, index: I) -> I::Mut where
    I: BitSliceIndex<'a, O, T>, 

👎 Deprecated since 0.18.0:

Use .get_mut() instead

Produces a write reference to a region of the slice.

This method corresponds to [Index::index], except that it produces a writable reference rather than a read-only reference. See BitSliceIndex for the possible types of the produced reference.

Use of this method locks the &mut BitSlice for the duration of the produced reference’s lifetime. If you need multiple non-overlapping write references into a single source &mut BitSlice, see the ::split_at_mut method.

Lifetimes

• 'a: Propagates the lifetime of the referent slice to the interior reference produced.

Parameters

• &mut self
• index: Some value whose type can be used to index BitSlices.

Returns

A writable reference into self, whose exact type is determined by index’s implementation of BitSliceIndex. This may be either a smaller &mut BitSlice when index is a range, or a BitMut proxy type when index is a usize. See the BitMut documentation for information on how to use it.

Panics

This panics if index is out of bounds of self.

Examples

use bitvec::prelude::*;

let mut src = 0u8;
let bits = src.bits_mut::<Msb0>();

assert!(!bits[0]);
*bits.at(0) = true;
//  note the leading dereference.
assert!(bits[0]);

This example shows multiple usage by using split_at_mut.

use bitvec::prelude::*;

let mut src = 0u8;
let bits = src.bits_mut::<Msb0>();

{
 let (mut a, rest) = bits.split_at_mut(2);
 let (mut b, rest) = rest.split_at_mut(3);
 *a.at(0) = true;
 *b.at(0) = true;
 *rest.at(0) = true;
}

assert_eq!(bits.as_slice()[0], 0b1010_0100);
//                               a b   rest

The above example splits the slice into three (the first, the second, and the rest) in order to hold multiple write references into the slice.

pub unsafe fn at_unchecked<'a, I>(&'a mut self, index: I) -> I::Mut where
    I: BitSliceIndex<'a, O, T>, 

👎 Deprecated since 0.18.0:

Use .get_unchecked_mut() instead

Version of at that does not perform boundary checking.

Safety

If index is outside the boundaries of self, then this function will induce safety violations. The caller must ensure that index is within the boundaries of self before calling.

pub unsafe fn split_at_unchecked(&self, mid: usize) -> (&Self, &Self)

Version of split_at that does not perform boundary checking.

Safety

If mid is outside the boundaries of self, then this function will induce safety violations. The caller must ensure that mid is within the boundaries of self before calling.

pub unsafe fn split_at_mut_unchecked(
    &mut self,
    mid: usize
) -> (&mut Self, &mut Self)

Version of split_at_mut that does not perform boundary checking.

Safety

If mid is outside the boundaries of self, then this function will induce safety violations. The caller must ensure that mid is within the boundaries of self before calling.

pub unsafe fn swap_unchecked(&mut self, a: usize, b: usize)

Version of swap that does not perform boundary checks.

Safety

a and b must be within the bounds of self, otherwise, the memory access is unsound and may induce undefined behavior.

pub fn all(&self) -> bool

Tests if all bits in the slice domain are set (logical ∧).

Truth Table

0 0 => 0
0 1 => 0
1 0 => 0
1 1 => 1

Parameters

• &self

Returns

Whether all bits in the slice domain are set. The empty slice returns true.

Examples

use bitvec::prelude::*;

let bits = 0xFDu8.bits::<Msb0>();
assert!(bits[.. 4].all());
assert!(!bits[4 ..].all());

pub fn any(&self) -> bool

Tests if any bit in the slice is set (logical ∨).

Truth Table

0 0 => 0
0 1 => 1
1 0 => 1
1 1 => 1

Parameters

• &self

Returns

Whether any bit in the slice domain is set. The empty slice returns false.

Examples

use bitvec::prelude::*;

let bits = 0x40u8.bits::<Msb0>();
assert!(bits[.. 4].any());
assert!(!bits[4 ..].any());

pub fn not_all(&self) -> bool

Tests if any bit in the slice is unset (logical ¬∧).

Truth Table

0 0 => 1
0 1 => 1
1 0 => 1
1 1 => 0

Parameters

• `&self

Returns

Whether any bit in the slice domain is unset.

Examples

use bitvec::prelude::*;

let bits = 0xFDu8.bits::<Msb0>();
assert!(!bits[.. 4].not_all());
assert!(bits[4 ..].not_all());

pub fn not_any(&self) -> bool

Tests if all bits in the slice are unset (logical ¬∨).

Truth Table

0 0 => 1
0 1 => 0
1 0 => 0
1 1 => 0

Parameters

• &self

Returns

Whether all bits in the slice domain are unset.

Examples

use bitvec::prelude::*;

let bits = 0x40u8.bits::<Msb0>();
assert!(!bits[.. 4].not_any());
assert!(bits[4 ..].not_any());

pub fn some(&self) -> bool

Tests whether the slice has some, but not all, bits set and some, but not all, bits unset.

This is false if either all() or not_any() are true.

Truth Table

0 0 => 0
0 1 => 1
1 0 => 1
1 1 => 0

Parameters

• &self

Returns

Whether the slice domain has mixed content. The empty slice returns false.

Examples

use bitvec::prelude::*;

let bits = 0b111_000_10u8.bits::<Msb0>();
assert!(!bits[0 .. 3].some());
assert!(!bits[3 .. 6].some());
assert!(bits[6 ..].some());

pub fn count_ones(&self) -> usize

Counts how many bits are set high.

Parameters

• &self

Returns

The number of high bits in the slice domain.

Examples

use bitvec::prelude::*;

let bits = [0xFDu8, 0x25].bits::<Msb0>();
assert_eq!(bits.count_ones(), 10);

pub fn count_zeros(&self) -> usize

Counts how many bits are set low.

Parameters

• &self

Returns

The number of low bits in the slice domain.

Examples

use bitvec::prelude::*;

let bits = [0xFDu8, 0x25].bits::<Msb0>();
assert_eq!(bits.count_zeros(), 6);

pub fn set_all(&mut self, value: bool)

Set all bits in the slice to a value.

Parameters

• &mut self
• value: The bit value to which all bits in the slice will be set.

Examples

use bitvec::prelude::*;

let mut src = 0u8;
let bits = src.bits_mut::<Msb0>();
bits[2 .. 6].set_all(true);
assert_eq!(bits.as_ref(), &[0b0011_1100]);
bits[3 .. 5].set_all(false);
assert_eq!(bits.as_ref(), &[0b0010_0100]);
bits[.. 1].set_all(true);
assert_eq!(bits.as_ref(), &[0b1010_0100]);

pub fn for_each<F>(&mut self, func: F) where
    F: Fn(usize, bool) -> bool, 

Provides mutable traversal of the collection.

It is impossible to implement IndexMut on BitSlice, because bits do not have addresses, so there can be no &mut u1. This method allows the client to receive an enumerated bit, and provide a new bit to set at each index.

Parameters

• &mut self
• func: A function which receives a (usize, bool) pair of index and value, and returns a bool. It receives the bit at each position, and the return value is written back at that position.

Examples

use bitvec::prelude::*;

let mut src = 0u8;
{
 let bits = src.bits_mut::<Msb0>();
 bits.for_each(|idx, _bit| idx % 3 == 0);
}
assert_eq!(src, 0b1001_0010);

pub fn add_assign_reverse<I>(&mut self, addend: I) -> bool where
    I: IntoIterator<Item = bool>, 

Performs “reverse” addition (left to right instead of right to left).

This addition interprets the slice, and the other addend, as having its least significant bits first in the order and its most significant bits last. This is most likely to be numerically useful under a Lsb0 BitOrder type.

Parameters

• &mut self: The addition uses self as one addend, and writes the sum back into self.
• addend: impl IntoIterator<Item=bool>: A stream of bits. When this is another BitSlice, iteration proceeds from left to right.

Return

The final carry bit is returned

Effects

Starting from index 0 and proceeding upwards until either self or addend expires, the carry-propagated addition of self[i] and addend[i] is written to self[i].

  101111
+ 0010__ (the two missing bits are logically zero)
--------
  100000 1 (the carry-out is returned)

Examples

use bitvec::prelude::*;

let mut a = 0b0000_1010u8;
let     b = 0b0000_1100u8;
//      s =      1 0110
let ab = &mut a.bits_mut::<Lsb0>()[.. 4];
let bb = &    b.bits::<Lsb0>()[.. 4];
let c = ab.add_assign_reverse(bb.iter().copied());
assert!(c);
assert_eq!(a, 0b0000_0110u8);

Performance Notes

When using Lsb0 BitOrder types, this can be accelerated by delegating the addition to the underlying types. This is a software implementation of the ripple-carry adder, which has O(n) runtime in the number of bits. The CPU is much faster, as it has access to element-wise or vectorized addition operations.

If your use case sincerely needs binary-integer arithmetic operations on bit sets, please file an issue.

pub fn as_slice(&self) -> &[T]

Accesses the backing storage of the BitSlice as a slice of its elements.

This will not include partially-owned edge elements, as they may be contended by other slice handles.

Parameters

• &self

Returns

A slice of all the elements that the BitSlice uses for storage.

Examples

use bitvec::prelude::*;

let src = [1u8, 66];
let bits = src.bits::<Msb0>();

let accum = bits.as_slice()
  .iter()
  .map(|elt| elt.count_ones())
  .sum::<u32>();
assert_eq!(accum, 3);

pub fn as_mut_slice(&mut self) -> &mut [T]

Accesses the underlying store.

This will not include partially-owned edge elements, as they may be contended by other slice handles.

Examples

use bitvec::prelude::*;

let mut src = [1u8, 64];
let bits = src.bits_mut::<Msb0>();
for elt in bits.as_mut_slice() {
  *elt |= 2;
}
assert_eq!(&[3, 66], bits.as_slice());

pub fn as_total_slice(&self) -> &[T::Access]

Accesses the underlying store, including contended partial elements.

This produces a slice of element wrappers that permit shared mutation, rather than a slice of the bare T fundamentals.

Parameters

• &self

Returns

A slice of all elements under the bit span, including any partially-owned edge elements, wrapped in safe shared-mutation types.

Trait Implementations

impl<O, T, I> AddAssign<I> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore,
    I: IntoIterator<Item = bool>,
    I::IntoIter: DoubleEndedIterator, 

Performs unsigned addition in place on a BitSlice.

If the addend bitstream is shorter than self, the addend is zero-extended at the left (so that its final bit matches with self’s final bit). If the addend is longer, the excess front length is unused.

Addition proceeds from the right ends of each slice towards the left. Because this trait is forbidden from returning anything, the final carry-out bit is discarded.

Note that, unlike BitVec, there is no subtraction implementation until I find a subtraction algorithm that does not require modifying the subtrahend.

Subtraction can be implemented by negating the intended subtrahend yourself and then using addition, or by using BitVecs instead of BitSlices.

Type Parameters

• I: IntoIterator<Item=bool, IntoIter: DoubleEndedIterator>: The bitstream to add into self. It must be finite and double-ended, since addition operates in reverse.

fn add_assign(&mut self, addend: I)

Performs unsigned wrapping addition in place.

Examples

This example shows addition of a slice wrapping from max to zero.

use bitvec::prelude::*;

let mut src = [0b1110_1111u8, 0b0000_0001];
let bits = src.bits_mut::<Msb0>();
let (nums, one) = bits.split_at_mut(12);
let (accum, steps) = nums.split_at_mut(4);
*accum += one.iter().copied();
assert_eq!(accum, &steps[.. 4]);
*accum += one.iter().copied();
assert_eq!(accum, &steps[4 ..]);

impl<O, T> AsMut<[T]> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

Provides write access to all fully-owned elements in the underlying memory buffer. This excludes the edge elements if they are partially-owned.

fn as_mut(&mut self) -> &mut [T]

Performs the conversion.

impl<O, T> AsMut<BitSlice<O, T>> for BitBox<O, T> where
    O: BitOrder,
    T: BitStore, 

fn as_mut(&mut self) -> &mut BitSlice<O, T>

Performs the conversion.

impl<O, T> AsMut<BitSlice<O, T>> for BitVec<O, T> where
    O: BitOrder,
    T: BitStore, 

fn as_mut(&mut self) -> &mut BitSlice<O, T>

Performs the conversion.

impl<O, T> AsRef<[T]> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

Provides read-only access to all fully-owned elements in the underlying memory buffer. This excludes the edge elements if they are partially-owned.

fn as_ref(&self) -> &[T]

Performs the conversion.

impl<O, T> AsRef<BitSlice<O, T>> for Iter<'_, O, T> where
    O: BitOrder,
    T: BitStore, 

fn as_ref(&self) -> &BitSlice<O, T>

Performs the conversion.

impl<O, T> AsRef<BitSlice<O, T>> for BitBox<O, T> where
    O: BitOrder,
    T: BitStore, 

fn as_ref(&self) -> &BitSlice<O, T>

Performs the conversion.

impl<O, T> AsRef<BitSlice<O, T>> for BitVec<O, T> where
    O: BitOrder,
    T: BitStore, 

fn as_ref(&self) -> &BitSlice<O, T>

Performs the conversion.

impl<O, T> Binary for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

Write out the contents of a BitSlice as a numeric format.

These implementations render the bits of memory governed by a BitSlice as one of the three numeric bases the Rust format system supports:

• Binary renders each bit individually as 0 or 1,
• Octal renders clusters of three bits as the numbers 0 through 7,
• Hex renders clusters of four bits as the numbers [0-9A-F].

The formatters produce a word for each T element of memory. The chunked formats (octal and hexadecimal) operate somewhat peculiarly: they show the semantic value of the memory as interpreted by the BitOrder type parameter’s implementation, and not the raw value of the memory as you might observe with a debugger.

Specifically, the chunked formats read between zero and three (octal) or four (hexadecimal) bits in BitOrder order out of a memory element, store those bits in first-high/last-low order, and then interpret that sequence as a number in their respective bases. This means that, for instance, the byte 3 (bit pattern 0b0000_0011), read in Lsb0 order, will produce the numerals "600" (110 000 00) in octal, and "C0" (1100 0000) in hexadecimal.

If the memory element is exhausted before a chunk is filled with three or four bits, then the number produced will have a lower value. The byte 0xFFu8 will always produce the octal numeral "773" (111 111 11).

The decision to chunk numeral words by memory element, even though it breaks the octal chunking pattern was made so that the rendered text will still show memory boundaries for easier inspection.

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<O, T, I> BitAndAssign<I> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore,
    I: IntoIterator<Item = bool>, 

Performs the Boolean AND operation against another bitstream and writes the result into self. If the other bitstream ends before self,, the remaining bits of self are cleared.

Type Parameters

• I: IntoIterator<Item=bool>: A stream of bits, which may be a BitSlice or some other bit producer as desired.

fn bitand_assign(&mut self, rhs: I)

ANDs a bitstream into a slice.

Parameters

• &mut self
• rhs: The bitstream to AND into self.

Examples

use bitvec::prelude::*;

let mut store = [0b0101_0100u8];
let     other = [0b0011_0000u8];
let lhs = store.bits_mut::<Msb0>();
let rhs = other.bits::<Msb0>();
lhs[.. 6] &= rhs[.. 4].iter().copied();
assert_eq!(store[0], 0b0001_0000);

impl<T> BitField for BitSlice<Lsb0, T> where
    T: BitStore, 

fn load_le<U>(&self) -> U where
    U: BitStore, 

Load from self, using little-endian element ordering.

fn load_be<U>(&self) -> U where
    U: BitStore, 

Load from self, using big-endian element ordering.

fn store_le<U>(&mut self, value: U) where
    U: BitStore, 

Store into self, using little-endian element ordering.

fn store_be<U>(&mut self, value: U) where
    U: BitStore, 

Store into self, using big-endian element ordering.

fn load<U>(&self) -> U where
    U: BitStore, 

Load the sequence of bits from self into the least-significant bits of an element.

fn store<U>(&mut self, value: U) where
    U: BitStore, 

Stores a sequence of bits from the user into the domain of self.

impl<T> BitField for BitSlice<Msb0, T> where
    T: BitStore, 

fn load_le<U>(&self) -> U where
    U: BitStore, 

Load from self, using little-endian element ordering.

fn load_be<U>(&self) -> U where
    U: BitStore, 

Load from self, using big-endian element ordering.

fn store_le<U>(&mut self, value: U) where
    U: BitStore, 

Store into self, using little-endian element ordering.

fn store_be<U>(&mut self, value: U) where
    U: BitStore, 

Store into self, using big-endian element ordering.

fn load<U>(&self) -> U where
    U: BitStore, 

Load the sequence of bits from self into the least-significant bits of an element.

fn store<U>(&mut self, value: U) where
    U: BitStore, 

Stores a sequence of bits from the user into the domain of self.

impl<O, T, I> BitOrAssign<I> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore,
    I: IntoIterator<Item = bool>, 

Performs the Boolean OR operation against another bitstream and writes the result into self. If the other bitstream ends before self, the remaining bits of self are not affected.

Type Parameters

• I: IntoIterator<Item=bool>: A stream of bits, which may be a BitSlice or some other bit producer as desired.

fn bitor_assign(&mut self, rhs: I)

ORs a bitstream into a slice.

Parameters

• &mut self
• rhs: The bitstream to OR into self.

Examples

use bitvec::prelude::*;

let mut store = [0b0101_0100u8];
let     other = [0b0011_0000u8];
let lhs = store.bits_mut::<Msb0>();
let rhs = other.bits::<Msb0>();
lhs[.. 6] |= rhs[.. 4].iter().copied();
assert_eq!(store[0], 0b0111_0100);

impl<O, T, I> BitXorAssign<I> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore,
    I: IntoIterator<Item = bool>, 

Performs the Boolean XOR operation against another bitstream and writes the result into self. If the other bitstream ends before self, the remaining bits of self are not affected.

Type Parameters

• I: IntoIterator<Item=bool>: A stream of bits, which may be a BitSlice or some other bit producer as desired.

fn bitxor_assign(&mut self, rhs: I)

XORs a bitstream into a slice.

Parameters

• &mut self
• rhs: The bitstream to XOR into self.

Examples

use bitvec::prelude::*;

let mut store = [0b0101_0100u8];
let     other = [0b0011_0000u8];
let lhs = store.bits_mut::<Msb0>();
let rhs = other.bits::<Msb0>();
lhs[.. 6] ^= rhs[.. 4].iter().copied();
assert_eq!(store[0], 0b0110_0100);

impl<O, T> Borrow<BitSlice<O, T>> for BitBox<O, T> where
    O: BitOrder,
    T: BitStore, 

fn borrow(&self) -> &BitSlice<O, T>

Immutably borrows from an owned value.

impl<O, T> Borrow<BitSlice<O, T>> for BitVec<O, T> where
    O: BitOrder,
    T: BitStore, 

Signifies that BitSlice is the borrowed form of BitVec.

fn borrow(&self) -> &BitSlice<O, T>

Borrows the BitVec as a BitSlice.

Parameters

• &self

Returns

A borrowed BitSlice of the vector.

Examples

use bitvec::prelude::*;
use std::borrow::Borrow;

let bv = bitvec![0; 13];
let bs: &BitSlice = bv.borrow();
assert!(!bs[10]);

impl<O, T> BorrowMut<BitSlice<O, T>> for BitBox<O, T> where
    O: BitOrder,
    T: BitStore, 

fn borrow_mut(&mut self) -> &mut BitSlice<O, T>

Mutably borrows from an owned value.

impl<O, T> BorrowMut<BitSlice<O, T>> for BitVec<O, T> where
    O: BitOrder,
    T: BitStore, 

Signifies that BitSlice is the borrowed form of BitVec.

fn borrow_mut(&mut self) -> &mut BitSlice<O, T>

Mutably borrows the BitVec as a BitSlice.

Parameters

• &mut self

Returns

A mutably borrowed BitSlice of the vector.

Examples

use bitvec::prelude::*;
use std::borrow::BorrowMut;

let mut bv = bitvec![0; 13];
let bs: &mut BitSlice = bv.borrow_mut();
assert!(!bs[10]);
bs.set(10, true);
assert!(bs[10]);

impl<O, T> Debug for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

Prints the BitSlice for debugging.

The output is of the form BitSlice<O, T> [ELT, *] where <O, T> is the order and element type, with square brackets on each end of the bits and all the elements of the array printed in binary. The printout is always in semantic order, and may not reflect the underlying buffer. To see the underlying buffer, use .as_total_slice().

The alternate character {:#?} prints each element on its own line, rather than having all elements on the same line.

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Renders the BitSlice type header and contents for debug.

Examples

use bitvec::prelude::*;

let src = [0b0101_0000_1111_0101u16, 0b00000000_0000_0010];
let bits = &src.bits::<Lsb0>()[.. 18];
assert_eq!(
    "BitSlice<Lsb0, u16> [1010111100001010, 01]",
    &format!("{:?}", bits),
);

impl<'a, O, T> Default for &'a BitSlice<O, T> where
    O: BitOrder,
    T: 'a + BitStore, 

fn default() -> Self

Returns the “default value” for a type.

impl<'a, O, T> Default for &'a mut BitSlice<O, T> where
    O: BitOrder,
    T: 'a + BitStore, 

fn default() -> Self

Returns the “default value” for a type.

impl<O, T> Display for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

Prints the BitSlice for displaying.

This prints each element in turn, formatted in binary in semantic order (so the first bit seen is printed first and the last bit seen is printed last). Each element of storage is separated by a space for ease of reading.

The alternate character {:#} prints each element on its own line.

To see the in-memory representation, use .as_total_slice() to get access to the raw elements and print that slice instead.

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<O, T> Eq for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

impl<O, T> From<&'_ BitSlice<O, T>> for BitBox<O, T> where
    O: BitOrder,
    T: BitStore, 

fn from(src: &BitSlice<O, T>) -> Self

Performs the conversion.

impl<O, T> From<&'_ BitSlice<O, T>> for BitVec<O, T> where
    O: BitOrder,
    T: BitStore, 

fn from(src: &BitSlice<O, T>) -> Self

Performs the conversion.

impl<'a, O, T> From<&'a [T]> for &'a BitSlice<O, T> where
    O: BitOrder,
    T: 'a + BitStore, 

fn from(src: &'a [T]) -> Self

Performs the conversion.

impl<'a, O, T> From<&'a T> for &'a BitSlice<O, T> where
    O: BitOrder,
    T: 'a + BitStore, 

fn from(src: &'a T) -> Self

Performs the conversion.

impl<'a, O, T> From<&'a mut [T]> for &'a mut BitSlice<O, T> where
    O: BitOrder,
    T: 'a + BitStore, 

fn from(src: &'a mut [T]) -> Self

Performs the conversion.

impl<'a, O, T> From<&'a mut T> for &'a mut BitSlice<O, T> where
    O: BitOrder,
    T: 'a + BitStore, 

fn from(src: &'a mut T) -> Self

Performs the conversion.

impl<O, T> Hash for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

Writes the contents of the BitSlice, in semantic bit order, into a hasher.

fn hash<H>(&self, hasher: &mut H) where
    H: Hasher, 

Feeds this value into the given Hasher.

pub fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<O, T> Index<Range<usize>> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

type Output = Self

The returned type after indexing.

fn index(&self, range: Range<usize>) -> &Self

Performs the indexing (container[index]) operation.

impl<O, T> Index<RangeFrom<usize>> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

type Output = Self

The returned type after indexing.

fn index(&self, range: RangeFrom<usize>) -> &Self

Performs the indexing (container[index]) operation.

impl<O, T> Index<RangeFull> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

type Output = Self

The returned type after indexing.

fn index(&self, _: RangeFull) -> &Self

Performs the indexing (container[index]) operation.

impl<O, T> Index<RangeInclusive<usize>> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

type Output = Self

The returned type after indexing.

fn index(&self, range: RangeInclusive<usize>) -> &Self

Performs the indexing (container[index]) operation.

impl<O, T> Index<RangeTo<usize>> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

type Output = Self

The returned type after indexing.

fn index(&self, range: RangeTo<usize>) -> &Self

Performs the indexing (container[index]) operation.

impl<O, T> Index<RangeToInclusive<usize>> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

type Output = Self

The returned type after indexing.

fn index(&self, range: RangeToInclusive<usize>) -> &Self

Performs the indexing (container[index]) operation.

impl<O, T> Index<usize> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

type Output = bool

The returned type after indexing.

fn index(&self, place: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<O, T> IndexMut<Range<usize>> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

fn index_mut(&mut self, range: Range<usize>) -> &mut Self

Performs the mutable indexing (container[index]) operation.

impl<O, T> IndexMut<RangeFrom<usize>> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

fn index_mut(&mut self, range: RangeFrom<usize>) -> &mut Self

Performs the mutable indexing (container[index]) operation.

impl<O, T> IndexMut<RangeFull> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

fn index_mut(&mut self, _: RangeFull) -> &mut Self

Performs the mutable indexing (container[index]) operation.

impl<O, T> IndexMut<RangeInclusive<usize>> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

fn index_mut(&mut self, range: RangeInclusive<usize>) -> &mut Self

Performs the mutable indexing (container[index]) operation.

impl<O, T> IndexMut<RangeTo<usize>> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

fn index_mut(&mut self, range: RangeTo<usize>) -> &mut Self

Performs the mutable indexing (container[index]) operation.

impl<O, T> IndexMut<RangeToInclusive<usize>> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

fn index_mut(&mut self, range: RangeToInclusive<usize>) -> &mut Self

Performs the mutable indexing (container[index]) operation.

impl<'a, O, T> IntoIterator for &'a BitSlice<O, T> where
    O: BitOrder,
    T: 'a + BitStore, 

type Item = &'a bool

The type of the elements being iterated over.

type IntoIter = Iter<'a, O, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, O, T> IntoIterator for &'a mut BitSlice<O, T> where
    O: BitOrder,
    T: 'a + BitStore, 

type Item = BitMut<'a, O, T>

The type of the elements being iterated over.

type IntoIter = IterMut<'a, O, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<O, T> LowerHex for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

Write out the contents of a BitSlice as a numeric format.

These implementations render the bits of memory governed by a BitSlice as one of the three numeric bases the Rust format system supports:

• Binary renders each bit individually as 0 or 1,
• Octal renders clusters of three bits as the numbers 0 through 7,
• Hex renders clusters of four bits as the numbers [0-9A-F].

The formatters produce a word for each T element of memory. The chunked formats (octal and hexadecimal) operate somewhat peculiarly: they show the semantic value of the memory as interpreted by the BitOrder type parameter’s implementation, and not the raw value of the memory as you might observe with a debugger.

Specifically, the chunked formats read between zero and three (octal) or four (hexadecimal) bits in BitOrder order out of a memory element, store those bits in first-high/last-low order, and then interpret that sequence as a number in their respective bases. This means that, for instance, the byte 3 (bit pattern 0b0000_0011), read in Lsb0 order, will produce the numerals "600" (110 000 00) in octal, and "C0" (1100 0000) in hexadecimal.

If the memory element is exhausted before a chunk is filled with three or four bits, then the number produced will have a lower value. The byte 0xFFu8 will always produce the octal numeral "773" (111 111 11).

The decision to chunk numeral words by memory element, even though it breaks the octal chunking pattern was made so that the rendered text will still show memory boundaries for easier inspection.

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, O, T> Neg for &'a mut BitSlice<O, T> where
    O: BitOrder,
    T: 'a + BitStore, 

Performs fixed-width 2’s-complement negation of a BitSlice.

Unlike the ! operator (Not trait), the unary - operator treats the BitSlice as if it represents a signed 2’s-complement integer of fixed width. The negation of a number in 2’s complement is defined as its inversion (using !) plus one, and on fixed-width numbers has the following discontinuities:

• A slice whose bits are all zero is considered to represent the number zero which negates as itself.
• A slice whose bits are all one is considered to represent the most negative number, which has no correpsonding positive number, and thus negates as zero.

This behavior was chosen so that all possible values would have some output, and so that repeated application converges at idempotence. The most negative input can never be reached by negation, but --MOST_NEG converges at the least unreasonable fallback value, 0.

Because BitSlice cannot move, the negation is performed in place.

type Output = Self

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Perform 2’s-complement fixed-width negation.

Negation is accomplished by inverting the bits and adding one. This has one edge case: 1000…, the most negative number for its width, will negate to zero instead of itself. It thas no corresponding positive number to which it can negate.

Parameters

• self

Examples

The contortions shown here are a result of this operator applying to a mutable reference, and this example balancing access to the original BitVec for comparison with aquiring a mutable borrow as a slice to ensure that the BitSlice implementation is used, not the BitVec.

Negate an arbitrary positive number (first bit unset).

use bitvec::prelude::*;

let mut src = 0b0110_1010u8;
let bits = src.bits_mut::<Msb0>();
eprintln!("{:?}", bits.split_at(4));
let num = &mut bits[.. 4];
-num;
eprintln!("{:?}", bits.split_at(4));
assert_eq!(&bits[.. 4], &bits[4 ..]);

Negate an arbitrary negative number. This example will use the above result to demonstrate round-trip correctness.

use bitvec::prelude::*;

let mut src = 0b1010_0110u8;
let bits = src.bits_mut::<Msb0>();
let num = &mut bits[.. 4];
-num;
assert_eq!(&bits[.. 4], &bits[4 ..]);

Negate the most negative number, which will become zero, and show convergence at zero.

use bitvec::prelude::*;

let mut src = 128u8;
let bits = src.bits_mut::<Msb0>();
let num = &mut bits[..];
-num;
assert!(bits.not_any());
let num = &mut bits[..];
-num;
assert!(bits.not_any());

impl<'a, O, T> Not for &'a mut BitSlice<O, T> where
    O: BitOrder,
    T: 'a + BitStore, 

Flips all bits in the slice, in place.

type Output = Self

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Inverts all bits in the slice.

This will not affect bits outside the slice in slice storage elements.

Parameters

• self

Examples

use bitvec::prelude::*;

let mut src = [0u8; 2];
let bits = &mut src.bits_mut::<Msb0>()[2 .. 14];
let _ = !bits;
//  The `bits` binding is consumed by the `!` operator, and a new
//  reference is returned.
// assert_eq!(bits.as_ref(), &[!0, !0]);
assert_eq!(src, [0x3F, 0xFC]);

impl<O, T> Octal for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

Write out the contents of a BitSlice as a numeric format.

These implementations render the bits of memory governed by a BitSlice as one of the three numeric bases the Rust format system supports:

• Binary renders each bit individually as 0 or 1,
• Octal renders clusters of three bits as the numbers 0 through 7,
• Hex renders clusters of four bits as the numbers [0-9A-F].

The formatters produce a word for each T element of memory. The chunked formats (octal and hexadecimal) operate somewhat peculiarly: they show the semantic value of the memory as interpreted by the BitOrder type parameter’s implementation, and not the raw value of the memory as you might observe with a debugger.

Specifically, the chunked formats read between zero and three (octal) or four (hexadecimal) bits in BitOrder order out of a memory element, store those bits in first-high/last-low order, and then interpret that sequence as a number in their respective bases. This means that, for instance, the byte 3 (bit pattern 0b0000_0011), read in Lsb0 order, will produce the numerals "600" (110 000 00) in octal, and "C0" (1100 0000) in hexadecimal.

If the memory element is exhausted before a chunk is filled with three or four bits, then the number produced will have a lower value. The byte 0xFFu8 will always produce the octal numeral "773" (111 111 11).

The decision to chunk numeral words by memory element, even though it breaks the octal chunking pattern was made so that the rendered text will still show memory boundaries for easier inspection.

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<O, T> Ord for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

fn cmp(&self, rhs: &Self) -> Ordering

This method returns an Ordering between self and other.

#[must_use]pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<A, B, C, D> PartialEq<&'_ BitSlice<C, D>> for BitSlice<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn eq(&self, rhs: &&BitSlice<C, D>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A, B, C, D> PartialEq<&'_ BitSlice<C, D>> for BitVec<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn eq(&self, rhs: &&BitSlice<C, D>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A, B, C, D> PartialEq<BitBox<C, D>> for BitSlice<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn eq(&self, rhs: &BitBox<C, D>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A, B, C, D> PartialEq<BitSlice<C, D>> for BitSlice<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

Tests if two BitSlices are semantically — not bitwise — equal.

It is valid to compare two slices of different ordering or element types.

The equality condition requires that they have the same number of total bits and that each pair of bits in semantic order are identical.

fn eq(&self, rhs: &BitSlice<C, D>) -> bool

Performas a comparison by ==.

Examples

use bitvec::prelude::*;

let lsrc = [8u8, 16, 32, 0];
let rsrc = 0x10_08_04_00u32;
let lbits = lsrc.bits::<Lsb0>();
let rbits = rsrc.bits::<Msb0>();

assert_eq!(lbits, rbits);

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A, B, C, D> PartialEq<BitSlice<C, D>> for &BitSlice<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn eq(&self, rhs: &BitSlice<C, D>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A, B, C, D> PartialEq<BitSlice<C, D>> for BitBox<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn eq(&self, rhs: &BitSlice<C, D>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A, B, C, D> PartialEq<BitSlice<C, D>> for BitVec<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn eq(&self, rhs: &BitSlice<C, D>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A, B, C, D> PartialEq<BitVec<C, D>> for BitSlice<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn eq(&self, rhs: &BitVec<C, D>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A, B, C, D> PartialEq<BitVec<C, D>> for &BitSlice<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn eq(&self, rhs: &BitVec<C, D>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A, B, C, D> PartialOrd<&'_ BitSlice<C, D>> for BitSlice<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn partial_cmp(&self, rhs: &&BitSlice<C, D>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]pub fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]pub fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A, B, C, D> PartialOrd<&'_ BitSlice<C, D>> for BitVec<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn partial_cmp(&self, rhs: &&BitSlice<C, D>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]pub fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]pub fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A, B, C, D> PartialOrd<BitBox<C, D>> for BitSlice<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn partial_cmp(&self, rhs: &BitBox<C, D>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]pub fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]pub fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A, B, C, D> PartialOrd<BitSlice<C, D>> for BitSlice<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

Compares two BitSlices by semantic — not bitwise — ordering.

The comparison sorts by testing each index for one slice to have a set bit where the other has an unset bit. If the slices are different, the slice with the set bit sorts greater than the slice with the unset bit.

If one of the slices is exhausted before they differ, the longer slice is greater.

fn partial_cmp(&self, rhs: &BitSlice<C, D>) -> Option<Ordering>

Performs a comparison by < or >.

Examples

use bitvec::prelude::*;

let src = 0x45u8;
let bits = src.bits::<Msb0>();
let a = &bits[0 .. 3]; // 010
let b = &bits[0 .. 4]; // 0100
let c = &bits[0 .. 5]; // 01000
let d = &bits[4 .. 8]; // 0101

assert!(a < b);
assert!(b < c);
assert!(c < d);

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]pub fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]pub fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A, B, C, D> PartialOrd<BitSlice<C, D>> for &BitSlice<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn partial_cmp(&self, rhs: &BitSlice<C, D>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]pub fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]pub fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A, B, C, D> PartialOrd<BitSlice<C, D>> for BitBox<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn partial_cmp(&self, rhs: &BitSlice<C, D>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]pub fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]pub fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A, B, C, D> PartialOrd<BitSlice<C, D>> for BitVec<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn partial_cmp(&self, rhs: &BitSlice<C, D>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]pub fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]pub fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A, B, C, D> PartialOrd<BitVec<C, D>> for BitSlice<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn partial_cmp(&self, rhs: &BitVec<C, D>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]pub fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]pub fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A, B, C, D> PartialOrd<BitVec<C, D>> for &BitSlice<A, B> where
    A: BitOrder,
    B: BitStore,
    C: BitOrder,
    D: BitStore, 

fn partial_cmp(&self, rhs: &BitVec<C, D>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]pub fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]pub fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<O, T> ShlAssign<usize> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

Shifts all bits in the array to the left — DOWN AND TOWARDS THE FRONT.

On fundamentals, the left-shift operator << moves bits away from the origin and towards the ceiling. This is because we label the bits in a primitive with the minimum on the right and the maximum on the left, which is big-endian bit order. This increases the value of the primitive being shifted.

THAT IS NOT HOW BitSlice WORKS!

BitSlice defines its layout with the minimum on the left and the maximum on the right! Thus, left-shifting moves bits towards the minimum.

In Msb0 order, the effect in memory will be what you expect the << operator to do.

In Lsb0 order, the effect will be equivalent to using >> on the fundamentals in memory!

Notes

In order to preserve the effecs in memory that this operator traditionally expects, the bits that are emptied by this operation are zeroed rather than left to their old value.

The shift amount is modulated against the array length, so it is not an error to pass a shift amount greater than the array length.

A shift amount of zero is a no-op, and returns immediately.

fn shl_assign(&mut self, shamt: usize)

Shifts a slice left, in place.

Parameters

• &mut self
• shamt: The shift amount. If this is greater than the length, then the slice is zeroed immediately.

Examples

use bitvec::prelude::*;

let mut src = [0x4Bu8, 0xA5];
let bits = &mut src.bits_mut::<Msb0>()[2 .. 14];
*bits <<= 3;
assert_eq!(src, [0b01_011_101, 0b001_000_01]);

impl<O, T> ShrAssign<usize> for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

Shifts all bits in the array to the right — UP AND TOWARDS THE BACK.

On fundamentals, the right-shift operator >> moves bits towards the origin and away from the ceiling. This is because we label the bits in a primitive with the minimum on the right and the maximum on the left, which is big-endian bit order. This decreases the value of the primitive being shifted.

THAT IS NOT HOW BitSlice WORKS!

BitSlice defines its layout with the minimum on the left and the maximum on the right! Thus, right-shifting moves bits towards the maximum.

In Msb0 order, the effect in memory will be what you expect the >> operator to do.

In Lsb0 order, the effect will be equivalent to using << on the fundamentals in memory!

Notes

In order to preserve the effects in memory that this operator traditionally expects, the bits that are emptied by this operation are zeroed rather than left to their old value.

The shift amount is modulated against the array length, so it is not an error to pass a shift amount greater than the array length.

A shift amount of zero is a no-op, and returns immediately.

fn shr_assign(&mut self, shamt: usize)

Shifts a slice right, in place.

Parameters

• &mut self
• shamt: The shift amount. If this is greater than the length, then the slice is zeroed immediately.

Examples

use bitvec::prelude::*;

let mut src = [0x4Bu8, 0xA5];
let bits = &mut src.bits_mut::<Msb0>()[2 .. 14];
*bits >>= 3;
assert_eq!(src, [0b01_000_00_1, 0b011_101_01])

impl<O, T> ToOwned for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

type Owned = BitVec<O, T>

The resulting type after obtaining ownership.

fn to_owned(&self) -> Self::Owned

Creates owned data from borrowed data, usually by cloning.

pub fn clone_into(&self, target: &mut Self::Owned)

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning.

impl<O, T> UpperHex for BitSlice<O, T> where
    O: BitOrder,
    T: BitStore, 

Write out the contents of a BitSlice as a numeric format.

These implementations render the bits of memory governed by a BitSlice as one of the three numeric bases the Rust format system supports:

• Binary renders each bit individually as 0 or 1,
• Octal renders clusters of three bits as the numbers 0 through 7,
• Hex renders clusters of four bits as the numbers [0-9A-F].

The formatters produce a word for each T element of memory. The chunked formats (octal and hexadecimal) operate somewhat peculiarly: they show the semantic value of the memory as interpreted by the BitOrder type parameter’s implementation, and not the raw value of the memory as you might observe with a debugger.

Specifically, the chunked formats read between zero and three (octal) or four (hexadecimal) bits in BitOrder order out of a memory element, store those bits in first-high/last-low order, and then interpret that sequence as a number in their respective bases. This means that, for instance, the byte 3 (bit pattern 0b0000_0011), read in Lsb0 order, will produce the numerals "600" (110 000 00) in octal, and "C0" (1100 0000) in hexadecimal.

If the memory element is exhausted before a chunk is filled with three or four bits, then the number produced will have a lower value. The byte 0xFFu8 will always produce the octal numeral "773" (111 111 11).

The decision to chunk numeral words by memory element, even though it breaks the octal chunking pattern was made so that the rendered text will still show memory boundaries for easier inspection.

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.