/rust/registry/src/index.crates.io-1949cf8c6b5b557f/bitvec-1.0.1/src/slice.rs

Source
#![doc = include_str!("../doc/slice.md")]

#[cfg(feature = "alloc")]
use alloc::vec::Vec;
use core::{
  marker::PhantomData,
  ops::RangeBounds,
};

use funty::Integral;
use tap::Pipe;
#[cfg(feature = "alloc")]
use tap::Tap;
use wyz::{
  bidi::BidiIterator,
  comu::{
    Const,
    Mut,
  },
  range::RangeExt,
};

#[cfg(feature = "alloc")]
use crate::vec::BitVec;
use crate::{
  domain::{
    BitDomain,
    Domain,
  },
  mem,
  order::{
    BitOrder,
    Lsb0,
    Msb0,
  },
  ptr::{
    self as bv_ptr,
    BitPtr,
    BitPtrRange,
    BitSpan,
    BitSpanError,
  },
  store::BitStore,
};

mod api;
mod iter;
mod ops;
mod specialization;
mod tests;
mod traits;

pub use self::{
  api::*,
  iter::*,
};

#[repr(transparent)]
#[doc = include_str!("../doc/slice/BitSlice.md")]
pub struct BitSlice<T = usize, O = Lsb0>
where
  T: BitStore,
  O: BitOrder,
{
  /// The ordering of bits within a `T` register.
  _ord: PhantomData<O>,
  /// The register type used for storage.
  _typ: PhantomData<[T]>,
  /// Indicate that this is a newtype wrapper over a wholly-untyped slice.
  ///
  /// This is necessary in order for the Rust compiler to remove restrictions
  /// on the possible values of reference handles to this type. Any other
  /// slice type here (such as `[u8]` or `[T]`) would require that `&/mut
  /// BitSlice` handles have values that correctly describe the region, and
  /// the encoding *does not* do this. As such, reference handles to
  /// `BitSlice` must not be even implicitly dereferenceäble to real memory,
  /// and the slice must be a ZST.
  ///
  /// References to a ZST have no restrictions about what the values can be,
  /// as they are never able to dereference real memory and thus both
  /// addresses and lengths are meaningless to the memory inspector.
  ///
  /// See `ptr::span` for more information on the encoding scheme used in
  /// references to `BitSlice`.
  _mem: [()],
}

