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

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

use core::{
  any,
  cmp,
  convert::TryFrom,
  fmt::{
    self,
    Debug,
    Display,
    Formatter,
    Pointer,
  },
  hash::{
    Hash,
    Hasher,
  },
  marker::PhantomData,
  ptr,
};

use tap::{
  Pipe,
  TryConv,
};
use wyz::{
  comu::{
    Address,
    Const,
    Frozen,
    Mut,
    Mutability,
    NullPtrError,
  },
  fmt::FmtForward,
};

use super::{
  check_alignment,
  AddressExt,
  BitPtrRange,
  BitRef,
  BitSpan,
  BitSpanError,
  MisalignError,
};
use crate::{
  access::BitAccess,
  devel as dvl,
  index::BitIdx,
  mem,
  order::{
    BitOrder,
    Lsb0,
  },
  store::BitStore,
};

#[repr(C, packed)]
#[doc = include_str!("../../doc/ptr/BitPtr.md")]
pub struct BitPtr<M = Const, T = usize, O = Lsb0>
where
  M: Mutability,
  T: BitStore,
  O: BitOrder,
{
  /// Memory addresses must be well-aligned and non-null.
  ///
  /// This is not actually a requirement of `BitPtr`, but it is a requirement
  /// of `BitSpan`, and it is extended across the entire crate for
  /// consistency.
  ptr: Address<M, T>,
  /// The index of the referent bit within `*addr`.
  bit: BitIdx<T::Mem>,
  /// The ordering used to select the bit at `head` in `*addr`.
  _or: PhantomData<O>,
}

impl<M, T, O> BitPtr<M, T, O>
where
  M: Mutability,
  T: BitStore,
  O: BitOrder,
{
  /// The canonical dangling pointer. This selects the starting bit of the
  /// canonical dangling pointer for `T`.
  pub const DANGLING: Self = Self {
    ptr: Address::DANGLING,
    bit: BitIdx::MIN,
    _or: PhantomData,
  };

  /// Loads the address field, sidestepping any alignment problems.
  ///
  /// This is the only safe way to access `(&self).ptr`. Do not perform field
  /// access on `.ptr` through a reference except through this method.
  #[inline]
  fn get_addr(&self) -> Address<M, T> {
    unsafe { ptr::addr_of!(self.ptr).read_unaligned() }
  }

  /// Tries to construct a `BitPtr` from a memory location and a bit index.
  ///
  /// ## Parameters
  ///
  /// - `ptr`: The address of a memory element. `Address` wraps raw pointers
  ///   or references, and enforces that they are not null. `BitPtr`
  ///   additionally requires that the address be well-aligned to its type;
  ///   misaligned addresses cause this to return an error.
  /// - `bit`: The index of the selected bit within `*ptr`.
  ///
  /// ## Returns
  ///
  /// This returns an error if `ptr` is not aligned to `T`; otherwise, it
  /// returns a new bit-pointer structure to the given element and bit.
  ///
  /// You should typically prefer to use constructors that take directly from
  /// a memory reference or pointer, such as the `TryFrom<*T>`
  /// implementations, the `From<&/mut T>` implementations, or the
  /// [`::from_ref()`], [`::from_mut()`], [`::from_slice()`], or
  /// [`::from_slice_mut()`] functions.
  ///
  /// [`::from_mut()`]: Self::from_mut
  /// [`::from_ref()`]: Self::from_ref
  /// [`::from_slice()`]: Self::from_slice
  /// [`::from_slice_mut()`]: Self::from_slice_mut
  #[inline]
  pub fn new(
    ptr: Address<M, T>,
    bit: BitIdx<T::Mem>,
  ) -> Result<Self, MisalignError<T>> {
    Ok(Self {
      ptr: check_alignment(ptr)?,
      bit,
      ..Self::DANGLING
    })
  }

  /// Constructs a `BitPtr` from an address and head index, without checking
  /// the address for validity.
  ///
  /// ## Parameters
  ///
  /// - `addr`: The memory address to use in the bit-pointer. See the Safety
  ///   section.
  /// - `head`: The index of the bit in `*addr` that this bit-pointer selects.
  ///
  /// ## Returns
  ///
  /// A new bit-pointer composed of the parameters. No validity checking is
  /// performed.
  ///
  /// ## Safety
  ///
  /// The `Address` type imposes a non-null requirement. `BitPtr` additionally
  /// requires that `addr` is well-aligned for `T`, and presumes that the
  /// caller has ensured this with [`bv_ptr::check_alignment`][0]. If this is
  /// not the case, then the program is incorrect, and subsequent behavior is
  /// not specified.
  ///
  /// [0]: crate::ptr::check_alignment.
  #[inline]
  pub unsafe fn new_unchecked(
    ptr: Address<M, T>,
    bit: BitIdx<T::Mem>,
  ) -> Self {
    if cfg!(debug_assertions) {
      Self::new(ptr, bit).unwrap()
    }
    else {
      Self {
        ptr,
        bit,
        ..Self::DANGLING
      }
    }
  }

  /// Gets the address of the base storage element.
  #[inline]
  pub fn address(self) -> Address<M, T> {
    self.get_addr()
  }

  /// Gets the `BitIdx` that selects the bit within the memory element.
  #[inline]
  pub fn bit(self) -> BitIdx<T::Mem> {
    self.bit
  }

  /// Decomposes a bit-pointer into its element address and bit index.
  ///
  /// ## Parameters
  ///
  /// - `self`
  ///
  /// ## Returns
  ///
  /// - `.0`: The memory address in which the referent bit is located.
  /// - `.1`: The index of the referent bit in `*.0` according to the `O` type
  ///   parameter.
  #[inline]
  pub fn raw_parts(self) -> (Address<M, T>, BitIdx<T::Mem>) {
    (self.address(), self.bit())
  }

  /// Converts a bit-pointer into a span descriptor by attaching a length
  /// counter (in bits).
  ///
  /// ## Parameters
  ///
  /// - `self`: The base address of the produced span.
  /// - `bits`: The length, in bits, of the span.
  ///
  /// ## Returns
  ///
  /// A span descriptor beginning at `self` and ending (exclusive) at `self +
  /// bits`. This fails if it is unable to encode the requested span into a
  /// descriptor.
  pub(crate) fn span(
    self,
    bits: usize,
  ) -> Result<BitSpan<M, T, O>, BitSpanError<T>> {
    BitSpan::new(self.ptr, self.bit, bits)
  }

  /// Converts a bit-pointer into a span descriptor, without performing
  /// encoding validity checks.
  ///
  /// ## Parameters
  ///
  /// - `self`: The base address of the produced span.
  /// - `bits`: The length, in bits, of the span.
  ///
  /// ## Returns
  ///
  /// An encoded span descriptor of `self` and `bits`. Note that no validity
  /// checks are performed!
  ///
  /// ## Safety
  ///
  /// The caller must ensure that the rules of `BitSpan::new` are not
  /// violated. Typically this method should only be used on parameters that
  /// have already passed through `BitSpan::new` and are known to be good.
  pub(crate) unsafe fn span_unchecked(self, bits: usize) -> BitSpan<M, T, O> {
    BitSpan::new_unchecked(self.get_addr(), self.bit, bits)
  }

  /// Produces a bit-pointer range beginning at `self` (inclusive) and ending
  /// at `self + count` (exclusive).
  ///
  /// ## Safety
  ///
  /// `self + count` must be within the same provenance region as `self`. The
  /// first bit past the end of an allocation is included in provenance
  /// regions, though it is not dereferenceable and will not be dereferenced.
  ///
  /// It is unsound to *even construct* a pointer that departs the provenance
  /// region, even if that pointer is never dereferenced!
  pub(crate) unsafe fn range(self, count: usize) -> BitPtrRange<M, T, O> {
    (self .. self.add(count)).into()
  }

  /// Removes write permissions from a bit-pointer.
  #[inline]
  pub fn to_const(self) -> BitPtr<Const, T, O> {
    let Self {
      ptr: addr,
      bit: head,
      ..
    } = self;
    BitPtr {
      ptr: addr.immut(),
      bit: head,
      ..BitPtr::DANGLING
    }
  }

  /// Adds write permissions to a bit-pointer.
  ///
  /// ## Safety
  ///
  /// This pointer must have been derived from a `*mut` pointer.
  #[inline]
  pub unsafe fn to_mut(self) -> BitPtr<Mut, T, O> {
    let Self {
      ptr: addr,
      bit: head,
      ..
    } = self;
    BitPtr {
      ptr: addr.assert_mut(),
      bit: head,
      ..BitPtr::DANGLING
    }
  }

  /// Freezes a bit-pointer, forbidding direct mutation.
  ///
  /// This is used as a necessary prerequisite to all mutation of memory.
  /// `BitPtr` uses an implementation scoped to `Frozen<_>` to perform
  /// alias-aware writes; see below.
  pub(crate) fn freeze(self) -> BitPtr<Frozen<M>, T, O> {
    let Self {
      ptr: addr,
      bit: head,
      ..
    } = self;
    BitPtr {
      ptr: addr.freeze(),
      bit: head,
      ..BitPtr::DANGLING
    }
  }
}

