math.rational

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from .math_rational_add_rational import add_rational  ← addRational, another function of this group · built into the same file, even by a slim install
from .math_rational_divide_rational import divide_rational  ← divideRational, another function of this group · built into the same file, even by a slim install
from .math_rational_multiply_rational import multiply_rational  ← multiplyRational, another function of this group · built into the same file, even by a slim install
from .math_rational_subtract_rational import subtract_rational  ← subtractRational, another function of this group · built into the same file, even by a slim install
from .math_rational_types import Rational, RationalOp


def calculate_rational(a: Rational, op: RationalOp, b: Rational) -> Rational:
    """Add, subtract, multiply or divide two fractions exactly.

    The result is always reduced with a positive denominator, so equal values
    have equal fields.
    """
    if op == "add":
        return add_rational(a, b)
    if op == "subtract":
        return subtract_rational(a, b)
    if op == "multiply":
        return multiply_rational(a, b)
    if op == "divide":
        return divide_rational(a, b)
    raise ValueError('unknown operation "%s"' % (op,))

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from typing import Tuple

from .math_gcd_lcm import gcd_wide  ← from math.gcd-lcm ^1.0.0 · built alongside by fune
from .math_rational_types import Rational

_MAX_SAFE = 9007199254740991


def rational_from_wide(numerator: int, denominator: int) -> Rational:
    """Reduce a wide fraction and bring it back into the exact number range.

    The arithmetic works on products that may be past 2^53, and only the
    reduced result has to fit.
    """
    if denominator == 0:
        raise ValueError("denominator must not be zero")
    g = gcd_wide(numerator, denominator)
    n = numerator // g
    d = denominator // g
    if d < 0:
        n, d = -n, -d
    # Python ints never overflow, but TypeScript numbers stop being exact here,
    # and the three languages must agree.
    if n > _MAX_SAFE or n < -_MAX_SAFE or d > _MAX_SAFE:
        raise ValueError("rational overflow: the reduced result exceeds 2^53 - 1")
    return Rational(numerator=n, denominator=d)


def rational(numerator: int, denominator: int) -> Rational:
    """Build a reduced fraction with a positive denominator."""
    for v in (numerator, denominator):
        if isinstance(v, bool) or not isinstance(v, int):
            raise TypeError("numerator and denominator must be integers")
        if v > _MAX_SAFE or v < -_MAX_SAFE:
            raise ValueError("rational overflow: numerator and denominator must be within 2^53 - 1")
    return rational_from_wide(numerator, denominator)


def rational_parts(r: Rational) -> Tuple[int, int]:
    """A checked, reduced operand as (numerator, denominator)."""
    n = rational(r.numerator, r.denominator)
    return n.numerator, n.denominator

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from .math_rational_rational import rational_from_wide, rational_parts  ← rational, another function of this group · built into the same file, even by a slim install
from .math_rational_types import Rational


def add_rational(a: Rational, b: Rational) -> Rational:
    """a + b, reduced."""
    an, ad = rational_parts(a)
    bn, bd = rational_parts(b)
    return rational_from_wide(an * bd + bn * ad, ad * bd)

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from .math_rational_rational import rational_from_wide, rational_parts  ← rational, another function of this group · built into the same file, even by a slim install
from .math_rational_types import Rational


def subtract_rational(a: Rational, b: Rational) -> Rational:
    """a - b, reduced."""
    an, ad = rational_parts(a)
    bn, bd = rational_parts(b)
    return rational_from_wide(an * bd - bn * ad, ad * bd)

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from .math_rational_rational import rational_from_wide, rational_parts  ← rational, another function of this group · built into the same file, even by a slim install
from .math_rational_types import Rational


def multiply_rational(a: Rational, b: Rational) -> Rational:
    """a × b, reduced."""
    an, ad = rational_parts(a)
    bn, bd = rational_parts(b)
    return rational_from_wide(an * bn, ad * bd)

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from .math_rational_rational import rational_from_wide, rational_parts  ← rational, another function of this group · built into the same file, even by a slim install
from .math_rational_types import Rational


def divide_rational(a: Rational, b: Rational) -> Rational:
    """a ÷ b, reduced. Dividing by zero is an error, never an infinity."""
    an, ad = rational_parts(a)
    bn, bd = rational_parts(b)
    if bn == 0:
        raise ValueError("division by zero")
    return rational_from_wide(an * bd, ad * bn)

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from .math_rational_rational import rational_parts  ← rational, another function of this group · built into the same file, even by a slim install
from .math_rational_types import Rational


def compare_rational(a: Rational, b: Rational) -> int:
    """-1, 0 or 1. Exact: cross-multiplied, never through a float."""
    an, ad = rational_parts(a)
    bn, bd = rational_parts(b)
    left = an * bd
    right = bn * ad
    return -1 if left < right else 1 if left > right else 0

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from .math_rational_rational import rational  ← rational, another function of this group · built into the same file, even by a slim install
from .math_rational_types import Rational
from .math_round_div import RoundingMode, round_div  ← from math.round-div ^1.0.0 · built alongside by fune


def rational_to_integer(r: Rational, mode: RoundingMode) -> int:
    """The integer a fraction rounds to, under an explicit rounding mode.

    This is the point where an exact rate becomes minor units, so the policy
    is the caller's to state.
    """
    n = rational(r.numerator, r.denominator)
    return round_div(n.numerator, n.denominator, mode)