direct_bit_access_operations.rs

Overview

This file provides functionality for direct bit-level access and manipulation on the AccountAddress type. It defines the DirectBitAccess trait, which exposes methods to get and set individual bits by index within a 256-bit address space. This capability is essential for low-level operations where bit-level control is necessary, such as encoding flags or performing bitmask operations on addresses.

The implementation ensures bounds checking for valid bit indices (0 to 255) and panics if an invalid index is accessed, reflecting strict enforcement of address size constraints.

Trait: DirectBitAccess

The DirectBitAccess trait declares two primary methods for bit manipulation:

Methods

get_bit_value(&self, index: usize) -> bool

• Purpose: Returns the boolean value (true or false) of a bit at a specific index in the underlying bit sequence.

• Parameters:

  • index: The zero-based bit position (0 ≤ index < 256).

• Returns: true if the bit is set (1); otherwise, false.

• Panics: If index is outside the valid range [0, 255], it panics with "index out of bounds".

• Usage Example:

let bit = account_address.get_bit_value(5);
if bit {
    // bit 5 is set
}

set_bit_value(&mut self, index: usize, value: bool)

• Purpose: Sets the bit at the specified index to the given boolean value.

• Parameters:

  • index: The zero-based bit position (0 ≤ index < 256).

  • value: The boolean to set at index. Currently, this method only supports setting bits to true and asserts accordingly.

• Panics:

  • If index is outside the valid range [0, 255], it panics with "index out of bounds".

  • If value is false, it asserts and panics with "set_bit_value: value must be true".

• Usage Note: The value parameter is presently redundant as only setting bits to true is supported.

• Usage Example:

account_address.set_bit_value(10, true);

Implementation Details for AccountAddress

• The AccountAddress type is assumed to wrap a fixed-size 32-byte array ([u8; 32]), representing 256 bits.

• Bits are accessed in big-endian order within each byte:

  • For get_bit_value, the bit is extracted by shifting the relevant byte right by (7 - (index % 8)) and masking the least significant bit.

  • For set_bit_value, the bit is set by bitwise OR-ing the target byte with a mask that sets the bit at position (7 - (index % 8)).

• The index is divided into hi (byte index) and lo (bit index within byte) components.

Algorithm for Bit Access

1. Calculate byte index (hi): index / 8

2. Calculate bit position (lo): index % 8

3. For getting the bit:

   • Retrieve byte at hi.

   • Shift right by (7 - lo).

   • Mask with 0x1 to isolate the bit.

4. For setting the bit:

   • Retrieve mutable copy of internal byte array.

   • Use bitwise OR with 1 << (7 - lo) to set the bit.

   • Update the internal array.

Interaction with Other Components

• This file depends on the AccountAddress type, which is imported from its parent module via super::AccountAddress.

• The trait DirectBitAccess is implemented specifically for AccountAddress, enabling bit-level operations on addresses.

• Other components that work with AccountAddress can utilize this trait to perform efficient and direct bit manipulations without needing to handle byte arrays manually.

• This low-level interface can support higher-level logic for address filtering, flag encoding, or cryptographic operations where individual bits of an address are significant.

Testing

• The tests module verifies correctness and boundary conditions of get_bit_value and set_bit_value.

• Tests include:

  • Setting a bit and verifying only that bit is set.

  • Panic checks for out-of-bound bit indices on both getter and setter.

  • Setting bits at the highest indices (254, 255) to check boundary conditions.

• These tests ensure robustness of bitwise operations and index validation.

Mermaid Diagram: Function Flowchart

flowchart TD
A[DirectBitAccess Trait]
A --> B[get_bit_value]
A --> C[set_bit_value]
B --> D[Check index < 256]
D -->|valid| E[Calculate hi = index / 8]
E --> F[Calculate lo = index % 8]
F --> G[Extract bit from byte array]
D -->|invalid| H[panic "index out of bounds"]
C --> I[Assert value == true]
I --> J[Check index < 256]
J -->|valid| K[Calculate hi = index / 8]
K --> L["Calculate lo = 7 - (index % 8)"]
L --> M[Set bit in byte array]
J -->|invalid| N[panic "index out of bounds"]

This flowchart illustrates the decision points and key steps in the get_bit_value and set_bit_value methods of the DirectBitAccess trait implementation for AccountAddress. It highlights index validation, bit position calculation, and bit retrieval or setting processes.