impl<T, O> BitPtr<Const, T, O>
where
  T: BitStore,
  O: BitOrder,
{
  /// Constructs a `BitPtr` to the zeroth bit in a single element.
  #[inline]
  pub fn from_ref(elem: &T) -> Self {
    unsafe { Self::new_unchecked(elem.into(), BitIdx::MIN) }
  }

  /// Constructs a `BitPtr` to the zeroth bit in the zeroth element of a
  /// slice.
  ///
  /// This method is distinct from `Self::from_ref(&elem[0])`, because it
  /// ensures that the returned bit-pointer has provenance over the entire
  /// slice. Indexing within a slice narrows the provenance range, and makes
  /// departure from the subslice, *even within the original slice*, illegal.
  #[inline]
  pub fn from_slice(slice: &[T]) -> Self {
    unsafe {
      Self::new_unchecked(slice.as_ptr().into_address(), BitIdx::MIN)
    }
  }

  /// Gets a raw pointer to the memory element containing the selected bit.
  #[inline]
  #[cfg(not(tarpaulin_include))]
  pub fn pointer(&self) -> *const T {
    self.get_addr().to_const()
  }
}

impl<T, O> BitPtr<Mut, T, O>
where
  T: BitStore,
  O: BitOrder,
{
  /// Constructs a mutable `BitPtr` to the zeroth bit in a single element.
  #[inline]
  pub fn from_mut(elem: &mut T) -> Self {
    unsafe { Self::new_unchecked(elem.into(), BitIdx::MIN) }
  }

  /// Constructs a `BitPtr` to the zeroth bit in the zeroth element of a
  /// mutable slice.
  ///
  /// This method is distinct from `Self::from_mut(&mut elem[0])`, because it
  /// ensures that the returned bit-pointer has provenance over the entire
  /// slice. Indexing within a slice narrows the provenance range, and makes
  /// departure from the subslice, *even within the original slice*, illegal.
  #[inline]
  pub fn from_mut_slice(slice: &mut [T]) -> Self {
    unsafe {
      Self::new_unchecked(slice.as_mut_ptr().into_address(), BitIdx::MIN)
    }
  }

  /// Constructs a mutable `BitPtr` to the zeroth bit in the zeroth element of
  /// a slice.
  ///
  /// This method is distinct from `Self::from_mut(&mut elem[0])`, because it
  /// ensures that the returned bit-pointer has provenance over the entire
  /// slice. Indexing within a slice narrows the provenance range, and makes
  /// departure from the subslice, *even within the original slice*, illegal.
  #[inline]
  pub fn from_slice_mut(slice: &mut [T]) -> Self {
    unsafe {
      Self::new_unchecked(slice.as_mut_ptr().into_address(), BitIdx::MIN)
    }
  }

  /// Gets a raw pointer to the memory location containing the selected bit.
  #[inline]
  #[cfg(not(tarpaulin_include))]
  pub fn pointer(&self) -> *mut T {
    self.get_addr().to_mut()
  }
}

