flexfloat 0.1.3__py3-none-any.whl → 0.3.0__py3-none-any.whl

flexfloat/bitarray/bitarray_int64.py

@@ -1,4 +1,14 @@
-"""Memory-efficient int64-based BitArray implementation for the flexfloat package."""
+"""Memory-efficient int64-based BitArray implementation for the flexfloat package.
+
+This implementation is ideal for large bit arrays, as it packs 64 bits per integer.
+Bit order: LSB-first (least significant bit at index 0, increasing to MSB).
+
+Example:
+    from flexfloat.bitarray import ListInt64BitArray
+    ba = ListInt64BitArray([0b10101010], length=8)
+    print(list(ba))
+    # Output: [False, True, False, True, False, True, False, True]
+"""
 
 from __future__ import annotations
 
@@ -9,129 +19,123 @@ from .bitarray import BitArray
 from .bitarray_mixins import BitArrayCommonMixin
 
 
-class Int64BitArray(BitArrayCommonMixin):
+class ListInt64BitArray(BitArrayCommonMixin):
     """A memory-efficient bit array class using a list of int64 values.
 
     This implementation packs 64 bits per integer, making it more memory efficient
     for large bit arrays compared to the boolean list implementation.
     """
 
-    def __init__(self, bits: list[bool] | None = None):
-        """Initialize a BitArray.
+    def __init__(self, chunks: list[int] | None = None, length: int = 0):
+        """Initializes a ListInt64BitArray.
 
         Args:
-            bits: Initial list of boolean values. Defaults to empty list.
+            chunks (list[int] | None, optional): Initial list of int64 chunks. Defaults
+                to empty list.
+            length (int, optional): The amount of bits in the array. Defaults to 0.
+
+        Raises:
+            ValueError: If length is negative.
         """
-        if bits is None:
-            bits = []
+        super().__init__()
+        chunks = chunks or []
+        if length < 0:
+            raise ValueError("Length must be non-negative")
+        self._length: int = length
+        self._chunks: list[int] = chunks
 
-        self._length = len(bits)
-        # Pack bits into int64 chunks (64 bits per int)
-        self._chunks: list[int] = []
+    @classmethod
+    def from_bits(cls, bits: list[bool] | None = None) -> "ListInt64BitArray":
+        """Creates a BitArray from a list of boolean values.
+
+        Args:
+            bits (list[bool] | None, optional): List of boolean values in LSB-first
+                order. Defaults to None, which creates an empty BitArray.
+
+        Returns:
+            ListInt64BitArray: A BitArray created from the bits.
+        """
+        if bits is None:
+            return cls()
+        chunks: list[int] = []
 
         for i in range(0, len(bits), 64):
             chunk = 0
             chunk_end = min(i + 64, len(bits))
             for j in range(i, chunk_end):
                 if bits[j]:
-                    chunk |= 1 << (63 - (j - i))
-            self._chunks.append(chunk)
+                    chunk |= 1 << (j - i)
+            chunks.append(chunk)
+
+        return cls(chunks, len(bits))
 
     @classmethod
-    def zeros(cls, length: int) -> Int64BitArray:
-        """Create a BitArray filled with zeros.
+    def zeros(cls, length: int) -> "ListInt64BitArray":
+        """Creates a BitArray filled with zeros.
 
         Args:
-            length: The length of the bit array.
+            length (int): The length of the bit array.
+
         Returns:
-            Int64BitArray: A BitArray filled with False values.
+            ListInt64BitArray: A BitArray filled with False values.
         """
