math.rational

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

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::math_rational_add_rational::add_rational;  ← addRational, another function of this group · built into the same file, even by a slim install
use super::math_rational_divide_rational::divide_rational;  ← divideRational, another function of this group · built into the same file, even by a slim install
use super::math_rational_multiply_rational::multiply_rational;  ← multiplyRational, another function of this group · built into the same file, even by a slim install
use super::math_rational_rational::{rational_from_value, rational_to_value};  ← rational, another function of this group · built into the same file, even by a slim install
use super::math_rational_subtract_rational::subtract_rational;  ← subtractRational, another function of this group · built into the same file, even by a slim install

/// Add, subtract, multiply or divide two fractions exactly.
///
/// The result is always reduced with a positive denominator, so equal values
/// have equal fields.
///
/// # Panics
/// Panics on a zero denominator, division by zero, an unknown operation, or a
/// result outside ±(2^53 - 1).
pub fn calculate_rational(a: &Rational, op: &str, b: &Rational) -> Rational {
    match op {
        "add" => add_rational(a, b),
        "subtract" => subtract_rational(a, b),
        "multiply" => multiply_rational(a, b),
        "divide" => divide_rational(a, b),
        other => panic!("unknown operation \"{}\"", other),
    }
}

pub fn fune_vector(args: &[Value]) -> Value {
    rational_to_value(&calculate_rational(
        &rational_from_value(&args[0]),
        args[1].as_str(),
        &rational_from_value(&args[2]),
    ))
}

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

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::math_gcd_lcm::gcd_wide;  ← from math.gcd-lcm ^1.0.0 · built alongside by fune

const MAX_SAFE: i128 = 9_007_199_254_740_991;

/// Reduce a wide fraction and bring it back into the exact number range. The
/// arithmetic works on i128 products, which may be past 2^53, and only the
/// reduced result has to fit.
///
/// # Panics
/// Panics if the denominator is zero or the reduced result is outside ±(2^53 - 1).
pub fn rational_from_wide(numerator: i128, denominator: i128) -> Rational {
    if denominator == 0 {
        panic!("denominator must not be zero");
    }
    let g = gcd_wide(numerator, denominator);
    let mut n = numerator / g;
    let mut d = denominator / g;
    if d < 0 {
        n = -n;
        d = -d;
    }
    // i64 could hold more, but TypeScript numbers stop being exact here, and
    // the three languages must agree.
    if n > MAX_SAFE || n < -MAX_SAFE || d > MAX_SAFE {
        panic!("rational overflow: the reduced result exceeds 2^53 - 1");
    }
    Rational {
        numerator: n as i64,
        denominator: d as i64,
    }
}

/// Build a reduced fraction with a positive denominator.
///
/// # Panics
/// Panics if the denominator is zero or either part is outside ±(2^53 - 1).
pub fn rational(numerator: i64, denominator: i64) -> Rational {
    let (n, d) = (numerator as i128, denominator as i128);
    if n > MAX_SAFE || n < -MAX_SAFE || d > MAX_SAFE || d < -MAX_SAFE {
        panic!("rational overflow: numerator and denominator must be within 2^53 - 1");
    }
    rational_from_wide(n, d)
}

/// A checked, reduced operand as i128s, ready to multiply without overflow.
pub fn rational_parts(r: &Rational) -> (i128, i128) {
    let n = rational(r.numerator, r.denominator);
    (n.numerator as i128, n.denominator as i128)
}

pub fn rational_to_value(r: &Rational) -> Value {
    Value::obj(vec![
        ("numerator", Value::Int(r.numerator)),
        ("denominator", Value::Int(r.denominator)),
    ])
}

/// Read an integer from JSON, refusing a fraction with the wording TypeScript
/// and Python use rather than let `as_i64` quietly truncate it.
pub fn rational_int_from_value(v: &Value) -> i64 {
    if let Value::Float(f) = v {
        if f.fract() != 0.0 {
            panic!("numerator and denominator must be integers");
        }
    }
    v.as_i64()
}

pub fn rational_from_value(v: &Value) -> Rational {
    Rational {
        numerator: rational_int_from_value(v.get("numerator")),
        denominator: rational_int_from_value(v.get("denominator")),
    }
}

pub fn fune_vector(args: &[Value]) -> Value {
    rational_to_value(&rational(
        rational_int_from_value(&args[0]),
        rational_int_from_value(&args[1]),
    ))
}

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

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::math_rational_rational::{rational_from_value, rational_from_wide, rational_parts, rational_to_value};  ← rational, another function of this group · built into the same file, even by a slim install

