Macro fbig 

fbig!() { /* proc-macro */ }

Computes an expression with the specified precision and rounding mode.

Macro takes into account 2 aspects.

1. Code simplification. Macro simplifies code and improves its readability by allowing to specify simple and concise expression and process input arguments transparently.

2. Error compensation. Macro compensates error caused by catastrophic cancellation and some other situations where precision can be lost by automatically increasing the working precision internally.

The macro does not take care of correct rounding, because the completion of the rounding algorithm in finite time depends on the macro’s input.

The macro accepts an expression to compute and a context. The expression can include:

• Path expressions: variable names, constant names, etc.
• Integer literals, e.g. 123, -5.
• Floating point literals, e.g. 1.234e-567.
• String literals, e.g. "-1.234_e-567".
• Binary operators.
• Unary - operator.
• Mathematical functions.
• Grouping with ( and ).
• Constants pi, e, ln_2, ln_10, sqrt2, phi, and euler_gamma.

Binary operators:

• +: addition.
• -: subtraction.
• *: multiplication.
• /: division.
• %: modular division.

Mathematical functions:

• recip(x): reciprocal of x.
• sqrt(x): square root of x.
• cbrt(x): cube root of x.
• ln(x): natural logarithm of x.
• log2(x): logarithm base 2 of x.
• log10(x): logarithm base 10 of x.
• log(x, b): logarithm with base b of x.
• log1p(x): ln(1 + x).
• exp(x): e to the power of x.
• exp2(x): 2 to the power of x.
• exp10(x): 10 to the power of x.
• expm1(x): e^x - 1.
• pow(b, x): b to the power of x.
• rem_pi(x): reduce x modulo 2π into (-2π, 2π).
• sin(x): sine of x.
• cos(x): cosine of x.
• tan(x): tangent of x.
• asin(x): arcsine of x.
• acos(x): arccosine of x.
• atan(x): arctangent of x.
• atan2(y, x): quadrant-aware arctangent of y / x.
• hypot(x, y): sqrt(x² + y²).
• fma(x, y, z): x * y + z with a single final rounding.
• mul_add(x, y, z): alias of fma.
• erf(x), erfc(x): error function and complement.
• gamma(x), ln_gamma(x), digamma(x): gamma, log-gamma, and digamma.
• gammainc(s, x): lower incomplete gamma (\gamma(s,x)).
• gammainc_upper(s, x): upper incomplete gamma (\Gamma(s,x)).
• ei(x), si(x), ci(x), li(x): exponential / sine / cosine / logarithmic integrals.
• fresnel_s(x), fresnel_c(x): Fresnel integrals.
• bessel_j(x, n): Bessel J of integer order n.
• bessel_j_nu(x, nu), bessel_y(x, nu), bessel_i(x, nu), bessel_k(x, nu): real-order Bessel.
• elliptic_k(m), elliptic_e(m), elliptic_f(x, m), elliptic_e_inc(x, m), elliptic_pi(n, m), elliptic_pi_inc(n, x, m): elliptic integrals ((m=k^2), (x=\sin\varphi)).
• legendre_p(x, n), legendre_p_assoc(x, n, m): Legendre / associated (Condon–Shortley).
• hypergeom_2f1(a, b, c, z): Gaussian ({}_2F_1).
• betainc(a, b, x): regularized incomplete beta (I_x(a,b)).
• normal_pdf(x, mu, sigma), normal_cdf(x, mu, sigma): normal density and CDF.
• gamma_pdf(x, alpha, beta), beta_pdf(x, alpha, beta): gamma (scale (\beta)) and beta densities.
• poisson_pmf(k, lambda), binomial_pmf(k, n, prob): discrete PMFs.
• chi_squared_cdf(x, k), student_t_pdf(x, nu): chi-squared CDF and Student-(t) density.
• ldexp(x, n), scalb(x, n): x · 2^n (n is an integer literal or expression).
• logb(x): floor(log2(|x|)) as a float.
• sinh(x): hyperbolic sine of x.
• cosh(x): hyperbolic cosine of x.
• tanh(x): hyperbolic tangent of x.
• asinh(x): hyperbolic arcsine of x.
• acosh(x): hyperbolic arccosine of x.
• atanh(x): hyperbolic arctangent of x.

Constants:

• pi: pi number.
• e: Euler number.
• ln_2: natural logarithm of 2.
• ln_10: natural logarithm of 10.
• sqrt2: √2.
• phi: golden ratio (1+√5)/2.
• euler_gamma: Euler–Mascheroni constant γ.

The context determines the precision, the rounding mode of the result, and also contains the cache of constants.

Also, the macro uses minimum and maximum exponent values from the context to limit possible exponent range of the result and to set the limit of precision required for error compensation. It is recommended to set the smallest exponent range to increase the performance of computations (the internal precision may be as large as the exponent of a number).

Per-operation rounding (what is rounded when, and what is not guaranteed) is documented in doc/EXPR.md.

A tuple (usize, RoundingMode, &mut Consts), or (usize, RoundingMode, &mut Consts, Exponent, Exponent) can be used as a temporary context (see examples below).

Any input argument in the expression is interpreted as exact (i.e. if an argument of an expression has type ExactNum and it is an inexact result of a previous computation).

Examples

// Precision, rounding mode, constants cache, and exponent range.
let p = 128;
let rm = RoundingMode::Up;
let mut cc = Consts::new().expect("Failed to allocate constants cache");
let emin = -10000;
let emax = 10000;

// Create a context.
let mut ctx = Context::new(p, rm, cc, emin, emax);

let x = 1;
let y = 4;
let z = 7;

// Compute an expression.
let ret = expr!(x + y / z - ("120" - 120), &mut ctx);

let (p, rm, mut cc, emin, emax) = ctx.to_raw_parts();

// Compute an expression using a temporary context.
let ret = expr!(x + y / z, (p, rm, &mut cc, emin, emax));

Compile-time literals

exact and fbig parse a string literal at compile time into an exact ExactNum:

use zenith_float::{exact, fbig, ExactNum, RoundingMode};

let a = exact!("3.25");
let b = fbig!("3.25");
assert_eq!(a.cmp(&b), Some(0));
assert_eq!(a.cmp(&ExactNum::from_word(13, 64).div(&ExactNum::from_word(4, 64), 64, RoundingMode::ToEven)), Some(0));

Complex expressions

cexpr is the same working-precision loop as expr, for ExactComplex. Cancellation is measured on both the real and imaginary parts. The imaginary unit in the expression is I (so i remains a variable name). Leaves include roots, logs/exps, elementary and inverse functions, hypot/fma, abs/arg/conj, ldexp/scalb/logb, erf/erfc/gamma/ln_gamma/digamma, ei/si/ci/li/fresnel_s/fresnel_c, and bessel_j_nu/bessel_y/bessel_i/bessel_k. Cancellation is tracked per part. There is no atan2 or rem_pi in cexpr!. Use cexpr! when the expression is complex; expr! stays real-valued. Alias for exact, matching dashu-float naming.