Struct Bits

pub struct Bits { /* private fields */ }

A cheaply cloneable chunk of contiugous memory, built on top of [bytes::Bytes] but providing bit-level operations.

Implementations

impl Bits

pub fn from_bytes(bytes: Bytes) -> Bits

Creates a new empty Bits from an instance of Bytes

pub fn from_static_bytes(bytes: &'static [u8]) -> Bits

pub fn from_owner_bytes<T>(owner: T) -> Bits

where T: AsRef<[u8]> + Send + 'static,

pub fn copy_from_bit_slice(bits: &BitSlice<u8, Msb0>) -> Bits

Creates a new Bits instance from the given BitSlice by copying it.

pub fn copy_from_bytes(bytes: &[u8]) -> Bits

Creates a new Bits instance from the given u8 slice by copying it.

pub fn slice_bits(&self, range: Range<usize>) -> Bits

Create a slice corresponding to the given range, which is given in bits. The given range is relative to the start of the buffer, not the current position.

pub fn slice_bytes(&self, range: Range<usize>) -> Bits

Create a slice corresponding to the given range, which is given in bytes. The given range is relative to the start of the buffer, not the current position. Note that the ‘start’ of this view may not correspond to a byte boundary on the underlying storage.

pub fn split_to_bits(&mut self, at: usize) -> Bits

Splits the bits into two at the given bit index.

Afterwards self contains elements [at, len), and the returned Bits contains elements [0, at).

pub fn split_to_bytes(&mut self, at: usize) -> Bits

Splits the bits into two at the given byte index. Note that this byte index is relative to the start of this view, and may not fall on a byte boundary in the underlying storage.

Afterwards self contains elements [at, len), and the returned Bits contains elements [0, at).

pub fn split_off_bits(&mut self, at: usize) -> Bits

Splits the bits into two at the given index.

Afterwards self contains elements [0, at), and the returned Bits contains elements [at, len).

pub fn split_off_bytes(&mut self, at: usize) -> Bits

Splits the bits into two at the given byte index. Note that this byte index is relative to the start of this view, and may not fall on a byte boundary in the underlying storage.

Afterwards self contains elements [0, at), and the returned Bits contains elements [at, len).

pub fn truncate_bits(&mut self, len: usize)

Shortens the buffer, keeping the first len bits and dropping the rest.

If len is greater than the buffer’s current length, this has no effect.

The split_off method can emulate truncate, but this causes the excess bits to be returned instead of dropped.

pub fn truncate_bytes(&mut self, len: usize)

Shortens the buffer, keeping the first len bytes and dropping the rest.

If len is greater than the buffer’s current length, this has no effect.

The split_off method can emulate truncate, but this causes the excess bits to be returned instead of dropped.

pub fn clear(&mut self)

Clears the buffer, removing all data.

pub fn len_bits(&self) -> usize

Returns the number of bits contained in this Bits

pub fn len_bytes(&self) -> usize

Returns the number of complete bytes contained in this Bits. Note that this Bits may contain a number of bits that does not evenly divide into bytes: this method returns the number of complete bytes, i.e. it does a truncating divide on the number of bits.

pub fn is_empty(&self) -> bool

Returns true if the Bits has a length of 0.

Methods from Deref<Target = BitSlice<u8, Msb0>>

pub fn len(&self) -> usize

Gets the number of bits in the bit-slice.

Original

slice::len

Examples

use bitvec::prelude::*;

assert_eq!(bits![].len(), 0);
assert_eq!(bits![0; 10].len(), 10);

pub fn is_empty(&self) -> bool

Tests if the bit-slice is empty (length zero).

Original

slice::is_empty

Examples

use bitvec::prelude::*;

assert!(bits![].is_empty());
assert!(!bits![0; 10].is_empty());

pub fn first(&self) -> Option<BitRef<'_, Const, T, O>>

Gets a reference to the first bit of the bit-slice, or None if it is empty.

Original

slice::first

API Differences

bitvec uses a custom structure for both read-only and mutable references to bool.

Examples

use bitvec::prelude::*;

let bits = bits![1, 0, 0];
assert_eq!(bits.first().as_deref(), Some(&true));

assert!(bits![].first().is_none());

pub fn split_first(&self) -> Option<(BitRef<'_, Const, T, O>, &BitSlice<T, O>)>

Splits the bit-slice into a reference to its first bit, and the rest of the bit-slice. Returns None when empty.

Original

slice::split_first

API Differences

bitvec uses a custom structure for both read-only and mutable references to bool.

Examples

use bitvec::prelude::*;

let bits = bits![1, 0, 0];
let (first, rest) = bits.split_first().unwrap();
assert_eq!(first, &true);
assert_eq!(rest, bits![0; 2]);

pub fn split_last(&self) -> Option<(BitRef<'_, Const, T, O>, &BitSlice<T, O>)>

Splits the bit-slice into a reference to its last bit, and the rest of the bit-slice. Returns None when empty.

Original

slice::split_last

API Differences

bitvec uses a custom structure for both read-only and mutable references to bool.

Examples

use bitvec::prelude::*;

let bits = bits![0, 0, 1];
let (last, rest) = bits.split_last().unwrap();
assert_eq!(last, &true);
assert_eq!(rest, bits![0; 2]);

pub fn last(&self) -> Option<BitRef<'_, Const, T, O>>

Gets a reference to the last bit of the bit-slice, or None if it is empty.

Original

slice::last

API Differences

bitvec uses a custom structure for both read-only and mutable references to bool.

Examples

use bitvec::prelude::*;

let bits = bits![0, 0, 1];
assert_eq!(bits.last().as_deref(), Some(&true));

assert!(bits![].last().is_none());

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

where I: BitSliceIndex<'a, T, O>,

Gets a reference to a single bit or a subsection of the bit-slice, depending on the type of index.

• If given a usize, this produces a reference structure to the bool at the position.
• If given any form of range, this produces a smaller bit-slice.

This returns None if the index departs the bounds of self.

Original

slice::get

API Differences

BitSliceIndex uses discrete types for immutable and mutable references, rather than a single referent type.

Examples

use bitvec::prelude::*;

let bits = bits![0, 1, 0];
assert_eq!(bits.get(1).as_deref(), Some(&true));
assert_eq!(bits.get(0 .. 2), Some(bits![0, 1]));
assert!(bits.get(3).is_none());
assert!(bits.get(0 .. 4).is_none());

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

where I: BitSliceIndex<'a, T, O>,

Gets a reference to a single bit or to a subsection of the bit-slice, without bounds checking.

This has the same arguments and behavior as .get(), except that it does not check that index is in bounds.

Original

slice::get_unchecked

Safety

You must ensure that index is within bounds (within the range 0 .. self.len()), or this method will introduce memory safety and/or undefined behavior.

It is library-level undefined behavior to index beyond the length of any bit-slice, even if you know that the offset remains within an allocation as measured by Rust or LLVM.

Examples

use bitvec::prelude::*;

let data = 0b0001_0010u8;
let bits = &data.view_bits::<Lsb0>()[.. 3];

unsafe {
  assert!(bits.get_unchecked(1));
  assert!(bits.get_unchecked(4));
}

pub fn as_ptr(&self) -> BitPtr<Const, T, O>

👎Deprecated: use .as_bitptr() instead

pub fn as_ptr_range(&self) -> Range<BitPtr<Const, T, O>>

Produces a range of bit-pointers to each bit in the bit-slice.

This is a standard-library range, which has no real functionality for pointer types. You should prefer .as_bitptr_range() instead, as it produces a custom structure that provides expected ranging functionality.

Original

slice::as_ptr_range

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

Produces an iterator over each bit in the bit-slice.

Original

slice::iter

API Differences

This iterator yields proxy-reference structures, not &bool. It can be adapted to yield &bool with the .by_refs() method, or bool with .by_vals().

This iterator, and its adapters, are fast. Do not try to be more clever than them by abusing .as_bitptr_range().

Examples

use bitvec::prelude::*;

let bits = bits![0, 1, 0, 1];
let mut iter = bits.iter();

assert!(!iter.next().unwrap());
assert!( iter.next().unwrap());
assert!( iter.next_back().unwrap());
assert!(!iter.next_back().unwrap());
assert!( iter.next().is_none());

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

Iterates over consecutive windowing subslices in a bit-slice.

Windows are overlapping views of the bit-slice. Each window advances one bit from the previous, so in a bit-slice [A, B, C, D, E], calling .windows(3) will yield [A, B, C], [B, C, D], and [C, D, E].

Original

slice::windows

Panics

This panics if size is 0.

Examples

use bitvec::prelude::*;

let bits = bits![0, 1, 0, 0, 1];
let mut iter = bits.windows(3);

assert_eq!(iter.next(), Some(bits![0, 1, 0]));
assert_eq!(iter.next(), Some(bits![1, 0, 0]));
assert_eq!(iter.next(), Some(bits![0, 0, 1]));
assert!(iter.next().is_none());

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

Iterates over non-overlapping subslices of a bit-slice.

Unlike .windows(), the subslices this yields do not overlap with each other. If self.len() is not an even multiple of chunk_size, then the last chunk yielded will be shorter.

Original

slice::chunks

Sibling Methods

• .chunks_mut() has the same division logic, but each yielded bit-slice is mutable.
• .chunks_exact() does not yield the final chunk if it is shorter than chunk_size.
• .rchunks() iterates from the back of the bit-slice to the front, with the final, possibly-shorter, segment at the front edge.

Panics

This panics if chunk_size is 0.

Examples

use bitvec::prelude::*;

let bits = bits![0, 1, 0, 0, 1];
let mut iter = bits.chunks(2);

assert_eq!(iter.next(), Some(bits![0, 1]));
assert_eq!(iter.next(), Some(bits![0, 0]));
assert_eq!(iter.next(), Some(bits![1]));
assert!(iter.next().is_none());

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

Iterates over non-overlapping subslices of a bit-slice.

If self.len() is not an even multiple of chunk_size, then the last few bits are not yielded by the iterator at all. They can be accessed with the .remainder() method if the iterator is bound to a name.

Original

slice::chunks_exact

Sibling Methods

• .chunks() yields any leftover bits at the end as a shorter chunk during iteration.
• .chunks_exact_mut() has the same division logic, but each yielded bit-slice is mutable.
• .rchunks_exact() iterates from the back of the bit-slice to the front, with the unyielded remainder segment at the front edge.

Panics

This panics if chunk_size is 0.

Examples

use bitvec::prelude::*;

let bits = bits![0, 1, 0, 0, 1];
let mut iter = bits.chunks_exact(2);

assert_eq!(iter.next(), Some(bits![0, 1]));
assert_eq!(iter.next(), Some(bits![0, 0]));
assert!(iter.next().is_none());
assert_eq!(iter.remainder(), bits![1]);

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

Iterates over non-overlapping subslices of a bit-slice, from the back edge.

Unlike .chunks(), this aligns its chunks to the back edge of self. If self.len() is not an even multiple of chunk_size, then the leftover partial chunk is self[0 .. len % chunk_size].

Original

slice::rchunks

Sibling Methods

• .rchunks_mut() has the same division logic, but each yielded bit-slice is mutable.
• .rchunks_exact() does not yield the final chunk if it is shorter than chunk_size.
• .chunks() iterates from the front of the bit-slice to the back, with the final, possibly-shorter, segment at the back edge.

Panics

This panics if chunk_size is 0.

Examples

use bitvec::prelude::*;

let bits = bits![0, 1, 0, 0, 1];
let mut iter = bits.rchunks(2);

assert_eq!(iter.next(), Some(bits![0, 1]));
assert_eq!(iter.next(), Some(bits![1, 0]));
assert_eq!(iter.next(), Some(bits![0]));
assert!(iter.next().is_none());

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

Iterates over non-overlapping subslices of a bit-slice, from the back edge.

If self.len() is not an even multiple of chunk_size, then the first few bits are not yielded by the iterator at all. They can be accessed with the .remainder() method if the iterator is bound to a name.

Original

slice::rchunks_exact

Sibling Methods

• .rchunks() yields any leftover bits at the front as a shorter chunk during iteration.
• .rchunks_exact_mut() has the same division logic, but each yielded bit-slice is mutable.
• .chunks_exact() iterates from the front of the bit-slice to the back, with the unyielded remainder segment at the back edge.

Panics

This panics if chunk_size is 0.

Examples

use bitvec::prelude::*;

let bits = bits![0, 1, 0, 0, 1];
let mut iter = bits.rchunks_exact(2);

assert_eq!(iter.next(), Some(bits![0, 1]));
assert_eq!(iter.next(), Some(bits![1, 0]));
assert!(iter.next().is_none());
assert_eq!(iter.remainder(), bits![0]);

pub fn split_at(&self, mid: usize) -> (&BitSlice<T, O>, &BitSlice<T, O>)

Splits a bit-slice in two parts at an index.

The returned bit-slices are self[.. mid] and self[mid ..]. mid is included in the right bit-slice, not the left.

If mid is 0 then the left bit-slice is empty; if it is self.len() then the right bit-slice is empty.

This method guarantees that even when either partition is empty, the encoded bit-pointer values of the bit-slice references is &self[0] and &self[mid].

Original

slice::split_at

Panics

This panics if mid is greater than self.len(). It is allowed to be equal to the length, in which case the right bit-slice is simply empty.

Examples

use bitvec::prelude::*;

let bits = bits![0, 0, 0, 1, 1, 1];
let base = bits.as_bitptr();

let (a, b) = bits.split_at(0);
assert_eq!(unsafe { a.as_bitptr().offset_from(base) }, 0);
assert_eq!(unsafe { b.as_bitptr().offset_from(base) }, 0);

let (a, b) = bits.split_at(6);
assert_eq!(unsafe { b.as_bitptr().offset_from(base) }, 6);

let (a, b) = bits.split_at(3);
assert_eq!(a, bits![0; 3]);
assert_eq!(b, bits![1; 3]);

pub fn split<F>(&self, pred: F) -> Split<'_, T, O, F>

where F: FnMut(usize, &bool) -> bool,

Iterates over subslices separated by bits that match a predicate. The matched bit is not contained in the yielded bit-slices.

Original

slice::split

API Differences

The predicate function receives the index being tested as well as the bit value at that index. This allows the predicate to have more than one bit of information about the bit-slice being traversed.

Sibling Methods

• .split_mut() has the same splitting logic, but each yielded bit-slice is mutable.
• .split_inclusive() includes the matched bit in the yielded bit-slice.
• .rsplit() iterates from the back of the bit-slice instead of the front.
• .splitn() times out after n yields.

Examples

use bitvec::prelude::*;

let bits = bits![0, 1, 1, 0];
//                     ^
let mut iter = bits.split(|pos, _bit| pos % 3 == 2);

assert_eq!(iter.next().unwrap(), bits![0, 1]);
assert_eq!(iter.next().unwrap(), bits![0]);
assert!(iter.next().is_none());

If the first bit is matched, then an empty bit-slice will be the first item yielded by the iterator. Similarly, if the last bit in the bit-slice matches, then an empty bit-slice will be the last item yielded.

use bitvec::prelude::*;

let bits = bits![0, 0, 1];
//                     ^
let mut iter = bits.split(|_pos, bit| *bit);

assert_eq!(iter.next().unwrap(), bits![0; 2]);
assert!(iter.next().unwrap().is_empty());
assert!(iter.next().is_none());

If two matched bits are directly adjacent, then an empty bit-slice will be yielded between them:

use bitvec::prelude::*;

let bits = bits![1, 0, 0, 1];
//                  ^  ^
let mut iter = bits.split(|_pos, bit| !*bit);

assert_eq!(iter.next().unwrap(), bits![1]);
assert!(iter.next().unwrap().is_empty());
assert_eq!(iter.next().unwrap(), bits![1]);
assert!(iter.next().is_none());

pub fn split_inclusive<F>(&self, pred: F) -> SplitInclusive<'_, T, O, F>

where F: FnMut(usize, &bool) -> bool,

Iterates over subslices separated by bits that match a predicate. Unlike .split(), this does include the matching bit as the last bit in the yielded bit-slice.

Original

slice::split_inclusive

API Differences

The predicate function receives the index being tested as well as the bit value at that index. This allows the predicate to have more than one bit of information about the bit-slice being traversed.

Sibling Methods

• .split_inclusive_mut() has the same splitting logic, but each yielded bit-slice is mutable.
• .split() does not include the matched bit in the yielded bit-slice.

Examples

use bitvec::prelude::*;

let bits = bits![0, 0, 1, 0, 1];
//                     ^     ^
let mut iter = bits.split_inclusive(|_pos, bit| *bit);

assert_eq!(iter.next().unwrap(), bits![0, 0, 1]);
assert_eq!(iter.next().unwrap(), bits![0, 1]);
assert!(iter.next().is_none());

pub fn rsplit<F>(&self, pred: F) -> RSplit<'_, T, O, F>

where F: FnMut(usize, &bool) -> bool,

Iterates over subslices separated by bits that match a predicate, from the back edge. The matched bit is not contained in the yielded bit-slices.

Original

slice::rsplit

API Differences

The predicate function receives the index being tested as well as the bit value at that index. This allows the predicate to have more than one bit of information about the bit-slice being traversed.

Sibling Methods

• .rsplit_mut() has the same splitting logic, but each yielded bit-slice is mutable.
• .split() iterates from the front of the bit-slice instead of the back.
• .rsplitn() times out after n yields.

Examples

use bitvec::prelude::*;

let bits = bits![0, 1, 1, 0];
//                     ^
let mut iter = bits.rsplit(|pos, _bit| pos % 3 == 2);

assert_eq!(iter.next().unwrap(), bits![0]);
assert_eq!(iter.next().unwrap(), bits![0, 1]);
assert!(iter.next().is_none());

If the last bit is matched, then an empty bit-slice will be the first item yielded by the iterator. Similarly, if the first bit in the bit-slice matches, then an empty bit-slice will be the last item yielded.

use bitvec::prelude::*;

let bits = bits![0, 0, 1];
//                     ^
let mut iter = bits.rsplit(|_pos, bit| *bit);

assert!(iter.next().unwrap().is_empty());
assert_eq!(iter.next().unwrap(), bits![0; 2]);
assert!(iter.next().is_none());

If two yielded bits are directly adjacent, then an empty bit-slice will be yielded between them:

use bitvec::prelude::*;

let bits = bits![1, 0, 0, 1];
//                  ^  ^
let mut iter = bits.split(|_pos, bit| !*bit);

assert_eq!(iter.next().unwrap(), bits![1]);
assert!(iter.next().unwrap().is_empty());
assert_eq!(iter.next().unwrap(), bits![1]);
assert!(iter.next().is_none());

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

where F: FnMut(usize, &bool) -> bool,

Iterates over subslices separated by bits that match a predicate, giving up after yielding n times. The nth yield contains the rest of the bit-slice. As with .split(), the yielded bit-slices do not contain the matched bit.

Original

slice::splitn

API Differences

The predicate function receives the index being tested as well as the bit value at that index. This allows the predicate to have more than one bit of information about the bit-slice being traversed.

Sibling Methods

• .splitn_mut() has the same splitting logic, but each yielded bit-slice is mutable.
• .rsplitn() iterates from the back of the bit-slice instead of the front.
• .split() has the same splitting logic, but never times out.

Examples

use bitvec::prelude::*;

let bits = bits![0, 0, 1, 0, 1, 0];
let mut iter = bits.splitn(2, |_pos, bit| *bit);

assert_eq!(iter.next().unwrap(), bits![0, 0]);
assert_eq!(iter.next().unwrap(), bits![0, 1, 0]);
assert!(iter.next().is_none());

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

where F: FnMut(usize, &bool) -> bool,

Iterates over mutable subslices separated by bits that match a predicate from the back edge, giving up after yielding n times. The nth yield contains the rest of the bit-slice. As with .split_mut(), the yielded bit-slices do not contain the matched bit.

Original

slice::rsplitn

API Differences

The predicate function receives the index being tested as well as the bit value at that index. This allows the predicate to have more than one bit of information about the bit-slice being traversed.

Sibling Methods

• .rsplitn_mut() has the same splitting logic, but each yielded bit-slice is mutable.
• .splitn(): iterates from the front of the bit-slice instead of the back.
• .rsplit() has the same splitting logic, but never times out.

Examples

use bitvec::prelude::*;

let bits = bits![0, 0, 1, 1, 0];
//                        ^
let mut iter = bits.rsplitn(2, |_pos, bit| *bit);

assert_eq!(iter.next().unwrap(), bits![0]);
assert_eq!(iter.next().unwrap(), bits![0, 0, 1]);
assert!(iter.next().is_none());

pub fn contains<T2, O2>(&self, other: &BitSlice<T2, O2>) -> bool

where T2: BitStore, O2: BitOrder,

Tests if the bit-slice contains the given sequence anywhere within it.

This scans over self.windows(other.len()) until one of the windows matches. The search key does not need to share type parameters with the bit-slice being tested, as the comparison is bit-wise. However, sharing type parameters will accelerate the comparison.

Original

slice::contains

Examples

use bitvec::prelude::*;

let bits = bits![0, 0, 1, 0, 1, 1, 0, 0];
assert!( bits.contains(bits![0, 1, 1, 0]));
assert!(!bits.contains(bits![1, 0, 0, 1]));

pub fn starts_with<T2, O2>(&self, needle: &BitSlice<T2, O2>) -> bool

where T2: BitStore, O2: BitOrder,

Tests if the bit-slice begins with the given sequence.

The search key does not need to share type parameters with the bit-slice being tested, as the comparison is bit-wise. However, sharing type parameters will accelerate the comparison.

Original

slice::starts_with

Examples

use bitvec::prelude::*;

let bits = bits![0, 1, 1, 0];
assert!( bits.starts_with(bits![0, 1]));
assert!(!bits.starts_with(bits![1, 0]));

This always returns true if the needle is empty:

use bitvec::prelude::*;

let bits = bits![0, 1, 0];
let empty = bits![];
assert!(bits.starts_with(empty));
assert!(empty.starts_with(empty));

pub fn ends_with<T2, O2>(&self, needle: &BitSlice<T2, O2>) -> bool

where T2: BitStore, O2: BitOrder,

Tests if the bit-slice ends with the given sequence.

The search key does not need to share type parameters with the bit-slice being tested, as the comparison is bit-wise. However, sharing type parameters will accelerate the comparison.

Original

slice::ends_with

Examples

use bitvec::prelude::*;

let bits = bits![0, 1, 1, 0];
assert!( bits.ends_with(bits![1, 0]));
assert!(!bits.ends_with(bits![0, 1]));

This always returns true if the needle is empty:

use bitvec::prelude::*;

let bits = bits![0, 1, 0];
let empty = bits![];
assert!(bits.ends_with(empty));
assert!(empty.ends_with(empty));

pub fn strip_prefix<T2, O2>( &self, prefix: &BitSlice<T2, O2>, ) -> Option<&BitSlice<T, O>>

where T2: BitStore, O2: BitOrder,

Removes a prefix bit-slice, if present.

Like .starts_with(), the search key does not need to share type parameters with the bit-slice being stripped. If self.starts_with(suffix), then this returns Some(&self[prefix.len() ..]), otherwise it returns None.

Original

slice::strip_prefix

API Differences

BitSlice does not support pattern searches; instead, it permits self and prefix to differ in type parameters.

Examples

use bitvec::prelude::*;

let bits = bits![0, 1, 0, 0, 1, 0, 1, 1, 0];
assert_eq!(bits.strip_prefix(bits![0, 1]).unwrap(), bits[2 ..]);
assert_eq!(bits.strip_prefix(bits![0, 1, 0, 0,]).unwrap(), bits[4 ..]);
assert!(bits.strip_prefix(bits![1, 0]).is_none());

pub fn strip_suffix<T2, O2>( &self, suffix: &BitSlice<T2, O2>, ) -> Option<&BitSlice<T, O>>

where T2: BitStore, O2: BitOrder,

Removes a suffix bit-slice, if present.

Like .ends_with(), the search key does not need to share type parameters with the bit-slice being stripped. If self.ends_with(suffix), then this returns Some(&self[.. self.len() - suffix.len()]), otherwise it returns None.

Original

slice::strip_suffix

API Differences

BitSlice does not support pattern searches; instead, it permits self and suffix to differ in type parameters.

Examples

use bitvec::prelude::*;

let bits = bits![0, 1, 0, 0, 1, 0, 1, 1, 0];
assert_eq!(bits.strip_suffix(bits![1, 0]).unwrap(), bits[.. 7]);
assert_eq!(bits.strip_suffix(bits![0, 1, 1, 0]).unwrap(), bits[.. 5]);
assert!(bits.strip_suffix(bits![0, 1]).is_none());

pub unsafe fn align_to<U>( &self, ) -> (&BitSlice<T, O>, &BitSlice<U, O>, &BitSlice<T, O>)

where U: BitStore,

Produces bit-slice view(s) with different underlying storage types.

This may have unexpected effects, and you cannot assume that before[idx] == after[idx]! Consult the tables in the manual for information about memory layouts.

Original

slice::align_to

Notes

Unlike the standard library documentation, this explicitly guarantees that the middle bit-slice will have maximal size. You may rely on this property.

Safety

You may not use this to cast away alias protections. Rust does not have support for higher-kinded types, so this cannot express the relation Outer<T> -> Outer<U> where Outer: BitStoreContainer, but memory safety does require that you respect this rule. Reälign integers to integers, Cells to Cells, and atomics to atomics, but do not cross these boundaries.

Examples

use bitvec::prelude::*;

let bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7];
let bits = bytes.view_bits::<Lsb0>();
let (pfx, mid, sfx) = unsafe {
  bits.align_to::<u16>()
};
assert!(pfx.len() <= 8);
assert_eq!(mid.len(), 48);
assert!(sfx.len() <= 8);

pub fn to_vec(&self) -> BitVec<<T as BitStore>::Unalias, O>

👎Deprecated: use .to_bitvec() instead

pub fn repeat(&self, n: usize) -> BitVec<<T as BitStore>::Unalias, O>

Creates a bit-vector by repeating a bit-slice n times.

Original

slice::repeat

Panics

This method panics if self.len() * n exceeds the BitVec capacity.

Examples

use bitvec::prelude::*;

assert_eq!(bits![0, 1].repeat(3), bitvec![0, 1, 0, 1, 0, 1]);

This panics by exceeding bit-vector maximum capacity:

use bitvec::prelude::*;

bits![0, 1].repeat(BitSlice::<usize, Lsb0>::MAX_BITS);

pub fn as_bitptr(&self) -> BitPtr<Const, T, O>

Gets a raw pointer to the zeroth bit of the bit-slice.

Original

slice::as_ptr

API Differences

This is renamed in order to indicate that it is returning a bitvec structure, not a raw pointer.

pub fn as_bitptr_range(&self) -> BitPtrRange<Const, T, O>

Views the bit-slice as a half-open range of bit-pointers, to its first bit in the bit-slice and first bit beyond it.

Original

slice::as_ptr_range

API Differences

This is renamed to indicate that it returns a bitvec structure, rather than an ordinary Range.

Notes

BitSlice does define a .as_ptr_range(), which returns a Range<BitPtr>. BitPtrRange has additional capabilities that Range<*const T> and Range<BitPtr> do not.

pub unsafe fn split_at_unchecked( &self, mid: usize, ) -> (&BitSlice<T, O>, &BitSlice<T, O>)

Splits a bit-slice at an index, without bounds checking.

See .split_at() for documentation.

Safety

You must ensure that mid is in the range 0 ..= self.len().

This method produces new bit-slice references. If mid is out of bounds, its behavior is library-level undefined. You must conservatively assume that an out-of-bounds split point produces compiler-level UB.

pub fn bit_domain(&self) -> BitDomain<'_, Const, T, O>

Partitions a bit-slice into maybe-contended and known-uncontended parts.

The documentation of BitDomain goes into this in more detail. In short, this produces a &BitSlice that is as large as possible without requiring alias protection, as well as any bits that were not able to be included in the unaliased bit-slice.

pub fn domain(&self) -> Domain<'_, Const, T, O>

Views the underlying memory of a bit-slice, removing alias protections where possible.

The documentation of Domain goes into this in more detail. In short, this produces a &[T] slice with alias protections removed, covering all elements that self completely fills. Partially-used elements on either the front or back edge of the slice are returned separately.

pub fn count_ones(&self) -> usize

Counts the number of bits set to 1 in the bit-slice contents.

Examples

use bitvec::prelude::*;

let bits = bits![1, 1, 0, 0];
assert_eq!(bits[.. 2].count_ones(), 2);
assert_eq!(bits[2 ..].count_ones(), 0);
assert_eq!(bits![].count_ones(), 0);

pub fn count_zeros(&self) -> usize

Counts the number of bits cleared to 0 in the bit-slice contents.

Examples

use bitvec::prelude::*;

let bits = bits![1, 1, 0, 0];
assert_eq!(bits[.. 2].count_zeros(), 0);
assert_eq!(bits[2 ..].count_zeros(), 2);
assert_eq!(bits![].count_zeros(), 0);

pub fn iter_ones(&self) -> IterOnes<'_, T, O>

Enumerates the index of each bit in a bit-slice set to 1.

This is a shorthand for a .enumerate().filter_map() iterator that selects the index of each true bit; however, its implementation is eligible for optimizations that the individual-bit iterator is not.

Specializations for the Lsb0 and Msb0 orderings allow processors with instructions that seek particular bits within an element to operate on whole elements, rather than on each bit individually.

Examples

This example uses .iter_ones(), a .filter_map() that finds the index of each set bit, and the known indices, in order to show that they have equivalent behavior.

use bitvec::prelude::*;

let bits = bits![0, 1, 0, 0, 1, 0, 0, 0, 1];

let iter_ones = bits.iter_ones();
let known_indices = [1, 4, 8].iter().copied();
let filter = bits.iter()
  .by_vals()
  .enumerate()
  .filter_map(|(idx, bit)| if bit { Some(idx) } else { None });
let all = iter_ones.zip(known_indices).zip(filter);

for ((iter_one, known), filtered) in all {
  assert_eq!(iter_one, known);
  assert_eq!(known, filtered);
}

pub fn iter_zeros(&self) -> IterZeros<'_, T, O>

Enumerates the index of each bit in a bit-slice cleared to 0.

This is a shorthand for a .enumerate().filter_map() iterator that selects the index of each false bit; however, its implementation is eligible for optimizations that the individual-bit iterator is not.

Specializations for the Lsb0 and Msb0 orderings allow processors with instructions that seek particular bits within an element to operate on whole elements, rather than on each bit individually.

Examples

This example uses .iter_zeros(), a .filter_map() that finds the index of each cleared bit, and the known indices, in order to show that they have equivalent behavior.

use bitvec::prelude::*;

let bits = bits![1, 0, 1, 1, 0, 1, 1, 1, 0];

let iter_zeros = bits.iter_zeros();
let known_indices = [1, 4, 8].iter().copied();
let filter = bits.iter()
  .by_vals()
  .enumerate()
  .filter_map(|(idx, bit)| if !bit { Some(idx) } else { None });
let all = iter_zeros.zip(known_indices).zip(filter);

for ((iter_zero, known), filtered) in all {
  assert_eq!(iter_zero, known);
  assert_eq!(known, filtered);
}

pub fn first_one(&self) -> Option<usize>

Finds the index of the first bit in the bit-slice set to 1.

Returns None if there is no true bit in the bit-slice.

Examples

use bitvec::prelude::*;

assert!(bits![].first_one().is_none());
assert!(bits![0].first_one().is_none());
assert_eq!(bits![0, 1].first_one(), Some(1));

pub fn first_zero(&self) -> Option<usize>

Finds the index of the first bit in the bit-slice cleared to 0.

Returns None if there is no false bit in the bit-slice.

Examples

use bitvec::prelude::*;

assert!(bits![].first_zero().is_none());
assert!(bits![1].first_zero().is_none());
assert_eq!(bits![1, 0].first_zero(), Some(1));

pub fn last_one(&self) -> Option<usize>

Finds the index of the last bit in the bit-slice set to 1.

Returns None if there is no true bit in the bit-slice.

Examples

use bitvec::prelude::*;

assert!(bits![].last_one().is_none());
assert!(bits![0].last_one().is_none());
assert_eq!(bits![1, 0].last_one(), Some(0));

pub fn last_zero(&self) -> Option<usize>

Finds the index of the last bit in the bit-slice cleared to 0.

Returns None if there is no false bit in the bit-slice.

Examples

use bitvec::prelude::*;

assert!(bits![].last_zero().is_none());
assert!(bits![1].last_zero().is_none());
assert_eq!(bits![0, 1].last_zero(), Some(0));

pub fn leading_ones(&self) -> usize

Counts the number of bits from the start of the bit-slice to the first bit set to 0.

This returns 0 if the bit-slice is empty.

Examples

use bitvec::prelude::*;

assert_eq!(bits![].leading_ones(), 0);
assert_eq!(bits![0].leading_ones(), 0);
assert_eq!(bits![1, 0].leading_ones(), 1);

pub fn leading_zeros(&self) -> usize

Counts the number of bits from the start of the bit-slice to the first bit set to 1.

This returns 0 if the bit-slice is empty.

Examples

use bitvec::prelude::*;

assert_eq!(bits![].leading_zeros(), 0);
assert_eq!(bits![1].leading_zeros(), 0);
assert_eq!(bits![0, 1].leading_zeros(), 1);

pub fn trailing_ones(&self) -> usize

Counts the number of bits from the end of the bit-slice to the last bit set to 0.

This returns 0 if the bit-slice is empty.

Examples

use bitvec::prelude::*;

assert_eq!(bits![].trailing_ones(), 0);
assert_eq!(bits![0].trailing_ones(), 0);
assert_eq!(bits![0, 1].trailing_ones(), 1);

pub fn trailing_zeros(&self) -> usize

Counts the number of bits from the end of the bit-slice to the last bit set to 1.

This returns 0 if the bit-slice is empty.

Examples

use bitvec::prelude::*;

assert_eq!(bits![].trailing_zeros(), 0);
assert_eq!(bits![1].trailing_zeros(), 0);
assert_eq!(bits![1, 0].trailing_zeros(), 1);

pub fn any(&self) -> bool

Tests if there is at least one bit set to 1 in the bit-slice.

Returns false when self is empty.

Examples

use bitvec::prelude::*;

assert!(!bits![].any());
assert!(!bits![0].any());
assert!(bits![0, 1].any());

pub fn all(&self) -> bool

Tests if every bit is set to 1 in the bit-slice.

Returns true when self is empty.

Examples

use bitvec::prelude::*;

assert!( bits![].all());
assert!(!bits![0].all());
assert!( bits![1].all());

pub fn not_any(&self) -> bool

Tests if every bit is cleared to 0 in the bit-slice.

Returns true when self is empty.

Examples

use bitvec::prelude::*;

assert!( bits![].not_any());
assert!(!bits![1].not_any());
assert!( bits![0].not_any());

pub fn not_all(&self) -> bool

Tests if at least one bit is cleared to 0 in the bit-slice.

Returns false when self is empty.

Examples

use bitvec::prelude::*;

assert!(!bits![].not_all());
assert!(!bits![1].not_all());
assert!( bits![0].not_all());

pub fn some(&self) -> bool

Tests if at least one bit is set to 1, and at least one bit is cleared to 0, in the bit-slice.

Returns false when self is empty.

Examples

use bitvec::prelude::*;

assert!(!bits![].some());
assert!(!bits![0].some());
assert!(!bits![1].some());
assert!( bits![0, 1].some());

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

Writes a new value into a single bit, using alias-safe operations.

This is equivalent to .set(), except that it does not require an &mut reference, and allows bit-slices with alias-safe storage to share write permissions.

Parameters

• &self: This method only exists on bit-slices with alias-safe storage, and so does not require exclusive access.
• index: The bit index to set. It must be in 0 .. self.len().
• value: The new bit-value to write into the bit at index.

Panics

This panics if index is out of bounds.

Examples

use bitvec::prelude::*;
use core::cell::Cell;

let bits: &BitSlice<_, _> = bits![Cell<usize>, Lsb0; 0, 1];
bits.set_aliased(0, true);
bits.set_aliased(1, false);

assert_eq!(bits, bits![1, 0]);

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

Writes a new value into a single bit, using alias-safe operations and without bounds checking.

This is equivalent to .set_unchecked(), except that it does not require an &mut reference, and allows bit-slices with alias-safe storage to share write permissions.

Parameters

• &self: This method only exists on bit-slices with alias-safe storage, and so does not require exclusive access.
• index: The bit index to set. It must be in 0 .. self.len().
• value: The new bit-value to write into the bit at index.

Safety

The caller must ensure that index is not out of bounds.

Examples

use bitvec::prelude::*;
use core::cell::Cell;

let data = Cell::new(0u8);
let bits = &data.view_bits::<Lsb0>()[.. 2];
unsafe {
  bits.set_aliased_unchecked(3, true);
}
assert_eq!(data.get(), 8);

pub const MAX_BITS: usize = 2_305_843_009_213_693_951usize

pub const MAX_ELTS: usize = BitSpan<Const, T, O>::REGION_MAX_ELTS

pub fn to_bitvec(&self) -> BitVec<<T as BitStore>::Unalias, O>

Copies a bit-slice into an owned bit-vector.

Since the new vector is freshly owned, this gets marked as ::Unalias to remove any guards that may have been inserted by the bit-slice’s history.

It does not use the underlying memory type, so that a BitSlice<_, Cell<_>> will produce a BitVec<_, Cell<_>>.

Original

slice::to_vec

Examples

use bitvec::prelude::*;

let bits = bits![0, 1, 0, 1];
let bv = bits.to_bitvec();
assert_eq!(bits, bv);

Trait Implementations

impl BitBuf for Bits

fn advance_bits(&mut self, count: usize)

Advance the internal cursor of the BitBuf by count bits.

fn remaining_bits(&self) -> usize

Returns the number of bits between the current position and the end of the buffer.

fn chunk_bits(&self) -> &BitSlice<u8, Msb0>

Returns a BitSlice starting at the current position and of length between 0 and BitBuf::remaining. Note that this can return a shorter slice.

fn chunk_bytes(&self) -> &[u8]

Returns a slice of bytes starting at the current position and of length between 0 and BitBuf::remaining_bytes. Note that this can return a shorter slice.

fn byte_aligned(&self) -> bool

Returns whether or not this BitBuf is fully byte-aligned (beginning and end) with the underlying storage.

fn advance_bytes(&mut self, count: usize)

Advance the internal cursor of the BitBuf by count bytes.

fn remaining_bytes(&self) -> usize

Return the number of full bytes between the current position and the end of the buffer.

fn has_remaining_bits(&self) -> bool

Returns true if there are any more bits to consume.

fn has_remaining_bytes(&self) -> bool

Returns true if there are any more cmplete bytes to consume.

fn chain<U>(self, next: U) -> Chain<Self, U>

where U: BitBuf, Self: Sized,

Creates an adaptor which will chain this buffer to another.

fn copy_to_bit_slice(&mut self, dest: &mut BitSlice<u8, Msb0>)

Copy bits from self into dest.

fn try_copy_to_bit_slice( &mut self, dest: &mut BitSlice<u8, Msb0>, ) -> Result<(), Error>

fn copy_to_slice_bytes(&mut self, dest: &mut [u8])

Copy bytes from self into dest. Call should call byte_aligned() beforehand to ensure buffer is fully byte-aligned before calling, call may panic if buffer isn’t byte-aligned.

fn try_copy_to_slice_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>

Try to copy bytes from self into dest. Returns error if self is not big enough to fill dest or if self is not fully byte-aligned (start and end points both falling on byte boundaries).

fn take_bits(self, limit: usize) -> Take<Self>

where Self: Sized,

Create an adaptor which can read at most limit bits from self.

fn take_bytes(self, limit: usize) -> Take<Self>

where Self: Sized,

Create an adaptor which can read at most limit bytes from self.

impl Clone for Bits

fn clone(&self) -> Bits

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Bits

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

Formats the value using the given formatter.

impl Deref for Bits

type Target = BitSlice<u8, Msb0>

The resulting type after dereferencing.

fn deref(&self) -> &<Bits as Deref>::Target

Dereferences the value.

impl From<&BitSlice<u8, Msb0>> for Bits

fn from(value: &BitSlice<u8, Msb0>) -> Bits

Converts to this type from the input type.

impl From<BitVec<u8, Msb0>> for Bits

fn from(bv: BitVec<u8, Msb0>) -> Bits

Converts to this type from the input type.

impl PartialEq for Bits

fn eq(&self, other: &Bits) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Bits

impl StructuralPartialEq for Bits