Struct bitvec::BitVec

#[repr(C)]
pub struct BitVec<C = BigEndian, T = u8> where
    C: Cursor,
    T: Bits,  { /* fields omitted */ }

A compact Vec of bits, whose cursor and storage type can be customized.

BitVec is a newtype wrapper over Vec, and as such is exactly three words in size on the stack.

Examples

use bitvec::*;

let mut bv: BitVec = BitVec::new();
bv.push(false);
bv.push(true);

assert_eq!(bv.len(), 2);
assert_eq!(bv[0], false);

assert_eq!(bv.pop(), Some(true));
assert_eq!(bv.len(), 1);

bv.set(0, true);
assert_eq!(bv[0], true);

bv.extend([0u8, 1, 0].iter().map(|n| *n != 0u8));
for bit in &*bv {
  println!("{}", bit);
}
assert_eq!(bv, bitvec![1, 0, 1, 0]);

The bitvec! macro is provided to make initialization more convenient.

use bitvec::*;

let mut bv = bitvec![0, 1, 2, 3];
bv.push(false);
assert_eq!(bv, bitvec![0, 1, 1, 1, 0]);

It can also initialize each element of a BitVec<_, T> with a given value. This may be more efficient than performing allocation and initialization in separate steps, especially when initializing a vector of zeros:

use bitvec::*;

let bv = bitvec![0; 15];
assert_eq!(bv, bitvec![0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]);

// The following is equivalent, but potentially slower:
let mut bv1: BitVec = BitVec::with_capacity(15);
bv1.resize(15, false);

Use a BitVec<T> as an efficient stack:

use bitvec::*;
let mut stack: BitVec = BitVec::new();

stack.push(false);
stack.push(true);
stack.push(true);

while let Some(top) = stack.pop() {
  //  Prints true, true, false
  println!("{}", top);
}

Indexing

The BitVec type allows you to access values by index, because it implements the Index trait. An example will be more explicit:

use bitvec::*;

let bv = bitvec![0, 0, 1, 1];
println!("{}", bv[1]); // it will display 'false'

However, be careful: if you try to access an index which isn’t in the BitVec, your software will panic! You cannot do this:

use bitvec::*;

let bv = bitvec![0, 1, 0, 1];
println!("{}", bv[6]); // it will panic!

In conclusion: always check if the index you want to get really exists before doing it.

Slicing

A BitVec is growable. A BitSlice, on the other hand, is fixed size. To get a bit slice, use &. Example:

use bitvec::*;
fn read_bitslice(slice: &BitSlice) {
    // use slice
}

let bv = bitvec![0, 1];
read_bitslice(&bv);

// … and that’s all!
// you can also do it like this:
let bs : &BitSlice = &bv;

In Rust, it’s more common to pass slices as arguments rather than vectors when you do not want to grow or shrink it. The same goes for Vec and &[], and String and &str.

Capacity and Reallocation

The capacity of a bit vector is the amount of space allocated for any future elements that will be added onto the vector. This is not to be confused with the length of a vector, which specifies the number of actual bits within the vector. If a vector’s length exceeds its capacity, its capacity will automatically be increased, but its elements will have to be reallocated.

For example, a bit vector with capacity 10 and length 0 would be an allocated, but uninhabited, vector, with space for ten more bits. Pushing ten or fewer bits onto the vector will not change its capacity or cause reallocation to occur. However, if the vector’s length is increased to eleven, it will have to reallocate, which can be slow. For this reason, it is recommended to use BitVec::with_capacity whenever possible to specify how big the bit vector is expected to get.

Guarantees

Due to its incredibly fundamental nature, BitVec makes a lot of guarantees about its design. This ensures that it is as low-overhead as possible in the general case, and can be correctly manipulated in fundamental ways by unsafe code.

Most fundamentally, BitVec is an always will be a ([BitPtr], capacity) doublet. No more, no less. The order of these fields is unspecified, and you should only interact with the members through the provided APIs. Note that BitPtr is not directly manipulable, and must never be written or interpreted as anything but opaque binary data by user code.

When a BitVec has allocated memory, then the memory to which it points is on the heap (as defined by the allocator Rust is configured to use by default), and its pointer points to len initialized bits in order of the Cursor type parameter, followed by capacity - len logically uninitialized bits.

BitVec will never perform a “small optimization” where elements are stored in its handle representation, for two reasons:

• It would make it more difficult for user code to correctly manipulate a BitVec. The contents of the BitVec would not have a stable address if the handle were moved, and it would be more difficult to determine if a BitVec had allocated memory.

• It would penalize the general, heap-allocated, case by incurring a branch on every access.

BitVec will never automatically shrink itself, even if it is emptied. This ensures that no unnecessary allocations or deallocations occur. Emptying a BitVec and then refilling it to the same length will incur no calls to the allocator. If you wish to free up unused memory, use shrink_to_fit.

Erasure

BitVec will not specifically overwrite any data that is removed from it, nor will it specifically preserve it. Its uninitialized memory is scratch space that may be used however the implementation desires, and must not be relied upon as stable. Do not rely on removed data to be erased for security purposes. Even if you drop a BitVec, its buffer may simply be reused for other data structures in your program. Even if you zero a BitVec’s memory first, that may not actually occur if the optimizer does not consider this an observable side effect. There is one case that will never break, however: using unsafe to construct a [T] slice over the BitVec’s capacity, and writing to the excess space, then increasing the length to match, is always valid.

Type Parameters

• C: Cursor: An implementor of the Cursor trait. This type is used to convert semantic indices into concrete bit positions in elements, and store or retrieve bit values from the storage type.
• T: Bits: An implementor of the Bits trait: u8, u16, u32, u64. This is the actual type in memory the slice will use to store data.

Safety

The BitVec handle has the same size as standard Rust Vec handles, but it is extremely binary incompatible with them. Attempting to treat BitVec<_, T> as Vec<T> in any manner except through the provided APIs is catastrophically unsafe and unsound.

Methods

impl<C, T> BitVec<C, T> where
    C: Cursor,
    T: Bits, 

pub fn new() -> Self

Constructs a new, empty, BitVec<C, T>.

The vector does not allocate until bits are written into it.

Returns

An empty, unallocated, BitVec handle.

Examples

use bitvec::*;

let bv: BitVec = BitVec::new();
assert!(bv.is_empty());
assert_eq!(bv.capacity(), 0);

pub fn with_capacity(capacity: usize) -> Self

Constructs a new, empty, BitVec<T> with the specified capacity.

The new vector will be able to hold at least capacity elements before it reallocates. If capacity is 0, it will not allocate.

Parameters

• capacity: The minimum number of bits that the new vector will need to be able to hold.

Returns

An empty vector with at least the given capacity.

Examples

use bitvec::*;

let bv: BitVec = BitVec::with_capacity(10);
assert!(bv.is_empty());
assert!(bv.capacity() >= 10);

pub unsafe fn from_raw_parts(pointer: BitPtr<T>, capacity: usize) -> Self

Creates a new BitVec<C, T> directly from the raw parts of another.

Parameters

• pointer: The BitPtr<T> to use.
• capacity: The number of T elements allocated in that slab.

Returns

A BitVec over the given slab of memory.

Safety

This is highly unsafe, due to the number of invariants that aren’t checked:

• pointer needs to have been previously allocated by some allocating type.
• pointer’s T needs to have the same size and alignment as it was initially allocated.
• pointer’s element count needs to be less than or equal to the original allocation capacity.
• capacity needs to be the original allocation capacity for the pointer.

Violating these will cause problems, like corrupting the handle’s concept of memory, the allocator’s internal data structures, and the sanity of your program. It is absolutely not safe to construct a BitVec whose T differs from the type used for the initial allocation.

The ownership of pointer is effectively transferred to the BitVec<C, T> which may then deallocate, reallocate, or modify the contents of the referent slice at will. Ensure that nothing else uses the pointer after calling this function.

pub fn capacity(&self) -> usize

Returns the number of bits the vector can hold without reallocating.

Parameters

• &self

Returns

The number of bits that the vector can hold before reallocating.

Examples

use bitvec::*;

let bv: BitVec = BitVec::with_capacity(10);
assert!(bv.is_empty());
assert!(bv.capacity() >= 10);

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more bits to be inserted.

The collection may reserve more space to avoid frequent reallocations. After calling reserve, capacity will be greater than or equal to self.len() + additional. Does nothing if the capacity is already sufficient.

Parameters

• &mut self
• additional: The number of extra bits to be granted space.

Panics

Panics if the new capacity would overflow the vector’s limits.

