Struct BitRef

#[repr(C, align(8))]
pub struct BitRef<'a, M = Const, T = usize, O = Lsb0>
where
    M: Mutability,
    T: BitStore,
    O: BitOrder,
{
    bitptr: BitPtr<M, T, O>,
    data: bool,
    _ref: PhantomData<&'a UnsafeCell<bool>>,
}

Proxy Bit-Reference

This structure simulates &/mut bool within BitSlice regions. It is analogous to the C++ type std::bitset<N>::reference.

This type wraps a BitPtr and caches a bool in one of the remaining padding bytes. It is then able to freely give out references to its cached bool, and commits the cached value back to the proxied location when dropped.

Original

This is semantically equivalent to &'a bool or &'a mut bool.

Quirks

Because this type has both a lifetime and a destructor, it can introduce an uncommon syntax error condition in Rust. When an expression that produces this type is in the final expression of a block, including if that expression is used as a condition in a match, if let, or if, then the compiler will attempt to extend the drop scope of this type to the outside of the block. This causes a lifetime mismatch error if the source region from which this proxy is produced begins its lifetime inside the block.

If you get a compiler error that this type causes something to be dropped while borrowed, you can end the borrow by putting any expression-ending syntax element after the offending expression that produces this type, including a semicolon or an item definition.

Examples

use bitvec::prelude::*;

let bits = bits![mut 0; 2];

let (left, right) = bits.split_at_mut(1);
let mut first = left.get_mut(0).unwrap();
let second = right.get_mut(0).unwrap();

// Writing through a dereference requires a `mut` binding.
*first = true;
// Writing through the explicit method call does not.
second.commit(true);

drop(first); // It’s not a reference, so NLL does not apply!
assert_eq!(bits, bits![1; 2]);

Fields

bitptr: BitPtr<M, T, O>

data: bool

_ref: PhantomData<&'a UnsafeCell<bool>>

Implementations

impl<M, T, O> BitRef<'_, M, T, O>

where M: Mutability, T: BitStore, O: BitOrder,

pub unsafe fn from_bitptr(bitptr: BitPtr<M, T, O>) -> BitRef<'_, M, T, O>

Converts a bit-pointer into a proxy bit-reference.

This reads through the pointer in order to cache the current bit value in the proxy.

Original

The syntax unsafe { &* ptr }.

Safety

This is equivalent to (and is!) dereferencing a raw pointer. The pointer must be well-constructed, refer to a live memory location in the program context, and not be aliased beyond its typing indicators.

pub fn into_bitptr(self) -> BitPtr<M, T, O>

Decays the bit-reference to an ordinary bit-pointer.

Original

The syntax &val as *T.

impl<T, O> BitRef<'_, Mut, T, O>

where T: BitStore, O: BitOrder,

pub fn replace(&mut self, src: bool) -> bool

Moves src into the referenced bit, returning the previous value.

Original

mem::replace

