Struct BitPattern

pub struct BitPattern<T: BitPatternType> { /* private fields */ }

A pattern of bits that integers can be matched against.

A BitPattern requires specific bits to be set and specific bits to be cleared, with others ignored. It can be constructed using the set_and_cleared method or the bitpattern! macro. The is_match method can be used for matching numbers against the pattern.

There is also a constant set_and_cleared_const method, which does not support type inference, due to a lack of support for generic const functions.

See the bitpatterns crate documentation for more details.

Examples

use bitpatterns::*;

// Create a bitpattern using the set_and_cleared methods
let pattern_1 = BitPattern::set_and_cleared(0b1100, 0b0001);
const PATTERN_2: BitPattern<u8> = BitPattern::<u8>::set_and_cleared_const(0b0010, 0b1001);
// Create equivalent patterns with the bitpattern! macro
// Creating patterns this way is typically clearer
let macro_pattern_1 = bitpattern!("0b11.0");
const MACRO_PATTERN_2: BitPattern<u8> = bitpattern!("0b0.10", u8);

// Now check for matches
// Note that bits which weren't specified in the patterns are ignored by default
assert!(pattern_1.is_match(30)); // 30 == 0b11110
assert!(!PATTERN_2.is_match(30));

assert!(!pattern_1.is_match(2)); // 2 == 0b0010
assert!(PATTERN_2.is_match(2));

Implementations

impl<T: BitPatternType> BitPattern<T>

pub fn is_match(&self, other: T) -> bool

Match a number against the BitPattern

See the BitPattern type documentation, the bitpattern! macro documentation, or the bitpatterns crate documentation for more details about constructing patterns and the corresponding matching rules. Also see the is_bit_match! macro documentation for details on matching against a temporary/single-use BitPattern.

Examples

use bitpatterns::*;

let pattern_1 = bitpattern!("0b10..");
// Compare numbers against pattern_1
assert!(pattern_1.is_match(8));   // 8  == 0b1000
assert!(pattern_1.is_match(11));  // 11 == 0b1011
assert!(!pattern_1.is_match(7));  // 7  == 0b0111
assert!(!pattern_1.is_match(16)); // 16 == 0b10000
  
// Digits which are more significant than those in the pattern are always ignored
let pattern_2 = bitpattern!("0b1");
assert!(pattern_2.is_match(3));  // 3 == 0b11
assert!(!pattern_2.is_match(2)); // 2 == 0b10

pub fn set_and_cleared(set: T, cleared: T) -> Self

Create a BitPattern by specifying the bits that must be set and cleared to match it

The bits that are set in set must be set in a matching number, and the bits that are set in cleared must not be set in a matching number. Any bits not specified in either will be ignored when matching numbers.

The behavior of a BitPattern in which a particular bit is set in both set and cleared (i.e. set & cleared != 0) is guaranteed to be deterministic for a particular version of this crate, but should not be considered stable across versions. Presently, the bits in set take precedence over those in cleared.

See the bitpattern! macro for a simpler way to construct a BitPattern, or set_and_cleared_const on the various BitPattern implementations for a constant version of this function.

impl BitPattern<u8>

pub const fn set_and_cleared_const(set: u8, cleared: u8) -> Self

Create a BitPattern by specifying the bits that must be set and cleared to match it

The bits that are set in set must be set in a matching number, and the bits that are set in cleared must not be set in a matching number. Any bits not specified in either will be ignored when matching numbers.

The behavior of a BitPattern in which a particular bit is set in both set and cleared (i.e. set & cleared != 0) is guaranteed to be deterministic for a particular version of this crate, but should not be considered stable across versions. Presently, the bits in set take precedence over those in cleared.

See the bitpattern! macro for a simpler way to construct a constant BitPattern, or set_and_cleared for a generic (but not constant) version of this function.

impl BitPattern<u16>

pub const fn set_and_cleared_const(set: u16, cleared: u16) -> Self

Create a BitPattern by specifying the bits that must be set and cleared to match it

The bits that are set in set must be set in a matching number, and the bits that are set in cleared must not be set in a matching number. Any bits not specified in either will be ignored when matching numbers.

The behavior of a BitPattern in which a particular bit is set in both set and cleared (i.e. set & cleared != 0) is guaranteed to be deterministic for a particular version of this crate, but should not be considered stable across versions. Presently, the bits in set take precedence over those in cleared.

See the bitpattern! macro for a simpler way to construct a constant BitPattern, or set_and_cleared for a generic (but not constant) version of this function.

impl BitPattern<u32>

pub const fn set_and_cleared_const(set: u32, cleared: u32) -> Self

Create a BitPattern by specifying the bits that must be set and cleared to match it

The bits that are set in set must be set in a matching number, and the bits that are set in cleared must not be set in a matching number. Any bits not specified in either will be ignored when matching numbers.

The behavior of a BitPattern in which a particular bit is set in both set and cleared (i.e. set & cleared != 0) is guaranteed to be deterministic for a particular version of this crate, but should not be considered stable across versions. Presently, the bits in set take precedence over those in cleared.

See the bitpattern! macro for a simpler way to construct a constant BitPattern, or set_and_cleared for a generic (but not constant) version of this function.

impl BitPattern<u64>

pub const fn set_and_cleared_const(set: u64, cleared: u64) -> Self

Create a BitPattern by specifying the bits that must be set and cleared to match it