/// Constructors.
impl<T, O> BitSlice<T, O>
where
  T: BitStore,
  O: BitOrder,
{
  /// Produces an empty bit-slice with an arbitrary lifetime.
  ///
  /// ## Original
  ///
  /// This is equivalent to the `&[]` literal.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// assert!(BitSlice::<u16, LocalBits>::empty().is_empty());
  /// assert_eq!(bits![], BitSlice::<u8, Msb0>::empty());
  /// ```
  #[inline]
  pub fn empty<'a>() -> &'a Self {
    unsafe { BitSpan::<Const, T, O>::EMPTY.into_bitslice_ref() }
  }

  /// Produces an empty bit-slice with an arbitrary lifetime.
  ///
  /// ## Original
  ///
  /// This is equivalent to the `&mut []` literal.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// assert!(BitSlice::<u16, LocalBits>::empty_mut().is_empty());
  /// assert_eq!(bits![mut], BitSlice::<u8, Msb0>::empty_mut());
  /// ```
  #[inline]
  pub fn empty_mut<'a>() -> &'a mut Self {
    unsafe { BitSpan::<Mut, T, O>::EMPTY.into_bitslice_mut() }
  }

  /// Constructs a shared `&BitSlice` reference over a shared element.
  ///
  /// The [`BitView`] trait, implemented on all [`BitStore`] implementors,
  /// provides a [`.view_bits::<O>()`] method which delegates to this function
  /// and may be more convenient for you to write.
  ///
  /// ## Parameters
  ///
  /// - `elem`: A shared reference to a memory element.
  ///
  /// ## Returns
  ///
  /// A shared `&BitSlice` over `elem`.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// let elem = 0u8;
  /// let bits = BitSlice::<_, Lsb0>::from_element(&elem);
  /// assert_eq!(bits.len(), 8);
  ///
  /// let bits = elem.view_bits::<Lsb0>();
  /// ```
  ///
  /// [`BitStore`]: crate::store::BitStore
  /// [`BitView`]: crate::view::BitView
  /// [`.view_bits::<O>()`]: crate::view::BitView::view_bits
  #[inline]
  pub fn from_element(elem: &T) -> &Self {
    unsafe {
      BitPtr::from_ref(elem)
        .span_unchecked(mem::bits_of::<T::Mem>())
        .into_bitslice_ref()
    }
  }

  /// Constructs an exclusive `&mut BitSlice` reference over an element.
  ///
  /// The [`BitView`] trait, implemented on all [`BitStore`] implementors,
  /// provides a [`.view_bits_mut::<O>()`] method which delegates to this
  /// function and may be more convenient for you to write.
  ///
  /// ## Parameters
  ///
  /// - `elem`: An exclusive reference to a memory element.
  ///
  /// ## Returns
  ///
  /// An exclusive `&mut BitSlice` over `elem`.
  ///
  /// Note that the original `elem` reference will be inaccessible for the
  /// duration of the returned bit-slice handle’s lifetime.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// let mut elem = 0u8;
  /// let bits = BitSlice::<_, Lsb0>::from_element_mut(&mut elem);
  /// bits.set(1, true);
  /// assert!(bits[1]);
  /// assert_eq!(elem, 2);
  ///
  /// let bits = elem.view_bits_mut::<Lsb0>();
  /// ```
  ///
  /// [`BitStore`]: crate::store::BitStore
  /// [`BitView`]: crate::view::BitView
  /// [`.view_bits_mut::<O>()`]: crate::view::BitView::view_bits_mut
  #[inline]
  pub fn from_element_mut(elem: &mut T) -> &mut Self {
    unsafe {
      BitPtr::from_mut(elem)
        .span_unchecked(mem::bits_of::<T::Mem>())
        .into_bitslice_mut()
    }
  }

  /// Constructs a shared `&BitSlice` reference over a slice of elements.
  ///
  /// The [`BitView`] trait, implemented on all `[T]` slices, provides a
  /// [`.view_bits::<O>()`] method which delegates to this function and may be
  /// more convenient for you to write.
  ///
  /// ## Parameters
  ///
  /// - `slice`: A shared reference to a slice of memory elements.
  ///
  /// ## Returns
  ///
  /// A shared `BitSlice` reference over all of `slice`.
  ///
  /// ## Panics
  ///
  /// This will panic if `slice` is too long to encode as a bit-slice view.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// let data = [0u16, 1];
  /// let bits = BitSlice::<_, Lsb0>::from_slice(&data);
  /// assert!(bits[16]);
  ///
  /// let bits = data.view_bits::<Lsb0>();
  /// ```
  ///
  /// [`BitView`]: crate::view::BitView
  /// [`.view_bits::<O>()`]: crate::view::BitView::view_bits
  #[inline]
  pub fn from_slice(slice: &[T]) -> &Self {
    Self::try_from_slice(slice).unwrap()
  }

  /// Attempts to construct a shared `&BitSlice` reference over a slice of
  /// elements.
  ///
  /// The [`BitView`], implemented on all `[T]` slices, provides a
  /// [`.try_view_bits::<O>()`] method which delegates to this function and
  /// may be more convenient for you to write.
  ///
  /// This is *very hard*, if not impossible, to cause to fail. Rust will not
  /// create excessive arrays on 64-bit architectures.
  ///
  /// ## Parameters
  ///
  /// - `slice`: A shared reference to a slice of memory elements.
  ///
  /// ## Returns
  ///
  /// A shared `&BitSlice` over `slice`. If `slice` is longer than can be
  /// encoded into a `&BitSlice` (see [`MAX_ELTS`]), this will fail and return
  /// the original `slice` as an error.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// let data = [0u8, 1];
  /// let bits = BitSlice::<_, Msb0>::try_from_slice(&data).unwrap();
  /// assert!(bits[15]);
  ///
  /// let bits = data.try_view_bits::<Msb0>().unwrap();
  /// ```
  ///
  /// [`BitView`]: crate::view::BitView
  /// [`MAX_ELTS`]: Self::MAX_ELTS
  /// [`.try_view_bits::<O>()`]: crate::view::BitView::try_view_bits
  #[inline]
  pub fn try_from_slice(slice: &[T]) -> Result<&Self, BitSpanError<T>> {
    let elts = slice.len();
    if elts >= Self::MAX_ELTS {
      elts.saturating_mul(mem::bits_of::<T::Mem>())
        .pipe(BitSpanError::TooLong)
        .pipe(Err)
    }
    else {
      Ok(unsafe { Self::from_slice_unchecked(slice) })
    }
  }

  /// Constructs an exclusive `&mut BitSlice` reference over a slice of
  /// elements.
  ///
  /// The [`BitView`] trait, implemented on all `[T]` slices, provides a
  /// [`.view_bits_mut::<O>()`] method which delegates to this function and
  /// may be more convenient for you to write.
  ///
  /// ## Parameters
  ///
  /// - `slice`: An exclusive reference to a slice of memory elements.
  ///
  /// ## Returns
  ///
  /// An exclusive `&mut BitSlice` over all of `slice`.
  ///
  /// ## Panics
  ///
  /// This panics if `slice` is too long to encode as a bit-slice view.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// let mut data = [0u16; 2];
  /// let bits = BitSlice::<_, Lsb0>::from_slice_mut(&mut data);
  /// bits.set(0, true);
  /// bits.set(17, true);
  /// assert_eq!(data, [1, 2]);
  ///
  /// let bits = data.view_bits_mut::<Lsb0>();
  /// ```
  ///
  /// [`BitView`]: crate::view::BitView
  /// [`.view_bits_mut::<O>()`]: crate::view::BitView::view_bits_mut
  #[inline]
  pub fn from_slice_mut(slice: &mut [T]) -> &mut Self {
    Self::try_from_slice_mut(slice).unwrap()
  }

  /// Attempts to construct an exclusive `&mut BitSlice` reference over a
  /// slice of elements.
  ///
  /// The [`BitView`] trait, implemented on all `[T]` slices, provides a
  /// [`.try_view_bits_mut::<O>()`] method which delegates to this function
  /// and may be more convenient for you to write.
  ///
  /// ## Parameters
  ///
  /// - `slice`: An exclusive reference to a slice of memory elements.
  ///
  /// ## Returns
  ///
  /// An exclusive `&mut BitSlice` over `slice`. If `slice` is longer than can
  /// be encoded into a `&mut BitSlice` (see [`MAX_ELTS`]), this will fail and
  /// return the original `slice` as an error.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// let mut data = [0u8; 2];
  /// let bits = BitSlice::<_, Msb0>::try_from_slice_mut(&mut data).unwrap();
  /// bits.set(7, true);
  /// bits.set(15, true);
  /// assert_eq!(data, [1; 2]);
  ///
  /// let bits = data.try_view_bits_mut::<Msb0>().unwrap();
  /// ```
  ///
  /// [`BitView`]: crate::view::BitView
  /// [`MAX_ELTS`]: Self::MAX_ELTS
  /// [`.try_view_bits_mut::<O>()`]: crate::view::BitView::try_view_bits_mut
  #[inline]
  pub fn try_from_slice_mut(
    slice: &mut [T],
  ) -> Result<&mut Self, BitSpanError<T>> {
    let elts = slice.len();
    if elts >= Self::MAX_ELTS {
      elts.saturating_mul(mem::bits_of::<T::Mem>())
        .pipe(BitSpanError::TooLong)
        .pipe(Err)
    }
    else {
      Ok(unsafe { Self::from_slice_unchecked_mut(slice) })
    }
  }

  /// Constructs a shared `&BitSlice` over an element slice, without checking
  /// its length.
  ///
  /// If `slice` is too long to encode into a `&BitSlice`, then the produced
  /// bit-slice’s length is unspecified.
  ///
  /// ## Safety
  ///
  /// You must ensure that `slice.len() < BitSlice::MAX_ELTS`.
  ///
  /// Calling this function with an over-long slice is **library-level**
  /// undefined behavior. You may not assume anything about its implementation
  /// or behavior, and must conservatively assume that over-long slices cause
  /// compiler UB.
  #[inline]
  pub unsafe fn from_slice_unchecked(slice: &[T]) -> &Self {
    let bits = slice.len().wrapping_mul(mem::bits_of::<T::Mem>());
    BitPtr::from_slice(slice)
      .span_unchecked(bits)
      .into_bitslice_ref()
  }

  /// Constructs an exclusive `&mut BitSlice` over an element slice, without
  /// checking its length.
  ///
  /// If `slice` is too long to encode into a `&mut BitSlice`, then the
  /// produced bit-slice’s length is unspecified.
  ///
  /// ## Safety
  ///
  /// You must ensure that `slice.len() < BitSlice::MAX_ELTS`.
  ///
  /// Calling this function with an over-long slice is **library-level**
  /// undefined behavior. You may not assume anything about its implementation
  /// or behavior, and must conservatively assume that over-long slices cause
  /// compiler UB.
  #[inline]
  pub unsafe fn from_slice_unchecked_mut(slice: &mut [T]) -> &mut Self {
    let bits = slice.len().wrapping_mul(mem::bits_of::<T::Mem>());
    BitPtr::from_slice_mut(slice)
      .span_unchecked(bits)
      .into_bitslice_mut()
  }
}