/// a + b, reduced.
///
/// # Panics
/// Panics on a zero denominator or a result outside ±(2^53 - 1).
pub fn add_rational(a: &Rational, b: &Rational) -> Rational {
    let (an, ad) = rational_parts(a);
    let (bn, bd) = rational_parts(b);
    rational_from_wide(an * bd + bn * ad, ad * bd)
}

pub fn fune_vector(args: &[Value]) -> Value {
    rational_to_value(&add_rational(&rational_from_value(&args[0]), &rational_from_value(&args[1])))
}

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

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::math_rational_rational::{rational_from_value, rational_from_wide, rational_parts, rational_to_value};  ← rational, another function of this group · built into the same file, even by a slim install

/// a - b, reduced.
///
/// # Panics
/// Panics on a zero denominator or a result outside ±(2^53 - 1).
pub fn subtract_rational(a: &Rational, b: &Rational) -> Rational {
    let (an, ad) = rational_parts(a);
    let (bn, bd) = rational_parts(b);
    rational_from_wide(an * bd - bn * ad, ad * bd)
}

pub fn fune_vector(args: &[Value]) -> Value {
    rational_to_value(&subtract_rational(&rational_from_value(&args[0]), &rational_from_value(&args[1])))
}

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

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::math_rational_rational::{rational_from_value, rational_from_wide, rational_parts, rational_to_value};  ← rational, another function of this group · built into the same file, even by a slim install

/// a × b, reduced.
///
/// # Panics
/// Panics on a zero denominator or a result outside ±(2^53 - 1).
pub fn multiply_rational(a: &Rational, b: &Rational) -> Rational {
    let (an, ad) = rational_parts(a);
    let (bn, bd) = rational_parts(b);
    rational_from_wide(an * bn, ad * bd)
}

pub fn fune_vector(args: &[Value]) -> Value {
    rational_to_value(&multiply_rational(&rational_from_value(&args[0]), &rational_from_value(&args[1])))
}

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

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::math_rational_rational::{rational_from_value, rational_from_wide, rational_parts, rational_to_value};  ← rational, another function of this group · built into the same file, even by a slim install

/// a ÷ b, reduced. Dividing by zero is an error, never an infinity.
///
/// # Panics
/// Panics if `b` is zero, on a zero denominator, or a result outside ±(2^53 - 1).
pub fn divide_rational(a: &Rational, b: &Rational) -> Rational {
    let (an, ad) = rational_parts(a);
    let (bn, bd) = rational_parts(b);
    if bn == 0 {
        panic!("division by zero");
    }
    rational_from_wide(an * bd, ad * bn)
}

pub fn fune_vector(args: &[Value]) -> Value {
    rational_to_value(&divide_rational(&rational_from_value(&args[0]), &rational_from_value(&args[1])))
}

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

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::math_rational_rational::{rational_from_value, rational_parts};  ← rational, another function of this group · built into the same file, even by a slim install

/// -1, 0 or 1. Exact: cross-multiplied in i128, never through a float.
///
/// # Panics
/// Panics on a zero denominator or a part outside ±(2^53 - 1).
pub fn compare_rational(a: &Rational, b: &Rational) -> i64 {
    let (an, ad) = rational_parts(a);
    let (bn, bd) = rational_parts(b);
    match (an * bd).cmp(&(bn * ad)) {
        std::cmp::Ordering::Less => -1,
        std::cmp::Ordering::Equal => 0,
        std::cmp::Ordering::Greater => 1,
    }
}

pub fn fune_vector(args: &[Value]) -> Value {
    Value::Int(compare_rational(&rational_from_value(&args[0]), &rational_from_value(&args[1])))
}

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

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::math_rational_rational::{rational, rational_from_value};  ← rational, another function of this group · built into the same file, even by a slim install
use super::math_round_div::round_div;  ← from math.round-div ^1.0.0 · built alongside by fune

/// The integer a fraction rounds to, under an explicit rounding mode: the
/// point where an exact rate becomes minor units, so the policy is the
/// caller's to state.
///
/// # Panics
/// Panics on a zero denominator, a part outside ±(2^53 - 1), or an unknown mode.
pub fn rational_to_integer(r: &Rational, mode: &str) -> i64 {
    let n = rational(r.numerator, r.denominator);
    round_div(n.numerator, n.denominator, mode)
}

pub fn fune_vector(args: &[Value]) -> Value {
    Value::Int(rational_to_integer(&rational_from_value(&args[0]), args[1].as_str()))
}