pub fn swap<T2, O2>(&mut self, other: &mut BitRef<'_, Mut, T2, O2>)

where T2: BitStore, O2: BitOrder,

Swaps the bit values of two proxies.

Original

mem::swap

pub fn commit(self, value: bool)

Commits a bit into the proxied location.

This function writes value directly into the proxied location, bypassing the cache and destroying the proxy. This eliminates the second write done in the destructor, and allows code to be slightly faster.

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

Writes value into the proxy.

This does not write into the proxied location; that is deferred until the proxy destructor runs.

Trait Implementations

impl<T, O> AsMut<bool> for BitRef<'_, Mut, T, O>

where T: BitStore, O: BitOrder,

fn as_mut(&mut self) -> &mut bool

Converts this type into a mutable reference of the (usually inferred) input type.

impl<M, T, O> AsRef<bool> for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore, O: BitOrder,

fn as_ref(&self) -> &bool

Converts this type into a shared reference of the (usually inferred) input type.

impl<T, O> Clone for BitRef<'_, Const, T, O>

where T: BitStore, O: BitOrder,

fn clone(&self) -> BitRef<'_, Const, T, O>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<M, T, O> Debug for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore, O: BitOrder,

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<M, T, O> Deref for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore, O: BitOrder,

type Target = bool

The resulting type after dereferencing.

fn deref(&self) -> &<BitRef<'_, M, T, O> as Deref>::Target

Dereferences the value.

impl<T, O> DerefMut for BitRef<'_, Mut, T, O>

where T: BitStore, O: BitOrder,

fn deref_mut(&mut self) -> &mut <BitRef<'_, Mut, T, O> as Deref>::Target

Mutably dereferences the value.

impl<M, T, O> Display for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore, O: BitOrder,

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<M, T, O> Drop for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore, O: BitOrder,

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, M, T1, T2, O1, O2> Extend<BitRef<'a, M, T2, O2>> for BitVec<T1, O1>

where M: Mutability, T1: BitStore, T2: BitStore, O1: BitOrder, O2: BitOrder,

Bit-Vector Extension by Proxy References

DO NOT use this. You clearly have a bit-slice. Use .extend_from_bitslice() instead!

Iterating over a bit-slice requires loading from memory and constructing a proxy reference for each bit. This is needlessly slow; the specialized method is able to avoid this per-bit cost and possibly even use batched operations.

fn extend<I>(&mut self, iter: I)

where I: IntoIterator<Item = BitRef<'a, M, T2, O2>>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

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

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

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

Reserves capacity in a collection for the given number of additional elements.

impl<'a, M, T1, T2, O1, O2> FromIterator<BitRef<'a, M, T2, O2>> for BitVec<T1, O1>

where M: Mutability, T1: BitStore, T2: BitStore, O1: BitOrder, O2: BitOrder,

Bit-Vector Collection from Proxy References

DO NOT use this. You clearly have a bit-slice. Use ::from_bitslice() instead!

Iterating over a bit-slice requires loading from memory and constructing a proxy reference for each bit. This is needlessly slow; the specialized method is able to avoid this per-bit cost and possibly even use batched operations.

fn from_iter<I>(iter: I) -> BitVec<T1, O1>

where I: IntoIterator<Item = BitRef<'a, M, T2, O2>>,

Creates a value from an iterator.

impl<M, T, O> Hash for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore, O: BitOrder,

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

where H: Hasher,

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<M, T, O> Not for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore, O: BitOrder,

type Output = bool

The resulting type after applying the ! operator.

fn not(self) -> <BitRef<'_, M, T, O> as Not>::Output

Performs the unary ! operation.

impl<M, T, O> Ord for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore, O: BitOrder,

fn cmp(&self, other: &BitRef<'_, M, T, O>) -> Ordering

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized,

Restrict a value to a certain interval.

impl<M, T, O> PartialEq<&bool> for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore, O: BitOrder,

fn eq(&self, other: &&bool) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<M, T, O> PartialEq<BitRef<'_, M, T, O>> for &bool

where M: Mutability, T: BitStore, O: BitOrder,

fn eq(&self, other: &BitRef<'_, M, T, O>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<M, T, O> PartialEq<BitRef<'_, M, T, O>> for bool

where M: Mutability, T: BitStore, O: BitOrder,

fn eq(&self, other: &BitRef<'_, M, T, O>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<M1, M2, O1, O2, T1, T2> PartialEq<BitRef<'_, M2, T2, O2>> for BitRef<'_, M1, T1, O1>

where M1: Mutability, M2: Mutability, T1: BitStore, T2: BitStore, O1: BitOrder, O2: BitOrder,

fn eq(&self, other: &BitRef<'_, M2, T2, O2>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<M, T, O> PartialEq<bool> for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore, O: BitOrder,

fn eq(&self, other: &bool) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<M, T, O> PartialOrd<&bool> for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore, O: BitOrder,

fn partial_cmp(&self, other: &&bool) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl<M1, M2, O1, O2, T1, T2> PartialOrd<BitRef<'_, M2, T2, O2>> for BitRef<'_, M1, T1, O1>

where M1: Mutability, M2: Mutability, T1: BitStore, T2: BitStore, O1: BitOrder, O2: BitOrder,

fn partial_cmp(&self, other: &BitRef<'_, M2, T2, O2>) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl<M, T, O> PartialOrd<bool> for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore, O: BitOrder,

fn partial_cmp(&self, other: &bool) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl<M, T, O> Pointer for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore, O: BitOrder,

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<M, T, O> Eq for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore, O: BitOrder,

impl<M, T, O> Send for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore + Sync, O: BitOrder,

impl<M, T, O> Sync for BitRef<'_, M, T, O>

where M: Mutability, T: BitStore + Sync, O: BitOrder,

Layout

Note: Unable to compute type layout, possibly due to this type having generic parameters. Layout can only be computed for concrete, fully-instantiated types.