/// Alternates of standard APIs.
impl<T, O> BitSlice<T, O>
where
  T: BitStore,
  O: BitOrder,
{
  /// Gets a raw pointer to the zeroth bit of the bit-slice.
  ///
  /// ## Original
  ///
  /// [`slice::as_ptr`](https://doc.rust-lang.org/std/primitive.slice.html#method.as_ptr)
  ///
  /// ## API Differences
  ///
  /// This is renamed in order to indicate that it is returning a `bitvec`
  /// structure, not a raw pointer.
  #[inline]
  pub fn as_bitptr(&self) -> BitPtr<Const, T, O> {
    self.as_bitspan().to_bitptr()
  }

  /// Gets a raw, write-capable pointer to the zeroth bit of the bit-slice.
  ///
  /// ## Original
  ///
  /// [`slice::as_mut_ptr`](https://doc.rust-lang.org/std/primitive.slice.html#method.as_mut_ptr)
  ///
  /// ## API Differences
  ///
  /// This is renamed in order to indicate that it is returning a `bitvec`
  /// structure, not a raw pointer.
  #[inline]
  pub fn as_mut_bitptr(&mut self) -> BitPtr<Mut, T, O> {
    self.as_mut_bitspan().to_bitptr()
  }

  /// Views the bit-slice as a half-open range of bit-pointers, to its first
  /// bit *in* the bit-slice and first bit *beyond* it.
  ///
  /// ## Original
  ///
  /// [`slice::as_ptr_range`](https://doc.rust-lang.org/std/primitive.slice.html#method.as_ptr_range)
  ///
  /// ## API Differences
  ///
  /// This is renamed to indicate that it returns a `bitvec` structure, rather
  /// than an ordinary `Range`.
  ///
  /// ## Notes
  ///
  /// `BitSlice` does define a [`.as_ptr_range()`], which returns a
  /// `Range<BitPtr>`. `BitPtrRange` has additional capabilities that
  /// `Range<*const T>` and `Range<BitPtr>` do not.
  ///
  /// [`.as_ptr_range()`]: Self::as_ptr_range
  #[inline]
  pub fn as_bitptr_range(&self) -> BitPtrRange<Const, T, O> {
    self.as_bitspan().to_bitptr_range()
  }

  /// 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.
  ///
  /// ## Original
  ///
  /// [`slice::as_mut_ptr_range`](https://doc.rust-lang.org/std/primitive.slice.html#method.as_mut_ptr_range)
  ///
  /// ## API Differences
  ///
  /// This is renamed to indicate that it returns a `bitvec` structure, rather
  /// than an ordinary `Range`.
  ///
  /// ## Notes
  ///
  /// `BitSlice` does define a [`.as_mut_ptr_range()`], which returns a
  /// `Range<BitPtr>`. `BitPtrRange` has additional capabilities that
  /// `Range<*mut T>` and `Range<BitPtr>` do not.
  #[inline]
  pub fn as_mut_bitptr_range(&mut self) -> BitPtrRange<Mut, T, O> {
    self.as_mut_bitspan().to_bitptr_range()
  }

  /// Copies the bits from `src` into `self`.
  ///
  /// `self` and `src` must have the same length.
  ///
  /// ## Performance
  ///
  /// 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.
  ///
  /// ## Original
  ///
  /// [`slice::clone_from_slice`](https://doc.rust-lang.org/std/primitive.slice.html#method.clone_from_slice)
  ///
  /// ## API Differences
  ///
  /// 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.
  ///
  /// ## Panics
  ///
  /// This panics if the two bit-slices have different lengths.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  /// ```
  ///
  /// [`.copy_from_bitslice()`]: Self::copy_from_bitslice
  #[inline]
  pub fn clone_from_bitslice<T2, O2>(&mut self, src: &BitSlice<T2, O2>)
  where
    T2: BitStore,
    O2: BitOrder,
  {
    assert_eq!(
      self.len(),
      src.len(),
      "cloning between bit-slices requires equal lengths",
    );

    if let Some(that) = src.coerce::<T, O>() {
      self.copy_from_bitslice(that);
    }
    //  TODO(myrrlyn): Test if `<T::Mem, O>` matches `<T2::Mem, O>` and
    //  specialize cloning.
    else {
      for (to, bit) in self.as_mut_bitptr_range().zip(src.iter().by_vals())
      {
        unsafe {
          to.write(bit);
        }
      }
    }
  }

  /// Copies all bits from `src` into `self`, using batched acceleration when
  /// possible.
  ///
  /// `self` and `src` must have the same length.
  ///
  /// ## Original
  ///
  /// [`slice::copy_from_slice`](https://doc.rust-lang.org/std/primitive.slice.html#method.copy_from_slice)
  ///
  /// ## Panics
  ///
  /// This panics if the two bit-slices have different lengths.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  /// ```
  #[inline]
  pub fn copy_from_bitslice(&mut self, src: &Self) {
    assert_eq!(
      self.len(),
      src.len(),
      "copying between bit-slices requires equal lengths",
    );

    let (to_head, from_head) =
      (self.as_bitspan().head(), src.as_bitspan().head());
    if to_head == from_head {
      match (self.domain_mut(), src.domain()) {
        (Domain::Enclave(mut to), Domain::Enclave(from)) => {
          to.store_value(from.load_value());
        },
        (
          Domain::Region {
            head: to_head,
            body: to_body,
            tail: to_tail,
          },
          Domain::Region {
            head: from_head,
            body: from_body,
            tail: from_tail,
          },
        ) => {
          if let (Some(mut to), Some(from)) = (to_head, from_head) {
            to.store_value(from.load_value());
          }
          for (to, from) in to_body.iter_mut().zip(from_body) {
            to.store_value(from.load_value());
          }
          if let (Some(mut to), Some(from)) = (to_tail, from_tail) {
            to.store_value(from.load_value());
          }
        },
        _ => unreachable!(
          "bit-slices with equal type parameters, lengths, and heads \
           will always have equal domains"
        ),
      }
    }
    if let (Some(this), Some(that)) =
      (self.coerce_mut::<T, Lsb0>(), src.coerce::<T, Lsb0>())
    {
      return this.sp_copy_from_bitslice(that);
    }
    if let (Some(this), Some(that)) =
      (self.coerce_mut::<T, Msb0>(), src.coerce::<T, Msb0>())
    {
      return this.sp_copy_from_bitslice(that);
    }
    for (to, bit) in self.as_mut_bitptr_range().zip(src.iter().by_vals()) {
      unsafe {
        to.write(bit);
      }
    }
  }

  /// Swaps the contents of two bit-slices.
  ///
  /// `self` and `other` must have the same length.
  ///
  /// ## Original
  ///
  /// [`slice::swap_with_slice`](https://doc.rust-lang.org/std/primitive.slice.html#method.swap_with_slice)
  ///
  /// ## API Differences
  ///
  /// This method is renamed, as it takes a bit-slice rather than an element
  /// slice.
  ///
  /// ## Panics
  ///
  /// This panics if the two bit-slices have different lengths.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// 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]);
  /// # if cfg!(target_endian = "little") {
  /// assert_eq!(two, 0x96A5);
  /// # }
  /// ```
  #[inline]
  pub fn swap_with_bitslice<T2, O2>(&mut self, other: &mut BitSlice<T2, O2>)
  where
    T2: BitStore,
    O2: BitOrder,
  {
    assert_eq!(
      self.len(),
      other.len(),
      "swapping between bit-slices requires equal lengths",
    );

    if let (Some(this), Some(that)) =
      (self.coerce_mut::<T, Lsb0>(), other.coerce_mut::<T, Lsb0>())
    {
      return this.sp_swap_with_bitslice(that);
    }
    if let (Some(this), Some(that)) =
      (self.coerce_mut::<T, Msb0>(), other.coerce_mut::<T, Msb0>())
    {
      return this.sp_swap_with_bitslice(that);
    }
    self.as_mut_bitptr_range()
      .zip(other.as_mut_bitptr_range())
      .for_each(|(a, b)| unsafe {
        bv_ptr::swap(a, b);
      });
  }
}