Examples

use bitvec::*;

let mut bv = bitvec![1; 5];
assert!(bv.capacity() >= 5);
bv.reserve(10);
assert!(bv.capacity() >= 15);

pub fn reserve_exact(&mut self, additional: usize)

Reserves the minimum capacity for at least additional more bits.

After calling reserve_exact, the capacity will be greater than or equal to self.len() + additional. Does nothing if the capacity is already sufficient.

Note that the allocator may give the collection more space than it requests. Therefore, the capacity cannot be relied upon to be precisely minimal. Prefer reserve if future insertions are expected.

Parameters

• &mut self
• additional: The number of extra bits to be granted space.

Panics

Panics if the new capacity would overflow the vector’s limits.

Examples

use bitvec::*;

let mut bv = bitvec![1; 5];
assert!(bv.capacity() >= 5);
bv.reserve_exact(10);
assert!(bv.capacity() >= 15);

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the vector as much as possible.

It will drop down as close as possible to the length, but the allocator may still inform the vector that there is space for a few more elements.

This does not affect the memory store! It will not zero the raw memory, nor will it deallocate.

Parameters

• &mut self

Examples

use bitvec::*;

let mut bv = bitvec![1; 100];
let cap = bv.capacity();
bv.truncate(10);
bv.shrink_to_fit();
assert!(bv.capacity() <= cap);

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

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

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

Parameters

• &mut self
• len: The new length of the vector.

Examples

use bitvec::*;

let mut bv = bitvec![1; 15];
bv.truncate(10);
assert_eq!(bv.len(), 10);

bv.truncate(15);
assert_eq!(bv.len(), 10);

pub fn as_bitslice(&self) -> &BitSlice<C, T>

Extracts a BitSlice containing the entire vector.

Equivalent to &s[..].

Parameters

• &self

Returns

A BitSlice over the vector.

Examples

use bitvec::*;

let bv = bitvec![0, 1, 1, 0];
let bs = bv.as_bitslice();

pub fn as_mut_bitslice(&mut self) -> &mut BitSlice<C, T>

Extracts a mutable BitSlice containing the entire vector.

Equivalent to &mut s[..].

Parameters

• &mut self

Returns

A mutable BitSlice over the vector.

Examples

use bitvec::*;

let mut bv = bitvec![0, 1, 1, 0];
let bs = bv.as_mut_bitslice();

pub unsafe fn set_len(&mut self, len: usize)

Sets the length of the vector.

This unconditionally sets the size of the vector, without modifying its contents. It is up to the caller to ensure that the vector’s buffer can hold the new size.

Parameters

• &mut self
• len: The new length of the vector. This must be less than the maximum number of bits that the vector can hold.

Panics

This panics if len overflows the vector's intrinsic or allocated capacities.

Safety

The caller must ensure that the new length is sound for the vector.

Examples

use bitvec::*;

let mut bv: BitVec = BitVec::with_capacity(15);
assert!(bv.is_empty());
unsafe { bv.set_len(10) };
assert_eq!(bv.len(), 10);

pub fn swap_remove(&mut self, index: usize) -> bool

Removes a bit from the vector and returns it.

The removed bit is replaced by the last bit in the vector.

Parameters

• &mut self
• index: The index whose bit is to be returned, and replaced by the tail.

Returns

The bit at the requested index.

Panics

Panics if the index is out of bounds.

Examples

use bitvec::*;

let mut bv = bitvec![0, 0, 0, 0, 1];
assert!(!bv[2]);
assert_eq!(bv.len(), 5);
assert!(!bv.swap_remove(2));
assert!(bv[2]);
assert_eq!(bv.len(), 4);

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

Inserts an element at a position, shifting all elements after it to the right.

Note that this is O(n) runtime.

Parameters

• &mut self
• index: The position at which to insert. This may be any value from 0 up to and including self.len(). At self.len(), it is equivalent to calling self.push(value).
• value: The value to be inserted.

Panics

Panics if index is greater than the length.

Examples

use bitvec::*;

let mut bv = bitvec![0, 0, 0, 0];
bv.insert(2, true);
assert_eq!(bv, bitvec![0, 0, 1, 0, 0]);
bv.insert(5, true);
assert_eq!(bv, bitvec![0, 0, 1, 0, 0, 1]);

pub fn remove(&mut self, index: usize) -> bool

Removes and returns the element at position index, shifting all elements after it to the left.

Parameters

• &mut self
• index: The position whose bit is to be removed. This must be in the domain 0 .. self.len().

Returns

The bit at the requested index.

Panics

Panics if index is out of bounds for the vector.

Examples

use bitvec::*;

let mut bv = bitvec![0, 0, 1, 0, 0];
assert!(bv.remove(2));
assert_eq!(bv, bitvec![0, 0, 0, 0]);

pub fn retain<F: FnMut(bool) -> bool>(&mut self, pred: F)

Retains only the bits that pass the predicate.

This removes all bits b where f(e) returns false. This method operates in place and preserves the order of the retained bits. Because it is in-place, it operates in O(n²) time.

Parameters

• &mut self
• pred: The testing predicate for each bit.

Type Parameters

• F: FnMut(bool) -> bool: A function that can be invoked on each bit, returning whether the bit should be kept or not.

Examples

use bitvec::*;

let mut bv = bitvec![0, 1, 0, 1, 0, 1];
bv.retain(|b| b);
assert_eq!(bv, bitvec![1, 1, 1]);

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

Appends a bit to the back of the vector.

If the vector is at capacity, this may cause a reallocation.

Parameters

• &mut self
• value: The bit value to append.

Panics

This will panic if the push will cause the vector to allocate above BitPtr<T> or machine capacity.

Examples

use bitvec::*;

let mut bv: BitVec = BitVec::new();
assert!(bv.is_empty());
bv.push(true);
assert_eq!(bv.len(), 1);
assert!(bv[0]);

pub fn pop(&mut self) -> Option<bool>

Removes the last bit from the collection, if present.

Parameters

• &mut self

Returns

If the vector is not empty, this returns the last bit; if it is empty, this returns None.

Examples

use bitvec::*;

let mut bv: BitVec = BitVec::new();
assert!(bv.is_empty());
bv.push(true);
assert_eq!(bv.len(), 1);
assert!(bv[0]);

assert!(bv.pop().unwrap());
assert!(bv.is_empty());
assert!(bv.pop().is_none());

pub fn append<D, U>(&mut self, other: &mut BitVec<D, U>) where
    D: Cursor,
    U: Bits, 

Moves all the elements of other into self, leaving other empty.

Parameters

• &mut self
• other: A BitVec of any order and storage type. Its bits are appended to self.

Panics

Panics if the joined vector is too large.

Examples

use bitvec::*;

let mut bv1 = bitvec![0; 10];
let mut bv2 = bitvec![1; 10];
bv1.append(&mut bv2);
assert_eq!(bv1.len(), 20);
assert!(bv1[10]);
assert!(bv2.is_empty());

pub fn drain<R: RangeBounds<usize>>(&mut self, range: R) -> Drain<C, T>

Creates a draining iterator that removes the specified range from the vector and yields the removed bits.

Notes

1. The element range is removed, regardless of whether the iterator is consumed.
2. The amount of items removed from the vector if the draining iterator is leaked, is left unspecified.

Parameters

• &mut self
• range: any range literal, which is used to define the range of the vector that is drained.

Returns

An iterator over the specified range.

Panics

Panics if the range is ill-formed, or if it is beyond the vector bounds.

Examples

use bitvec::*;

let mut bv = bitvec![0, 0, 1, 1, 1, 0, 0];
assert_eq!(bv.len(), 7);
for bit in bv.drain(2 .. 5) {
  assert!(bit);
}
assert!(bv.not_any());
assert_eq!(bv.len(), 4);

pub fn clear(&mut self)

Clears the vector, removing all values.

Note that this method has no effect on the allocated capacity of the vector.

Parameters

• &mut self

Effects

Becomes an uninhabited slice.

Examples

use bitvec::*;

let mut bv = bitvec![1; 30];
assert_eq!(bv.len(), 30);
assert!(bv.iter().all(|b| b));
bv.clear();
assert!(bv.is_empty());

After calling clear(), bv will no longer show raw memory, so the above test cannot show that the underlying memory is not altered. This is also an implementation detail on which you should not rely.

pub fn split_off(&mut self, at: usize) -> Self

Splits the collection into two at the given index.

Returns a newly allocated Self. self contains elements [0, at), and the returned Self contains elements [at, self.len()).

