astro_float

Macro expr

Source 
expr!() { /* proc-macro */ }
Expand description

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, and ln_10.

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.
  • exp(x): e to the power of x.
  • pow(b, x): b to the power of x.
  • 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.
  • 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.

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).

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 BigFloat 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 = 123;
let y = "2345";
let z = 234.5e+1;

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

assert_eq!(ret, BigFloat::from(124));

// Destructure context.
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));

assert_eq!(ret, BigFloat::from(124));