/// Extensions of standard APIs.
impl<T, O> BitSlice<T, O>
where
  T: BitStore,
  O: BitOrder,
{
  /// 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.
  ///
  /// ## Parameters
  ///
  /// - `&mut self`
  /// - `index`: The bit-index to set. It must be in `0 .. self.len()`.
  /// - `value`: The new bit-value to write into the bit at `index`.
  ///
  /// ## Panics
  ///
  /// This panics if `index` is out of bounds.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// let bits = bits![mut 0, 1];
  /// bits.set(0, true);
  /// bits.set(1, false);
  ///
  /// assert_eq!(bits, bits![1, 0]);
  /// ```
  #[inline]
  pub fn set(&mut self, index: usize, value: bool) {
    self.replace(index, value);
  }

  /// Writes a new value into a single bit, without bounds checking.
  ///
  /// ## Parameters
  ///
  /// - `&mut self`
  /// - `index`: The bit-index to set. It must be in `0 .. self.len()`.
  /// - `value`: The new bit-value to write into the bit at `index`.
  ///
  /// ## Safety
  ///
  /// 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.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// 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);
  /// ```
  #[inline]
  pub unsafe fn set_unchecked(&mut self, index: usize, value: bool) {
    self.replace_unchecked(index, value);
  }

  /// Writes a new value into a bit, and returns its previous value.
  ///
  /// ## Panics
  ///
  /// This panics if `index` is not less than `self.len()`.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// let bits = bits![mut 0];
  /// assert!(!bits.replace(0, true));
  /// assert!(bits[0]);
  /// ```
  #[inline]
  pub fn replace(&mut self, index: usize, value: bool) -> bool {
    self.assert_in_bounds(index, 0 .. self.len());
    unsafe { self.replace_unchecked(index, value) }
  }

  /// Writes a new value into a bit, returning the previous value, without
  /// bounds checking.
  ///
  /// ## Safety
  ///
  /// `index` must be less than `self.len()`.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// 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]);
  /// ```
  #[inline]
  pub unsafe fn replace_unchecked(
    &mut self,
    index: usize,
    value: bool,
  ) -> bool {
    self.as_mut_bitptr().add(index).replace(value)
  }

  /// Swaps two bits in a bit-slice, without bounds checking.
  ///
  /// See [`.swap()`] for documentation.
  ///
  /// ## Safety
  ///
  /// 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.
  ///
  /// [`.swap()`]: Self::swap
  #[inline]
  pub unsafe fn swap_unchecked(&mut self, a: usize, b: usize) {
    let a = self.as_mut_bitptr().add(a);
    let b = self.as_mut_bitptr().add(b);
    bv_ptr::swap(a, b);
  }

  /// Splits a bit-slice at an index, without bounds checking.
  ///
  /// See [`.split_at()`] for documentation.
  ///
  /// ## Safety
  ///
  /// You must ensure that `mid` is in the range `0 ..= self.len()`.
  ///
  /// This method produces new bit-slice references. If `mid` is out of
  /// bounds, its behavior is **library-level** undefined. You must
  /// conservatively assume that an out-of-bounds split point produces
  /// compiler-level UB.
  ///
  /// [`.split_at()`]: Self::split_at
  #[inline]
  pub unsafe fn split_at_unchecked(&self, mid: usize) -> (&Self, &Self) {
    let len = self.len();
    let left = self.as_bitptr();
    let right = left.add(mid);
    let left = left.span_unchecked(mid);
    let right = right.span_unchecked(len - mid);
    let left = left.into_bitslice_ref();
    let right = right.into_bitslice_ref();
    (left, right)
  }

  /// Splits a mutable bit-slice at an index, without bounds checking.
  ///
  /// See [`.split_at_mut()`] for documentation.
  ///
  /// ## Safety
  ///
  /// You must ensure that `mid` is in the range `0 ..= self.len()`.
  ///
  /// This method produces new bit-slice references. If `mid` is out of
  /// bounds, its behavior is **library-level** undefined. You must
  /// conservatively assume that an out-of-bounds split point produces
  /// compiler-level UB.
  ///
  /// [`.split_at_mut()`]: Self::split_at_mut
  #[inline]
  pub unsafe fn split_at_unchecked_mut(
    &mut self,
    mid: usize,
  ) -> (&mut BitSlice<T::Alias, O>, &mut BitSlice<T::Alias, O>) {
    let len = self.len();
    let left = self.alias_mut().as_mut_bitptr();
    let right = left.add(mid);
    (
      left.span_unchecked(mid).into_bitslice_mut(),
      right.span_unchecked(len - mid).into_bitslice_mut(),
    )
  }

  /// Copies bits from one region of the bit-slice to another region of
  /// itself, without doing bounds checks.
  ///
  /// The regions are allowed to overlap.
  ///
  /// ## Parameters
  ///
  /// - `&mut self`
  /// - `src`: The range within `self` from which to copy.
  /// - `dst`: The starting index within `self` at which to paste.
  ///
  /// ## Effects
  ///
  /// `self[src]` is copied to `self[dest .. dest + src.len()]`. The bits of
  /// `self[src]` are in an unspecified, but initialized, state.
  ///
  /// ## Safety
  ///
  /// `src.end()` and `dest + src.len()` must be entirely within bounds.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// 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);
  /// ```
  #[inline]
  pub unsafe fn copy_within_unchecked<R>(&mut self, src: R, dest: usize)
  where R: RangeExt<usize> {
    if let Some(this) = self.coerce_mut::<T, Lsb0>() {
      return this.sp_copy_within_unchecked(src, dest);
    }
    if let Some(this) = self.coerce_mut::<T, Msb0>() {
      return this.sp_copy_within_unchecked(src, dest);
    }
    let source = src.normalize(0, self.len());
    let source_len = source.len();
    let rev = source.contains(&dest);
    let dest = dest .. dest + source_len;
    for (from, to) in self
      .get_unchecked(source)
      .as_bitptr_range()
      .zip(self.get_unchecked_mut(dest).as_mut_bitptr_range())
      .bidi(rev)
    {
      to.write(from.read());
    }
  }

  #[inline]
  #[doc(hidden)]
  #[cfg(not(tarpaulin_include))]
  #[deprecated = "use `.iter_mut().enumerate()`"]
  pub fn for_each(&mut self, mut func: impl FnMut(usize, bool) -> bool) {
    for (idx, ptr) in self.as_mut_bitptr_range().enumerate() {
      unsafe {
        ptr.write(func(idx, ptr.read()));
      }
    }
  }
}

