Struct bitvec::prelude::BitRef

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

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.

Methods from Deref<Target = bool>

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.

pub 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<M, O, T> Eq for BitRef<'_, M, O, T> where
    M: Mutability,
    O: BitOrder,
    T: BitStore, 

Implement equality by comparing the proxied bool values.

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, 

DO NOT use this. You clearly have a BitSlice. Use BitVec::extend_from_bitslice.

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.

pub fn extend_one(&mut self, item: A)

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

Extends a collection with exactly one element.

pub 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, 

DO NOT use this. You clearly have a BitSlice. Use BitVec::from_bitslice instead.

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.

pub 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.

#[must_use]

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

Compares and returns the maximum of two values.

#[must_use]

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

Compares and returns the minimum of two values.

#[must_use]

pub 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 ==.

#[must_use]

pub 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 ==.

#[must_use]

pub 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 ==.

#[must_use]

pub 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.

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

pub 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.

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

pub 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.

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

pub 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.