[−][src]Trait bitvec::order::BitOrder

pub trait BitOrder {
    const TYPENAME: &'static str;

    fn at<T>(place: BitIdx<T>) -> BitPos<T>
    where
        T: BitStore;

    fn mask<T>(place: BitIdx<T>) -> BitMask<T>
    where
        T: BitStore,
    { ... }
}

An ordering over an element.

Usage

bitvec structures store and operate on semantic counts, not bit positions. The BitOrder::at function takes a semantic ordering, BitIdx, and produces an electrical position, BitPos.

Associated Constants

const TYPENAME: &'static str

Name of the ordering type, for use in text display.

Loading content...

Required methods

fn at<T>(place: BitIdx<T>) -> BitPos<T> where
    T: BitStore, 

Translate a semantic bit index into an electrical bit position.

Parameters

  • place: The semantic bit value.

Returns

  • A concrete position. This value can be used for shifting and masking to extract a bit from an element. This must be in the domain 0 .. T::BITS.

Type Parameters

  • T: BitStore: The storage type for which the position will be calculated.

Invariants

The function must be total for the domain .. T::BITS. All values in this domain are valid indices that the library will pass to it, and which this function must satisfy.

The function must be bijective over the domain .. T::BITS. All input values in this domain must have one and only one correpsonding output, which must also be in this domain.

The function may support input in the domain T::BITS ... The library will not produce any values in this domain as input indices. The function must not produce output in the domain T::BITS ... It must choose between panicking, or producing an output in .. T::BITS. The reduction in domain from T::BITS .. to .. T::BITS removes the requirement for inputs in T::BITS .. to have unique outputs in .. T::BITS.

This function must be pure. Calls which have the same input must produce the same output. This invariant is only required to be upheld for the lifetime of all data structures which use an implementor. The behavior of the function may be modified after all existing dependent data structures are destroyed and before any new dependent data structures are created.

Non-Invariants

This function is not required to be stateless. It may refer to immutable global state, subject to the purity requirement on lifetimes.

Safety

This function requires that the output be in the domain .. T::BITS. Implementors must uphold this themselves. Outputs in the domain T::BITS .. will induce panics elsewhere in the library.

Loading content...

Provided methods

fn mask<T>(place: BitIdx<T>) -> BitMask<T> where
    T: BitStore, 

Translate a semantic bit index into an electrical bit mask.

This is an optional function; a default implementation is provided for you.

The default implementation of this function calls Self::at to produce an electrical position, then turns that into a bitmask by setting the nth bit more significant than the least significant bit of the element. BitOrder implementations may choose to provide a faster mask production here, but they must satisfy the invariants listed below.

Parameters

  • place: A semantic bit index into a memory element.

Returns

A one-hot encoding of the provided BitOrder’s electrical position in the T element.

Type Parameters

  • T: The storage type for which the mask will be calculated. The mask must also be this type, as it will be applied to an element of T in order to set, clear, or test a single bit.

Invariants

A one-hot encoding means that there is exactly one bit set in the produced value. It must be equivalent to 1 << *Self::at(place).

As with at, this function must produce a unique mapping from each legal index in the T domain to a one-hot value of T.

Safety

This function requires that the output is always a one-hot value. It is illegal to produce a value with more than one bit set, and doing so will cause uncontrolled side effects.

Loading content...

Implementors

impl BitOrder for Lsb0[src]

fn at<T>(place: BitIdx<T>) -> BitPos<T> where
    T: BitStore, [src]

Maps a semantic count to a concrete position.

Lsb0 order moves from LSbit first to MSbit last.

impl BitOrder for Msb0[src]

fn at<T>(place: BitIdx<T>) -> BitPos<T> where
    T: BitStore, [src]

Maps a semantic count to a concrete position.

Msb0 order moves from MSbit first to LSbit last.

Loading content...