/// Views of underlying memory.
impl<T, O> BitSlice<T, O>
where
  T: BitStore,
  O: BitOrder,
{
  /// 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.
  #[inline]
  #[cfg(not(tarpaulin_include))]
  pub fn bit_domain(&self) -> BitDomain<Const, T, O> {
    self.domain().into_bit_domain()
  }

  /// 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.
  #[inline]
  #[cfg(not(tarpaulin_include))]
  pub fn bit_domain_mut(&mut self) -> BitDomain<Mut, T, O> {
    self.domain_mut().into_bit_domain()
  }

  /// 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.
  #[inline]
  #[cfg(not(tarpaulin_include))]
  pub fn domain(&self) -> Domain<Const, T, O> {
    Domain::new(self)
  }

  /// 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.
  #[inline]
  #[cfg(not(tarpaulin_include))]
  pub fn domain_mut(&mut self) -> Domain<Mut, T, O> {
    Domain::new(self)
  }
}

/// Bit-value queries.
impl<T, O> BitSlice<T, O>
where
  T: BitStore,
  O: BitOrder,
{
  /// Counts the number of bits set to `1` in the bit-slice contents.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// 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);
  /// ```
  #[inline]
  pub fn count_ones(&self) -> usize {
    match self.domain() {
      Domain::Enclave(elem) => elem.load_value().count_ones() as usize,
      Domain::Region { head, body, tail } => {
        head.map_or(0, |elem| elem.load_value().count_ones() as usize)
          + body
            .iter()
            .map(BitStore::load_value)
            .map(|elem| elem.count_ones() as usize)
            .sum::<usize>() + tail
          .map_or(0, |elem| elem.load_value().count_ones() as usize)
      },
    }
  }

  /// Counts the number of bits cleared to `0` in the bit-slice contents.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// 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);
  /// ```
  #[inline]
  pub fn count_zeros(&self) -> usize {
    match self.domain() {
      Domain::Enclave(elem) => (elem.load_value()
        | !elem.mask().into_inner())
      .count_zeros() as usize,
      Domain::Region { head, body, tail } => {
        head.map_or(0, |elem| {
          (elem.load_value() | !elem.mask().into_inner()).count_zeros()
            as usize
        }) + body
          .iter()
          .map(BitStore::load_value)
          .map(|elem| elem.count_zeros() as usize)
          .sum::<usize>() + tail.map_or(0, |elem| {
          (elem.load_value() | !elem.mask().into_inner()).count_zeros()
            as usize
        })
      },
    }
  }

  /// Enumerates the index of each bit in a bit-slice set to `1`.
  ///
  /// This is a shorthand for a `.enumerate().filter_map()` iterator that
  /// selects the index of each `true` bit; however, its implementation is
  /// eligible for optimizations that the individual-bit iterator is not.
  ///
  /// Specializations for the `Lsb0` and `Msb0` orderings allow processors
  /// with instructions that seek particular bits within an element to operate
  /// on whole elements, rather than on each bit individually.
  ///
  /// ## Examples
  ///
  /// This example uses `.iter_ones()`, a `.filter_map()` that finds the index
  /// of each set bit, and the known indices, in order to show that they have
  /// equivalent behavior.
  ///
  /// ```rust
  /// 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);
  /// }
  /// ```
  #[inline]
  pub fn iter_ones(&self) -> IterOnes<T, O> {
    IterOnes::new(self)
  }

  /// Enumerates the index of each bit in a bit-slice cleared to `0`.
  ///
  /// This is a shorthand for a `.enumerate().filter_map()` iterator that
  /// selects the index of each `false` bit; however, its implementation is
  /// eligible for optimizations that the individual-bit iterator is not.
  ///
  /// Specializations for the `Lsb0` and `Msb0` orderings allow processors
  /// with instructions that seek particular bits within an element to operate
  /// on whole elements, rather than on each bit individually.
  ///
  /// ## Examples
  ///
  /// This example uses `.iter_zeros()`, a `.filter_map()` that finds the
  /// index of each cleared bit, and the known indices, in order to show that
  /// they have equivalent behavior.
  ///
  /// ```rust
  /// 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);
  /// }
  /// ```
  #[inline]
  pub fn iter_zeros(&self) -> IterZeros<T, O> {
    IterZeros::new(self)
  }

  /// Finds the index of the first bit in the bit-slice set to `1`.
  ///
  /// Returns `None` if there is no `true` bit in the bit-slice.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// 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));
  /// ```
  #[inline]
  pub fn first_one(&self) -> Option<usize> {
    self.iter_ones().next()
  }

  /// Finds the index of the first bit in the bit-slice cleared to `0`.
  ///
  /// Returns `None` if there is no `false` bit in the bit-slice.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// 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));
  /// ```
  #[inline]
  pub fn first_zero(&self) -> Option<usize> {
    self.iter_zeros().next()
  }

  /// Finds the index of the last bit in the bit-slice set to `1`.
  ///
  /// Returns `None` if there is no `true` bit in the bit-slice.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// 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));
  /// ```
  #[inline]
  pub fn last_one(&self) -> Option<usize> {
    self.iter_ones().next_back()
  }

  /// Finds the index of the last bit in the bit-slice cleared to `0`.
  ///
  /// Returns `None` if there is no `false` bit in the bit-slice.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// 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));
  /// ```
  #[inline]
  pub fn last_zero(&self) -> Option<usize> {
    self.iter_zeros().next_back()
  }

  /// Counts the number of bits from the start of the bit-slice to the first
  /// bit set to `0`.
  ///
  /// This returns `0` if the bit-slice is empty.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// assert_eq!(bits![].leading_ones(), 0);
  /// assert_eq!(bits![0].leading_ones(), 0);
  /// assert_eq!(bits![1, 0].leading_ones(), 1);
  /// ```
  #[inline]
  pub fn leading_ones(&self) -> usize {
    self.first_zero().unwrap_or_else(|| self.len())
  }

  /// Counts the number of bits from the start of the bit-slice to the first
  /// bit set to `1`.
  ///
  /// This returns `0` if the bit-slice is empty.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// assert_eq!(bits![].leading_zeros(), 0);
  /// assert_eq!(bits![1].leading_zeros(), 0);
  /// assert_eq!(bits![0, 1].leading_zeros(), 1);
  /// ```
  #[inline]
  pub fn leading_zeros(&self) -> usize {
    self.first_one().unwrap_or_else(|| self.len())
  }

  /// Counts the number of bits from the end of the bit-slice to the last bit
  /// set to `0`.
  ///
  /// This returns `0` if the bit-slice is empty.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// assert_eq!(bits![].trailing_ones(), 0);
  /// assert_eq!(bits![0].trailing_ones(), 0);
  /// assert_eq!(bits![0, 1].trailing_ones(), 1);
  /// ```
  #[inline]
  pub fn trailing_ones(&self) -> usize {
    let len = self.len();
    self.last_zero().map(|idx| len - 1 - idx).unwrap_or(len)
  }

  /// Counts the number of bits from the end of the bit-slice to the last bit
  /// set to `1`.
  ///
  /// This returns `0` if the bit-slice is empty.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// assert_eq!(bits![].trailing_zeros(), 0);
  /// assert_eq!(bits![1].trailing_zeros(), 0);
  /// assert_eq!(bits![1, 0].trailing_zeros(), 1);
  /// ```
  #[inline]
  pub fn trailing_zeros(&self) -> usize {
    let len = self.len();
    self.last_one().map(|idx| len - 1 - idx).unwrap_or(len)
  }

  /// Tests if there is at least one bit set to `1` in the bit-slice.
  ///
  /// Returns `false` when `self` is empty.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// assert!(!bits![].any());
  /// assert!(!bits![0].any());
  /// assert!(bits![0, 1].any());
  /// ```
  #[inline]
  pub fn any(&self) -> bool {
    self.count_ones() > 0
  }

  /// Tests if every bit is set to `1` in the bit-slice.
  ///
  /// Returns `true` when `self` is empty.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// assert!( bits![].all());
  /// assert!(!bits![0].all());
  /// assert!( bits![1].all());
  /// ```
  #[inline]
  pub fn all(&self) -> bool {
    self.count_zeros() == 0
  }

  /// Tests if every bit is cleared to `0` in the bit-slice.
  ///
  /// Returns `true` when `self` is empty.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// assert!( bits![].not_any());
  /// assert!(!bits![1].not_any());
  /// assert!( bits![0].not_any());
  /// ```
  #[inline]
  pub fn not_any(&self) -> bool {
    self.count_ones() == 0
  }

  /// Tests if at least one bit is cleared to `0` in the bit-slice.
  ///
  /// Returns `false` when `self` is empty.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// assert!(!bits![].not_all());
  /// assert!(!bits![1].not_all());
  /// assert!( bits![0].not_all());
  /// ```
  #[inline]
  pub fn not_all(&self) -> bool {
    self.count_zeros() > 0
  }

  /// Tests if at least one bit is set to `1`, and at least one bit is cleared
  /// to `0`, in the bit-slice.
  ///
  /// Returns `false` when `self` is empty.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// assert!(!bits![].some());
  /// assert!(!bits![0].some());
  /// assert!(!bits![1].some());
  /// assert!( bits![0, 1].some());
  /// ```
  #[inline]
  pub fn some(&self) -> bool {
    self.any() && self.not_all()
  }
}