Note that the capacity of self does not change.

Parameters

• &mut self
• at: The index at which to perform the split. This must be in the domain 0 ..= self.len(). When it is self.len(), an empty vector is returned.

Returns

A new BitVec containing all the elements from at onwards.

Panics

Panics if at is beyond self.len().

Examples

use bitvec::*;

let mut bv1 = bitvec![0, 0, 0, 1, 1, 1];
let bv2 = bv1.split_off(3);
assert_eq!(bv1, bitvec![0, 0, 0]);
assert_eq!(bv2, bitvec![1, 1, 1]);

pub fn resize(&mut self, new_len: usize, value: bool)

Resizes the BitVec in place so that len is equal to new_len.

If new_len is greater than len, then the vector is extended by the difference, and filled with the provided value. If new_len is less than len, then the vector is just truncated.

Parameters

• &mut self
• new_len: The new length of the vector.
• value: The fill value if the vector is to be extended.

Examples

use bitvec::*;

let mut bv = bitvec![0; 4];
bv.resize(8, true);
assert_eq!(bv, bitvec![0, 0, 0, 0, 1, 1, 1, 1]);
bv.resize(5, false);
assert_eq!(bv, bitvec![0, 0, 0, 0, 1]);

pub fn splice<R, I>(
    &mut self,
    range: R,
    replacement: I
) -> Splice<C, T, <I as IntoIterator>::IntoIter> where
    R: RangeBounds<usize>,
    I: Iterator<Item = bool>, 

Creates a splicing iterator that exchanges the specified range for the replacement iterator, yielding the removed items. The range and its replacement do not need to be the same size.

pub fn set_elements(&mut self, element: T)

Sets the backing storage to the provided element.

This unconditionally sets each allocated element in the backing storage to the provided value, without altering the BitVec length or capacity. It operates on the underlying Vec’s memory region directly, and will ignore the BitVec’s cursors.

This has the unobservable effect of setting the allocated, but dead, bits beyond the end of the vector’s length, up to its capacity.

Parameters

• &mut self
• element: The value to which each allocated element in the backing store will be set.

Examples

use bitvec::*;

let mut bv = bitvec![0; 10];
assert_eq!(bv.as_slice(), &[0, 0]);
bv.set_elements(0xA5);
assert_eq!(bv.as_slice(), &[0xA5, 0xA5]);

Methods from Deref<Target = BitSlice<C, T>>

pub fn len(&self) -> usize

Returns the number of bits contained in the BitSlice.

Parameters

• &self

Returns

The number of live bits in the slice domain.

Examples

use bitvec::*;

let store: &[u8] = &[0];
let bv: &BitSlice = store.into();
assert_eq!(bv.len(), 8);

pub fn is_empty(&self) -> bool

Tests if the slice is empty.

Parameters

• &self

Returns

Whether the slice has no live bits.

Examples

use bitvec::*;

let bv: &BitSlice = BitSlice::empty();
assert!(bv.is_empty());
let bv: &BitSlice = (&[0u8] as &[u8]).into();;
assert!(!bv.is_empty());

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

Gets the first element of the slice, if present.

Parameters

• &self

Returns

None if the slice is empty, or Some(bit) if it is not.

Examples

use bitvec::*;

assert!(BitSlice::<BigEndian, u8>::empty().first().is_none());
let bv: &BitSlice = (&[128u8] as &[u8]).into();
assert!(bv.first().unwrap());

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

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

Parameters

• &self

Returns

If the slice is empty, this returns None, otherwise, it returns Some of:

• the first bit
• a &BitSlice of all the rest of the bits (this may be empty)

Examples

use bitvec::*;

assert!(BitSlice::<BigEndian, u8>::empty().split_first().is_none());

let store: &[u8] = &[128];
let bv: &BitSlice = store.into();
let (h, t) = bv.split_first().unwrap();
assert!(h);
assert!(t.not_any());

let bv = &bv[0 .. 1];
let (h, t) = bv.split_first().unwrap();
assert!(h);
assert!(t.is_empty());

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

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

Parameters

• &self

Returns

If the slice is empty, this returns None, otherwise, it returns Some of:

• the first bit
• a &mut BitSlice of all the rest of the bits (this may be empty)

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

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

Parameters

• &self

Returns

If the slice is empty, this returns None, otherwise, it returns Some of:

• the last bit
• a &BitSlice of all the rest of the bits (this may be empty)

Examples

use bitvec::*;

assert!(BitSlice::<BigEndian, u8>::empty().split_last().is_none());

let bv: &BitSlice = (&[1u8] as &[u8]).into();
let (t, h) = bv.split_last().unwrap();
assert!(t);
assert!(h.not_any());

let bv = &bv[7 .. 8];
let (t, h) = bv.split_last().unwrap();
assert!(t);
assert!(h.is_empty());

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

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

Parameters

• &self

Returns

If the slice is empty, this returns None, otherwise, it returns Some of:

• the last bit
• a &BitSlice of all the rest of the bits (this may be empty)

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

Gets the last element of the slice, or None if it is empty.

Parameters

• &self

Returns

None if the slice is empty, or Some(bit) if it is not.

Examples

use bitvec::*;

assert!(BitSlice::<BigEndian, u8>::empty().last().is_none());
let bv: &BitSlice = (&[1u8] as &[u8]).into();
assert!(bv.last().unwrap());

pub fn get(&self, index: usize) -> Option<bool>

Gets the bit value at the given position.

Parameters

• &self
• index: The bit index to retrieve.

Returns

The bit at the specified index, if any.

Examples

use bitvec::*;

let bv: &BitSlice = (&[8u8] as &[u8]).into();
assert!(bv.get(4).unwrap());
assert!(!bv.get(3).unwrap());
assert!(bv.get(10).is_none());

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

Sets the bit value at the given position.

Parameters

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

Panics

This method panics if index is outside the slice domain.

Examples

use bitvec::*;

let store: &mut [u8] = &mut [8u8];
let bv: &mut BitSlice = store.into();
assert!(!bv[3]);
bv.set(3, true);
assert!(bv[3]);

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

Retrieves a read pointer to the start of the underlying data slice.

Parameters

• &self

Returns

A pointer to the first element, partial or not, in the underlying store.

Safety

The caller must ensure that the slice outlives the pointer this function returns, or else it will dangle and point to garbage.

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

Examples

use bitvec::*;

let store: &[u8] = &[0; 4];
let bv: &BitSlice = store.into();
assert_eq!(store.as_ptr(), bv.as_ptr());

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

Retrieves a write pointer to the start of the underlying data slice.

Parameters

• &mut self

Returns

A pointer to the first element, partial or not, in the underlying store.

Safety

The caller must ensure that the slice outlives the pointer this function returns, or else it will dangle and point to garbage.

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

Examples

use bitvec::*;

let store: &mut [u8] = &mut[0; 4];
let store_ptr = store.as_mut_ptr();
let bv: &mut BitSlice = store.into();
assert_eq!(store_ptr, bv.as_mut_ptr());

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

Swaps two bits in the slice.

Parameters

• &mut self
• a: The first index to be swapped.
• b: The second index to be swapped.

Panics

Panics if either a or b are out of bounds.

Examples

use bitvec::*;

let store: &mut [u8] = &mut[32u8];
let bv: &mut BitSlice = store.into();
assert!(!bv[0]);
assert!(bv[2]);
bv.swap(0, 2);
assert!(bv[0]);
assert!(!bv[2]);

pub fn reverse(&mut self)

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

Parameters

• &mut self

Examples

use bitvec::*;

let store: &mut [u8] = &mut[0b1010_1010];
{
  let bv: &mut BitSlice = store.into();
  bv[1 .. 7].reverse();
}
eprintln!("{:b}", store[0]);
assert_eq!(store[0], 0b1101_0100);

pub fn iter(&self) -> Iter<C, T>

Provides read-only iteration across the slice domain.

The iterator returned from this method implements ExactSizeIterator and DoubleEndedIterator just as the consuming .into_iter() method’s iterator does.

Parameters

• &self

Returns

An iterator over all bits in the slice domain, in C and T ordering.

Examples

use bitvec::*;

let store: &[u8] = &[64];
let bv: &BitSlice = store.into();
let mut iter = bv[.. 2].iter();
assert!(!iter.next().unwrap());
assert!(iter.next().unwrap());
assert!(iter.next().is_none());

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

Produces a sliding iterator over consecutive windows in the slice. Each windows has the width size. The windows overlap. If the slice is shorter than size, the produced iterator is empty.

Parameters