/// Port of the `*bool` inherent API.
impl<M, T, O> BitPtr<M, T, O>
where
  M: Mutability,
  T: BitStore,
  O: BitOrder,
{
  /// Tests if a bit-pointer is the null value.
  ///
  /// This is always false, as a `BitPtr` is a `NonNull` internally. Use
  /// `Option<BitPtr>` to express the potential for a null pointer.
  ///
  /// ## Original
  ///
  /// [`pointer::is_null`](https://doc.rust-lang.org/std/primitive.pointer.html#method.is_null)
  #[inline]
  #[deprecated = "`BitPtr` is never null"]
  pub fn is_null(self) -> bool {
    false
  }

  /// Casts to a `BitPtr` with a different storage parameter.
  ///
  /// This is not free! In order to maintain value integrity, it encodes a
  /// `BitSpan` encoded descriptor with its value, casts that, then decodes
  /// into a `BitPtr` of the target type. If `T` and `U` have different
  /// `::Mem` associated types, then this may change the selected bit in
  /// memory. This is an unavoidable cost of the addressing and encoding
  /// schemes.
  ///
  /// ## Original
  ///
  /// [`pointer::cast`](https://doc.rust-lang.org/std/primitive.pointer.html#method.cast)
  #[inline]
  pub fn cast<U>(self) -> BitPtr<M, U, O>
  where U: BitStore {
    let (addr, head, _) =
      unsafe { self.span_unchecked(1) }.cast::<U>().raw_parts();
    unsafe { BitPtr::new_unchecked(addr, head) }
  }

  /// Decomposes a bit-pointer into its address and head-index components.
  ///
  /// ## Original
  ///
  /// [`pointer::to_raw_parts`](https://doc.rust-lang.org/std/primitive.pointer.html#method.to_raw_parts)
  ///
  /// ## API Differences
  ///
  /// The original method is unstable as of 1.54.0; however, because `BitPtr`
  /// already has a similar API, the name is optimistically stabilized here.
  /// Prefer [`.raw_parts()`] until the original inherent stabilizes.
  ///
  /// [`.raw_parts()`]: Self::raw_parts
  #[inline]
  #[cfg(not(tarpaulin_include))]
  pub fn to_raw_parts(self) -> (Address<M, T>, BitIdx<T::Mem>) {
    self.raw_parts()
  }

  /// Produces a proxy reference to the referent bit.
  ///
  /// Because `BitPtr` guarantees that it is non-null and well-aligned, this
  /// never returns `None`. However, this is still unsafe to call on any
  /// bit-pointers created from conjured values rather than known references.
  ///
  /// ## Original
  ///
  /// [`pointer::as_ref`](https://doc.rust-lang.org/std/primitive.pointer.html#method.as_ref)
  ///
  /// ## API Differences
  ///
  /// This produces a proxy type rather than a true reference. The proxy
  /// implements `Deref<Target = bool>`, and can be converted to `&bool` with
  /// a reborrow `&*`.
  ///
  /// ## Safety
  ///
  /// Since `BitPtr` does not permit null or misaligned pointers, this method
  /// will always dereference the pointer in order to create the proxy. As
  /// such, you must ensure the following conditions are met:
  ///
  /// - the pointer must be dereferenceable as defined in the standard library
  ///   documentation
  /// - the pointer must point to an initialized instance of `T`
  /// - you must ensure that no other pointer will race to modify the referent
  ///   location while this call is reading from memory to produce the proxy
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// let data = 1u8;
  /// let ptr = BitPtr::<_, _, Lsb0>::from_ref(&data);
  /// let val = unsafe { ptr.as_ref() }.unwrap();
  /// assert!(*val);
  /// ```
  #[inline]
  pub unsafe fn as_ref<'a>(self) -> Option<BitRef<'a, Const, T, O>> {
    Some(BitRef::from_bitptr(self.to_const()))
  }

  /// Creates a new bit-pointer at a specified offset from the original.
  ///
  /// `count` is in units of bits.
  ///
  /// ## Original
  ///
  /// [`pointer::offset`](https://doc.rust-lang.org/std/primitive.pointer.html#method.offset)
  ///
  /// ## Safety
  ///
  /// `BitPtr` is implemented with Rust raw pointers internally, and is
  /// subject to all of Rust’s rules about provenance and permission tracking.
  /// You must abide by the safety rules established in the original method,
  /// to which this internally delegates.
  ///
  /// Additionally, `bitvec` imposes its own rules: while Rust cannot observe
  /// provenance beyond an element or byte level, `bitvec` demands that
  /// `&mut BitSlice` have exclusive view over all bits it observes. You must
  /// not produce a bit-pointer that departs a `BitSlice` region and intrudes
  /// on any `&mut BitSlice`’s handle, and you must not produce a
  /// write-capable bit-pointer that intrudes on a `&BitSlice` handle that
  /// expects its contents to be immutable.
  ///
  /// Note that it is illegal to *construct* a bit-pointer that invalidates
  /// any of these rules. If you wish to defer safety-checking to the point of
  /// dereferencing, and allow the temporary construction *but not*
  /// *dereference* of illegal `BitPtr`s, use [`.wrapping_offset()`] instead.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// let data = 5u8;
  /// let ptr = BitPtr::<_, _, Lsb0>::from_ref(&data);
  /// unsafe {
  ///   assert!(ptr.read());
  ///   assert!(!ptr.offset(1).read());
  ///   assert!(ptr.offset(2).read());
  /// }
  /// ```
  ///
  /// [`.wrapping_offset()`]: Self::wrapping_offset
  #[inline]
  #[must_use = "returns a new bit-pointer rather than modifying its argument"]
  pub unsafe fn offset(self, count: isize) -> Self {
    let (elts, head) = self.bit.offset(count);
    Self::new_unchecked(self.ptr.offset(elts), head)
  }

  /// Creates a new bit-pointer at a specified offset from the original.
  ///
  /// `count` is in units of bits.
  ///
  /// ## Original
  ///
  /// [`pointer::wrapping_offset`](https://doc.rust-lang.org/std/primitive.pointer.html#method.wrapping_offset)
  ///
  /// ## API Differences
  ///
  /// `bitvec` makes it explicitly illegal to wrap a pointer around the high
  /// end of the address space, because it is incapable of representing a null
  /// pointer.
  ///
  /// However, `<*T>::wrapping_offset` has additional properties as a result
  /// of its tolerance for wrapping the address space: it tolerates departing
  /// a provenance region, and is not unsafe to use to *create* a bit-pointer
  /// that is outside the bounds of its original provenance.
  ///
  /// ## Safety
  ///
  /// This function is safe to use because the bit-pointers it creates defer
  /// their provenance checks until the point of dereference. As such, you
  /// can safely use this to perform arbitrary pointer arithmetic that Rust
  /// considers illegal in ordinary arithmetic, as long as you do not
  /// dereference the bit-pointer until it has been brought in bounds of the
  /// originating provenance region.
  ///
  /// This means that, to the Rust rule engine,
  /// `let z = x.wrapping_add(y as usize).wrapping_sub(x as usize);` is not
  /// equivalent to `y`, but `z` is safe to construct, and
  /// `z.wrapping_add(x as usize).wrapping_sub(y as usize)` produces a
  /// bit-pointer that *is* equivalent to `x`.
  ///
  /// See the documentation of the original method for more details about
  /// provenance regions, and the distinctions that the optimizer makes about
  /// them.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// let data = 0u32;
  /// let mut ptr = BitPtr::<_, _, Lsb0>::from_ref(&data);
  /// let end = ptr.wrapping_offset(32);
  /// while ptr < end {
  ///   # #[cfg(feature = "std")] {
  ///   println!("{}", unsafe { ptr.read() });
  ///   # }
  ///   ptr = ptr.wrapping_offset(3);
  /// }
  /// ```
  #[inline]
  #[must_use = "returns a new bit-pointer rather than modifying its argument"]
  pub fn wrapping_offset(self, count: isize) -> Self {
    let (elts, head) = self.bit.offset(count);
    unsafe { Self::new_unchecked(self.ptr.wrapping_offset(elts), head) }
  }

  /// Calculates the distance (in bits) between two bit-pointers.
  ///
  /// This method is the inverse of [`.offset()`].
  ///
  /// ## Original
  ///
  /// [`pointer::offset_from`](https://doc.rust-lang.org/std/primitive.pointer.html#method.offset_from)
  ///
  /// ## API Differences
  ///
  /// The base pointer may have a different `BitStore` type parameter, as long
  /// as they share an underlying memory type. This is necessary in order to
  /// accommodate aliasing markers introduced between when an origin pointer
  /// was taken and when `self` compared against it.
  ///
  /// ## Safety
  ///
  /// Both `self` and `origin` **must** be drawn from the same provenance
  /// region. This means that they must be created from the same Rust
  /// allocation, whether with `let` or the allocator API, and must be in the
  /// (inclusive) range `base ..= base + len`. The first bit past the end of
  /// a region can be addressed, just not dereferenced.
  ///
  /// See the original `<*T>::offset_from` for more details on region safety.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// let data = 0u32;
  /// let base = BitPtr::<_, _, Lsb0>::from_ref(&data);
  /// let low = unsafe { base.add(10) };
  /// let high = unsafe { low.add(15) };
  /// unsafe {
  ///   assert_eq!(high.offset_from(low), 15);
  ///   assert_eq!(low.offset_from(high), -15);
  ///   assert_eq!(low.offset(15), high);
  ///   assert_eq!(high.offset(-15), low);
  /// }
  /// ```
  ///
  /// While this method is safe to *construct* bit-pointers that depart a
  /// provenance region, it remains illegal to *dereference* those pointers!
  ///
  /// This usage is incorrect, and a program that contains it is not
  /// well-formed.
  ///
  /// ```rust,no_run
  /// use bitvec::prelude::*;
  ///
  /// let a = 0u8;
  /// let b = !0u8;
  ///
  /// let a_ptr = BitPtr::<_, _, Lsb0>::from_ref(&a);
  /// let b_ptr = BitPtr::<_, _, Lsb0>::from_ref(&b);
  /// let diff = (b_ptr.pointer() as isize)
  ///   .wrapping_sub(a_ptr.pointer() as isize)
  ///   // Remember: raw pointers are byte-stepped,
  ///   // but bit-pointers are bit-stepped.
  ///   .wrapping_mul(8);
  /// // This pointer to `b` has `a`’s provenance:
  /// let b_ptr_2 = a_ptr.wrapping_offset(diff);
  ///
  /// // They are *arithmetically* equal:
  /// assert_eq!(b_ptr, b_ptr_2);
  /// // But it is still undefined behavior to cross provenances!
  /// assert_eq!(0, unsafe { b_ptr_2.offset_from(b_ptr) });
  /// ```
  ///
  /// [`.offset()`]: Self::offset
  #[inline]
  pub unsafe fn offset_from<U>(self, origin: BitPtr<M, U, O>) -> isize
  where U: BitStore<Mem = T::Mem> {
    self.get_addr()
      .cast::<T::Mem>()
      .offset_from(origin.get_addr().cast::<T::Mem>())
      .wrapping_mul(mem::bits_of::<T::Mem>() as isize)
      .wrapping_add(self.bit.into_inner() as isize)
      .wrapping_sub(origin.bit.into_inner() as isize)
  }

  /// Adjusts a bit-pointer upwards in memory. This is equivalent to
  /// `.offset(count as isize)`.
  ///
  /// `count` is in units of bits.
  ///
  /// ## Original
  ///
  /// [`pointer::add`](https://doc.rust-lang.org/std/primitive.pointer.html#method.add)
  ///
  /// ## Safety
  ///
  /// See [`.offset()`](Self::offset).
  #[inline]
  #[must_use = "returns a new bit-pointer rather than modifying its argument"]
  pub unsafe fn add(self, count: usize) -> Self {
    self.offset(count as isize)
  }

  /// Adjusts a bit-pointer downwards in memory. This is equivalent to
  /// `.offset((count as isize).wrapping_neg())`.
  ///
  /// `count` is in units of bits.
  ///
  /// ## Original
  ///
  /// [`pointer::sub`](https://doc.rust-lang.org/std/primitive.pointer.html#method.sub)
  ///
  /// ## Safety
  ///
  /// See [`.offset()`](Self::offset).
  #[inline]
  #[must_use = "returns a new bit-pointer rather than modifying its argument"]
  pub unsafe fn sub(self, count: usize) -> Self {
    self.offset((count as isize).wrapping_neg())
  }

  /// Adjusts a bit-pointer upwards in memory, using wrapping semantics. This
  /// is equivalent to `.wrapping_offset(count as isize)`.
  ///
  /// `count` is in units of bits.
  ///
  /// ## Original
  ///
  /// [`pointer::wrapping_add`](https://doc.rust-lang.org/std/primitive.pointer.html#method.wrapping_add)
  ///
  /// ## Safety
  ///
  /// See [`.wrapping_offset()`](Self::wrapping_offset).
  #[inline]
  #[must_use = "returns a new bit-pointer rather than modifying its argument"]
  pub fn wrapping_add(self, count: usize) -> Self {
    self.wrapping_offset(count as isize)
  }

  /// Adjusts a bit-pointer downwards in memory, using wrapping semantics.
  /// This is equivalent to
  /// `.wrapping_offset((count as isize).wrapping_neg())`.
  ///
  /// `count` is in units of bits.
  ///
  /// ## Original
  ///
  /// [`pointer::wrapping_add`](https://doc.rust-lang.org/std/primitive.pointer.html#method.wrapping_add)
  ///
  /// ## Safety
  ///
  /// See [`.wrapping_offset()`](Self::wrapping_offset).
  #[inline]
  #[must_use = "returns a new bit-pointer rather than modifying its argument"]
  pub fn wrapping_sub(self, count: usize) -> Self {
    self.wrapping_offset((count as isize).wrapping_neg())
  }

  /// Reads the bit from `*self`.
  ///
  /// ## Original
  ///
  /// [`pointer::read`](https://doc.rust-lang.org/std/primitive.pointer.html#method.read)
  ///
  /// ## Safety
  ///
  /// See [`ptr::read`](crate::ptr::read).
  #[inline]
  pub unsafe fn read(self) -> bool {
    (*self.ptr.to_const()).load_value().get_bit::<O>(self.bit)
  }

  /// Reads the bit from `*self` using a volatile load.
  ///
  /// Prefer using a crate such as [`voladdress`][0] to manage volatile I/O
  /// and use `bitvec` only on the local objects it provides. Individual I/O
  /// operations for individual bits are likely not the behavior you want.
  ///
  /// ## Original
  ///
  /// [`pointer::read_volatile`](https://doc.rust-lang.org/std/primitive.pointer.html#method.read_volatile)
  ///
  /// ## Safety
  ///
  /// See [`ptr::read_volatile`](crate::ptr::read_volatile).
  ///
  /// [0]: https://docs.rs/voladdress/later/voladdress
  #[inline]
  pub unsafe fn read_volatile(self) -> bool {
    self.ptr.to_const().read_volatile().get_bit::<O>(self.bit)
  }

  /// Reads the bit from `*self` using an unaligned memory access.
  ///
  /// `BitPtr` forbids unaligned addresses. If you have such an address, you
  /// must perform your memory accesses on the raw element, and only use
  /// `bitvec` on a well-aligned stack temporary. This method should never be
  /// necessary.
  ///
  /// ## Original
  ///
  /// [`pointer::read_unaligned`](https://doc.rust-lang.org/std/primitive.pointer.html#method.read_unaligned)
  ///
  /// ## Safety
  ///
  /// See [`ptr::read_unaligned`](crate::ptr::read_unaligned)
  #[inline]
  #[deprecated = "`BitPtr` does not have unaligned addresses"]
  pub unsafe fn read_unaligned(self) -> bool {
    self.ptr.to_const().read_unaligned().get_bit::<O>(self.bit)
  }

  /// Copies `count` bits from `self` to `dest`. The source and destination
  /// may overlap.
  ///
  /// Note that overlap is only defined when `O` and `O2` are the same type.
  /// If they differ, then `bitvec` does not define overlap, and assumes that
  /// they are wholly discrete in memory.
  ///
  /// ## Original
  ///
  /// [`pointer::copy_to`](https://doc.rust-lang.org/std/primitive.pointer.html#method.copy_to)
  ///
  /// ## Safety
  ///
  /// See [`ptr::copy`](crate::ptr::copy).
  #[inline]
  #[cfg(not(tarpaulin_include))]
  pub unsafe fn copy_to<T2, O2>(self, dest: BitPtr<Mut, T2, O2>, count: usize)
  where
    T2: BitStore,
    O2: BitOrder,
  {
    super::copy(self.to_const(), dest, count);
  }

  /// Copies `count` bits from `self` to `dest`. The source and destination
  /// may *not* overlap.
  ///
  /// ## Original
  ///
  /// [`pointer::copy_to_nonoverlapping`](https://doc.rust-lang.org/std/primitive.pointer.html#method.copy_to_nonoverlapping)
  ///
  /// ## Safety
  ///
  /// See [`ptr::copy_nonoverlapping`](crate::ptr::copy_nonoverlapping).
  #[inline]
  #[cfg(not(tarpaulin_include))]
  pub unsafe fn copy_to_nonoverlapping<T2, O2>(
    self,
    dest: BitPtr<Mut, T2, O2>,
    count: usize,
  ) where
    T2: BitStore,
    O2: BitOrder,
  {
    super::copy_nonoverlapping(self.to_const(), dest, count);
  }

  /// Computes the offset (in bits) that needs to be applied to the
  /// bit-pointer in order to make it aligned to the given *byte* alignment.
  ///
  /// “Alignment” here means that the bit-pointer selects the starting bit of
  /// a memory location whose address satisfies the requested alignment.
  ///
  /// `align` is measured in **bytes**. If you wish to align your bit-pointer
  /// to a specific fraction (½, ¼, or ⅛ of one byte), please file an issue
  /// and I will work on adding this functionality.
  ///
  /// ## Original
  ///
  /// [`pointer::align_offset`](https://doc.rust-lang.org/std/primitive.pointer.html#method.align_offset)
  ///
  /// ## Notes
  ///
  /// If the base-element address of the bit-pointer is already aligned to
  /// `align`, then this will return the bit-offset required to select the
  /// first bit of the successor element.
  ///
  /// If it is not possible to align the bit-pointer, then the implementation
  /// returns `usize::MAX`.
  ///
  /// The return value is measured in bits, not `T` elements or bytes. The
  /// only thing you can do with it is pass it into [`.add()`] or
  /// [`.wrapping_add()`].
  ///
  /// Note from the standard library: It is permissible for the implementation
  /// to *always* return `usize::MAX`. Only your algorithm’s performance can
  /// depend on getting a usable offset here; it must be correct independently
  /// of this function providing a useful value.
  ///
  /// ## Safety
  ///
  /// There are no guarantees whatsoëver that offsetting the bit-pointer will
  /// not overflow or go beyond the allocation that the bit-pointer selects.
  /// It is up to the caller to ensure that the returned offset is correct in
  /// all terms other than alignment.
  ///
  /// ## Panics
  ///
  /// This method panics if `align` is not a power of two.
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// let data = [0u8; 3];
  /// let ptr = BitPtr::<_, _, Lsb0>::from_slice(&data);
  /// let ptr = unsafe { ptr.add(2) };
  /// let count = ptr.align_offset(2);
  /// assert!(count >= 6);
  /// ```
  ///
  /// [`.add()`]: Self::add
  /// [`.wrapping_add()`]: Self::wrapping_add
  #[inline]
  pub fn align_offset(self, align: usize) -> usize {
    let width = mem::bits_of::<T::Mem>();
    match (
      self.ptr.to_const().align_offset(align),
      self.bit.into_inner() as usize,
    ) {
      (0, 0) => 0,
      (0, head) => align * mem::bits_of::<u8>() - head,
      (usize::MAX, _) => usize::MAX,
      (elts, head) => elts.wrapping_mul(width).wrapping_sub(head),
    }
  }
}

