Core API

This section documents the core FlexFloat class and its methods.

FlexFloat Class

class flexfloat.FlexFloat(sign=False, exponent=None, fraction=None)[source]

Bases: object

A class to represent a floating-point number with growable exponent and fixed-size fraction. This class is designed to handle very large or very small numbers by adjusting the exponent dynamically. While keeping the mantissa (fraction) fixed in size.

This class follows the IEEE 754 double-precision floating-point format, but extends it to allow for a growable exponent and a fixed-size fraction.

sign

The sign of the number (True for negative, False for positive).

Type:: bool

exponent

A growable bit array representing the exponent (uses off-set binary representation).

Type:: BitArray

fraction

A fixed-size bit array representing the fraction (mantissa) of the number.

Type:: BitArray

classmethod set_bitarray_implementation(implementation)[source]

Set the BitArray implementation to use for all FlexFloat instances.

Parameters:: implementation (Type[BitArray]) – The BitArray implementation class to use.

__init__(sign=False, exponent=None, fraction=None)[source]

Initializes a FlexFloat instance.

BitArrays are expected to be LSB-first (least significant bit at index 0, increasing to MSB).

Parameters:

sign (bool, optional) – The sign of the number (True for negative, False for positive). Defaults to False.
exponent (BitArray | None, optional) – The exponent bit array. If None, represents 0. Defaults to None.
fraction (BitArray | None, optional) – The fraction bit array. If None, represents 0. Defaults to None.

sign: bool: The sign of the number (True for negative, False for positive).

exponent: BitArray: A growable bit array representing the exponent (uses off-set binary representation).

fraction: BitArray: A fixed-size bit array representing the fraction (mantissa) of the number.

classmethod from_float(value)[source]

Creates a FlexFloat instance from a number.

Parameters:: value (Number) – The number to convert to FlexFloat.
Returns:: A new FlexFloat instance representing the number.
Return type:: FlexFloat

classmethod from_int(value)[source]

Creates a FlexFloat instance from an integer without overflow or underflow.

This method can handle arbitrarily large integers by dynamically growing the exponent size as needed. The fraction length can be customized to control precision.

Parameters:: value (int) – The integer value to convert to FlexFloat.
Returns:: A new FlexFloat instance representing the integer.
Return type:: FlexFloat

to_float()[source]

Converts the FlexFloat instance back to a 64-bit float.

If float is bigger than 64 bits, it will truncate the value to fit.

Returns:: The floating-point number represented by the FlexFloat instance.
Return type:: float
Raises:: ValueError – If the FlexFloat does not have standard 64-bit exponent and fraction.

to_int()[source]

Converts the FlexFloat instance to an integer.

The conversion truncates towards zero, similar to Python’s int(float) behavior. For example: int(3.7) = 3, int(-3.7) = -3.

Returns:: The integer representation of the FlexFloat instance.
Return type:: int
Raises:: ArithmeticError – If the FlexFloat represents infinity or NaN.

__float__()[source]

Converts the FlexFloat instance to a float.

This method is provided for compatibility with Python’s float type. It uses the to_float method to perform the conversion.

Returns:: The floating-point representation of the FlexFloat instance.
Return type:: float

__int__()[source]

Converts the FlexFloat instance to an integer.

This method is provided for compatibility with Python’s int type. It uses the to_int method to perform the conversion.

Returns:: The integer representation of the FlexFloat instance.
Return type:: int

__repr__()[source]

Returns a string representation of the FlexFloat instance.

Returns:: A string representation of the FlexFloat instance.
Return type:: str

pretty()[source]

Returns an easier to read string representation of the FlexFloat instance. Mainly converts the exponent and fraction to integers for readability.

Returns:: A pretty string representation of the FlexFloat instance.
Return type:: str

classmethod nan()[source]

Creates a FlexFloat instance representing NaN (Not a Number).

Returns:: A new FlexFloat instance representing NaN.
Return type:: FlexFloat

classmethod infinity(sign=False)[source]

Creates a FlexFloat instance representing Infinity.

Parameters:: sign (bool, optional) – Indicates if the infinity is negative. Defaults to False.
Returns:: A new FlexFloat instance representing Infinity.
Return type:: FlexFloat

classmethod zero(sign=False)[source]

Creates a FlexFloat instance representing zero.

Parameters:: sign (bool, optional) – Indicates if the zero is negative. Defaults to False.
Returns:: A new FlexFloat instance representing zero.
Return type:: FlexFloat

is_nan()[source]

Checks if the FlexFloat instance represents NaN (Not a Number).

Returns:: True if the FlexFloat instance is NaN, False otherwise.
Return type:: bool

is_infinity()[source]

Checks if the FlexFloat instance represents Infinity.

Returns:: True if the FlexFloat instance is Infinity, False otherwise.
Return type:: bool