• &self
• size: The width of each window.

Returns

An iterator which yields sliding views into the slice.

Panics

This function panics if the size is zero.

Examples

use bitvec::*;

let store: &[u8] = &[0b0100_1011];
let bv: &BitSlice = store.into();
let mut windows = bv.windows(4);
assert_eq!(windows.next(), Some(&bv[0 .. 4]));
assert_eq!(windows.next(), Some(&bv[1 .. 5]));
assert_eq!(windows.next(), Some(&bv[2 .. 6]));
assert_eq!(windows.next(), Some(&bv[3 .. 7]));
assert_eq!(windows.next(), Some(&bv[4 .. 8]));
assert!(windows.next().is_none());

pub fn chunks(&self, size: usize) -> Chunks<C, T>

Produces a galloping iterator over consecutive chunks in the slice. Each chunk, except possibly the last, has the width size. The chunks do not overlap. If the slice is shorter than size, the produced iterator produces only one chunk.

Parameters

• &self
• size: The width of each chunk.

Returns

An iterator which yields consecutive chunks of the slice.

Panics

This function panics if the size is zero.

Examples

use bitvec::*;

let store: &[u8] = &[0b0100_1011];
let bv: &BitSlice = store.into();
let mut chunks = bv.chunks(3);
assert_eq!(chunks.next(), Some(&bv[0 .. 3]));
assert_eq!(chunks.next(), Some(&bv[3 .. 6]));
assert_eq!(chunks.next(), Some(&bv[6 .. 8]));
assert!(chunks.next().is_none());

pub fn chunks_mut(&mut self, size: usize) -> ChunksMut<C, T>

Produces a galloping iterator over consecutive chunks in the slice. Each chunk, except possibly the last, has the width size. The chunks do not overlap. If the slice is shorter than size, the produced iterator produces only one chunk.

Parameters

• &mut self
• size: The width of each chunk.

Returns

An iterator which yields consecutive mutable chunks of the slice.

Panics

This function panics if the size is zero.

pub fn chunks_exact(&self, size: usize) -> ChunksExact<C, T>

Produces a galloping iterator over consecutive chunks in the slice. Each chunk has the width size. If size does not evenly divide the slice, then the remainder is not part of the iteration, and can be accessed separately with the .remainder() method.

Parameters

• &self
• size: The width of each chunk.

Returns

An iterator which yields consecutive chunks of the slice.

Panics

This function panics if size is zero.

Examples

use bitvec::*;

let store: &[u8] = &[0b0100_1011];
let bv: &BitSlice = store.into();
let mut chunks_exact = bv.chunks_exact(3);
assert_eq!(chunks_exact.next(), Some(&bv[0 .. 3]));
assert_eq!(chunks_exact.next(), Some(&bv[3 .. 6]));
assert!(chunks_exact.next().is_none());
assert_eq!(chunks_exact.remainder(), &bv[6 .. 8]);

pub fn chunks_exact_mut(&mut self, size: usize) -> ChunksExactMut<C, T>

Produces a galloping iterator over consecutive chunks in the slice. Each chunk has the width size. If size does not evenly divide the slice, then the remainder is not part of the iteration, and can be accessed separately with the .remainder() method.

Parameters

• &mut self
• size: The width of each chunk.

Returns

An iterator which yields consecutive mutable chunks of the slice.

Panics

This function panics if size is zero.

pub fn rchunks(&self, size: usize) -> RChunks<C, T>

Produces a galloping iterator over consecutive chunks in the slice, from the back to the front. Each chunk, except possibly the front, has the width size. The chunks do not overlap. If the slice is shorter than size, then the iterator produces one item.

Parameters

• &self
• size: The width of each chunk.

Returns

An iterator which yields consecutive chunks of the slice, from the back to the front.

Panics

This function panics if size is zero.

Examples

use bitvec::*;

let store: &[u8] = &[0b0100_1011];
let bv: &BitSlice = store.into();
let mut rchunks = bv.rchunks(3);
assert_eq!(rchunks.next(), Some(&bv[5 .. 8]));
assert_eq!(rchunks.next(), Some(&bv[2 .. 5]));
assert_eq!(rchunks.next(), Some(&bv[0 .. 2]));
assert!(rchunks.next().is_none());

pub fn rchunks_mut(&mut self, size: usize) -> RChunksMut<C, T>

Produces a galloping iterator over consecutive chunks in the slice, from the back to the front. Each chunk, except possibly the front, has the width size. The chunks do not overlap. If the slice is shorter than size, then the iterator produces one item.

Parameters

• &mut self
• size: The width of each chunk.

Returns

An iterator which yields consecutive mutable chunks of the slice, from the back to the front.

Panics

This function panics if size is zero.

pub fn rchunks_exact(&self, size: usize) -> RChunksExact<C, T>

Produces a galloping iterator over consecutive chunks in the slice, from the back to the front. Each chunk has the width size. If size does not evenly divide the slice, then the remainder is not part of the iteration, and can be accessed separately with the .remainder() method.

Parameters

• &self
• size: The width of each chunk.

Returns

An iterator which yields consecutive chunks of the slice, from the back to the front.

Panics

This function panics if size is zero.

Examples

use bitvec::*;

let store: &[u8] = &[0b0100_1011];
let bv: &BitSlice = store.into();
let mut rchunks_exact = bv.rchunks_exact(3);
assert_eq!(rchunks_exact.next(), Some(&bv[5 .. 8]));
assert_eq!(rchunks_exact.next(), Some(&bv[2 .. 5]));
assert!(rchunks_exact.next().is_none());
assert_eq!(rchunks_exact.remainder(), &bv[0 .. 2]);

pub fn rchunks_exact_mut(&mut self, size: usize) -> RChunksExactMut<C, T>

Produces a galloping iterator over consecutive chunks in the slice, from the back to the front. Each chunk has the width size. If size does not evenly divide the slice, then the remainder is not part of the iteration, and can be accessed separately with the .remainder() method.

Parameters

• &mut self
• size: The width of each chunk.

Returns

An iterator which yields consecutive mutable chunks of the slice, from the back to the front.

Panics

This function panics if size is zero.

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

Divides one slice into two at an index.

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

Parameters

• &self
• mid: The index at which to split

Returns

• The bits up to but not including mid.
• The bits from mid onwards.

Panics

Panics if mid > self.len().

Examples

use bitvec::*;

let store: &[u8] = &[0x0F];
let bv: &BitSlice = store.into();

let (l, r) = bv.split_at(0);
assert!(l.is_empty());
assert_eq!(r, bv);

let (l, r) = bv.split_at(4);
assert_eq!(l, &bv[0 .. 4]);
assert_eq!(r, &bv[4 .. 8]);

let (l, r) = bv.split_at(8);
assert_eq!(l, bv);
assert!(r.is_empty());

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

Divides one slice into two at an index.

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

Parameters

• &mut self
• mid: The index at which to split

Returns

• The bits up to but not including mid.
• The bits from mid onwards.

Panics

Panics if mid > self.len().

pub fn starts_with<D, U>(&self, prefix: &BitSlice<D, U>) -> bool where
    D: Cursor,
    U: Bits, 

Tests if the slice begins with the given prefix.

Parameters

• &self
• prefix: Any BitSlice against which self is tested. This is not required to have the same cursor or storage types as self.

Returns

Whether self begins with prefix. This is true only if self is at least as long as prefix and their bits are semantically equal.

Examples

use bitvec::*;

let store: &[u8] = &[0xA6];
let bv: &BitSlice = store.into();;
assert!(bv.starts_with(&bv[.. 3]));
assert!(!bv.starts_with(&bv[3 ..]));

pub fn ends_with<D, U>(&self, suffix: &BitSlice<D, U>) -> bool where
    D: Cursor,
    U: Bits, 

Tests if the slice ends with the given suffix.

Parameters

• &self
• suffix: Any BitSlice against which self is tested. This is not required to have the same cursor or storage types as self.

Returns

Whether self ends with suffix. This is true only if self is at least as long as suffix and their bits are semantically equal.

Examples

use bitvec::*;

let store: &[u8] = &[0xA6];
let bv: &BitSlice = store.into();
assert!(bv.ends_with(&bv[5 ..]));
assert!(!bv.ends_with(&bv[.. 5]));

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

Rotates the slice, in place, to the left.

After calling this method, the bits from [.. by] will be at the back of the slice, and the bits from [by ..] will be at the front. This operates fully in-place.

In-place rotation of bits requires this method to take O(k × n) time. It is impossible to use machine intrinsics to perform galloping rotation on bits.