/// Port of the `*mut bool` inherent API.
impl<T, O> BitPtr<Mut, T, O>
where
  T: BitStore,
  O: BitOrder,
{
  /// Produces a proxy reference to the referent bit.
  ///
  /// Because `BitPtr` guarantees that it is non-null and well-aligned, this
  /// never returns `None`. However, this is still unsafe to call on any
  /// bit-pointers created from conjured values rather than known references.
  ///
  /// ## Original
  ///
  /// [`pointer::as_mut`](https://doc.rust-lang.org/std/primitive.pointer.html#method.as_mut)
  ///
  /// ## API Differences
  ///
  /// This produces a proxy type rather than a true reference. The proxy
  /// implements `DerefMut<Target = bool>`, and can be converted to
  /// `&mut bool` with a reborrow `&mut *`.
  ///
  /// Writes to the proxy are not reflected in the proxied location until the
  /// proxy is destroyed, either through `Drop` or its [`.commit()`] method.
  ///
  /// ## Safety
  ///
  /// Since `BitPtr` does not permit null or misaligned pointers, this method
  /// will always dereference the pointer in order to create the proxy. As
  /// such, you must ensure the following conditions are met:
  ///
  /// - the pointer must be dereferenceable as defined in the standard library
  ///   documentation
  /// - the pointer must point to an initialized instance of `T`
  /// - you must ensure that no other pointer will race to modify the referent
  ///   location while this call is reading from memory to produce the proxy
  /// - you must ensure that no other `bitvec` handle targets the referent bit
  ///
  /// ## Examples
  ///
  /// ```rust
  /// use bitvec::prelude::*;
  ///
  /// let mut data = 0u8;
  /// let ptr = BitPtr::<_, _, Lsb0>::from_mut(&mut data);
  /// let mut val = unsafe { ptr.as_mut() }.unwrap();
  /// assert!(!*val);
  /// *val = true;
  /// assert!(*val);
  /// ```
  ///
  /// [`.commit()`]: crate::ptr::BitRef::commit
  #[inline]
  pub unsafe fn as_mut<'a>(self) -> Option<BitRef<'a, Mut, T, O>> {
    Some(BitRef::from_bitptr(self))
  }

  /// Copies `count` bits from the region starting at `src` to the region
  /// starting at `self`.
  ///
  /// The regions are free to overlap; the implementation will detect overlap
  /// and correctly avoid it.
  ///
  /// Note: this has the *opposite* argument order from [`ptr::copy`]: `self`
  /// is the destination, not the source.
  ///
  /// ## Original
  ///
  /// [`pointer::copy_from`](https://doc.rust-lang.org/std/primitive.pointer.html#method.copy_from)
  ///
  /// ## Safety
  ///
  /// See [`ptr::copy`].
  ///
  /// [`ptr::copy`]: crate::ptr::copy
  #[inline]
  #[cfg(not(tarpaulin_include))]
  pub unsafe fn copy_from<T2, O2>(
    self,
    src: BitPtr<Const, T2, O2>,
    count: usize,
  ) where
    T2: BitStore,
    O2: BitOrder,
  {
    src.copy_to(self, count);
  }

  /// Copies `count` bits from the region starting at `src` to the region
  /// starting at `self`.
  ///
  /// Unlike [`.copy_from()`], the two regions may *not* overlap; this method
  /// does not attempt to detect overlap and thus may have a slight
  /// performance boost over the overlap-handling `.copy_from()`.
  ///
  /// Note: this has the *opposite* argument order from
  /// [`ptr::copy_nonoverlapping`]: `self` is the destination, not the source.
  ///
  /// ## Original
  ///
  /// [`pointer::copy_from_nonoverlapping`](https://doc.rust-lang.org/std/primitive.pointer.html#method.copy_from_nonoverlapping)
  ///
  /// ## Safety
  ///
  /// See [`ptr::copy_nonoverlapping`].
  ///
  /// [`.copy_from()`]: Self::copy_from
  #[inline]
  #[cfg(not(tarpaulin_include))]
  pub unsafe fn copy_from_nonoverlapping<T2, O2>(
    self,
    src: BitPtr<Const, T2, O2>,
    count: usize,
  ) where
    T2: BitStore,
    O2: BitOrder,
  {
    src.copy_to_nonoverlapping(self, count);
  }

  /// Runs the destructor of the referent value.
  ///
  /// `bool` has no destructor; this function does nothing.
  ///
  /// ## Original
  ///
  /// [`pointer::drop_in_place`](https://doc.rust-lang.org/std/primitive.pointer.html#method.drop_in_place)
  ///
  /// ## Safety
  ///
  /// See [`ptr::drop_in_place`].
  ///
  /// [`ptr::drop_in_place`]: crate::ptr::drop_in_place
  #[inline]
  #[deprecated = "this has no effect, and should not be called"]
  pub fn drop_in_place(self) {}

  /// Writes a new bit into the given location.
  ///
  /// ## Original
  ///
  /// [`pointer::write`](https://doc.rust-lang.org/std/primitive.pointer.html#method.write)
  ///
  /// ## Safety
  ///
  /// See [`ptr::write`].
  ///
  /// [`ptr::write`]: crate::ptr::write
  #[inline]
  pub unsafe fn write(self, value: bool) {
    self.replace(value);
  }

  /// Writes a new bit using volatile I/O operations.
  ///
  /// Because processors do not generally have single-bit read or write
  /// instructions, this must perform a volatile read of the entire memory
  /// location, perform the write locally, then perform another volatile write
  /// to the entire location. These three steps are guaranteed to be
  /// sequential with respect to each other, but are not guaranteed to be
  /// atomic.
  ///
  /// Volatile operations are intended to act on I/O memory, and are *only*
  /// guaranteed not to be elided or reördered by the compiler across other
  /// I/O operations.
  ///
  /// You should not use `bitvec` to act on volatile memory. You should use a
  /// crate specialized for volatile I/O work, such as [`voladdr`], and use it
  /// to explicitly manage the I/O and ask it to perform `bitvec` work only on
  /// the local snapshot of a volatile location.
  ///
  /// ## Original
  ///
  /// [`pointer::write_volatile`](https://doc.rust-lang.org/std/primitive.pointer.html#method.write_volatile)
  ///
  /// ## Safety
  ///
  /// See [`ptr::write_volatile`].
  ///
  /// [`ptr::write_volatile`]: crate::ptr::write_volatile
  /// [`voladdr`]: https://docs.rs/voladdr/latest/voladdr
  #[inline]
  #[allow(clippy::needless_borrow)] // Clippy is wrong.
  pub unsafe fn write_volatile(self, value: bool) {
    let ptr = self.ptr.to_mut();
    let mut tmp = ptr.read_volatile();
    Self::new_unchecked((&mut tmp).into(), self.bit).write(value);
    ptr.write_volatile(tmp);
  }

  /// Writes a bit into memory, tolerating unaligned addresses.
  ///
  /// `BitPtr` does not have unaligned addresses. `BitPtr` itself is capable
  /// of operating on misaligned addresses, but elects to disallow use of them
  /// in keeping with the rest of `bitvec`’s requirements.
  ///
  /// ## Original
  ///
  /// [`pointer::write_unaligned`](https://doc.rust-lang.org/std/primitive.pointer.html#method.write_unaligned)
  ///
  /// ## Safety
  ///
  /// See [`ptr::write_unaligned`].
  ///
  /// [`ptr::write_unaligned`]: crate::ptr::write_unaligned
  #[inline]
  #[allow(clippy::needless_borrow)] // Clippy is wrong.
  #[deprecated = "`BitPtr` does not have unaligned addresses"]
  pub unsafe fn write_unaligned(self, value: bool) {
    let ptr = self.ptr.to_mut();
    let mut tmp = ptr.read_unaligned();
    Self::new_unchecked((&mut tmp).into(), self.bit).write(value);
    ptr.write_unaligned(tmp);
  }

  /// Replaces the bit at `*self` with a new value, returning the previous
  /// value.
  ///
  /// ## Original
  ///
  /// [`pointer::replace`](https://doc.rust-lang.org/std/primitive.pointer.html#method.replace)
  ///
  /// ## Safety
  ///
  /// See [`ptr::replace`].
  ///
  /// [`ptr::replace`]: crate::ptr::replace
  #[inline]
  pub unsafe fn replace(self, value: bool) -> bool {
    self.freeze().frozen_write_bit(value)
  }

  /// Swaps the bits at two mutable locations.
  ///
  /// ## Original
  ///
  /// [`pointer::swap`](https://doc.rust-lang.org/std/primitive.pointer.html#method.swap)
  ///
  /// ## Safety
  ///
  /// See [`ptr::swap`].
  ///
  /// [`ptr::swap`]: crate::ptr::swap
  #[inline]
  pub unsafe fn swap<T2, O2>(self, with: BitPtr<Mut, T2, O2>)
  where
    T2: BitStore,
    O2: BitOrder,
  {
    self.write(with.replace(self.read()));
  }
}

