Struct bitvec::ptr::BitRef

#[repr(C, align(8))]
pub struct BitRef<'a, M, O = Lsb0, T = usize> where
    M: Mutability,
    O: BitOrder,
    T: BitStore,  { /* private fields */ }

A proxy reference, equivalent to C++ std::bitset<N>::reference.

This type wraps a BitPtr and caches a bool in a padding byte. It is then able to freely produce references to the cached bool, and commits the cache back to the referent bit location on drop.

Lifetimes

• 'a: The lifetime of the source &'a mut BitSlice that created the BitRef.

Type Parameters

• M: The write permission of the reference. When this is Const, the DerefMut implementation is removed, forbidding the proxy from writing back to memory.
• O: The ordering used to address a bit in memory.
• T: The storage type containing the referent bit.

Quirks

Because this type has both a lifetime and a destructor, it can introduce an uncommon 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 goes out of scope at the end of 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();

// Referential behavior
*first = true;
// Direct write
second.set(true);

drop(first); // it’s not a reference!
assert_eq!(bits, bits![1; 2]);

Implementations

impl<M, O, T> BitRef<'_, M, O, T> where
    M: Mutability,
    O: BitOrder,
    T: BitStore, 

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

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

The conversion reads from the pointer, then stores the bool in a padding byte.

Parameters

• bitptr: A bit-pointer to turn into a bit-reference.

Returns

A bit-reference pointing at bitptr.

Safety

The bitptr must address a location that is valid for reads and, if M is Mut, writes.

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

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

Parameters

• self

Returns

The interior bit-pointer, without the associated cache. If this was a write-capable pointer, then the cached bit is committed to memory before this method returns.

impl<O, T> BitRef<'_, Mut, O, T> where
    O: BitOrder,
    T: BitStore, 

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

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

Original

mem::replace

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

Swaps the values at two mutable locations, without deïnitializing either one.

Original

mem::swap

pub fn set(self, value: bool)

Writes a bit into the proxied location without an intermediate copy.

This function writes value directly into the proxied location, and does not store value in the proxy’s internal cache. This should be equivalent to the behavior seen when using ordinary DerefMut proxying, but the latter depends on compiler optimization.

Parameters

• self: This destroys the proxy, as it becomes invalid when writing directly to the location without updating the cache.
• value: The new bit to write into the proxied slot.

Trait Implementations

impl<O, T> Clone for BitRef<'_, Const, O, T> where
    O: BitOrder,
    T: BitStore, 

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<M, O, T> Debug for BitRef<'_, M, O, T> where
    M: Mutability,
    O: BitOrder,
    T: BitStore, 

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

Formats the value using the given formatter.

impl<M, O, T> Deref for BitRef<'_, M, O, T> where
    M: Mutability,
    O: BitOrder,
    T: BitStore, 

type Target = bool

The resulting type after dereferencing.

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

Dereferences the value.

impl<O, T> DerefMut for BitRef<'_, Mut, O, T> where
    O: BitOrder,
    T: BitStore, 

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

Mutably dereferences the value.

impl<M, O, T> Display for BitRef<'_, M, O, T> where
    M: Mutability,
    O: BitOrder,
    T: BitStore, 

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

Formats the value using the given formatter.

impl<M, O, T> Drop for BitRef<'_, M, O, T> where
    M: Mutability,
    O: BitOrder,
    T: BitStore, 

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, M, O1, O2, T1, T2> Extend<BitRef<'a, M, O2, T2>> for BitVec<O1, T1> where
    M: Mutability,
    O1: BitOrder,
    O2: BitOrder,
    T1: BitStore,
    T2: BitStore, 

fn extend<I>(&mut self, iter: I) where
    I: IntoIterator<Item = BitRef<'a, M, O2, T2>>, 

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, O1, O2, T1, T2> FromIterator<BitRef<'a, M, O2, T2>> for BitVec<O1, T1> where
    M: Mutability,
    O1: BitOrder,
    O2: BitOrder,
    T1: BitStore,
    T2: BitStore, 

fn from_iter<I>(iter: I) -> Self where
    I: IntoIterator<Item = BitRef<'a, M, O2, T2>>, 

Creates a value from an iterator.

impl<M, O, T> Hash for BitRef<'_, M, O, T> where
    M: Mutability,
    O: BitOrder,
    T: BitStore, 

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, 

Feeds a slice of this type into the given Hasher.

impl<M, O, T> Not for BitRef<'_, M, O, T> where
    M: Mutability,
    O: BitOrder,
    T: BitStore, 

type Output = bool

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Performs the unary ! operation.

impl<M, O, T> Ord for BitRef<'_, M, O, T> where
    M: Mutability,
    O: BitOrder,
    T: BitStore, 

Implement ordering by comparing the proxied bool values.

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

Restrict a value to a certain interval.

impl<M, O, T> PartialEq<&'_ bool> for BitRef<'_, M, O, T> where
    M: Mutability,
    O: BitOrder,
    T: BitStore, 

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

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

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

This method tests for !=.

impl<M1, M2, O1, O2, T1, T2> PartialEq<BitRef<'_, M2, O2, T2>> for BitRef<'_, M1, O1, T1> where
    M1: Mutability,
    M2: Mutability,
    O1: BitOrder,
    O2: BitOrder,
    T1: BitStore,
    T2: BitStore, 

Test equality of proxy references by the value of their proxied bit.

To test equality by address, decay to a BitPtr with into_bitptr.

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

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

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

This method tests for !=.

impl<M, O, T> PartialEq<bool> for BitRef<'_, M, O, T> where
    M: Mutability,
    O: BitOrder,
    T: BitStore, 

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

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

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

This method tests for !=.

impl<M, O, T> PartialOrd<&'_ bool> for BitRef<'_, M, O, T> where
    M: Mutability,
    O: BitOrder,
    T: BitStore, 

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

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

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

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

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

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

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

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

impl<M1, M2, O1, O2, T1, T2> PartialOrd<BitRef<'_, M2, O2, T2>> for BitRef<'_, M1, O1, T1> where
    M1: Mutability,
    M2: Mutability,
    O1: BitOrder,
    O2: BitOrder,
    T1: BitStore,
    T2: BitStore, 

Order proxy references by the value of their proxied bit.

To order by address, decay to a BitPtr with into_bitptr.

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

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

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

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

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

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

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

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

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

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

impl<M, O, T> PartialOrd<bool> for BitRef<'_, M, O, T> where
    M: Mutability,
    O: BitOrder,
    T: BitStore, 

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

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

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

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

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

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

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

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

impl<M, O, T> Pointer for BitRef<'_, M, O, T> where
    M: Mutability,
    O: BitOrder,
    T: BitStore, 

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

Formats the value using the given formatter.

impl<M, O, T> Eq for BitRef<'_, M, O, T> where
    M: Mutability,
    O: BitOrder,
    T: BitStore, 

Implement equality by comparing the proxied bool values.