jam.types.base.bit module
jam.types.base.bit
Bit type implementation for the JAM protocol.
Type Definition
Bit
Single bit value (0/1)
Used in bit sequences
Packed bit storage
No alignment requirements
Encoding Format
Single Bit:
0 -> [0] # LSB of byte
1 -> [1] # LSB of byte
Bit Sequences:
[b0 b1 b2 b3 b4 b5 b6 b7] # Packed into bytes
LSB first within each byte
Implementation Details
Memory Layout
Single bit storage
Packed into bytes
LSB first ordering
No padding bits
Bit Operations
Bit masking
Bit shifting
Bit counting
Bit packing/unpacking
Error Handling
Common error cases:
Invalid value:
if value not in (0, 1): raise ValueError(f"Invalid bit value: {value}")
Buffer underflow:
if len(buffer) - offset < 1: raise BufferError("Need 1 byte for bit")
Position overflow:
if bit_position >= 8: raise ValueError(f"Invalid bit position: {bit_position}")
Examples
Basic Usage
from jam.types.base.bit import Bit
# Create and encode
value = Bit(1)
encoded = value.encode() # -> [01]
value = Bit(0)
encoded = value.encode() # -> [00]
# Decode
decoded = Bit.decode(encoded)
assert decoded == 0
Bit Sequences
from jam.types.base.sequences import BitArray
from jam.types.base.bit import Bit
# Create 8-bit sequence
bits = BitArray[8]([
Bit(1), Bit(0), Bit(1), Bit(0),
Bit(1), Bit(0), Bit(1), Bit(0)
])
# Encode: packed bits
encoded = bits.encode() # -> [AA] # 10101010
# Decode
decoded = BitArray[8].decode(encoded)
assert [bit.value for bit in decoded] == [1,0,1,0,1,0,1,0]
Custom Types
from dataclasses import dataclass
from jam.types.base.bit import Bit, decodable_bit
@decodable_bit
@dataclass
class Flag:
value: int # 0 or 1
# Create and encode
flag = Flag(1)
encoded = flag.encode() # -> [01]
# Decode
decoded = Flag.decode(encoded)
assert decoded.value == 1