Parameters

• &mut self
• by: The number of bits by which to rotate left. This must be in the range 0 ..= self.len(). If it is 0 or self.len(), then this method is a no-op.

Examples

use bitvec::*;

let store: &mut [u8] = &mut [0xF0];
let bv: &mut BitSlice = store.into();
bv.rotate_left(2);
assert_eq!(bv.as_ref()[0], 0xC3);

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

Rotates the slice, in place, to the right.

After calling this method, the bits from [self.len() - by ..] will be at the front of the slice, and the bits from [.. self.len() - by] will be at the back. This operates fully in-place.

In-place rotation of bits requires this method to take O(k × n) time. It is impossible to use machine intrinsics to perform galloping rotation on bits.

Parameters

• &mut self
• by: The number of bits by which to rotate right. This must be in the range 0 ..= self.len(). If it is 0 or self.len, then this method is a no-op.

Examples

use bitvec::*;

let store: &mut [u8] = &mut [0xF0];
let bv: &mut BitSlice = store.into();
bv.rotate_right(2);
assert_eq!(bv.as_ref()[0], 0x3C);

pub fn all(&self) -> bool

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

Truth Table

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

Parameters

• &self

Returns

Whether all bits in the slice domain are set.

Examples

use bitvec::*;

let store: &[u8] = &[0xFD];
let bv: &BitSlice = store.into();
assert!(bv[.. 4].all());
assert!(!bv[4 ..].all());

pub fn any(&self) -> bool

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

Truth Table

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

Parameters

• &self

Returns

Whether any bit in the slice domain is set.

Examples

use bitvec::*;

let store: &[u8] = &[0x40];
let bv: &BitSlice = store.into();
assert!(bv[.. 4].any());
assert!(!bv[4 ..].any());

pub fn not_all(&self) -> bool

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

Truth Table

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

Parameters