impl<M, T, O> BitPtr<Frozen<M>, T, O>
where
  M: Mutability,
  T: BitStore,
  O: BitOrder,
{
  /// Writes through a bit-pointer that has had its mutability permission
  /// removed.
  ///
  /// This is used to allow `BitPtr<Const, _, AliasSafe<T>>` pointers, which
  /// are not `Mut` but may still modify memory, to do so.
  pub(crate) unsafe fn frozen_write_bit(self, value: bool) -> bool {
    (*self.ptr.cast::<T::Access>().to_const())
      .write_bit::<O>(self.bit, value)
  }
}

#[cfg(not(tarpaulin_include))]
impl<M, T, O> Clone for BitPtr<M, T, O>
where
  M: Mutability,
  T: BitStore,
  O: BitOrder,
{
  #[inline]
  fn clone(&self) -> Self {
    Self {
      ptr: self.get_addr(),
      ..*self
    }
  }
}

impl<M, T, O> Eq for BitPtr<M, T, O>
where
  M: Mutability,
  T: BitStore,
  O: BitOrder,
{
}

impl<M, T, O> Ord for BitPtr<M, T, O>
where
  M: Mutability,
  T: BitStore,
  O: BitOrder,
{
  #[inline]
  fn cmp(&self, other: &Self) -> cmp::Ordering {
    self.partial_cmp(other).expect(
      "BitPtr has a total ordering when type parameters are identical",
    )
  }
}