-        instance = cls.__new__(cls)
-        instance._length = length
-        instance._chunks = [0] * ((length + 63) // 64)
-        return instance
+        return cls([0] * ((length + 63) // 64), length)
 
     @classmethod
-    def ones(cls, length: int) -> Int64BitArray:
-        """Create a BitArray filled with ones.
+    def ones(cls, length: int) -> "ListInt64BitArray":
+        """Creates a BitArray filled with ones.
 
         Args:
-            length: The length of the bit array.
+            length (int): The length of the bit array.
+
         Returns:
-            Int64BitArray: A BitArray filled with True values.
+            ListInt64BitArray: A BitArray filled with True values.
         """
-        instance = cls.__new__(cls)
-        instance._length = length
-        num_full_chunks = length // 64
-        remaining_bits = length % 64
-
-        instance._chunks = []
-
-        # Add full chunks of all 1s
-        for _ in range(num_full_chunks):
-            instance._chunks.append(0xFFFFFFFFFFFFFFFF)  # All 64 bits set
+        chunks = [0xFFFFFFFFFFFFFFFF] * (length // 64)
+        if length % 64 > 0:
+            partial_chunk = (1 << (length % 64)) - 1
+            chunks.append(partial_chunk)
+        return cls(chunks, length)
 
-        # Add partial chunk if needed
-        if remaining_bits > 0:
-            partial_chunk = (1 << remaining_bits) - 1
-            partial_chunk <<= 64 - remaining_bits  # Left-align the bits
-            instance._chunks.append(partial_chunk)
+    def _get_bit(self, index: int) -> bool:
+        """Gets a single bit at the specified index (LSB-first).
 
-        return instance
+        Args:
+            index (int): The bit index (LSB-first).
 
-    @staticmethod
-    def parse_bitarray(bitstring: str) -> Int64BitArray:
-        """Parse a string of bits (with optional spaces) into a BitArray instance."""
-        bits = [c == "1" for c in bitstring if c in "01"]
-        return Int64BitArray(bits)
+        Returns:
+            bool: The value of the bit at the specified index.
 
-    def _get_bit(self, index: int) -> bool:
-        """Get a single bit at the specified index."""
+        Raises:
+            IndexError: If index is out of range.
+        """
         if index < 0 or index >= self._length:
             raise IndexError("Bit index out of range")
-
         chunk_index = index // 64
         bit_index = index % 64
-        bit_position = 63 - bit_index  # Left-aligned
-
+        bit_position = bit_index  # LSB-first
         return bool(self._chunks[chunk_index] & (1 << bit_position))
 
     def _set_bit(self, index: int, value: bool) -> None:
-        """Set a single bit at the specified index."""
-        if index < 0 or index >= self._length:
-            raise IndexError("Bit index out of range")
-
-        chunk_index = index // 64
-        bit_index = index % 64
-        bit_position = 63 - bit_index  # Left-aligned
-
-        if value:
-            self._chunks[chunk_index] |= 1 << bit_position
-        else:
-            self._chunks[chunk_index] &= ~(1 << bit_position)
+        """Sets a single bit at the specified index (LSB-first).
 
-    def to_float(self) -> float:
-        """Convert a 64-bit array to a floating-point number.
+        Args:
+            index (int): The bit index (LSB-first).
+            value (bool): The value to set.
 
-        Returns:
-            float: The floating-point number represented by the bit array.
         Raises:
-            AssertionError: If the bit array is not 64 bits long.
+            IndexError: If index is out of range.
         """
-        assert self._length == 64, "Bit array must be 64 bits long."
-
-        # Convert first chunk directly to bytes
-        chunk = self._chunks[0]
-        byte_values = bytearray()
-        for i in range(8):
-            byte = (chunk >> (56 - i * 8)) & 0xFF
-            byte_values.append(byte)
-
-        # Unpack as double precision (64 bits)
-        return struct.unpack("!d", bytes(byte_values))[0]  # type: ignore
+        if index < 0 or index >= self._length:
+            raise IndexError("Bit index out of range")
+        chunk_index = index // 64
+        bit_index = index % 64
+        bit_position = bit_index  # LSB-first
+        mask = 1 << bit_position
+        self._chunks[chunk_index] ^= (-value ^ self._chunks[chunk_index]) & mask
 
     def to_int(self) -> int:
-        """Convert the bit array to an unsigned integer.
+        """Converts the bit array to an unsigned integer (LSB-first).
 
         Returns:
             int: The integer represented by the bit array.
@@ -139,83 +143,54 @@ class Int64BitArray(BitArrayCommonMixin):
         result = 0
         for i in range(self._length):
             if self._get_bit(i):
-                result |= 1 << (self._length - 1 - i)
+                result |= 1 << i
         return result
 
-    def to_signed_int(self) -> int:
-        """Convert a bit array into a signed integer using off-set binary
-        representation.
+    def to_float(self) -> float:
+        """Converts a 64-bit array to a floating-point number (LSB-first).
 
         Returns:
-            int: The signed integer represented by the bit array.
+            float: The floating-point number represented by the bit array.
+
         Raises:
-            AssertionError: If the bit array is empty.
+            AssertionError: If the bit array is not 64 bits long.
         """
-        assert self._length > 0, "Bit array must not be empty."
-
-        int_value = self.to_int()
-        # Half of the maximum value
-        bias = 1 << (self._length - 1)
-        # If the sign bit is set, subtract the bias
-        return int_value - bias
-
-    def shift(self, shift_amount: int, fill: bool = False) -> Int64BitArray:
-        """Shift the bit array left or right by a specified number of bits.
+        assert self._length == 64, "Bit array must be 64 bits long."
+        chunk = self._chunks[0]
+        byte_values = bytearray()
+        for i in range(8):
+            byte = (chunk >> (i * 8)) & 0xFF  # LSB-first
+            byte_values.append(byte)
+        float_value = struct.unpack("<d", bytes(byte_values))[0]
+        return float_value  # type: ignore
 
-        This function shifts the bits in the array, filling in new bits with the
-        specified fill value.
-        If the value is positive, it shifts left; if negative, it shifts right.
-        Fills the new bits with the specified fill value (default is False).
+    def copy(self) -> "ListInt64BitArray":
+        """Creates a copy of the bit array.
 
-        Args:
-            shift_amount (int): The number of bits to shift. Positive for left shift,
-                negative for right shift.
-            fill (bool): The value to fill in the new bits created by the shift.
-                Defaults to False.
         Returns:
-            Int64BitArray: A new BitArray with the bits shifted and filled.
+            ListInt64BitArray: A new BitArray with the same bits.
         """
-        if shift_amount == 0:
-            return self.copy()
-
-        # Convert to bit list for simplicity (can be optimized later)
-        bits = list(self)
-
-        if abs(shift_amount) > len(bits):
-            new_bits = [fill] * len(bits)
-        elif shift_amount > 0:
-            new_bits = [fill] * shift_amount + bits[:-shift_amount]
-        else:
-            new_bits = bits[-shift_amount:] + [fill] * (-shift_amount)
+        return ListInt64BitArray(self._chunks.copy(), self._length)
 
-        return Int64BitArray(new_bits)
-
-    def copy(self) -> Int64BitArray:
-        """Create a copy of the bit array.
+    def __len__(self) -> int:
+        """Returns the length of the bit array.
 
         Returns:
-            Int64BitArray: A new BitArray with the same bits.
+            int: The number of bits in the array.
         """
-        instance = Int64BitArray.__new__(Int64BitArray)
-        instance._length = self._length
-        instance._chunks = self._chunks.copy()  # This creates a shallow copy
-        return instance
-
-    def __len__(self) -> int:
-        """Return the length of the bit array."""
         return self._length
 
     @overload
     def __getitem__(self, index: int) -> bool: ...
     @overload
-    def __getitem__(self, index: slice) -> Int64BitArray: ...
+    def __getitem__(self, index: slice) -> "ListInt64BitArray": ...
 
-    def __getitem__(self, index: int | slice) -> bool | Int64BitArray:
-        """Get an item or slice from the bit array."""
+    def __getitem__(self, index: int | slice) -> bool | ListInt64BitArray:
+        """Get a bit or a slice of bits as a new ListInt64BitArray."""
         if isinstance(index, slice):
             start, stop, step = index.indices(self._length)
             bits = [self._get_bit(i) for i in range(start, stop, step)]
-            return Int64BitArray(bits)
+            return ListInt64BitArray.from_bits(bits)
         return self._get_bit(index)
 
     @overload
@@ -226,7 +201,16 @@ class Int64BitArray(BitArrayCommonMixin):
     def __setitem__(
         self, index: int | slice, value: bool | list[bool] | BitArray
     ) -> None:
-        """Set an item or slice in the bit array."""
+        """Sets an item or slice in the bit array.
+
+        Args:
+            index (int or slice): The index or slice to set.
+            value (bool or list[bool] or BitArray): The value(s) to assign.
+
+        Raises:
+            TypeError: If value type does not match index type.
+            ValueError: If value length does not match slice length.
+        """
         if isinstance(index, slice):
             start, stop, step = index.indices(self._length)
             indices = list(range(start, stop, step))
@@ -251,22 +235,47 @@ class Int64BitArray(BitArrayCommonMixin):
             raise TypeError("Cannot assign a list or BitArray to a single index")
 
     def __iter__(self) -> Iterator[bool]:
-        """Iterate over the bits in the array."""
+        """Iterates over the bits in the array.
+
+        Yields:
+            bool: The next bit in the array.
+        """
         for i in range(self._length):
             yield self._get_bit(i)
 
-    def __add__(self, other: BitArray | list[bool]) -> Int64BitArray:
-        """Concatenate two bit arrays."""
+    def __add__(self, other: BitArray | list[bool]) -> "ListInt64BitArray":
+        """Concatenates two bit arrays.
+
+        Args:
+            other (BitArray or list[bool]): The other bit array or list to concatenate.
+
+        Returns:
+            ListInt64BitArray: The concatenated bit array.
+        """
         if isinstance(other, BitArray):
-            return Int64BitArray(list(self) + list(other))
-        return Int64BitArray(list(self) + other)
+            return ListInt64BitArray.from_bits(list(self) + list(other))
+        return ListInt64BitArray.from_bits(list(self) + other)
 
-    def __radd__(self, other: list[bool]) -> Int64BitArray:
-        """Reverse concatenation with a list."""
-        return Int64BitArray(other + list(self))
+    def __radd__(self, other: list[bool]) -> "ListInt64BitArray":
+        """Reverse concatenation with a list.
+
+        Args:
+            other (list[bool]): The list to concatenate before this bit array.
+
+        Returns:
+            ListInt64BitArray: The concatenated bit array.
+        """
+        return ListInt64BitArray.from_bits(other + list(self))
 
     def __eq__(self, other: object) -> bool:
-        """Check equality with another BitArray or list."""
+        """Checks equality with another BitArray or list.
+
+        Args:
+            other (object): The object to compare with.
+
+        Returns:
+            bool: True if equal, False otherwise.
+        """
         if isinstance(other, BitArray):
             if len(self) != len(other):
                 return False
@@ -276,19 +285,35 @@ class Int64BitArray(BitArrayCommonMixin):
         return False
 
     def __bool__(self) -> bool:
-        """Return True if any bit is set."""
+        """Returns True if any bit is set.
+
+        Returns:
+            bool: True if any bit is set, False otherwise.
+        """
         return any(chunk != 0 for chunk in self._chunks)
 
     def __repr__(self) -> str:
-        """Return a string representation of the BitArray."""
-        return f"Int64BitArray({list(self)})"
+        """Returns a string representation of the BitArray.
+
+        Returns:
+            str: String representation of the BitArray.
+        """
+        return f"ListInt64BitArray({list(self)})"
 
     def any(self) -> bool:
-        """Return True if any bit is set to True."""
+        """Returns True if any bit is set to True.
+
+        Returns:
+            bool: True if any bit is set to True, False otherwise.
+        """
         return any(chunk != 0 for chunk in self._chunks)
 
     def all(self) -> bool:
-        """Return True if all bits are set to True."""
+        """Returns True if all bits are set to True.
+
+        Returns:
+            bool: True if all bits are set to True, False otherwise.
+        """
         if self._length == 0:
             return True
 
@@ -301,7 +326,7 @@ class Int64BitArray(BitArrayCommonMixin):
         # Check partial chunk if exists
         remaining_bits = self._length % 64
         if remaining_bits > 0:
-            expected_pattern = ((1 << remaining_bits) - 1) << (64 - remaining_bits)
+            expected_pattern = (1 << remaining_bits) - 1
             if self._chunks[-1] != expected_pattern:
                 return False
 

flexfloat/bitarray/bitarray_mixins.py

@@ -1,9 +1,20 @@
-"""Mixin classes providing common BitArray functionality."""
+"""Mixin classes providing common BitArray functionality.
+
+This module provides mixins for BitArray implementations, offering default methods that
+rely on the BitArray protocol. Bit order is always LSB-first.
+
+Example:
+    class MyBitArray(BitArrayCommonMixin):
+        ... # implement BitArray protocol methods
+    ba = MyBitArray.from_bits([True, False])
+    print(list(ba))
+    # Output: [True, False]
+"""
 
 from __future__ import annotations
 
 import struct
-from typing import Any
+from typing import Any, Iterable
 
 from .bitarray import BitArray
 
@@ -12,39 +23,24 @@ class BitArrayCommonMixin(BitArray):
     """Mixin providing common methods that can be implemented using the BitArray
     protocol.
 
-    This mixin provides default implementations for methods that can be expressed
-    in terms of the core BitArray protocol methods (__iter__, __len__, etc.).
+    Bit order: LSB-first (least significant bit at index 0, increasing to MSB).
+
+    This mixin provides default implementations for methods that can be expressed in
+    terms of the core BitArray protocol methods (__iter__, __len__, etc.).
 
     Classes using this mixin must implement the BitArray protocol.
     """
 
     @classmethod
-    def from_float(cls, value: float) -> Any:
-        """Convert a floating-point number to a bit array.
-
-        Args:
-            value (float): The floating-point number to convert.
-        Returns:
-            BitArray: A BitArray representing the bits of the floating-point number.
-        """
-        # Pack as double precision (64 bits)
-        packed = struct.pack("!d", value)
-        # Convert to boolean list
-        bits = [bool((byte >> bit) & 1) for byte in packed for bit in range(7, -1, -1)]
-        return cls(bits)
+    def from_float(cls, value: float) -> BitArray:
+        """Create a BitArray from a float value."""
+        packed = struct.pack("<d", value)
+        bits = [bool((byte >> bit) & 1) for byte in packed for bit in range(8)]
+        return cls.from_bits(bits)
 
     @classmethod
-    def from_signed_int(cls, value: int, length: int) -> Any:
-        """Convert a signed integer to a bit array using off-set binary representation.
-
-        Args:
-            value (int): The signed integer to convert.
-            length (int): The length of the resulting bit array.
-        Returns:
-            BitArray: A BitArray representing the bits of the signed integer.
-        Raises:
-            AssertionError: If the value is out of range for the specified length.
-        """
+    def from_signed_int(cls, value: int, length: int) -> BitArray:
+        """Create a BitArray from a signed integer value."""
         half = 1 << (length - 1)
         max_value = half - 1
         min_value = -half
@@ -53,19 +49,33 @@ class BitArrayCommonMixin(BitArray):
             min_value <= value <= max_value
         ), "Value out of range for specified length."
 
-        # Convert to unsigned integer representation
-        unsigned_value = value - half
+        unsigned_value = value + half
+        bits = [(unsigned_value >> i) & 1 == 1 for i in range(length)]
+        return cls.from_bits(bits)
 
-        bits = [(unsigned_value >> i) & 1 == 1 for i in range(length - 1, -1, -1)]
-        return cls(bits)
+    @classmethod
+    def parse_bitarray(cls, bitstring: Iterable[str]) -> BitArray:
+        """Parses a string of bits (with optional spaces) into a BitArray instance."""
+        return cls.from_bits([c == "1" for c in bitstring if c in "01"])
 
     def __str__(self) -> str:
-        """Return a string representation of the bits."""
-        # This assumes self implements __iter__ as per the BitArray protocol
-        return "".join("1" if bit else "0" for bit in self)  # type: ignore
+        """Returns a string representation of the bits (LSB-first, index 0 is
+        rightmost).
+
+        Returns:
+            str: String representation of the bits.
+        """
+        return "".join("1" if bit else "0" for bit in reversed(list(self)))
+
+    def __eq__(self, other: Any) -> bool:
+        """Checks equality with another BitArray or list.
 
-    def __eq__(self, other: object) -> bool:
-        """Check equality with another BitArray or list."""
+        Args:
+            other (Any): The object to compare with.
+
+        Returns:
+            bool: True if equal, False otherwise.
+        """
         if hasattr(other, "__iter__") and hasattr(other, "__len__"):
             if len(self) != len(other):  # type: ignore
                 return False
@@ -73,21 +83,74 @@ class BitArrayCommonMixin(BitArray):
         return False
 
     def __bool__(self) -> bool:
-        """Return True if any bit is set."""
+        """Returns True if any bit is set.
+
+        Returns:
+            bool: True if any bit is set, False otherwise.
+        """
         return self.any()
 
     def any(self) -> bool:
-        """Return True if any bit is set to True."""
-        return any(self)  # type: ignore
+        """Returns True if any bit is set to True.
+
+        Returns:
+            bool: True if any bit is set to True, False otherwise.
+        """
+        return any(self)
 
     def all(self) -> bool:
-        """Return True if all bits are set to True."""
-        return all(self)  # type: ignore
+        """Returns True if all bits are set to True.
+
+        Returns:
+            bool: True if all bits are set to True, False otherwise.
+        """
+        return all(self)
 
     def count(self, value: bool = True) -> int:
-        """Count the number of bits set to the specified value."""
-        return sum(1 for bit in self if bit == value)  # type: ignore
+        """Counts the number of bits set to the specified value.
+
+        Args:
+            value (bool, optional): The value to count. Defaults to True.
+
+        Returns:
+            int: The number of bits set to the specified value.
+        """
+        return sum(1 for bit in self if bit == value)
+
+    def reverse(self) -> BitArray:
+        """Returns a new BitArray with the bits in reverse order."""
+        return self.from_bits(list(reversed(self)))
+
+    def to_signed_int(self) -> int:
+        """Converts a bit array into a signed integer using off-set binary
+        representation.
+
+        Returns:
+            int: The signed integer represented by the bit array.
+
+        Raises:
+            AssertionError: If the bit array is empty.
+        """
+        assert len(self) > 0, "Bit array must not be empty."
+
+        int_value: int = self.to_int()
+        # Half of the maximum value
+        bias = 1 << (len(self) - 1)
+        # Subtract the bias to get the signed value
+        return int_value - bias
+
+    def shift(self, shift_amount: int, fill: bool = False) -> BitArray:
+        """Shifts the bit array left or right by a specified number of bits."""
+        if shift_amount == 0:
+            return self.copy()
+
+        bits = list(self)
+
+        if abs(shift_amount) > len(bits):
+            new_bits = [fill] * len(bits)
+        elif shift_amount > 0:  # Right shift
+            new_bits = bits[shift_amount:] + [fill] * shift_amount
+        else:  # Left shift
+            new_bits = [fill] * (-shift_amount) + bits[:shift_amount]
 
-    def reverse(self) -> Any:
-        """Return a new BitArray with the bits in reverse order."""
-        return self.__class__(list(self)[::-1])  # type: ignore
+        return self.from_bits(new_bits)