Struct bitvec::ptr::BitRef

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

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]);

Implementations§

source§

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

source

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

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.

source

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

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

Original

The syntax &val as *T.

source§

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

source

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

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

Original

mem::replace

source

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

source

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.

source

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§

source§

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

source§

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

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

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

source§

fn as_ref(&self) -> &bool

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

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

source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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.
source§

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

Dereferences the value.
source§

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

source§

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

Mutably dereferences the value.
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

fn drop(&mut self)

Executes the destructor for this type. Read more
source§

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.

source§

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. Read more
source§

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)
Extends a collection with exactly one element.
source§

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. Read more
source§

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.

source§

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

Creates a value from an iterator. Read more
source§

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

source§

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

Feeds this value into the given Hasher. Read more
1.3.0 · source§

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

Feeds a slice of this type into the given Hasher. Read more
source§

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.
source§

fn not(self) -> Self::Output

Performs the unary ! operation. Read more
source§

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

source§

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

This method returns an Ordering between self and other. Read more
1.21.0 · source§

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

Compares and returns the maximum of two values. Read more
1.21.0 · source§

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

Compares and returns the minimum of two values. Read more
1.50.0 · source§

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval. Read more
source§

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

source§

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

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

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

source§

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

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

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

source§

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

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

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,

source§

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

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

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

source§

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

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

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

source§

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

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

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

This method tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

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

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

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

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

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

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

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,

source§

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

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

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

This method tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

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

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

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

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

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

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

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

source§

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

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

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

This method tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

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

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

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

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

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

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

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

source§

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

Formats the value using the given formatter.
source§

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

source§

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

source§

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

Auto Trait Implementations§

§

impl<'a, M = Const, T = usize, O = Lsb0> !RefUnwindSafe for BitRef<'a, M, T, O>

§

impl<'a, M, T, O> Unpin for BitRef<'a, M, T, O>where M: Unpin, O: Unpin,

§

impl<'a, M = Const, T = usize, O = Lsb0> !UnwindSafe for BitRef<'a, M, T, O>

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> Conv for T

source§

fn conv<T>(self) -> Twhere Self: Into<T>,

Converts self into T using Into<T>. Read more
source§

impl<T> FmtForward for T

source§

fn fmt_binary(self) -> FmtBinary<Self>where Self: Binary,

Causes self to use its Binary implementation when Debug-formatted.
source§

fn fmt_display(self) -> FmtDisplay<Self>where Self: Display,

Causes self to use its Display implementation when Debug-formatted.
source§

fn fmt_lower_exp(self) -> FmtLowerExp<Self>where Self: LowerExp,

Causes self to use its LowerExp implementation when Debug-formatted.
source§

fn fmt_lower_hex(self) -> FmtLowerHex<Self>where Self: LowerHex,

Causes self to use its LowerHex implementation when Debug-formatted.
source§

fn fmt_octal(self) -> FmtOctal<Self>where Self: Octal,

Causes self to use its Octal implementation when Debug-formatted.
source§

fn fmt_pointer(self) -> FmtPointer<Self>where Self: Pointer,

Causes self to use its Pointer implementation when Debug-formatted.
source§

fn fmt_upper_exp(self) -> FmtUpperExp<Self>where Self: UpperExp,

Causes self to use its UpperExp implementation when Debug-formatted.
source§

fn fmt_upper_hex(self) -> FmtUpperHex<Self>where Self: UpperHex,

Causes self to use its UpperHex implementation when Debug-formatted.
source§

fn fmt_list(self) -> FmtList<Self>where &'a Self: for<'a> IntoIterator,

Formats each item in a sequence. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Pipe for Twhere T: ?Sized,

source§

fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere Self: Sized,

Pipes by value. This is generally the method you want to use. Read more
source§

fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere R: 'a,

Borrows self and passes that borrow into the pipe function. Read more
source§

fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere R: 'a,

Mutably borrows self and passes that borrow into the pipe function. Read more
source§

fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> Rwhere Self: Borrow<B>, B: 'a + ?Sized, R: 'a,

Borrows self, then passes self.borrow() into the pipe function. Read more
source§

fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R ) -> Rwhere Self: BorrowMut<B>, B: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.borrow_mut() into the pipe function. Read more
source§

fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> Rwhere Self: AsRef<U>, U: 'a + ?Sized, R: 'a,

Borrows self, then passes self.as_ref() into the pipe function.
source§

fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> Rwhere Self: AsMut<U>, U: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.as_mut() into the pipe function.
source§

fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> Rwhere Self: Deref<Target = T>, T: 'a + ?Sized, R: 'a,

Borrows self, then passes self.deref() into the pipe function.
source§

fn pipe_deref_mut<'a, T, R>( &'a mut self, func: impl FnOnce(&'a mut T) -> R ) -> Rwhere Self: DerefMut<Target = T> + Deref, T: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.deref_mut() into the pipe function.
source§

impl<T> Tap for T

source§

fn tap(self, func: impl FnOnce(&Self)) -> Self

Immutable access to a value. Read more
source§

fn tap_mut(self, func: impl FnOnce(&mut Self)) -> Self

Mutable access to a value. Read more
source§

fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Selfwhere Self: Borrow<B>, B: ?Sized,

Immutable access to the Borrow<B> of a value. Read more
source§

fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere Self: BorrowMut<B>, B: ?Sized,

Mutable access to the BorrowMut<B> of a value. Read more
source§

fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Selfwhere Self: AsRef<R>, R: ?Sized,

Immutable access to the AsRef<R> view of a value. Read more
source§

fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere Self: AsMut<R>, R: ?Sized,

Mutable access to the AsMut<R> view of a value. Read more
source§

fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Selfwhere Self: Deref<Target = T>, T: ?Sized,

Immutable access to the Deref::Target of a value. Read more
source§

fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Selfwhere Self: DerefMut<Target = T> + Deref, T: ?Sized,

Mutable access to the Deref::Target of a value. Read more
source§

fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self

Calls .tap() only in debug builds, and is erased in release builds.
source§

fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self

Calls .tap_mut() only in debug builds, and is erased in release builds.
source§

fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Selfwhere Self: Borrow<B>, B: ?Sized,

Calls .tap_borrow() only in debug builds, and is erased in release builds.
source§

fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere Self: BorrowMut<B>, B: ?Sized,

Calls .tap_borrow_mut() only in debug builds, and is erased in release builds.
source§

fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Selfwhere Self: AsRef<R>, R: ?Sized,

Calls .tap_ref() only in debug builds, and is erased in release builds.
source§

fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere Self: AsMut<R>, R: ?Sized,

Calls .tap_ref_mut() only in debug builds, and is erased in release builds.
source§

fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Selfwhere Self: Deref<Target = T>, T: ?Sized,

Calls .tap_deref() only in debug builds, and is erased in release builds.
source§

fn tap_deref_mut_dbg<T>(self, func: impl FnOnce(&mut T)) -> Selfwhere Self: DerefMut<Target = T> + Deref, T: ?Sized,

Calls .tap_deref_mut() only in debug builds, and is erased in release builds.
source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for Twhere T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T> TryConv for T

source§

fn try_conv<T>(self) -> Result<T, Self::Error>where Self: TryInto<T>,

Attempts to convert self into T using TryInto<T>. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.