mask.rs

Overview

This file defines a generic Bitmask struct that provides functionality to perform bitwise masking operations on a given bit source type TBitsSource. It encapsulates a mask and a meaningful mask, allowing selective comparison of bits for matching purposes. This is useful in scenarios requiring filtering or matching entities based on specific bit patterns, such as permissions, flags, or address matching.

The Bitmask struct supports generic bit sources as long as they implement certain bitwise and cloning traits. It implements methods to check if a given bit source matches the mask under the constraints of the meaningful mask bits.

Structs and Implementations

`Bitmask<TBitsSource>`

A generic container that holds two bitmasks:

mask_bits: The bit pattern to match against.
meaningful_mask_bits: The bit positions that are significant for the match.

Type Parameters

TBitsSource: The underlying bit storage type (e.g., integer types like u8, u16, u64). Must implement cloning, default, partial equality, and bitwise AND operations.

Derives

TypedBuilder: Enables a builder pattern for constructing instances.
Clone, Default, Debug, Eq, PartialEq, Serialize, Deserialize: Standard traits for cloning, default construction, debug printing, equality comparisons, and (de)serialization support.

Fields

Field	Type	Description
`mask_bits`	`TBitsSource`	Bit values that represent the mask pattern.
`meaningful_mask_bits`	`TBitsSource`	Bit positions that are considered meaningful in the mask. Bits outside this mask are ignored in comparisons.

Methods

is_match(&self, account_address: &TBitsSource) -> bool
Checks if the provided account_address matches the mask considering only the meaningful bits.
Parameters:
- account_address: Reference to a bit source instance to compare against the mask.
Returns:
- true if the bits in account_address masked by meaningful_mask_bits exactly match mask_bits masked by meaningful_mask_bits.
- false otherwise.
Usage Example:
```
let mask = Bitmask::<u8>::builder()
    .mask_bits(0b0101_0001)
    .meaningful_mask_bits(0b1111_0000)
    .build();

let address = 0b0101_0011;
assert!(mask.is_match(&address)); // matches on meaningful bits
```
mask_bits(&self) -> &TBitsSource
Returns a reference to the stored mask_bits.
meaningful_mask_bits(&self) -> &TBitsSource
Returns a reference to the stored meaningful_mask_bits.

Implementation Details

The is_match method uses bitwise AND to isolate the meaningful bits in both the stored mask and the input address. It then compares these masked values for equality. This design allows bits outside the meaningful mask to be ignored, enabling flexible partial matching of bit patterns.

The trait bounds on TBitsSource ensure that bitwise AND and cloning operations are supported on the references to the bit source, facilitating generic usage with types that represent bitfields.

`fmt::Display` Implementation for `Bitmask<TBitsSource>` (Test-Only)

An inefficient but convenient Display trait implementation exists in the test module for debugging purposes. It prints the mask as a string of bits where:

'1' represents a meaningful bit set to 1.
'0' represents a meaningful bit set to 0.
'*' represents a bit position that is not meaningful.

This makes the bitmask human-readable during testing.

Test Module

The tests module includes unit tests to verify the correctness of the Bitmask's behavior:

default_mask_matches_any: Tests that a default mask (all zeroes) matches any address because no meaningful bits are set.
full_match_returns_true: Tests that a mask with all meaningful bits set (!0) matches exactly the same bit pattern.
single_non_matching_bit_fails_match: Tests that if a meaningful bit differs, the match fails.
meaningless_non_matching_bits_are_ignored_in_matches: Tests that differences in bits outside the meaningful mask do not affect matching.

These tests use integer types (u8, u16, u64) to exercise the generic implementation.

Interaction with Other System Components

This file is focused on bitmask matching logic and is designed to be generic over bit source types. It can be used wherever bitwise filtering or matching is required, such as:

Address filtering or access control based on bit flags.
Feature flags or permissions encoded as bits.
Mask-based classification or routing.

No direct dependencies on other application-specific modules are present in this file, but it likely interacts with components that require bit pattern matching or filtering.

Key Algorithms and Concepts

Bitwise Masking: Uses bitwise AND to isolate significant bits and compare them.
Generic Programming: Abstracts over any bit source type that supports required bitwise operations.
Selective Bit Matching: Only bits marked as meaningful affect the matching outcome, allowing flexible partial matches.

Diagram: `Bitmask` Struct and Method Overview

classDiagram
class Bitmask {
-mask_bits
-meaningful_mask_bits
+is_match()
+mask_bits()
+meaningful_mask_bits()
}

This diagram shows the Bitmask struct encapsulating two private fields representing bit patterns and three public methods: is_match for matching logic, and accessors for the stored masks.