flexfloat 0.1.2__py3-none-any.whl → 0.1.5__py3-none-any.whl

flexfloat/__init__.py

@@ -1,13 +1,36 @@
 """FlexFloat - A library for arbitrary precision floating point arithmetic.
 
-This package provides the FlexFloat class for handling floating-point numbers
-with growable exponents and fixed-size fractions.
+This package provides the FlexFloat class for handling floating-point numbers with
+growable exponents and fixed-size fractions. It also provides several BitArray
+implementations for efficient bit manipulation.
+
+Example:
+    from flexfloat import FlexFloat
+    x = FlexFloat(1.5, exponent_length=8, fraction_length=23)
+    print(x)
+    # Output: FlexFloat(sign=False, exponent=..., fraction=...)
+
+Modules:
+    core: Main FlexFloat class implementation
+    bitarray: BitArray implementations (bool, int64, bigint)
+    types: Type definitions
 """
 
-from .bitarray import BitArray
+from .bitarray import (
+    BigIntBitArray,
+    BitArray,
+    ListBoolBitArray,
+    ListInt64BitArray,
+)
 from .core import FlexFloat
 
-__version__ = "0.1.2"
+__version__ = "0.1.5"
 __author__ = "Ferran Sanchez Llado"
 
-__all__ = ["FlexFloat", "BitArray"]
+__all__ = [
+    "FlexFloat",
+    "BitArray",
+    "ListBoolBitArray",
+    "ListInt64BitArray",
+    "BigIntBitArray",
+]

flexfloat/bitarray/__init__.py

@@ -0,0 +1,31 @@
+"""BitArray implementation for the flexfloat package.
+
+This module provides a factory and utilities for working with different BitArray
+implementations, including:
+    - ListBoolBitArray: List of booleans (default, flexible, easy to use)
+    - ListInt64BitArray: List of int64 chunks (memory efficient for large arrays)
+    - BigIntBitArray: Single Python int (arbitrary size, efficient for very large
+        arrays)
+
+Example:
+    from flexfloat.bitarray import create_bitarray
+    ba = create_bitarray('int64', [True, False, True])
+    print(type(ba).__name__)
+    # Output: ListInt64BitArray
+"""
+
+from __future__ import annotations
+
+from .bitarray import BitArray
+from .bitarray_bigint import BigIntBitArray
+from .bitarray_bool import ListBoolBitArray
+from .bitarray_int64 import ListInt64BitArray
+from .bitarray_mixins import BitArrayCommonMixin
+
+__all__ = [
+    "BitArray",
+    "ListBoolBitArray",
+    "ListInt64BitArray",
+    "BigIntBitArray",
+    "BitArrayCommonMixin",
+]

flexfloat/bitarray/bitarray.py