The bits that are set in set must be set in a matching number, and the bits that are set in cleared must not be set in a matching number. Any bits not specified in either will be ignored when matching numbers.

The behavior of a BitPattern in which a particular bit is set in both set and cleared (i.e. set & cleared != 0) is guaranteed to be deterministic for a particular version of this crate, but should not be considered stable across versions. Presently, the bits in set take precedence over those in cleared.

See the bitpattern! macro for a simpler way to construct a constant BitPattern, or set_and_cleared for a generic (but not constant) version of this function.

impl BitPattern<u128>

pub const fn set_and_cleared_const(set: u128, cleared: u128) -> Self

Create a BitPattern by specifying the bits that must be set and cleared to match it

The bits that are set in set must be set in a matching number, and the bits that are set in cleared must not be set in a matching number. Any bits not specified in either will be ignored when matching numbers.

The behavior of a BitPattern in which a particular bit is set in both set and cleared (i.e. set & cleared != 0) is guaranteed to be deterministic for a particular version of this crate, but should not be considered stable across versions. Presently, the bits in set take precedence over those in cleared.

See the bitpattern! macro for a simpler way to construct a constant BitPattern, or set_and_cleared for a generic (but not constant) version of this function.

impl BitPattern<i8>

pub const fn set_and_cleared_const(set: i8, cleared: i8) -> Self

Create a BitPattern by specifying the bits that must be set and cleared to match it

The bits that are set in set must be set in a matching number, and the bits that are set in cleared must not be set in a matching number. Any bits not specified in either will be ignored when matching numbers.

The behavior of a BitPattern in which a particular bit is set in both set and cleared (i.e. set & cleared != 0) is guaranteed to be deterministic for a particular version of this crate, but should not be considered stable across versions. Presently, the bits in set take precedence over those in cleared.

See the bitpattern! macro for a simpler way to construct a constant BitPattern, or set_and_cleared for a generic (but not constant) version of this function.

impl BitPattern<i16>

pub const fn set_and_cleared_const(set: i16, cleared: i16) -> Self

Create a BitPattern by specifying the bits that must be set and cleared to match it

The bits that are set in set must be set in a matching number, and the bits that are set in cleared must not be set in a matching number. Any bits not specified in either will be ignored when matching numbers.

The behavior of a BitPattern in which a particular bit is set in both set and cleared (i.e. set & cleared != 0) is guaranteed to be deterministic for a particular version of this crate, but should not be considered stable across versions. Presently, the bits in set take precedence over those in cleared.

See the bitpattern! macro for a simpler way to construct a constant BitPattern, or set_and_cleared for a generic (but not constant) version of this function.

impl BitPattern<i32>

pub const fn set_and_cleared_const(set: i32, cleared: i32) -> Self

Create a BitPattern by specifying the bits that must be set and cleared to match it

The bits that are set in set must be set in a matching number, and the bits that are set in cleared must not be set in a matching number. Any bits not specified in either will be ignored when matching numbers.

The behavior of a BitPattern in which a particular bit is set in both set and cleared (i.e. set & cleared != 0) is guaranteed to be deterministic for a particular version of this crate, but should not be considered stable across versions. Presently, the bits in set take precedence over those in cleared.

See the bitpattern! macro for a simpler way to construct a constant BitPattern, or set_and_cleared for a generic (but not constant) version of this function.

impl BitPattern<i64>

pub const fn set_and_cleared_const(set: i64, cleared: i64) -> Self

Create a BitPattern by specifying the bits that must be set and cleared to match it

The bits that are set in set must be set in a matching number, and the bits that are set in cleared must not be set in a matching number. Any bits not specified in either will be ignored when matching numbers.

The behavior of a BitPattern in which a particular bit is set in both set and cleared (i.e. set & cleared != 0) is guaranteed to be deterministic for a particular version of this crate, but should not be considered stable across versions. Presently, the bits in set take precedence over those in cleared.

See the bitpattern! macro for a simpler way to construct a constant BitPattern, or set_and_cleared for a generic (but not constant) version of this function.

impl BitPattern<i128>

pub const fn set_and_cleared_const(set: i128, cleared: i128) -> Self

Create a BitPattern by specifying the bits that must be set and cleared to match it

The bits that are set in set must be set in a matching number, and the bits that are set in cleared must not be set in a matching number. Any bits not specified in either will be ignored when matching numbers.

The behavior of a BitPattern in which a particular bit is set in both set and cleared (i.e. set & cleared != 0) is guaranteed to be deterministic for a particular version of this crate, but should not be considered stable across versions. Presently, the bits in set take precedence over those in cleared.

See the bitpattern! macro for a simpler way to construct a constant BitPattern, or set_and_cleared for a generic (but not constant) version of this function.

Trait Implementations

impl<T: Clone + BitPatternType> Clone for BitPattern<T>

fn clone(&self) -> BitPattern<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: BitPatternType> Debug for BitPattern<T>

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

Formats the value using the given formatter.

impl<T: BitPatternType> Display for BitPattern<T>

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

Formats the value using the given formatter.

impl<T: Hash + BitPatternType> Hash for BitPattern<T>

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

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<T: PartialEq + BitPatternType> PartialEq for BitPattern<T>

fn eq(&self, other: &BitPattern<T>) -> 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<T: Copy + BitPatternType> Copy for BitPattern<T>

impl<T: Eq + BitPatternType> Eq for BitPattern<T>

impl<T: BitPatternType> StructuralPartialEq for BitPattern<T>