/// Buffer manipulation.
impl<T, O> BitSlice<T, O>
where
  T: BitStore,
  O: BitOrder,
{
  /// 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`.
  ///
  /// ## Panics
  ///
  /// This panics if `by` is not less than `self.len()`.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// 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]);
  /// ```
  #[inline]
  pub fn shift_left(&mut self, by: usize) {
    if by == 0 {
      return;
    }

    let len = self.len();
    if by == len {
      return self.fill(false);
    }
    assert!(
      by <= len,
      "shift must be less than the length of the bit-slice: {} >= {}",
      by,
      len,
    );

    unsafe {
      self.copy_within_unchecked(by .., 0);
      self.get_unchecked_mut(len - by ..).fill(false);
    }
  }

  /// 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()
  /// - by]`: 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`.
  ///
  /// ## Panics
  ///
  /// This panics if `by` is not less than `self.len()`.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// 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]);
  /// ```
  #[inline]
  pub fn shift_right(&mut self, by: usize) {
    if by == 0 {
      return;
    }

    let len = self.len();
    if by == len {
      return self.fill(false);
    }
    assert!(
      by <= len,
      "shift must be less than the length of the bit-slice: {} >= {}",
      by,
      len,
    );

    unsafe {
      self.copy_within_unchecked(.. len - by, by);
      self.get_unchecked_mut(.. by).fill(false);
    }
  }
}

