| [ Web Proxy ] |
| Viewing: https://docs.rs/bitvec/latest/bitvec/array/struct.BitArray.html | [Back] [Original] |
#[repr(transparent)]pub struct BitArray<A = [usize; 1], O = Lsb0>where
A: BitViewSized,
O: BitOrder,{
pub _ord: PhantomData<O>,
pub data: A,
}This type is a wrapper over the array fundamental [T; N] that views its
contents as a BitSlice region. As an array, it can be held directly by value
and does not require an indirection such as the &BitSlice reference.
BitArray is a Rust analogue of the C++ std::bitset<N> container. However,
restrictions in the Rust type system do not allow specifying exact bit lengths
in the array type. Instead, it must specify a storage array that can contain all
the bits you want.
Because BitArray is a plain-old-data object, its fields are public and it has
no restrictions on its interior value. You can freely access the interior
storage and move data in or out of the BitArray type with no cost.
As a convenience, the BitArr! type-constructor macro can produce correct
type definitions from an exact bit count and your memory-layout type parameters.
Values of that type can then be built from the bitarr! value-constructor
macro:
use bitvec::prelude::*;
type Example = BitArr!(for 43, in u32, Msb0);
let example: Example = bitarr!(u32, Msb0; 1; 33);
struct HasBitfield {
inner: Example,
}
let ex2 = HasBitfield {
inner: BitArray::new([1, 2]),
};Note that the actual type of the Example alias is BitArray<[u32; 2], Msb0>,
as that is ceil(32, 43), so the bitarr! macro can accept any number of bits
in 33 .. 65 and will produce a value of the correct type.
BitArray differs from the other data structures in the crate in that it does
not take a T: BitStore parameter, but rather takes A: BitViewSized. That
trait is implemented by all T: BitStore scalars and all [T; N] arrays of
them, and provides the logic to translate the aggregate storage into the memory
sequence that the crate expects.
As with all BitSlice regions, the O: BitOrder parameter specifies the
ordering of bits within a single A::Store element.
Exact bit lengths cannot be encoded into the BitArray type until the
const-generics system in the compiler can allow type-level computation on type
integers. When this stabilizes, bitvec will issue a major upgrade that
replaces the BitArray<A, O> definition with BitArray<T, O, const N: usize>
and match the C++ std::bitset<N> definition.
As with ordinary arrays, large arrays can be expensive to move by value, and
should generally be preferred to have static locations such as actual static
bindings, a long lifetime in a low stack frame, or a heap allocation. While you
certainly can Box<[BitArray<A, O>]> directly, you may instead prefer the
BitBox or BitVec heap-allocated regions. These offer the same storage
behavior and are better optimized than Box<BitArray> for working with the
contained BitSlice region.
use bitvec::prelude::*;
const WELL_KNOWN: BitArr!(for 16, in u8, Lsb0) = BitArray::<[u8; 2], Lsb0> {
data: *b"bv",
..BitArray::ZERO
};
struct HasBitfields {
inner: BitArr!(for 50, in u8, Lsb0),
}
impl HasBitfields {
fn new() -> Self {
Self {
inner: bitarr!(u8, Lsb0; 0; 50),
}
}
fn some_field(&self) -> &BitSlice<u8, Lsb0> {
&self.inner[2 .. 52]
}
}_ord: PhantomData<O>The ordering of bits within an A::Store element.
data: AThe wrapped data buffer.
use .as_bitslice() or .as_raw_slice() instead
Returns a bit-slice containing the entire bit-array. Equivalent to
&a[..].
Because BitArray can be viewed as a slice of bits or as a slice of
elements with equal ease, you should switch to using .as_bitslice()
or .as_raw_slice() to make your choice explicit.
use .as_mut_bitslice() or .as_raw_mut_slice() instead
Returns a mutable bit-slice containing the entire bit-array. Equivalent
to &mut a[..].
Because BitArray can be viewed as a slice of bits or as a slice of
elements with equal ease, you should switch to using
.as_mut_bitslice() or .as_raw_mut_slice() to make your choice
explicit.
A bit-array with all bits initialized to zero.
Wraps an existing buffer as a bit-array.
use bitvec::prelude::*;
let data = [0u16, 1, 2, 3];
let bits = BitArray::<_, Msb0>::new(data);
assert_eq!(bits.len(), 64);Removes the bit-array wrapper, returning the contained buffer.
use bitvec::prelude::*;
let bits = bitarr![0; 30];
let native: [usize; 1] = bits.into_inner();Explicitly views the bit-array as a bit-slice.
Explicitly views the bit-array as a mutable bit-slice.
Views the bit-array as a slice of its underlying memory elements.
Views the bit-array as a mutable slice of its underlying memory elements.
Gets the length (in bits) of the bit-array.
This method is a compile-time constant.
Tests whether the array is empty.
This method is a compile-time constant.
Gets the number of bits in the bit-slice.
use bitvec::prelude::*;
assert_eq!(bits![].len(), 0);
assert_eq!(bits![0; 10].len(), 10);Tests if the bit-slice is empty (length zero).
use bitvec::prelude::*;
assert!(bits![].is_empty());
assert!(!bits![0; 10].is_empty());Gets a reference to the first bit of the bit-slice, or None if it is
empty.
bitvec uses a custom structure for both read-only and mutable
references to bool.
use bitvec::prelude::*;
let bits = bits![1, 0, 0];
assert_eq!(bits.first().as_deref(), Some(&true));
assert!(bits![].first().is_none());Gets a mutable reference to the first bit of the bit-slice, or None if
it is empty.
bitvec uses a custom structure for both read-only and mutable
references to bool. This must be bound as mut in order to write
through it.
use bitvec::prelude::*;
let bits = bits![mut 0; 3];
if let Some(mut first) = bits.first_mut() {
*first = true;
}
assert_eq!(bits, bits![1, 0, 0]);
assert!(bits![mut].first_mut().is_none());Splits the bit-slice into a reference to its first bit, and the rest of
the bit-slice. Returns None when empty.
bitvec uses a custom structure for both read-only and mutable
references to bool.
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]);Splits the bit-slice into mutable references of its first bit, and the
rest of the bit-slice. Returns None when empty.
bitvec uses a custom structure for both read-only and mutable
references to bool. This must be bound as mut in order to write
through it.
use bitvec::prelude::*;
let bits = bits![mut 0; 3];
if let Some((mut first, rest)) = bits.split_first_mut() {
*first = true;
assert_eq!(rest, bits![0; 2]);
}
assert_eq!(bits, bits![1, 0, 0]);Splits the bit-slice into a reference to its last bit, and the rest of
the bit-slice. Returns None when empty.
bitvec uses a custom structure for both read-only and mutable
references to bool.
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]);Splits the bit-slice into mutable references to its last bit, and the
rest of the bit-slice. Returns None when empty.
bitvec uses a custom structure for both read-only and mutable
references to bool. This must be bound as mut in order to write
through it.
use bitvec::prelude::*;
let bits = bits![mut 0; 3];
if let Some((mut last, rest)) = bits.split_last_mut() {
*last = true;
assert_eq!(rest, bits![0; 2]);
}
assert_eq!(bits, bits![0, 0, 1]);Gets a reference to the last bit of the bit-slice, or None if it is
empty.
bitvec uses a custom structure for both read-only and mutable
references to bool.
use bitvec::prelude::*;
let bits = bits![0, 0, 1];
assert_eq!(bits.last().as_deref(), Some(&true));
assert!(bits![].last().is_none());Gets a mutable reference to the last bit of the bit-slice, or None if
it is empty.
bitvec uses a custom structure for both read-only and mutable
references to bool. This must be bound as mut in order to write
through it.
use bitvec::prelude::*;
let bits = bits![mut 0; 3];
if let Some(mut last) = bits.last_mut() {
*last = true;
}
assert_eq!(bits, bits![0, 0, 1]);
assert!(bits![mut].last_mut().is_none());Gets a reference to a single bit or a subsection of the bit-slice,
depending on the type of index.
usize, this produces a reference structure to the bool
at the position.This returns None if the index departs the bounds of self.
BitSliceIndex uses discrete types for immutable and mutable
references, rather than a single referent type.
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());Gets a mutable reference to a single bit or a subsection of the
bit-slice, depending on the type of index.
usize, this produces a reference structure to the bool
at the position.This returns None if the index departs the bounds of self.
BitSliceIndex uses discrete types for immutable and mutable
references, rather than a single referent type.
use bitvec::prelude::*;
let bits = bits![mut 0; 3];
*bits.get_mut(0).unwrap() = true;
bits.get_mut(1 ..).unwrap().fill(true);
assert_eq!(bits, bits![1; 3]);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.
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.
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));
}Gets a mutable reference to a single bit or a subsection of the
bit-slice, depending on the type of index.
This has the same arguments and behavior as .get_mut(), except that
it does not check that index is in bounds.
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.
use bitvec::prelude::*;
let mut data = 0u8;
let bits = &mut data.view_bits_mut::<Lsb0>()[.. 3];
unsafe {
bits.get_unchecked_mut(1).commit(true);
bits.get_unchecked_mut(4 .. 6).fill(true);
}
assert_eq!(data, 0b0011_0010);use .as_bitptr() instead
use .as_mut_bitptr() instead
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.
Produces a range of mutable 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_mut_bitptr_range() instead, as
it produces a custom structure that provides expected ranging
functionality.
Exchanges the bit values at two indices.
This panics if either a or b are out of bounds.
use bitvec::prelude::*;
let bits = bits![mut 0, 1];
bits.swap(0, 1);
assert_eq!(bits, bits![1, 0]);Reverses the order of bits in a bit-slice.
use bitvec::prelude::*;
let bits = bits![mut 0, 0, 1, 0, 1, 1, 0, 0, 1];
bits.reverse();
assert_eq!(bits, bits![1, 0, 0, 1, 1, 0, 1, 0, 0]);Produces an iterator over each bit in the bit-slice.
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().
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());Produces a mutable iterator over each bit in the bit-slice.
This iterator yields proxy-reference structures, not &mut bool. In
addition, it marks each proxy as alias-tainted.
If you are using this in an ordinary loop and not keeping multiple
yielded proxy-references alive at the same scope, you may use the
.remove_alias() adapter to undo the alias marking.
This iterator is fast. Do not try to be more clever than it by abusing
.as_mut_bitptr_range().
use bitvec::prelude::*;
let bits = bits![mut 0; 4];
let mut iter = bits.iter_mut();
iter.nth(1).unwrap().commit(true); // index 1
iter.next_back().unwrap().commit(true); // index 3
assert!(iter.next().is_some()); // index 2
assert!(iter.next().is_none()); // complete
assert_eq!(bits, bits![0, 1, 0, 1]);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].
This panics if size is 0.
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());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.
.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.This panics if chunk_size is 0.
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());Iterates over non-overlapping mutable subslices of a bit-slice.
Iterators do not require that each yielded item is destroyed before the
next is produced. This means that each bit-slice yielded must be marked
as aliased. If you are using this in a loop that does not collect
multiple yielded subslices for the same scope, then you can remove the
alias marking by calling the (unsafe) method .remove_alias() on
the iterator.
.chunks() has the same division logic, but each yielded bit-slice
is immutable..chunks_exact_mut() does not yield the final chunk if it is
shorter than chunk_size..rchunks_mut() iterates from the back of the bit-slice to the
front, with the final, possibly-shorter, segment at the front edge.This panics if chunk_size is 0.
use bitvec::prelude::*;
let bits = bits![mut u8, Msb0; 0; 5];
for (idx, chunk) in unsafe {
bits.chunks_mut(2).remove_alias()
}.enumerate() {
chunk.store(idx + 1);
}
assert_eq!(bits, bits![0, 1, 1, 0, 1]);
// ^^^^ ^^^^ ^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.
.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.This panics if chunk_size is 0.
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]);Iterates over non-overlapping mutable 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 .into_remainder() method if the iterator is bound to a
name.
Iterators do not require that each yielded item is destroyed before the
next is produced. This means that each bit-slice yielded must be marked
as aliased. If you are using this in a loop that does not collect
multiple yielded subslices for the same scope, then you can remove the
alias marking by calling the (unsafe) method .remove_alias() on
the iterator.
.chunks_mut() yields any leftover bits at the end as a shorter
chunk during iteration..chunks_exact() has the same division logic, but each yielded
bit-slice is immutable..rchunks_exact_mut() iterates from the back of the bit-slice
forwards, with the unyielded remainder segment at the front edge.This panics if chunk_size is 0.
use bitvec::prelude::*;
let bits = bits![mut u8, Msb0; 0; 5];
let mut iter = bits.chunks_exact_mut(2);
for (idx, chunk) in iter.by_ref().enumerate() {
chunk.store(idx + 1);
}
iter.into_remainder().store(1u8);
assert_eq!(bits, bits![0, 1, 1, 0, 1]);
// remainder ^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].
.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.This panics if chunk_size is 0.
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());Iterates over non-overlapping mutable subslices of a bit-slice, from the back edge.
Unlike .chunks_mut(), 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].
Iterators do not require that each yielded item is destroyed before the
next is produced. This means that each bit-slice yielded must be marked
as aliased. If you are using this in a loop that does not collect
multiple yielded values for the same scope, then you can remove the
alias marking by calling the (unsafe) method .remove_alias() on
the iterator.
.rchunks() has the same division logic, but each yielded bit-slice
is immutable..rchunks_exact_mut() does not yield the final chunk if it is
shorter than chunk_size..chunks_mut() iterates from the front of the bit-slice to the
back, with the final, possibly-shorter, segment at the back edge.use bitvec::prelude::*;
let bits = bits![mut u8, Msb0; 0; 5];
for (idx, chunk) in unsafe {
bits.rchunks_mut(2).remove_alias()
}.enumerate() {
chunk.store(idx + 1);
}
assert_eq!(bits, bits![1, 1, 0, 0, 1]);
// remainder ^ ^^^^ ^^^^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.
.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.This panics if chunk_size is 0.
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]);Iterates over non-overlapping mutable 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 .into_remainder() method if the iterator is bound to a
name.
Iterators do not require that each yielded item is destroyed before the
next is produced. This means that each bit-slice yielded must be marked
as aliased. If you are using this in a loop that does not collect
multiple yielded subslices for the same scope, then you can remove the
alias marking by calling the (unsafe) method .remove_alias() on
the iterator.
.rchunks_mut() yields any leftover bits at the front as a shorter
chunk during iteration..rchunks_exact() has the same division logic, but each yielded
bit-slice is immutable..chunks_exact_mut() iterates from the front of the bit-slice
backwards, with the unyielded remainder segment at the back edge.This panics if chunk_size is 0.
use bitvec::prelude::*;
let bits = bits![mut u8, Msb0; 0; 5];
let mut iter = bits.rchunks_exact_mut(2);
for (idx, chunk) in iter.by_ref().enumerate() {
chunk.store(idx + 1);
}
iter.into_remainder().store(1u8);
assert_eq!(bits, bits![1, 1, 0, 0, 1]);
// remainder ^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].
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.
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]);Splits a mutable 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].
The end bits of the left half and the start bits of the right half might
be stored in the same memory element. In order to avoid breaking
bitvecs memory-safety guarantees, both bit-slices are marked as
T::Alias. This marking allows them to be used without interfering with
each other when they interact with memory.
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.
use bitvec::prelude::*;
let bits = bits![mut u8, Msb0; 0; 6];
let base = bits.as_mut_bitptr();
let (a, b) = bits.split_at_mut(0);
assert_eq!(unsafe { a.as_mut_bitptr().offset_from(base) }, 0);
assert_eq!(unsafe { b.as_mut_bitptr().offset_from(base) }, 0);
let (a, b) = bits.split_at_mut(6);
assert_eq!(unsafe { b.as_mut_bitptr().offset_from(base) }, 6);
let (a, b) = bits.split_at_mut(3);
a.store(3);
b.store(5);
assert_eq!(bits, bits![0, 1, 1, 1, 0, 1]);Iterates over subslices separated by bits that match a predicate. The matched bit is not contained in the yielded bit-slices.
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.
.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.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());Iterates over mutable subslices separated by bits that match a predicate. The matched bit is not contained in the yielded bit-slices.
Iterators do not require that each yielded item is destroyed before the
next is produced. This means that each bit-slice yielded must be marked
as aliased. If you are using this in a loop that does not collect
multiple yielded subslices for the same scope, then you can remove the
alias marking by calling the (unsafe) method .remove_alias() on
the iterator.
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.
.split() has the same splitting logic, but each yielded bit-slice
is immutable..split_inclusive_mut() includes the matched bit in the yielded
bit-slice..rsplit_mut() iterates from the back of the bit-slice instead of
the front..splitn_mut() times out after n yields.use bitvec::prelude::*;
let bits = bits![mut 0, 0, 1, 0, 1, 0];
// ^ ^
for group in bits.split_mut(|_pos, bit| *bit) {
group.set(0, true);
}
assert_eq!(bits, bits![1, 0, 1, 1, 1, 1]);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.
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.
.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.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());Iterates over mutable subslices separated by bits that match a
predicate. Unlike .split_mut(), this does include the matching bit
as the last bit in the bit-slice.
Iterators do not require that each yielded item is destroyed before the
next is produced. This means that each bit-slice yielded must be marked
as aliased. If you are using this in a loop that does not collect
multiple yielded subslices for the same scope, then you can remove the
alias marking by calling the (unsafe) method .remove_alias() on
the iterator.
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.
.split_inclusive() has the same splitting logic, but each yielded
bit-slice is immutable..split_mut() does not include the matched bit in the yielded
bit-slice.use bitvec::prelude::*;
let bits = bits![mut 0, 0, 0, 0, 0];
// ^
for group in bits.split_inclusive_mut(|pos, _bit| pos % 3 == 2) {
group.set(0, true);
}
assert_eq!(bits, bits![1, 0, 0, 1, 0]);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.
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.
.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.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());Iterates over mutable subslices separated by bits that match a predicate, from the back. The matched bit is not contained in the yielded bit-slices.
Iterators do not require that each yielded item is destroyed before the
next is produced. This means that each bit-slice yielded must be marked
as aliased. If you are using this in a loop that does not collect
multiple yielded subslices for the same scope, then you can remove the
alias marking by calling the (unsafe) method .remove_alias() on
the iterator.
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.
.rsplit() has the same splitting logic, but each yielded bit-slice
is immutable..split_mut() iterates from the front of the bit-slice to the back..rsplitn_mut() iterates from the front of the bit-slice to the
back.use bitvec::prelude::*;
let bits = bits![mut 0, 0, 1, 0, 1, 0];
// ^ ^
for group in bits.rsplit_mut(|_pos, bit| *bit) {
group.set(0, true);
}
assert_eq!(bits, bits![1, 0, 1, 1, 1, 1]);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.
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.
.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.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());Iterates over mutable 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_mut(), the yielded
bit-slices do not contain the matched bit.
Iterators do not require that each yielded item is destroyed before the
next is produced. This means that each bit-slice yielded must be marked
as aliased. If you are using this in a loop that does not collect
multiple yielded subslices for the same scope, then you can remove the
alias marking by calling the (unsafe) method .remove_alias() on
the iterator.
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.
.splitn() has the same splitting logic, but each yielded bit-slice
is immutable..rsplitn_mut() iterates from the back of the bit-slice instead of
the front..split_mut() has the same splitting logic, but never times out.use bitvec::prelude::*;
let bits = bits![mut 0, 0, 1, 0, 1, 0];
for group in bits.splitn_mut(2, |_pos, bit| *bit) {
group.set(0, true);
}
assert_eq!(bits, bits![1, 0, 1, 1, 1, 0]);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.
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.
.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.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());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.
Iterators do not require that each yielded item is destroyed before the
next is produced. This means that each bit-slice yielded must be marked
as aliased. If you are using this in a loop that does not collect
multiple yielded subslices for the same scope, then you can remove the
alias marking by calling the (unsafe) method .remove_alias() on
the iterator.
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.
.rsplitn() has the same splitting logic, but each yielded
bit-slice is immutable..splitn_mut() iterates from the front of the bit-slice instead of
the back..rsplit_mut() has the same splitting logic, but never times out.use bitvec::prelude::*;
let bits = bits![mut 0, 0, 1, 0, 0, 1, 0, 0, 0];
for group in bits.rsplitn_mut(2, |_idx, bit| *bit) {
group.set(0, true);
}
assert_eq!(bits, bits![1, 0, 1, 0, 0, 1, 1, 0, 0]);
// ^ group 2 ^ group 1Tests 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.
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]));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.
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));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.
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));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.
BitSlice does not support pattern searches; instead, it permits self
and prefix to differ in type parameters.
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());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.
BitSlice does not support pattern searches; instead, it permits self
and suffix to differ in type parameters.
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());Rotates the contents of a bit-slice to the left (towards the zero index).
This essentially splits the bit-slice at by, then exchanges the two
pieces. self[.. by] becomes the first section, and is then followed by
self[.. by].
The implementation is batch-accelerated where possible. It should have a
runtime complexity much lower than O(by).
use bitvec::prelude::*;
let bits = bits![mut 0, 0, 1, 0, 1, 0];
// split occurs here ^
bits.rotate_left(2);
assert_eq!(bits, bits![1, 0, 1, 0, 0, 0]);Rotates the contents of a bit-slice to the right (away from the zero index).
This essentially splits the bit-slice at self.len() - by, then
exchanges the two pieces. self[len - by ..] becomes the first section,
and is then followed by self[.. len - by].
The implementation is batch-accelerated where possible. It should have a
runtime complexity much lower than O(by).
use bitvec::prelude::*;
let bits = bits![mut 0, 0, 1, 1, 1, 0];
// split occurs here ^
bits.rotate_right(2);
assert_eq!(bits, bits![1, 0, 0, 0, 1, 1]);Fills the bit-slice with a given bit.
This is a recent stabilization in the standard library. bitvec
previously offered this behavior as the novel API .set_all(). That
method name is now removed in favor of this standard-library analogue.
use bitvec::prelude::*;
let bits = bits![mut 0; 5];
bits.fill(true);
assert_eq!(bits, bits![1; 5]);Fills the bit-slice with bits produced by a generator function.
The generator function receives the index of the bit being initialized as an argument.
use bitvec::prelude::*;
let bits = bits![mut 0; 5];
bits.fill_with(|idx| idx % 2 == 0);
assert_eq!(bits, bits![1, 0, 1, 0, 1]);use .clone_from_bitslice() instead
use .copy_from_bitslice() instead
Copies a span of bits to another location in the bit-slice.
src is the range of bit-indices in the bit-slice to copy, and dest is the starting index of the destination range. srcanddest .. dest +
src.len()are permitted to overlap; the copy will automatically detect and manage this. However, bothsrcanddest .. dest + src.len()**must** fall within the bounds ofself`.
This panics if either the source or destination range exceed
self.len().
use bitvec::prelude::*;
let bits = bits![mut 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0];
bits.copy_within(1 .. 5, 8);
// v v v v
assert_eq!(bits, bits![1, 1, 1, 1, 0, 0, 0, 0, 1, 1, 1, 0]);
// ^ ^ ^ ^use .swap_with_bitslice() instead
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.
Unlike the standard library documentation, this explicitly guarantees that the middle bit-slice will have maximal size. You may rely on this property.
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. Relign integers to integers,
Cells to Cells, and atomics to atomics, but do not cross these
boundaries.
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);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.
Unlike the standard library documentation, this explicitly guarantees that the middle bit-slice will have maximal size. You may rely on this property.
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. Relign integers to integers,
Cells to Cells, and atomics to atomics, but do not cross these
boundaries.
use bitvec::prelude::*;
let mut bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7];
let bits = bytes.view_bits_mut::<Lsb0>();
let (pfx, mid, sfx) = unsafe {
bits.align_to_mut::<u16>()
};
assert!(pfx.len() <= 8);
assert_eq!(mid.len(), 48);
assert!(sfx.len() <= 8);use .to_bitvec() instead
Creates a bit-vector by repeating a bit-slice n times.
This method panics if self.len() * n exceeds the BitVec capacity.
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:
Gets a raw pointer to the zeroth bit of the bit-slice.
This is renamed in order to indicate that it is returning a bitvec
structure, not a raw pointer.
Gets a raw, write-capable pointer to the zeroth bit of the bit-slice.
This is renamed in order to indicate that it is returning a bitvec
structure, not a raw pointer.
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.
This is renamed to indicate that it returns a bitvec structure, rather
than an ordinary Range.
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.
Views the bit-slice as a half-open range of write-capable bit-pointers, to its first bit in the bit-slice and the first bit beyond it.
This is renamed to indicate that it returns a bitvec structure, rather
than an ordinary Range.
BitSlice does define a [.as_mut_ptr_range()], which returns a
Range<BitPtr>. BitPtrRange has additional capabilities that
Range<*mut T> and Range<BitPtr> do not.
Copies the bits from src into self.
self and src must have the same length.
If src has the same type arguments as self, it will use the same
implementation as .copy_from_bitslice(); if you know that this will
always be the case, you should prefer to use that method directly.
Only .copy_from_bitslice() is able to perform acceleration; this
method is always required to perform a bit-by-bit crawl over both
bit-slices.
This is renamed to reflect that it copies from another bit-slice, not from an element slice.
In order to support general usage, it allows src to have different
type parameters than self, at the cost of performance optimizations.
This panics if the two bit-slices have different lengths.
use bitvec::prelude::*;Copies all bits from src into self, using batched acceleration when
possible.
self and src must have the same length.
This panics if the two bit-slices have different lengths.
use bitvec::prelude::*;Swaps the contents of two bit-slices.
self and other must have the same length.
This method is renamed, as it takes a bit-slice rather than an element slice.
This panics if the two bit-slices have different lengths.
use bitvec::prelude::*;
let mut one = [0xA5u8, 0x69];
let mut two = 0x1234u16;
let one_bits = one.view_bits_mut::<Msb0>();
let two_bits = two.view_bits_mut::<Lsb0>();
one_bits.swap_with_bitslice(two_bits);
assert_eq!(one, [0x2C, 0x48]);
assert_eq!(two, 0x96A5);Writes a new value into a single bit.
This is the replacement for *slice[index] = value;, as bitvec is not
able to express that under the current IndexMut API signature.
&mut selfindex: The bit-index to set. It must be in 0 .. self.len().value: The new bit-value to write into the bit at index.This panics if index is out of bounds.
use bitvec::prelude::*;
let bits = bits![mut 0, 1];
bits.set(0, true);
bits.set(1, false);
assert_eq!(bits, bits![1, 0]);Writes a new value into a single bit, without bounds checking.
&mut selfindex: The bit-index to set. It must be in 0 .. self.len().value: The new bit-value to write into the bit at index.You must ensure that index is in the range 0 .. self.len().
This performs bit-pointer offset arithmetic without doing any bounds
checks. If index is out of bounds, then this will issue an
out-of-bounds access and will trigger memory unsafety.
use bitvec::prelude::*;
let mut data = 0u8;
let bits = &mut data.view_bits_mut::<Lsb0>()[.. 2];
assert_eq!(bits.len(), 2);
unsafe {
bits.set_unchecked(3, true);
}
assert_eq!(data, 8);Writes a new value into a bit, and returns its previous value.
This panics if index is not less than self.len().
use bitvec::prelude::*;
let bits = bits![mut 0];
assert!(!bits.replace(0, true));
assert!(bits[0]);Writes a new value into a bit, returning the previous value, without bounds checking.
index must be less than self.len().
use bitvec::prelude::*;
let bits = bits![mut 0, 0];
let old = unsafe {
let a = &mut bits[.. 1];
a.replace_unchecked(1, true)
};
assert!(!old);
assert!(bits[1]);Swaps two bits in a bit-slice, without bounds checking.
See .swap() for documentation.
You must ensure that a and b are both in the range 0 .. self.len().
This method performs bit-pointer offset arithmetic without doing any
bounds checks. If a or b are out of bounds, then this will issue an
out-of-bounds access and will trigger memory unsafety.
Splits a bit-slice at an index, without bounds checking.
See .split_at() for documentation.
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.
Splits a mutable bit-slice at an index, without bounds checking.
See .split_at_mut() for documentation.
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.
Copies bits from one region of the bit-slice to another region of itself, without doing bounds checks.
The regions are allowed to overlap.
&mut selfsrc: The range within self from which to copy.dst: The starting index within self at which to paste.self[src] is copied to self[dest .. dest + src.len()]. The bits of
self[src] are in an unspecified, but initialized, state.
src.end() and dest + src.len() must be entirely within bounds.
use bitvec::prelude::*;
let mut data = 0b1011_0000u8;
let bits = data.view_bits_mut::<Msb0>();
unsafe {
bits.copy_within_unchecked(.. 4, 2);
}
assert_eq!(data, 0b1010_1100);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.
Partitions a mutable bit-slice into maybe-contended and known-uncontended parts.
The documentation of BitDomain goes into this in more detail. In
short, this produces a &mut 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.
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.
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 &mut [T] slice with alias protections removed,
covering all elements that self completely fills. Partially-used
elements on the front or back edge of the slice are returned separately.
Counts the number of bits set to 1 in the bit-slice contents.
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);Counts the number of bits cleared to 0 in the bit-slice contents.
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);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.
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);
}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.
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);
}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.
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));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.
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));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.
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));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.
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));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.
use bitvec::prelude::*;
assert_eq!(bits![].leading_ones(), 0);
assert_eq!(bits![0].leading_ones(), 0);
assert_eq!(bits![1, 0].leading_ones(), 1);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.
use bitvec::prelude::*;
assert_eq!(bits![].leading_zeros(), 0);
assert_eq!(bits![1].leading_zeros(), 0);
assert_eq!(bits![0, 1].leading_zeros(), 1);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.
use bitvec::prelude::*;
assert_eq!(bits![].trailing_ones(), 0);
assert_eq!(bits![0].trailing_ones(), 0);
assert_eq!(bits![0, 1].trailing_ones(), 1);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.
use bitvec::prelude::*;
assert_eq!(bits![].trailing_zeros(), 0);
assert_eq!(bits![1].trailing_zeros(), 0);
assert_eq!(bits![1, 0].trailing_zeros(), 1);Tests if there is at least one bit set to 1 in the bit-slice.
Returns false when self is empty.
use bitvec::prelude::*;
assert!(!bits![].any());
assert!(!bits![0].any());
assert!(bits![0, 1].any());Tests if every bit is set to 1 in the bit-slice.
Returns true when self is empty.
use bitvec::prelude::*;
assert!( bits![].all());
assert!(!bits![0].all());
assert!( bits![1].all());Tests if every bit is cleared to 0 in the bit-slice.
Returns true when self is empty.
use bitvec::prelude::*;
assert!( bits![].not_any());
assert!(!bits![1].not_any());
assert!( bits![0].not_any());Tests if at least one bit is cleared to 0 in the bit-slice.
Returns false when self is empty.
use bitvec::prelude::*;
assert!(!bits![].not_all());
assert!(!bits![1].not_all());
assert!( bits![0].not_all());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.
use bitvec::prelude::*;
assert!(!bits![].some());
assert!(!bits![0].some());
assert!(!bits![1].some());
assert!( bits![0, 1].some());Shifts the contents of a bit-slice left (towards the zero-index),
clearing the right bits to 0.
This is a strictly-worse analogue to taking bits = &bits[by ..]: it
has to modify the entire memory region that bits governs, and destroys
contained information. Unless the actual memory layout and contents of
your bit-slice matters to your program, you should probably prefer to
munch your way forward through a bit-slice handle.
Note also that the left here is semantic only, and does not necessarily correspond to a left-shift instruction applied to the underlying integer storage.
This has no effect when by is 0. When by is self.len(), the
bit-slice is entirely cleared to 0.
This panics if by is not less than self.len().
use bitvec::prelude::*;
let bits = bits![mut 1, 1, 1, 1, 0, 0, 1, 0, 1, 1, 1, 1];
// these bits are retained ^--------------------------^
bits.shift_left(2);
assert_eq!(bits, bits![1, 1, 0, 0, 1, 0, 1, 1, 1, 1, 0, 0]);
// and move here ^--------------------------^
let bits = bits![mut 1; 2];
bits.shift_left(2);
assert_eq!(bits, bits![0; 2]);Shifts the contents of a bit-slice right (away from the zero-index),
clearing the left bits to 0.
This is a strictly-worse analogue to taking `bits = &bits[.. bits.len()
: it must modify the entire memory region that bits` governs, and
destroys contained information. Unless the actual memory layout and
contents of your bit-slice matters to your program, you should
probably prefer to munch your way backward through a bit-slice handle.Note also that the right here is semantic only, and does not necessarily correspond to a right-shift instruction applied to the underlying integer storage.
This has no effect when by is 0. When by is self.len(), the
bit-slice is entirely cleared to 0.
This panics if by is not less than self.len().
use bitvec::prelude::*;
let bits = bits![mut 1, 1, 1, 1, 0, 0, 1, 0, 1, 1, 1, 1];
// these bits stay ^--------------------------^
bits.shift_right(2);
assert_eq!(bits, bits![0, 0, 1, 1, 1, 1, 0, 0, 1, 0, 1, 1]);
// and move here ^--------------------------^
let bits = bits![mut 1; 2];
bits.shift_right(2);
assert_eq!(bits, bits![0; 2]);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.
&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.This panics if index is out of bounds.
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]);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.
&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.The caller must ensure that index is not out of bounds.
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);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-slices
history.
It does not use the underlying memory type, so that a BitSlice<_, Cell<_>> will produce a BitVec<_, Cell<_>>.
use bitvec::prelude::*;
let bits = bits![0, 1, 0, 1];
let bv = bits.to_bitvec();
assert_eq!(bits, bv);tarpaulin_include only.tarpaulin_include only.& operator.& operation. Read moretarpaulin_include only.tarpaulin_include only.BitFieldThe BitArray implementation is only ever called when the entire bit-array is
available for use, which means it can skip the bit-slice memory detection and
instead use the underlying storage elements directly.
The implementation still performs the segmentation for each element contained in the array, in order to maintain value consistency so that viewing the array as a bit-slice is still able to correctly interact with data contained in it.
| operator.| operation. Read moretarpaulin_include only.tarpaulin_include only.^ operator.^ operation. Read moretarpaulin_include only.tarpaulin_include only.tarpaulin_include only.tarpaulin_include only.source. Read moretarpaulin_include only.tarpaulin_include only.tarpaulin_include only.container[index]) operation. Read morecontainer[index]) operation. Read moretarpaulin_include only.tarpaulin_include only.! operator.! operation. Read moretarpaulin_include only.tarpaulin_include only.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.tarpaulin_include only.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.tarpaulin_include only.tarpaulin_include only.clone_to_uninit)self to use its Binary implementation when Debug-formatted.self to use its Display implementation when
Debug-formatted.self to use its LowerExp implementation when
Debug-formatted.self to use its LowerHex implementation when
Debug-formatted.self to use its Octal implementation when Debug-formatted.self to use its Pointer implementation when
Debug-formatted.self to use its UpperExp implementation when
Debug-formatted.self to use its UpperHex implementation when
Debug-formatted.Calls U::from(self).
That is, this conversion is whatever the implementation of
From<T> for U chooses to do.
self and passes that borrow into the pipe function. Read moreself and passes that borrow into the pipe function. Read moreself, then passes self.as_ref() into the pipe function.self, then passes self.as_mut() into the pipe
function.self, then passes self.deref() into the pipe function.self, then passes self.deref_mut() into the pipe
function.arbitrary_self_types)Borrow<B> of a value. Read moreBorrowMut<B> of a value. Read moreAsRef<R> view of a value. Read moreAsMut<R> view of a value. Read moreDeref::Target of a value. Read moreDeref::Target of a value. Read more.tap() only in debug builds, and is erased in release builds..tap_mut() only in debug builds, and is erased in release
builds..tap_borrow() only in debug builds, and is erased in release
builds..tap_borrow_mut() only in debug builds, and is erased in release
builds..tap_ref() only in debug builds, and is erased in release
builds..tap_ref_mut() only in debug builds, and is erased in release
builds..tap_deref() only in debug builds, and is erased in release
builds..tap_deref_mut() only in debug builds, and is erased in release
builds.| Web Proxy Viewer | New URL | Original Page |