impl<M1, M2, T1, T2, O> PartialEq<BitPtr<M2, T2, O>> for BitPtr<M1, T1, O>
where
  M1: Mutability,
  M2: Mutability,
  T1: BitStore,
  T2: BitStore,
  O: BitOrder,
{
  #[inline]
  fn eq(&self, other: &BitPtr<M2, T2, O>) -> bool {
    if !dvl::match_store::<T1::Mem, T2::Mem>() {
      return false;
    }
    self.get_addr().to_const() as usize
      == other.get_addr().to_const() as usize
      && self.bit.into_inner() == other.bit.into_inner()
  }
}

impl<M1, M2, T1, T2, O> PartialOrd<BitPtr<M2, T2, O>> for BitPtr<M1, T1, O>
where
  M1: Mutability,
  M2: Mutability,
  T1: BitStore,
  T2: BitStore,
  O: BitOrder,
{
  #[inline]
  fn partial_cmp(&self, other: &BitPtr<M2, T2, O>) -> Option<cmp::Ordering> {
    if !dvl::match_store::<T1::Mem, T2::Mem>() {
      return None;
    }
    match (self.get_addr().to_const() as usize)
      .cmp(&(other.get_addr().to_const() as usize))
    {
      cmp::Ordering::Equal => {
        self.bit.into_inner().partial_cmp(&other.bit.into_inner())
      },
      ord => Some(ord),
    }
  }
}

