Struct bitvec::array::BitArray

source ·

#[repr(transparent)]
pub struct BitArray<A = [usize; 1], O = Lsb0>where
    A: BitViewSized,
    O: BitOrder,{
    pub _ord: PhantomData<O>,
    pub data: A,
}

Expand description

Bit-Precision Array Immediate

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.

Original

[T; N]

Usage

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.

Type Parameters

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.

Future API Changes

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.

Large Bit-Arrays

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.

Examples

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]
  }
}

Fields§

§_ord: PhantomData<O>

The ordering of bits within an A::Store element.

§data: A

The wrapped data buffer.

Struct bitvec::array::BitArray

Fields§

Implementations§

impl<A, O> BitArray<A, O>where A: BitViewSized, O: BitOrder,

pub fn as_slice(&self) -> &BitSlice<A::Store, O> ⓘ

pub fn as_mut_slice(&mut self) -> &mut BitSlice<A::Store, O> ⓘ

impl<A, O> BitArray<A, O>where A: BitViewSized, O: BitOrder,

pub const ZERO: Self = _

pub fn new(data: A) -> Self

pub fn into_inner(self) -> A

pub fn as_bitslice(&self) -> &BitSlice<A::Store, O> ⓘ

pub fn as_mut_bitslice(&mut self) -> &mut BitSlice<A::Store, O> ⓘ

pub fn as_raw_slice(&self) -> &[A::Store]

pub fn as_raw_mut_slice(&mut self) -> &mut [A::Store]

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

Methods from Deref<Target = BitSlice<A::Store, O>>§

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

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

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

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

pub fn split_first_mut( &mut self ) -> Option<(BitRef<'_, Mut, T::Alias, O>, &mut BitSlice<T::Alias, O>)>

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

pub fn split_last_mut( &mut self ) -> Option<(BitRef<'_, Mut, T::Alias, O>, &mut BitSlice<T::Alias, O>)>

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

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

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

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

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

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

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

pub fn as_mut_ptr(&mut self) -> BitPtr<Mut, T, O>

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

pub fn as_mut_ptr_range(&mut self) -> Range<BitPtr<Mut, T, O>>

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

pub fn reverse(&mut self)

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

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

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

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

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

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

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

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

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

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