/// Crate internals.
impl<T, O> BitSlice<T, O>
where
  T: BitStore,
  O: BitOrder,
{
  /// Gets the structural form of the encoded reference.
  pub(crate) fn as_bitspan(&self) -> BitSpan<Const, T, O> {
    BitSpan::from_bitslice_ptr(self)
  }

  /// Gets the structural form of the encoded reference.
  pub(crate) fn as_mut_bitspan(&mut self) -> BitSpan<Mut, T, O> {
    BitSpan::from_bitslice_ptr_mut(self)
  }

  /// Asserts that `index` is within the given bounds.
  ///
  /// ## Parameters
  ///
  /// - `&self`
  /// - `index`: The bit index to test against the bit-slice.
  /// - `bounds`: The bounds to check. cannot exceed `0 ..= self.len()`.
  ///
  /// ## Panics
  ///
  /// This panics if `bounds` is outside `index`.
  pub(crate) fn assert_in_bounds<R>(&self, index: usize, bounds: R)
  where R: RangeExt<usize> {
    let bounds = bounds.normalize(0, self.len());
    assert!(
      bounds.contains(&index),
      "index {} out of range: {:?}",
      index,
      bounds.end_bound()
    );
  }

  /// Marks an exclusive bit-slice as covering an aliased memory region.
  pub(crate) fn alias_mut(&mut self) -> &mut BitSlice<T::Alias, O> {
    unsafe { self.as_mut_bitspan().cast::<T::Alias>().into_bitslice_mut() }
  }

  /// Removes an aliasing marker from an exclusive bit-slice handle.
  ///
  /// ## Safety
  ///
  /// This may only be used when the bit-slice is either known to be
  /// unaliased, or this call is combined with an operation that adds an
  /// aliasing marker and the total number of aliasing markers remains
  /// unchanged.
  pub(crate) unsafe fn unalias_mut(
    this: &mut BitSlice<T::Alias, O>,
  ) -> &mut Self {
    this.as_mut_bitspan().cast::<T>().into_bitslice_mut()
  }

  /// Splits a mutable bit-slice at a midpoint, without either doing bounds
  /// checks or adding an alias marker to the returned sections.
  ///
  /// This method has the same behavior as [`.split_at_unchecked_mut()`],
  /// except that it does not apply an aliasing marker to the partitioned
  /// subslices.
  ///
  /// ## Safety
  ///
  /// See `split_at_unchecked_mut`. Additionally, this is only safe when `T`
  /// is alias-safe.
  ///
  /// [`.split_at_unchecked_mut()`]: Self::split_at_unchecked_mut
  pub(crate) unsafe fn split_at_unchecked_mut_noalias(
    &mut self,
    mid: usize,
  ) -> (&mut Self, &mut Self) {
    //  Split the slice at the requested midpoint, adding an alias layer
    let (head, tail) = self.split_at_unchecked_mut(mid);
    //  Remove the new alias layer.
    (Self::unalias_mut(head), Self::unalias_mut(tail))
  }
}