#[cfg(not(tarpaulin_include))]
impl<T, O> From<&T> for BitPtr<Const, T, O>
where
  T: BitStore,
  O: BitOrder,
{
  #[inline]
  fn from(elem: &T) -> Self {
    Self::from_ref(elem)
  }
}

#[cfg(not(tarpaulin_include))]
impl<T, O> From<&mut T> for BitPtr<Mut, T, O>
where
  T: BitStore,
  O: BitOrder,
{
  #[inline]
  fn from(elem: &mut T) -> Self {
    Self::from_mut(elem)
  }
}

impl<T, O> TryFrom<*const T> for BitPtr<Const, T, O>
where
  T: BitStore,
  O: BitOrder,
{
  type Error = BitPtrError<T>;

  #[inline]
  fn try_from(elem: *const T) -> Result<Self, Self::Error> {
    elem.try_conv::<Address<Const, T>>()?
      .pipe(|ptr| Self::new(ptr, BitIdx::MIN))?
      .pipe(Ok)
  }
}

impl<T, O> TryFrom<*mut T> for BitPtr<Mut, T, O>
where
  T: BitStore,
  O: BitOrder,
{
  type Error = BitPtrError<T>;

  #[inline]
  fn try_from(elem: *mut T) -> Result<Self, Self::Error> {
    elem.try_conv::<Address<Mut, T>>()?
      .pipe(|ptr| Self::new(ptr, BitIdx::MIN))?
      .pipe(Ok)
  }
}