@@ -0,0 +1,298 @@
+"""BitArray protocol definition for the flexfloat package.
+
+This module defines the BitArray protocol, which all BitArray implementations must
+follow. The protocol ensures a consistent interface for bit manipulation.
+
+Example:
+    from flexfloat.bitarray import BitArray
+    class MyBitArray(BitArray):
+        ...
+    my_bitarray = MyBitArray()
+    isinstance(my_bitarray, BitArray)  # True
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Iterator, Protocol, overload, runtime_checkable
+
+
+@runtime_checkable
+class BitArray(Protocol):
+    """Protocol defining the interface for BitArray implementations.
+
+    This protocol defines all the methods and properties that a BitArray
+    implementation must provide.
+
+    For consistency, all BitArray implementations should order bits as LSB-first,
+    meaning the least significant bit is at index 0 and the most significant bit
+    is at the highest index.
+    """
+
+    @classmethod
+    def from_bits(cls, bits: list[bool] | None = None) -> "BitArray":
+        """Creates a BitArray from a list of boolean values.
+
+        Args:
+            bits (list[bool] | None, optional): List of boolean values. Defaults to
+                None, which creates an empty BitArray.
+
+        Returns:
+            BitArray: A BitArray created from the bits.
+        """
+        ...
+
+    @classmethod
+    def from_float(cls, value: float) -> "BitArray":
+        """Converts 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.
+        """
+        ...
+
+    @classmethod
+    def from_signed_int(cls, value: int, length: int) -> "BitArray":
+        """Converts 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.
+        """
+        ...
+
+    @classmethod
+    def zeros(cls, length: int) -> "BitArray":
+        """Creates a BitArray filled with zeros.
+
+        Args:
+            length (int): The length of the bit array.
+
+        Returns:
+            BitArray: A BitArray filled with False values.
+        """
+        ...
+
+    @classmethod
+    def ones(cls, length: int) -> "BitArray":
+        """Creates a BitArray filled with ones.
+
+        Args:
+            length (int): The length of the bit array.
+
+        Returns:
+            BitArray: A BitArray filled with True values.
+        """
+        ...
+
+    @classmethod
+    def parse_bitarray(cls, bitstring: Iterable[str]) -> "BitArray":
+        """Parses a string of bits (with optional spaces) into a BitArray instance.
+        Non-valid characters are ignored.
+
+        Args:
+            bitstring (Iterable[str]): A string of bits, e.g., "1010 1100".
+
+        Returns:
+            BitArray: A BitArray instance created from the bit string.
+        """
+        ...
+
+    def to_float(self) -> float:
+        """Converts a 64-bit array to a floating-point number.
+
+        Returns:
+            float: The floating-point number represented by the bit array.
+
+        Raises:
+            AssertionError: If the bit array is not 64 bits long.
+        """
+        ...
+
+    def to_int(self) -> int:
+        """Converts the bit array to an unsigned integer.
+
+        Returns:
+            int: The integer represented by the bit array.
+        """
+        ...
+
+    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.
+        """
+        ...
+
+    def shift(self, shift_amount: int, fill: bool = False) -> "BitArray":
+        """Shifts the bit array left or right by a specified number of bits.
+
+        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).
+
+        Args:
+            shift_amount (int): The number of bits to shift. Positive for left shift,
+                negative for right shift.
+            fill (bool, optional): The value to fill in the new bits created by the
+                shift. Defaults to False.
+
+        Returns:
+            BitArray: A new BitArray with the bits shifted and filled.
+        """
+        ...
+
+    def copy(self) -> "BitArray":
+        """Creates a copy of the bit array.
+
+        Returns:
+            BitArray: A new BitArray with the same bits.
+        """
+        ...
+
+    def __len__(self) -> int:
+        """Returns the length of the bit array.
+
+        Returns:
+            int: The number of bits in the array.
+        """
+        ...
+
+    @overload
+    def __getitem__(self, index: int) -> bool: ...
+    @overload
+    def __getitem__(self, index: slice) -> "BitArray": ...
+
+    def __getitem__(self, index: int | slice) -> bool | BitArray:
+        """Get a bit or a slice of bits as a new BitArray."""
+        ...
+
+    @overload
+    def __setitem__(self, index: int, value: bool) -> None: ...
+    @overload
+    def __setitem__(self, index: slice, value: "BitArray" | list[bool]) -> None: ...
+
+    def __setitem__(
+        self, index: int | slice, value: bool | list[bool] | "BitArray"
+    ) -> None:
+        """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.
+        """
+        ...
+
+    def __iter__(self) -> Iterator[bool]:
+        """Iterates over the bits in the array.
+
+        Yields:
+            bool: The next bit in the array.
+        """
+        ...
+
+    def __add__(self, other: "BitArray" | list[bool]) -> "BitArray":
+        """Concatenates two bit arrays.
+
+        Args:
+            other (BitArray or list[bool]): The other bit array or list to concatenate.
+
+        Returns:
+            BitArray: The concatenated bit array.
+        """
+        ...
+
+    def __radd__(self, other: list[bool]) -> "BitArray":
+        """Reverse concatenation with a list.
+
+        Args:
+            other (list[bool]): The list to concatenate before this bit array.
+
+        Returns:
+            BitArray: The concatenated bit array.
+        """
+        ...
+
+    def __eq__(self, other: object) -> bool:
+        """Checks equality with another BitArray or list.
+
+        Args:
+            other (object): The object to compare with.
+
+        Returns:
+            bool: True if equal, False otherwise.
+        """
+        ...
+
+    def __bool__(self) -> bool:
+        """Returns True if any bit is set.
+
+        Returns:
+            bool: True if any bit is set, False otherwise.
+        """
+        ...
+
+    def __repr__(self) -> str:
+        """Returns a string representation of the BitArray.
+
+        Returns:
+            str: String representation of the BitArray.
+        """
+        ...
+
+    def __str__(self) -> str:
+        """Returns a string representation of the bits.
+
+        Returns:
+            str: String representation of the bits.
+        """
+        ...
+
+    def any(self) -> bool:
+        """Returns True if any bit is set to True.
+
+        Returns:
+            bool: True if any bit is set to True, False otherwise.
+        """
+        ...
+
+    def all(self) -> bool:
+        """Returns True if all bits are set to True.
+
+        Returns:
+            bool: True if all bits are set to True, False otherwise.
+        """
+        ...
+
+    def count(self, value: bool = True) -> int:
+        """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.
+        """
+        ...
+
+    def reverse(self) -> "BitArray":
+        """Returns a new BitArray with the bits in reverse order.
+
+        Returns:
+            BitArray: A new BitArray with the bits in reverse order.
+        """
+        ...