/// Methods available only when `T` allows shared mutability.
impl<T, O> BitSlice<T, O>
where
  T: BitStore + radium::Radium,
  O: BitOrder,
{
  /// Writes a new value into a single bit, using alias-safe operations.
  ///
  /// This is equivalent to [`.set()`], except that it does not require an
  /// `&mut` reference, and allows bit-slices with alias-safe storage to share
  /// write permissions.
  ///
  /// ## Parameters
  ///
  /// - `&self`: This method only exists on bit-slices with alias-safe
  ///   storage, and so does not require exclusive access.
  /// - `index`: The bit index to set. It must be in `0 .. self.len()`.
  /// - `value`: The new bit-value to write into the bit at `index`.
  ///
  /// ## Panics
  ///
  /// This panics if `index` is out of bounds.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// 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]);
  /// ```
  ///
  /// [`.set()`]: Self::set
  #[inline]
  pub fn set_aliased(&self, index: usize, value: bool) {
    self.assert_in_bounds(index, 0 .. self.len());
    unsafe {
      self.set_aliased_unchecked(index, value);
    }
  }

  /// Writes a new value into a single bit, using alias-safe operations and
  /// without bounds checking.
  ///
  /// This is equivalent to [`.set_unchecked()`], except that it does not
  /// require an `&mut` reference, and allows bit-slices with alias-safe
  /// storage to share write permissions.
  ///
  /// ## Parameters
  ///
  /// - `&self`: This method only exists on bit-slices with alias-safe
  ///   storage, and so does not require exclusive access.
  /// - `index`: The bit index to set. It must be in `0 .. self.len()`.
  /// - `value`: The new bit-value to write into the bit at `index`.
  ///
  /// ## Safety
  ///
  /// The caller must ensure that `index` is not out of bounds.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// 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);
  /// ```
  ///
  /// [`.set_unchecked()`]: Self::set_unchecked
  #[inline]
  pub unsafe fn set_aliased_unchecked(&self, index: usize, value: bool) {
    self.as_bitptr().add(index).freeze().frozen_write_bit(value);
  }
}

/// Miscellaneous information.
impl<T, O> BitSlice<T, O>
where
  T: BitStore,
  O: BitOrder,
{
  /// The inclusive maximum length of a `BitSlice<_, T>`.
  ///
  /// As `BitSlice` is zero-indexed, the largest possible *index* is one less
  /// than this value.
  ///
  /// |CPU word width|         Value         |
  /// |-------------:|----------------------:|
  /// |   32 bits    |     `0x1fff_ffff`     |
  /// |   64 bits    |`0x1fff_ffff_ffff_ffff`|
  pub const MAX_BITS: usize = BitSpan::<Const, T, O>::REGION_MAX_BITS;
  /// The inclusive maximum length that a `[T]` slice can be for
  ///  `BitSlice<_, T>` to cover it.
  ///
  /// A `BitSlice<_, T>` that begins in the interior of an element and
  /// contains the maximum number of bits will extend one element past the
  /// cutoff that would occur if the bit-slice began at the zeroth bit. Such a
  /// bit-slice is difficult to manually construct, but would not otherwise
  /// fail.
  ///
  /// |Type Bits|Max Elements (32-bit)| Max Elements (64-bit) |
  /// |--------:|--------------------:|----------------------:|
  /// |        8|    `0x0400_0001`    |`0x0400_0000_0000_0001`|
  /// |       16|    `0x0200_0001`    |`0x0200_0000_0000_0001`|
  /// |       32|    `0x0100_0001`    |`0x0100_0000_0000_0001`|
  /// |       64|    `0x0080_0001`    |`0x0080_0000_0000_0001`|
  pub const MAX_ELTS: usize = BitSpan::<Const, T, O>::REGION_MAX_ELTS;
}

#[cfg(feature = "alloc")]
impl<T, O> BitSlice<T, O>
where
  T: BitStore,
  O: BitOrder,
{
  /// Copies a bit-slice into an owned bit-vector.
  ///
  /// Since the new vector is freshly owned, this gets marked as `::Unalias`
  /// to remove any guards that may have been inserted by the bit-slice’s
  /// history.
  ///
  /// It does *not* use the underlying memory type, so that a `BitSlice<_,
  /// Cell<_>>` will produce a `BitVec<_, Cell<_>>`.
  ///
  /// ## Original
  ///
  /// [`slice::to_vec`](https://doc.rust-lang.org/std/primitive.slice.html#method.to_vec)
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// let bits = bits![0, 1, 0, 1];
  /// let bv = bits.to_bitvec();
  /// assert_eq!(bits, bv);
  /// ```
  #[inline]
  pub fn to_bitvec(&self) -> BitVec<T::Unalias, O> {
    self.domain()
      .map(<T::Unalias as BitStore>::new)
      .collect::<Vec<_>>()
      .pipe(BitVec::from_vec)
      .tap_mut(|bv| unsafe {
        bv.set_head(self.as_bitspan().head());
        bv.set_len(self.len());
      })
  }
}

#[inline]
#[doc = include_str!("../doc/slice/from_raw_parts_unchecked.md")]
pub unsafe fn from_raw_parts_unchecked<'a, T, O>(
  ptr: BitPtr<Const, T, O>,
  len: usize,
) -> &'a BitSlice<T, O>
where
  O: BitOrder,
  T: 'a + BitStore,
{
  ptr.span_unchecked(len).into_bitslice_ref()
}

#[inline]
#[doc = include_str!("../doc/slice/from_raw_parts_unchecked_mut.md")]
pub unsafe fn from_raw_parts_unchecked_mut<'a, T, O>(
  ptr: BitPtr<Mut, T, O>,
  len: usize,
) -> &'a mut BitSlice<T, O>
where
  O: BitOrder,
  T: 'a + BitStore,
{
  ptr.span_unchecked(len).into_bitslice_mut()
}

Coverage Report

Created: 2026-01-08 06:10