impl<M, T, O> Debug for BitPtr<M, T, O>
where
  M: Mutability,
  T: BitStore,
  O: BitOrder,
{
  #[inline]
  fn fmt(&self, fmt: &mut Formatter) -> fmt::Result {
    write!(
      fmt,
      "{} Bit<{}, {}>",
      M::RENDER,
      any::type_name::<T>(),
      any::type_name::<O>(),
    )?;
    Pointer::fmt(self, fmt)
  }
}

impl<M, T, O> Pointer for BitPtr<M, T, O>
where
  M: Mutability,
  T: BitStore,
  O: BitOrder,
{
  #[inline]
  fn fmt(&self, fmt: &mut Formatter) -> fmt::Result {
    fmt.debug_tuple("")
      .field(&self.get_addr().fmt_pointer())
      .field(&self.bit.fmt_binary())
      .finish()
  }
}

#[cfg(not(tarpaulin_include))]
impl<M, T, O> Hash for BitPtr<M, T, O>
where
  M: Mutability,
  T: BitStore,
  O: BitOrder,
{
  #[inline]
  fn hash<H>(&self, state: &mut H)
  where H: Hasher {
    self.get_addr().hash(state);
    self.bit.hash(state);
  }
}

impl<M, T, O> Copy for BitPtr<M, T, O>
where
  M: Mutability,
  T: BitStore,
  O: BitOrder,
{
}

/// Errors produced by invalid bit-pointer components.
#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub enum BitPtrError<T>
where T: BitStore
{
  /// Attempted to construct a bit-pointer with the null element address.
  Null(NullPtrError),
  /// Attempted to construct a bit-pointer with an address not aligned for the
  /// element type.
  Misaligned(MisalignError<T>),
}

#[cfg(not(tarpaulin_include))]
impl<T> From<MisalignError<T>> for BitPtrError<T>
where T: BitStore
{
  #[inline]
  fn from(err: MisalignError<T>) -> Self {
    Self::Misaligned(err)
  }
}

#[cfg(not(tarpaulin_include))]
impl<T> From<NullPtrError> for BitPtrError<T>
where T: BitStore
{
  #[inline]
  fn from(err: NullPtrError) -> Self {
    Self::Null(err)
  }
}

#[cfg(not(tarpaulin_include))]
impl<T> Display for BitPtrError<T>
where T: BitStore
{
  #[inline]
  fn fmt(&self, fmt: &mut Formatter) -> fmt::Result {
    match self {
      Self::Null(err) => Display::fmt(err, fmt),
      Self::Misaligned(err) => Display::fmt(err, fmt),
    }
  }
}

#[cfg(feature = "std")]
impl<T> std::error::Error for BitPtrError<T> where T: BitStore {}

Coverage Report

Created: 2025-11-11 06:29