flexfloat/bitarray/bitarray_bigint.py

@@ -0,0 +1,305 @@
+"""Infinite-size int-based BitArray implementation for the flexfloat package.
+
+This implementation is suitable for extremely large bit arrays, leveraging Python's
+arbitrary-precision integers. Bit order: LSB-first (least significant bit at index 0).
+
+Example:
+    from flexfloat.bitarray import BigIntBitArray
+    ba = BigIntBitArray(0b1011, length=4)
+    print(list(ba))
+    # Output: [True, True, False, True]
+"""
+
+from __future__ import annotations
+
+import struct
+from typing import Iterator, overload
+
+from .bitarray import BitArray
+from .bitarray_mixins import BitArrayCommonMixin
+
+
+class BigIntBitArray(BitArrayCommonMixin):
+    """A memory-efficient bit array class using Python's infinite-size int.
+
+    This implementation stores all bits as a single Python integer, leveraging
+    Python's arbitrary precision arithmetic for potentially unlimited size.
+    Since Python integers are arbitrary precision, this can handle bit arrays
+    of any size limited only by available memory.
+    """
+
+    def __init__(self, value: int = 0, length: int = 0):
+        """Initializes a BigIntBitArray.
+
+        Args:
+            value (int, optional): Initial integer value representing the bits. Defaults
+                to 0.
+            length (int, optional): The number of bits in the array. Defaults to 0.
+
+        Raises:
+            ValueError: If length is negative.
+        """
+        super().__init__()
+        if length < 0:
+            raise ValueError("Length must be non-negative")
+        self._length: int = length
+        self._value: int = value
+
+    @classmethod
+    def from_bits(cls, bits: list[bool] | None = None) -> "BigIntBitArray":
+        """Creates a BitArray from a list of boolean values.
+
+        Args:
+            bits (list[bool] | None, optional): List of boolean values. Defaults to
+                None, which creates an empty BitArray.
+
+        Returns:
+            BigIntBitArray: A BitArray created from the bits.
+        """
+        if bits is None:
+            return cls()
+        value = 0
+
+        # Pack bits into a single integer (LSB-first)
+        # Least significant bit is at index 0
+        for i, bit in enumerate(bits):
+            if bit:
+                value |= 1 << i
+
+        return cls(value, len(bits))
+
+    @classmethod
+    def zeros(cls, length: int) -> "BigIntBitArray":
+        """Creates a BitArray filled with zeros.
+
+        Args:
+            length (int): The length of the bit array.
+
+        Returns:
+            BigIntBitArray: A BitArray filled with False values.
+        """
+        return cls(0, length)
+
+    @classmethod
+    def ones(cls, length: int) -> "BigIntBitArray":
+        """Creates a BitArray filled with ones.
+
+        Args:
+            length (int): The length of the bit array.
+
+        Returns:
+            BigIntBitArray: A BitArray filled with True values.
+        """
+        return cls((1 << length) - 1 if length > 0 else 0, length)
+
+    def _get_bit(self, index: int) -> bool:
+        """Gets a single bit at the specified index (LSB-first).
+
+        Args:
+            index (int): The bit index (LSB-first).
+
+        Returns:
+            bool: The value of the 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")
+        bit_position = index  # LSB-first
+        return bool(self._value & (1 << bit_position))
+
+    def _set_bit(self, index: int, value: bool) -> None:
+        """Sets a single bit at the specified index (LSB-first).
+
+        Args:
+            index (int): The bit index (LSB-first).
+            value (bool): The value to set.
+
+        Raises:
+            IndexError: If index is out of range.
+        """
+        if index < 0 or index >= self._length:
+            raise IndexError("Bit index out of range")
+        bit_position = index  # LSB-first
+
+        if value:
+            self._value |= 1 << bit_position
+        else:
+            self._value &= ~(1 << bit_position)
+
+    def to_float(self) -> float:
+        """Converts a 64-bit array to a floating-point number (LSB-first).
+
+        Returns:
+            float: The floating-point number represented by the bit array.
+
+        Raises:
+            AssertionError: If the bit array is not 64 bits long.
+        """
+        assert self._length == 64, "Bit array must be 64 bits long."
+
+        # Convert integer to bytes (big-endian)
+        byte_values = bytearray()
+        value = self._value
+        for i in range(8):
+            byte = (value >> (i * 8)) & 0xFF  # LSB-first
+            byte_values.append(byte)
+
+        # Unpack as double precision (64 bits)
+        float_value = struct.unpack("<d", bytes(byte_values))[0]
+        return float_value  # type: ignore
+
+    def to_int(self) -> int:
+        """Converts the bit array to an unsigned integer (LSB-first).
+
+        Returns:
+            int: The integer represented by the bit array.
+        """
+        return self._value
+
+    def copy(self) -> "BigIntBitArray":
+        """Creates a copy of the bit array.
+
+        Returns:
+            BigIntBitArray: A new BitArray with the same bits.
+        """
+        return BigIntBitArray(self._value, self._length)
+
+    def __len__(self) -> int:
+        """Returns the length of the bit array.
+
+        Returns:
+            int: The number of bits in the array.
+        """
+        return self._length
+
+    @overload
+    def __getitem__(self, index: int) -> bool: ...
+    @overload
+    def __getitem__(self, index: slice) -> BigIntBitArray: ...
+
+    def __getitem__(self, index: int | slice) -> bool | BigIntBitArray:
+        """Gets an item or slice from the bit array.
+
+        Args:
+            index (int or slice): The index or slice to retrieve.
+
+        Returns:
+            bool or BigIntBitArray: The bit value or a new BitArray for the slice.
+        """
+        if isinstance(index, int):
+            return self._get_bit(index)
+        start, stop, step = index.indices(self._length)
+        if step != 1:
+            # Handle step != 1 by extracting individual bits
+            bits: list[bool] = [self._get_bit(i) for i in range(start, stop, step)]
+        else:
+            # Efficient slice extraction for step == 1
+            bits = []
+            for i in range(start, stop):
+                bits.append(self._get_bit(i))
+        return BigIntBitArray.from_bits(bits)
+
+    @overload
+    def __setitem__(self, index: int, value: bool) -> None: ...
+    @overload
+    def __setitem__(self, index: slice, value: BitArray | list[bool]) -> None: ...
+
+    def __setitem__(
+        self, index: int | slice, value: bool | list[bool] | BitArray
+    ) -> None:
+        """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, int):
+            if not isinstance(value, bool):
+                raise TypeError("Value must be bool for single index")
+            self._set_bit(index, value)
+        else:  # slice
+            start, stop, step = index.indices(self._length)
+
+            # Convert value to list of bools
+            if isinstance(value, bool):
+                raise TypeError("Cannot assign bool to slice")
+            if not hasattr(value, "__iter__"):
+                raise TypeError("Value must be iterable for slice assignment")
+            value_list = list(value)
+
+            if step != 1:
+                # Handle step != 1
+                indices = list(range(start, stop, step))
+                if len(value_list) != len(indices):
+                    raise ValueError("Value length doesn't match slice length")
+                for i, v in zip(indices, value_list):
+                    self._set_bit(i, bool(v))
+            else:
+                # Handle step == 1
+                if len(value_list) != (stop - start):
+                    raise ValueError("Value length doesn't match slice length")
+                for i, v in enumerate(value_list):
+                    self._set_bit(start + i, bool(v))
+
+    def __iter__(self) -> Iterator[bool]:
+        """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]) -> "BigIntBitArray":
+        """Concatenates two bit arrays.
+
+        Args:
+            other (BitArray or list[bool]): The other bit array or list to concatenate.
+
+        Returns:
+            BigIntBitArray: The concatenated bit array.
+
+        Raises:
+            TypeError: If other is not iterable.
+        """
+        if hasattr(other, "__iter__"):
+            other_bits = list(other)
+        else:
+            raise TypeError("Can only concatenate with iterable")
+
+        all_bits = list(self) + other_bits
+        return BigIntBitArray.from_bits(all_bits)
+
+    def __radd__(self, other: list[bool]) -> "BigIntBitArray":
+        """Reverse concatenation with a list.
+
+        Args:
+            other (list[bool]): The list to concatenate before this bit array.
+
+        Returns:
+            BigIntBitArray: The concatenated bit array.
+
+        Raises:
+            TypeError: If other is not iterable.
+        """
+        if hasattr(other, "__iter__"):
+            other_bits = list(other)
+        else:
+            raise TypeError("Can only concatenate with iterable")
+
+        all_bits = other_bits + list(self)
+        return BigIntBitArray.from_bits(all_bits)
+
+    def __repr__(self) -> str:
+        """Returns a string representation of the BitArray.
+
+        Returns:
+            str: String representation of the BitArray.
+        """
+        return f"BigIntBitArray({list(self)})"