is_zero()[source]

Checks if the FlexFloat instance represents zero.

Returns:: True if the FlexFloat instance is zero, False otherwise.
Return type:: bool

copy()[source]

Creates a copy of the FlexFloat instance.

Returns:: A new FlexFloat instance with the same data as the original.
Return type:: FlexFloat

__str__()[source]

Returns a float representation of the FlexFloat using a generic algorithm.

Currently, it only operates in one format: scientific notation with 5 decimal places.

Returns:: The string representation in scientific notation.
Return type:: str

__neg__()[source]

Negates the FlexFloat instance.

Returns:: A new FlexFloat instance with the sign flipped.
Return type:: FlexFloat

__add__(other)[source]

Adds two FlexFloat instances together.

Parameters:: other (FlexFloat | Number) – The other FlexFloat instance to add.
Returns:: A new FlexFloat instance representing the sum.
Return type:: FlexFloat
Raises:: TypeError – If other is not a FlexFloat or numeric type.

__radd__(other)[source]

Right addition operator for FlexFloat instances.

This method allows the FlexFloat instance to be added to another FlexFloat or numeric type on the right side of the addition operator.

Parameters:: other (FlexFloat | Number) – The other FlexFloat instance or numeric type to add.
Returns:: A new FlexFloat instance representing the sum.
Return type:: FlexFloat

__sub__(other)[source]

Subtracts one FlexFloat instance from another.

Parameters:: other (FlexFloat | Number) – The FlexFloat instance to subtract.
Returns:: A new FlexFloat instance representing the difference.
Return type:: FlexFloat
Raises:: TypeError – If other is not a FlexFloat or numeric type.

__rsub__(other)[source]

Right-hand subtraction for FlexFloat instances.

This method allows the FlexFloat instance to be subtracted from another FlexFloat or numeric type on the right side of the subtraction operator.

Parameters:: other (FlexFloat | Number) – The other FlexFloat instance or numeric type to subtract from.
Returns:: A new FlexFloat instance representing the difference.
Return type:: FlexFloat

__mul__(other)[source]

Multiplies two FlexFloat instances together.

Parameters:: other (FlexFloat | Number) – The other FlexFloat instance to multiply.
Returns:: A new FlexFloat instance representing the product.
Return type:: FlexFloat
Raises:: TypeError – If other is not a FlexFloat or numeric type.

__rmul__(other)[source]

Right-hand multiplication for Number types.

Parameters:: other (Number) – The number to multiply with this FlexFloat.
Returns:: A new FlexFloat instance representing the product.
Return type:: FlexFloat

__truediv__(other)[source]

Divides this FlexFloat by another FlexFloat or number.

Parameters:: other (FlexFloat | Number) – The divisor.
Returns:: A new FlexFloat instance representing the quotient.
Return type:: FlexFloat
Raises:: TypeError – If other is not a FlexFloat or numeric type.

__rtruediv__(other)[source]

Right-hand division for Number types.

Parameters:: other (Number) – The number to divide by this FlexFloat.
Returns:: A new FlexFloat instance representing the quotient.
Return type:: FlexFloat

__abs__()[source]

Returns the absolute value of the FlexFloat instance.

Returns:

A new FlexFloat instance with the same exponent and fraction, but: with the sign set to False (positive).

Return type:

FlexFloat

abs()[source]

Calculates the absolute value of the FlexFloat instance.

Returns:

A new FlexFloat instance with the same exponent and fraction, but: with the sign set to False (positive).

Return type:

FlexFloat

__pow__(other)[source]

Raises this FlexFloat to the power of another FlexFloat or number.

Parameters:: other (FlexFloat | Number) – The exponent.
Returns:: A new FlexFloat instance representing the power.
Return type:: FlexFloat
Raises:: TypeError – If other is not a FlexFloat or numeric type.

__rpow__(other)[source]

Right-hand power operation for Number types.

Parameters:: other (Number) – The base to raise to the power of this FlexFloat.
Returns:: A new FlexFloat instance representing the power.
Return type:: FlexFloat

__eq__(other)[source]

Check if this FlexFloat is equal to another value.

Parameters:: other (object) – The value to compare with.
Returns:: True if the values are equal, False otherwise.
Return type:: bool

__ne__(other)[source]

Check if this FlexFloat is not equal to another value.

Parameters:: other (object) – The value to compare with.
Returns:: True if the values are not equal, False otherwise.
Return type:: bool

__lt__(other)[source]

Check if this FlexFloat is less than another value.

Parameters:: other (FlexFloat | Number) – The value to compare with.
Returns:: True if this FlexFloat is less than other, False otherwise.
Return type:: bool

__le__(other)[source]

Check if this FlexFloat is less than or equal to another value.

Parameters:

other (FlexFloat | Number) – The value to compare with.

Returns:

True if this FlexFloat is less than or equal to other, False: otherwise.

Return type:

bool

__gt__(other)[source]

Check if this FlexFloat is greater than another value.

Parameters:: other (FlexFloat | Number) – The value to compare with.
Returns:: True if this FlexFloat is greater than other, False otherwise.
Return type:: bool

__ge__(other)[source]

Check if this FlexFloat is greater than or equal to another value.

Parameters:

other (FlexFloat | Number) – The value to compare with.

Returns:

True if this FlexFloat is greater than or equal to other, False: otherwise.

Return type:

bool

Class Methods

classmethod FlexFloat.from_float(value)[source]

Creates a FlexFloat instance from a number.

Parameters:: value (Number) – The number to convert to FlexFloat.
Returns:: A new FlexFloat instance representing the number.
Return type:: FlexFloat

classmethod FlexFloat.nan()[source]

Creates a FlexFloat instance representing NaN (Not a Number).

Returns:: A new FlexFloat instance representing NaN.
Return type:: FlexFloat

classmethod FlexFloat.infinity(sign=False)[source]

Creates a FlexFloat instance representing Infinity.

Parameters:: sign (bool, optional) – Indicates if the infinity is negative. Defaults to False.
Returns:: A new FlexFloat instance representing Infinity.
Return type:: FlexFloat

classmethod FlexFloat.zero(sign=False)[source]

Creates a FlexFloat instance representing zero.

Parameters:: sign (bool, optional) – Indicates if the zero is negative. Defaults to False.
Returns:: A new FlexFloat instance representing zero.
Return type:: FlexFloat

classmethod FlexFloat.set_bitarray_implementation(implementation)[source]

Set the BitArray implementation to use for all FlexFloat instances.

Parameters:: implementation (Type[BitArray]) – The BitArray implementation class to use.

Instance Methods

Type Checking

FlexFloat.is_zero()[source]

Checks if the FlexFloat instance represents zero.

Returns:: True if the FlexFloat instance is zero, False otherwise.
Return type:: bool

FlexFloat.is_infinity()[source]

Checks if the FlexFloat instance represents Infinity.

Returns:: True if the FlexFloat instance is Infinity, False otherwise.
Return type:: bool

FlexFloat.is_nan()[source]

Checks if the FlexFloat instance represents NaN (Not a Number).

Returns:: True if the FlexFloat instance is NaN, False otherwise.
Return type:: bool

Conversion Methods

FlexFloat.to_float()[source]

Converts the FlexFloat instance back to a 64-bit float.

If float is bigger than 64 bits, it will truncate the value to fit.

Returns:: The floating-point number represented by the FlexFloat instance.
Return type:: float
Raises:: ValueError – If the FlexFloat does not have standard 64-bit exponent and fraction.

FlexFloat.copy()[source]

Creates a copy of the FlexFloat instance.

Returns:: A new FlexFloat instance with the same data as the original.
Return type:: FlexFloat

FlexFloat.abs()[source]

Calculates the absolute value of the FlexFloat instance.

Returns:

A new FlexFloat instance with the same exponent and fraction, but: with the sign set to False (positive).

Return type:

FlexFloat

FlexFloat.pretty()[source]

Returns an easier to read string representation of the FlexFloat instance. Mainly converts the exponent and fraction to integers for readability.

Returns:: A pretty string representation of the FlexFloat instance.
Return type:: str

Examples

Basic Usage

from flexfloat import FlexFloat

# Create FlexFloat numbers
x = FlexFloat.from_float(1.5)
y = FlexFloat.from_float(2.5)

# Arithmetic operations
sum_result = x + y
print(sum_result)  # 4.00000e+00
product = x * y
print(product)  # 3.75000e+00
quotient = x / y
print(quotient)  # 6.00000e-01
power = x ** 2
print(power)  # 2.25000e+00

Special Values

from flexfloat import FlexFloat

# Create special values
inf = FlexFloat.infinity()
nan = FlexFloat.nan()
zero = FlexFloat.zero()

# Check types
print(inf.is_infinity())    # True
print(nan.is_nan())         # True
print(zero.is_zero())       # True
print(inf)                  # inf
print(nan)                  # nan
print(zero)                 # 0.0

Large Numbers

from flexfloat import FlexFloat

# Work with numbers beyond float range
large = FlexFloat.from_float(10) ** 400
very_large = large * FlexFloat.from_float(2)

print(very_large)  # 5.67344e+921

Type Conversions

from flexfloat import FlexFloat

# From various types
from_int = FlexFloat.from_float(42)
from_float = FlexFloat.from_float(3.14159)

# To various types
as_float = from_float.to_float()

# Copy and abs
copy = from_float.copy()
absolute = from_float.abs()

# Pretty string
print(from_float.pretty())  # FlexFloat(exponent=1, fraction=2570632149304942)