• `&self

Returns

Whether any bit in the slice domain is unset.

Examples

use bitvec::*;

let store: &[u8] = &[0xFD];
let bv: &BitSlice = store.into();
assert!(!bv[.. 4].not_all());
assert!(bv[4 ..].not_all());

pub fn not_any(&self) -> bool

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

Truth Table

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

Parameters

• &self

Returns

Whether all bits in the slice domain are unset.

Examples

use bitvec::*;

let store: &[u8] = &[0x40];
let bv: &BitSlice = store.into();
assert!(!bv[.. 4].not_any());
assert!(bv[4 ..].not_any());

pub fn some(&self) -> bool

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

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

Truth Table

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

Parameters

• &self

Returns

Whether the slice domain has mixed content.

Examples

use bitvec::*;

let store: &[u8] = &[0b111_000_10];
let bv: &BitSlice = store.into();
assert!(!bv[0 .. 3].some());
assert!(!bv[3 .. 6].some());
assert!(bv[6 ..].some());

pub fn count_ones(&self) -> usize

Counts how many bits are set high.

Parameters

• &self

Returns

The number of high bits in the slice domain.

Examples

use bitvec::*;

let store: &[u8] = &[0xFD, 0x25];
let bv: &BitSlice = store.into();
assert_eq!(bv.count_ones(), 10);

pub fn count_zeros(&self) -> usize

Counts how many bits are set low.

Parameters

• &self

Returns

The number of low bits in the slice domain.

Examples

use bitvec::*;

let store: &[u8] = &[0xFD, 0x25];
let bv: &BitSlice = store.into();
assert_eq!(bv.count_zeros(), 6);

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

Set all bits in the slice to a value.

Parameters

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

Examples

use bitvec::*;

let store: &mut [u8] = &mut [0];
let bv: &mut BitSlice = store.into();
bv[2 .. 6].set_all(true);
assert_eq!(bv.as_ref(), &[0b0011_1100]);
bv[3 .. 5].set_all(false);
assert_eq!(bv.as_ref(), &[0b0010_0100]);
bv[.. 1].set_all(true);
assert_eq!(bv.as_ref(), &[0b1010_0100]);

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

Provides mutable traversal of the collection.

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

Parameters

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

Examples

use bitvec::*;

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

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

Accesses the underlying store.

Examples

use bitvec::*;

let mut bv: BitVec = bitvec![0, 0, 0, 0, 0, 0, 0, 0, 1];
for elt in bv.as_mut_slice() {
  *elt += 2;
}
assert_eq!(&[2, 0b1000_0010], bv.as_slice());

pub fn head(&self) -> Option<&T>

pub fn head_mut(&mut self) -> Option<&mut T>

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

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

pub fn tail(&self) -> Option<&T>

pub fn tail_mut(&mut self) -> Option<&mut T>

pub fn bitptr(&self) -> BitPtr<T>

Accesses the underlying pointer structure.

Parameters

• &self

Returns

The BitPtr structure of the slice handle.

Trait Implementations

impl<C, T> Drop for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Readies the underlying storage for Drop.

fn drop(&mut self)

Rebuild the interior Vec and let it run the deallocator.

impl<C, T> Eq for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

impl<A, B, C, D> PartialOrd<BitVec<C, D>> for BitSlice<A, B> where
    A: Cursor,
    B: Bits,
    C: Cursor,
    D: Bits, 

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

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

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

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

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

impl<A, B, C, D> PartialOrd<BitVec<C, D>> for BitVec<A, B> where
    A: Cursor,
    B: Bits,
    C: Cursor,
    D: Bits, 

Compares two BitVecs by semantic — not bitwise — ordering.

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

If one of the vectors is exhausted before they differ, the longer vector is greater.

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

Performs a comparison by < or >.

Parameters

• &self
• rhs: The other vector to compare.

Returns

The relative ordering of the two vectors.

Examples

use bitvec::*;

let a = bitvec![0, 1, 0, 0];
let b = bitvec![0, 1, 0, 1];
let c = bitvec![0, 1, 0, 1, 1];
assert!(a < b);
assert!(b < c);

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

impl<A, B, C, D> PartialOrd<BitSlice<C, D>> for BitVec<A, B> where
    A: Cursor,
    B: Bits,
    C: Cursor,
    D: Bits, 

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

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

impl<C, T> AsMut<BitSlice<C, T>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

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

Performs the conversion.

impl<C, T> AsMut<[T]> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Gives write access to all live elements in the underlying storage, including the partially-filled tail.

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

Performs the conversion.

impl<A, B, C, D> PartialEq<BitVec<C, D>> for BitSlice<A, B> where
    A: Cursor,
    B: Bits,
    C: Cursor,
    D: Bits, 

Allow comparison against the allocated form.

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

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

#[must_use]

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

This method tests for !=.

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

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

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

#[must_use]

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

This method tests for !=.

impl<A, B, C, D> PartialEq<BitVec<C, D>> for BitVec<A, B> where
    A: Cursor,
    B: Bits,
    C: Cursor,
    D: Bits, 

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

It is valid to compare two vectors of different endianness or element types.

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

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

Performs a comparison by ==.

Parameters

• &self
• rhs: The other vector to compare.

Returns

Whether the vectors compare equal.

Examples

use bitvec::*;

let l: BitVec<LittleEndian, u16> = bitvec![LittleEndian, u16; 0, 1, 0, 1];
let r: BitVec<BigEndian, u32> = bitvec![BigEndian, u32; 0, 1, 0, 1];
assert!(l == r);

This example uses the same types to prove that raw, bitwise, values are not used for equality comparison.

use bitvec::*;

let l: BitVec<BigEndian, u8> = bitvec![BigEndian, u8; 0, 1, 0, 1];
let r: BitVec<LittleEndian, u8> = bitvec![LittleEndian, u8; 0, 1, 0, 1];

assert_eq!(l, r);
assert_ne!(l.as_slice(), r.as_slice());

#[must_use]

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

This method tests for !=.

impl<A, B, C, D> PartialEq<BitSlice<C, D>> for BitVec<A, B> where
    A: Cursor,
    B: Bits,
    C: Cursor,
    D: Bits, 

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

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

#[must_use]

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

This method tests for !=.

impl<C, T> AsRef<BitSlice<C, T>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

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

Performs the conversion.

impl<C, T> AsRef<[T]> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Gives read access to all live elements in the underlying storage, including the partially-filled tail.

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

Accesses the underlying store.

Examples

use bitvec::*;

let bv = bitvec![0, 0, 0, 0, 0, 0, 0, 0, 1];
assert_eq!(&[0, 0b1000_0000], bv.as_slice());

impl<C, T> Clone for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<C, T> Default for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

fn default() -> Self

Returns the "default value" for a type.

impl<C, T> Ord for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

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

This method returns an Ordering between self and other.

default fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

default fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

default fn clamp(self, min: Self, max: Self) -> Self

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

Restrict a value to a certain interval.

impl<C, T> From<BitVec<C, T>> for BitBox<C, T> where
    C: Cursor,
    T: Bits, 

fn from(src: BitVec<C, T>) -> Self

Performs the conversion.

impl<C, T, '_> From<&'_ BitSlice<C, T>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Copies a BitSlice into an owned BitVec.

The idiomatic BitSlice to BitVec conversion is BitSlice::to_owned, but just as &[T].into() yields a Vec, &BitSlice.into() yields a BitVec.

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

Performs the conversion.

impl<C, T, '_> From<&'_ [bool]> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Builds a BitVec out of a slice of bool.

This is primarily for the bitvec! macro; it is not recommended for general use.

fn from(src: &[bool]) -> Self

Performs the conversion.

impl<C, T> From<BitBox<C, T>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

fn from(src: BitBox<C, T>) -> Self

Performs the conversion.

impl<C, T, '_> From<&'_ [T]> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Builds a BitVec out of a borrowed slice of elements.

This copies the memory as-is from the source buffer into the new BitVec. The source buffer will be unchanged by this operation, so you don't need to worry about using the correct cursor type for the read.

This operation does a copy from the source buffer into a new allocation, as it can only borrow the source and not take ownership.

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

Builds a BitVec<C: Cursor, T: Bits> from a borrowed &[T].

Parameters

• src: The elements to use as the values for the new vector.

Examples

use bitvec::*;

let src: &[u8] = &[5, 10];
let bv: BitVec = src.into();
assert!(bv[5]);
assert!(bv[7]);
assert!(bv[12]);
assert!(bv[14]);

impl<C, T> From<Box<[T]>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Builds a BitVec out of an owned slice of elements.

This moves the memory as-is from the source buffer into the new BitVec. The source buffer will be unchanged by this operation, so you don't need to worry about using the correct cursor type.

fn from(src: Box<[T]>) -> Self

Consumes a Box<[T: Bits]> and creates a BitVec<C: Cursor, T> from it.

Parameters

• src: The source box whose memory will be used.

Returns

A new BitVec using the src Box’s memory.

Examples

use bitvec::*;

let src: Box<[u8]> = Box::new([3, 6, 9, 12, 15]);
let bv: BitVec = src.into();

impl<C, T> From<Vec<T>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Builds a BitVec out of a Vec of elements.

This moves the memory as-is from the source buffer into the new BitVec. The source buffer will be unchanged by this operation, so you don't need to worry about using the correct cursor type.

fn from(src: Vec<T>) -> Self

Consumes a Vec<T: Bits> and creates a BitVec<C: Cursor, T> from it.

Parameters

• src: The source vector whose memory will be used.

Returns

A new BitVec using the src Vec’s memory.

Panics

Panics if the source vector would cause the BitVec to overflow capacity.

Examples

use bitvec::*;

let src: Vec<u8> = vec![1, 2, 4, 8];
let bv: BitVec = src.into();
assert_eq!(
  "[00000001, 00000010, 00000100, 00001000]",
  &format!("{}", bv),
);

impl<C, T> IntoIterator for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Produces an iterator over all the bits in the vector.

This iterator follows the ordering in the vector type, and implements ExactSizeIterator, since BitVecs always know exactly how large they are, and DoubleEndedIterator, since they have known ends.

type Item = bool

The type of the elements being iterated over.

type IntoIter = IntoIter<C, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Iterates over the vector.

Examples

use bitvec::*;

let bv = bitvec![BigEndian, u8; 1, 1, 1, 1, 0, 0, 0, 0];
let mut count = 0;
for bit in bv {
  if bit { count += 1; }
}
assert_eq!(count, 4);

impl<'a, C, T> IntoIterator for &'a BitVec<C, T> where
    C: Cursor,
    T: 'a + Bits, 

type Item = bool

The type of the elements being iterated over.

type IntoIter = <&'a BitSlice<C, T> as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<C, T> Into<Box<[T]>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

fn into(self) -> Box<[T]>

Performs the conversion.

impl<C, T> Into<Vec<T>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

fn into(self) -> Vec<T>

Performs the conversion.

impl<C, T> Extend<bool> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Extends a BitVec with the contents of another bitstream.

At present, this just calls .push() in a loop. When specialization becomes available, it will be able to more intelligently perform bulk moves from the source into self when the source is BitSlice-compatible.

fn extend<I: IntoIterator<Item = bool>>(&mut self, src: I)

Extends a BitVec from another bitstream.

Parameters

• &mut self
• src: A source bitstream.

Type Parameters

• I: IntoIterator<Item=bool>: The source bitstream with which to extend self.

Examples

use bitvec::*;

let mut bv = bitvec![0; 4];
bv.extend(bitvec![1; 4]);
assert_eq!(0x0F, bv.as_slice()[0]);

impl<C, T> Debug for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Prints the BitVec for debugging.

The output is of the form BitVec<C, T> [ELT, *], where <C, T> is the endianness and element type, with square brackets on each end of the bits and all the live elements in the vector printed in binary. The printout is always in semantic order, and may not reflect the underlying store. To see the underlying store, use format!("{:?}", self.as_slice()); instead.

The alternate character {:#?} prints each element on its own line, rather than separated by a space.

fn fmt(&self, f: &mut Formatter) -> Result

Renders the BitVec type header and contents for debug.

Examples

use bitvec::*;

let bv = bitvec![LittleEndian, u16;
  0, 1, 0, 1, 0, 0, 0, 0, 1, 1, 1, 1, 0, 1, 0, 1
];
assert_eq!(
  "BitVec<LittleEndian, u16> [0101000011110101]",
  &format!("{:?}", bv)
);

impl<C, T> FromIterator<bool> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Permits the construction of a BitVec by using .collect() on an iterator of bool.

fn from_iter<I: IntoIterator<Item = bool>>(src: I) -> Self

Collects an iterator of bool into a vector.

Examples

use bitvec::*;

use std::iter::repeat;
let bv: BitVec = repeat(true)
  .take(4)
  .chain(repeat(false).take(4))
  .collect();
assert_eq!(bv.as_slice()[0], 0xF0);

impl<C, T> DerefMut for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Mutably reborrows the BitVec as a BitSlice.

This mimics the separation between Vec<T> and [T].

fn deref_mut(&mut self) -> &mut Self::Target

Dereferences &mut BitVec down to &mut BitSlice.

Examples

use bitvec::*;

let mut bv: BitVec = bitvec![0; 6];
let bref: &mut BitSlice = &mut bv;
assert!(!bref[5]);
bref.set(5, true);
assert!(bref[5]);

impl<C, T> Deref for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Reborrows the BitVec as a BitSlice.

This mimics the separation between Vec<T> and [T].

type Target = BitSlice<C, T>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences &BitVec down to &BitSlice.

Examples

use bitvec::*;

let bv: BitVec = bitvec![1; 4];
let bref: &BitSlice = &bv;
assert!(bref[2]);

impl<C, T> Hash for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

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

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

Writes each bit of the BitVec, as a full bool, into the hasher.

Parameters

• &self
• hasher: The hashing pool into which the vector is written.

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

Feeds a slice of this type into the given [Hasher].

impl<C, T> Add<BitVec<C, T>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Adds two BitVecs together, zero-extending the shorter.

BitVec addition works just like adding numbers longhand on paper. The first bits in the BitVec are the highest, so addition works from right to left, and the shorter BitVec is assumed to be extended to the left with zero.

The output BitVec may be one bit longer than the longer input, if addition overflowed.

Numeric arithmetic is provided on BitVec as a convenience. Serious numeric computation on variable-length integers should use the num_bigint crate instead, which is written specifically for that use case. BitVecs are not intended for arithmetic, and bitvec makes no guarantees about sustained correctness in arithmetic at this time.

type Output = Self

The resulting type after applying the + operator.

fn add(self, addend: Self) -> Self::Output

Adds two BitVecs.

Examples

use bitvec::*;

let a = bitvec![0, 1, 0, 1];
let b = bitvec![0, 0, 1, 1];
let s = a + b;
assert_eq!(bitvec![1, 0, 0, 0], s);

This example demonstrates the addition of differently-sized BitVecs, and will overflow.

use bitvec::*;

let a = bitvec![1; 4];
let b = bitvec![1; 1];
let s = b + a;
assert_eq!(bitvec![1, 0, 0, 0, 0], s);

impl<C, T> Sub<BitVec<C, T>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Subtracts one BitVec from another assuming 2’s-complement encoding.

Subtraction is a more complex operation than addition. The bit-level work is largely the same, but semantic distinctions must be made. Unlike addition, which is commutative and tolerant of switching the order of the addends, subtraction cannot swap the minuend (LHS) and subtrahend (RHS).

Because of the properties of 2’s-complement arithmetic, M - S is equivalent to M + (!S + 1). Subtraction therefore bitflips the subtrahend and adds one. This may, in a degenerate case, cause the subtrahend to increase in length.

Once the subtrahend is stable, the minuend zero-extends its left side in order to match the length of the subtrahend if needed (this is provided by the >> operator).

When the minuend is stable, the minuend and subtrahend are added together by the <BitVec as Add> implementation. The output will be encoded in 2’s-complement, so a leading one means that the output is considered negative.

Interpreting the contents of a BitVec as an integer is beyond the scope of this crate.

Numeric arithmetic is provided on BitVec as a convenience. Serious numeric computation on variable-length integers should use the num_bigint crate instead, which is written specifically for that use case. BitVecs are not intended for arithmetic, and bitvec makes no guarantees about sustained correctness in arithmetic at this time.

type Output = Self

The resulting type after applying the - operator.

fn sub(self, subtrahend: Self) -> Self::Output

Subtracts one BitVec from another.

Examples

Minuend larger than subtrahend, positive difference.

use bitvec::*;

let a = bitvec![1, 0];
let b = bitvec![   1];
let c = a - b;
assert_eq!(bitvec![0, 1], c);

Minuend smaller than subtrahend, negative difference.

use bitvec::*;

let a = bitvec![   1];
let b = bitvec![1, 0];
let c = a - b;
assert_eq!(bitvec![1, 1], c);

Subtraction from self is correctly handled.

use bitvec::*;

let a = bitvec![0, 1, 1, 0];
let b = a.clone();
let c = a - b;
assert!(c.not_any(), "{:?}", c);

impl<C, T> Neg for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

2’s-complement negation of a BitVec.

In 2’s-complement, negation is defined as bit-inversion followed by adding one.

Numeric arithmetic is provided on BitVec as a convenience. Serious numeric computation on variable-length integers should use the num_bigint crate instead, which is written specifically for that use case. BitVecs are not intended for arithmetic, and bitvec makes no guarantees about sustained correctness in arithmetic at this time.

type Output = Self

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Numerically negates a BitVec using 2’s-complement arithmetic.

Examples

use bitvec::*;

let bv = bitvec![0, 1, 1];
let ne = -bv;
assert_eq!(ne, bitvec![1, 0, 1]);

impl<C, T> AddAssign<BitVec<C, T>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Adds another BitVec into self, zero-extending the shorter.

BitVec addition works just like adding numbers longhand on paper. The first bits in the BitVec are the highest, so addition works from right to left, and the shorter BitVec is assumed to be extended to the left with zero.

The output BitVec may be one bit longer than the longer input, if addition overflowed.

Numeric arithmetic is provided on BitVec as a convenience. Serious numeric computation on variable-length integers should use the num_bigint crate instead, which is written specifically for that use case. BitVecs are not intended for arithmetic, and bitvec makes no guarantees about sustained correctness in arithmetic at this time.

fn add_assign(&mut self, addend: Self)

Adds another BitVec into self.

Examples

use bitvec::*;

let mut a = bitvec![1, 0, 0, 1];
let b = bitvec![0, 1, 1, 1];
a += b;
assert_eq!(a, bitvec![1, 0, 0, 0, 0]);

impl<C, T> SubAssign<BitVec<C, T>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Subtracts another BitVec from self, assuming 2’s-complement encoding.

The minuend is zero-extended, or the subtrahend sign-extended, as needed to ensure that the vectors are the same width before subtraction occurs.

The Sub trait has more documentation on the subtraction process.

Numeric arithmetic is provided on BitVec as a convenience. Serious numeric computation on variable-length integers should use the num_bigint crate instead, which is written specifically for that use case. BitVecs are not intended for arithmetic, and bitvec makes no guarantees about sustained correctness in arithmetic at this time.

fn sub_assign(&mut self, subtrahend: Self)

Subtracts another BitVec from self.

Examples

use bitvec::*;

let a = bitvec![0, 0, 0, 1];
let b = bitvec![0, 0, 0, 0];
let c = a - b;
assert_eq!(c, bitvec![0, 0, 0, 1]);

impl<C, T> Not for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Flips all bits in the vector.

type Output = Self

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Inverts all bits in the vector.

Examples

use bitvec::*;

let bv: BitVec<BigEndian, u32> = BitVec::from(&[0u32] as &[u32]);
let flip = !bv;
assert_eq!(!0u32, flip.as_slice()[0]);

impl<C, T, I> BitAnd<I> for BitVec<C, T> where
    C: Cursor,
    T: Bits,
    I: IntoIterator<Item = bool>, 

Performs the Boolean AND operation between each element of a BitVec and anything that can provide a stream of bool values (such as another BitVec, or any bool generator of your choice). The BitVec emitted will have the length of the shorter sequence of bits -- if one is longer than the other, the extra bits will be ignored.

type Output = Self

The resulting type after applying the & operator.

fn bitand(self, rhs: I) -> Self::Output

ANDs a vector and a bitstream, producing a new vector.

Examples

use bitvec::*;

let lhs = bitvec![BigEndian, u8; 0, 1, 0, 1];
let rhs = bitvec![BigEndian, u8; 0, 0, 1, 1];
let and = lhs & rhs;
assert_eq!("[0001]", &format!("{}", and));

impl<C, T, I> BitOr<I> for BitVec<C, T> where
    C: Cursor,
    T: Bits,
    I: IntoIterator<Item = bool>, 

Performs the Boolean OR operation between each element of a BitVec and anything that can provide a stream of bool values (such as another BitVec, or any bool generator of your choice). The BitVec emitted will have the length of the shorter sequence of bits -- if one is longer than the other, the extra bits will be ignored.

type Output = Self

The resulting type after applying the | operator.

fn bitor(self, rhs: I) -> Self::Output

ORs a vector and a bitstream, producing a new vector.

Examples

use bitvec::*;

let lhs = bitvec![0, 1, 0, 1];
let rhs = bitvec![0, 0, 1, 1];
let or  = lhs | rhs;
assert_eq!("[0111]", &format!("{}", or));

impl<C, T, I> BitXor<I> for BitVec<C, T> where
    C: Cursor,
    T: Bits,
    I: IntoIterator<Item = bool>, 

Performs the Boolean XOR operation between each element of a BitVec and anything that can provide a stream of bool values (such as another BitVec, or any bool generator of your choice). The BitVec emitted will have the length of the shorter sequence of bits -- if one is longer than the other, the extra bits will be ignored.

type Output = Self

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: I) -> Self::Output

XORs a vector and a bitstream, producing a new vector.

Examples

use bitvec::*;

let lhs = bitvec![0, 1, 0, 1];
let rhs = bitvec![0, 0, 1, 1];
let xor = lhs ^ rhs;
assert_eq!("[0110]", &format!("{}", xor));

impl<C, T> Shl<usize> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Shifts all bits in the vector to the left – DOWN AND TOWARDS THE FRONT.

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

THAT IS NOT HOW BITVEC WORKS!

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

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

In LittleEndian order, the effect will be equivalent to using >> on the primitives in memory!

Notes

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

The length of the vector is decreased by the shift amount.

If the shift amount is greater than the length, the vector calls clear() and zeroes its memory. This is not an error.

type Output = Self

The resulting type after applying the << operator.

fn shl(self, shamt: usize) -> Self::Output

Shifts a BitVec to the left, shortening it.

Examples

use bitvec::*;

let bv = bitvec![BigEndian, u8; 0, 0, 0, 1, 1, 1];
assert_eq!("[000111]", &format!("{}", bv));
assert_eq!(0b0001_1100, bv.as_slice()[0]);
assert_eq!(bv.len(), 6);
let ls = bv << 2usize;
assert_eq!("[0111]", &format!("{}", ls));
assert_eq!(0b0111_0000, ls.as_slice()[0]);
assert_eq!(ls.len(), 4);

impl<C, T> Shr<usize> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Shifts all bits in the vector to the right – UP AND TOWARDS THE BACK.

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

THAT IS NOT HOW BITVEC WORKS!

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

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

In LittleEndian order, the effect will be equivalent to using << on the primitives in memory!

Notes

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

The length of the vector is increased by the shift amount.

If the new length of the vector would overflow, a panic occurs. This is an error.

type Output = Self

The resulting type after applying the >> operator.

fn shr(self, shamt: usize) -> Self::Output

Shifts a BitVec to the right, lengthening it and filling the front with 0.

Examples

use bitvec::*;

let bv = bitvec![BigEndian, u8; 0, 0, 0, 1, 1, 1];
assert_eq!("[000111]", &format!("{}", bv));
assert_eq!(0b0001_1100, bv.as_slice()[0]);
assert_eq!(bv.len(), 6);
let rs = bv >> 2usize;
assert_eq!("[00000111]", &format!("{}", rs));
assert_eq!(0b0000_0111, rs.as_slice()[0]);
assert_eq!(rs.len(), 8);

impl<C, T, I> BitAndAssign<I> for BitVec<C, T> where
    C: Cursor,
    T: Bits,
    I: IntoIterator<Item = bool>, 

Performs the Boolean AND operation in place on a BitVec, using a stream of bool values as the other bit for each operation. If the other stream is shorter than self, self will be truncated when the other stream expires.

fn bitand_assign(&mut self, rhs: I)

ANDs another bitstream into a vector.

Examples

use bitvec::*;

let mut src  = bitvec![BigEndian, u8; 0, 1, 0, 1];
        src &= bitvec![BigEndian, u8; 0, 0, 1, 1];
assert_eq!("[0001]", &format!("{}", src));

impl<C, T, I> BitOrAssign<I> for BitVec<C, T> where
    C: Cursor,
    T: Bits,
    I: IntoIterator<Item = bool>, 

Performs the Boolean OR operation in place on a BitVec, using a stream of bool values as the other bit for each operation. If the other stream is shorter than self, self will be truncated when the other stream expires.

fn bitor_assign(&mut self, rhs: I)

ORs another bitstream into a vector.

Examples

use bitvec::*;

let mut src  = bitvec![0, 1, 0, 1];
        src |= bitvec![0, 0, 1, 1];
assert_eq!("[0111]", &format!("{}", src));

impl<C, T, I> BitXorAssign<I> for BitVec<C, T> where
    C: Cursor,
    T: Bits,
    I: IntoIterator<Item = bool>, 

Performs the Boolean XOR operation in place on a BitVec, using a stream of bool values as the other bit for each operation. If the other stream is shorter than self, self will be truncated when the other stream expires.

fn bitxor_assign(&mut self, rhs: I)

XORs another bitstream into a vector.

Examples

use bitvec::*;

let mut src  = bitvec![0, 1, 0, 1];
        src ^= bitvec![0, 0, 1, 1];
assert_eq!("[0110]", &format!("{}", src));

impl<C, T> ShlAssign<usize> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Shifts all bits in the vector to the left – DOWN AND TOWARDS THE FRONT.

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

THAT IS NOT HOW BITVEC WORKS!

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

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

In LittleEndian order, the effect will be equivalent to using >> on the primitives in memory!

Notes

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

The length of the vector is decreased by the shift amount.

If the shift amount is greater than the length, the vector calls clear() and zeroes its memory. This is not an error.

fn shl_assign(&mut self, shamt: usize)

Shifts a BitVec to the left in place, shortening it.

Examples

use bitvec::*;

let mut bv = bitvec![LittleEndian, u8; 0, 0, 0, 1, 1, 1];
assert_eq!("[000111]", &format!("{}", bv));
assert_eq!(0b0011_1000, bv.as_slice()[0]);
assert_eq!(bv.len(), 6);
bv <<= 2;
assert_eq!("[0111]", &format!("{}", bv));
assert_eq!(0b0000_1110, bv.as_slice()[0]);
assert_eq!(bv.len(), 4);

impl<C, T> ShrAssign<usize> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Shifts all bits in the vector to the right – UP AND TOWARDS THE BACK.

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

THAT IS NOT HOW BITVEC WORKS!

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

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

In LittleEndian order, the effect will be equivalent to using << on the primitives in memory!

Notes

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

The length of the vector is increased by the shift amount.

If the new length of the vector would overflow, a panic occurs. This is an error.

fn shr_assign(&mut self, shamt: usize)

Shifts a BitVec to the right in place, lengthening it and filling the front with 0.

Examples

use bitvec::*;

let mut bv = bitvec![LittleEndian, u8; 0, 0, 0, 1, 1, 1];
assert_eq!("[000111]", &format!("{}", bv));
assert_eq!(0b0011_1000, bv.as_slice()[0]);
assert_eq!(bv.len(), 6);
bv >>= 2;
assert_eq!("[00000111]", &format!("{}", bv));
assert_eq!(0b1110_0000, bv.as_slice()[0]);
assert_eq!(bv.len(), 8);

impl<C, T> Index<usize> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Gets the bit at a specific index. The index must be less than the length of the BitVec.

type Output = bool

The returned type after indexing.

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

Looks up a single bit by semantic count.

Examples

use bitvec::*;

let bv = bitvec![BigEndian, u8; 0, 0, 0, 0, 0, 0, 0, 0, 1, 0];
assert!(!bv[7]); // ---------------------------------^  |  |
assert!( bv[8]); // ------------------------------------^  |
assert!(!bv[9]); // ---------------------------------------^

If the index is greater than or equal to the length, indexing will panic.

The below test will panic when accessing index 1, as only index 0 is valid.

use bitvec::*;

let mut bv: BitVec = BitVec::new();
bv.push(true);
bv[1];

impl<C, T> Index<Range<usize>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

type Output = BitSlice<C, T>

The returned type after indexing.

fn index(&self, Range { start: start, end: end }: Range<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<C, T> Index<RangeInclusive<usize>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

type Output = BitSlice<C, T>

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<C, T> Index<RangeFrom<usize>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

type Output = BitSlice<C, T>

The returned type after indexing.

fn index(&self, RangeFrom { start: start }: RangeFrom<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<C, T> Index<RangeFull> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

type Output = BitSlice<C, T>

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<C, T> Index<RangeTo<usize>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

type Output = BitSlice<C, T>

The returned type after indexing.

fn index(&self, RangeTo { end: end }: RangeTo<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<C, T> Index<RangeToInclusive<usize>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

type Output = BitSlice<C, T>

The returned type after indexing.

fn index(
    &self,
    RangeToInclusive { end: end }: RangeToInclusive<usize>
) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<C, T> IndexMut<Range<usize>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

fn index_mut(
    &mut self,
    Range { start: start, end: end }: Range<usize>
) -> &mut Self::Output

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

impl<C, T> IndexMut<RangeInclusive<usize>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

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

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

impl<C, T> IndexMut<RangeFrom<usize>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

fn index_mut(
    &mut self,
    RangeFrom { start: start }: RangeFrom<usize>
) -> &mut Self::Output

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

impl<C, T> IndexMut<RangeFull> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

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

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

impl<C, T> IndexMut<RangeTo<usize>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

fn index_mut(
    &mut self,
    RangeTo { end: end }: RangeTo<usize>
) -> &mut Self::Output

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

impl<C, T> IndexMut<RangeToInclusive<usize>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

fn index_mut(
    &mut self,
    RangeToInclusive { end: end }: RangeToInclusive<usize>
) -> &mut Self::Output

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

impl<C, T> Display for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Prints the BitVec for displaying.

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

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

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

fn fmt(&self, f: &mut Formatter) -> Result

Renders the BitVec contents for display.

Examples

use bitvec::*;

let bv = bitvec![BigEndian, u8; 0, 1, 0, 0, 1, 0, 1, 1, 0, 1];
assert_eq!("[01001011, 01]", &format!("{}", bv));

impl<C, T> Borrow<BitSlice<C, T>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Signifies that BitSlice is the borrowed form of BitVec.

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

Borrows the BitVec as a BitSlice.

Parameters

• &self

Returns

A borrowed BitSlice of the vector.

Examples

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

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

impl<C, T> Write for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

default fn write_vectored(&mut self, bufs: &[IoVec]) -> Result<usize, Error>

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

Like write, except that it writes from a slice of buffers.

default fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

default fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

default fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Write.

impl<C, T> BorrowMut<BitSlice<C, T>> for BitVec<C, T> where
    C: Cursor,
    T: Bits, 

Signifies that BitSlice is the borrowed form of BitVec.

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

Mutably borrows the BitVec as a BitSlice.

Parameters

• &mut self

Returns

A mutably borrowed BitSlice of the vector.

Examples

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

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