Class: CReal

CReal

Constructive real numbers, also known as recursive, or computable reals. Each recursive real number is represented as an object that provides an approximation function for the real number. The approximation function guarantees that the generated approximation is accurate to the specified precision. Arithmetic operations on constructive reals produce new such objects; they typically do not perform any real computation. In this sense, arithmetic computations are exact: They produce a description which describes the exact answer, and can be used to later approximate it to arbitrary precision.

When approximations are generated, e.g. for output, they are accurate to the requested precision; no cumulative rounding errors are visible. In order to achieve this precision, the approximation function will often need to approximate subexpressions to greater precision than was originally demanded. Thus the approximation of a constructive real number generated through a complex sequence of operations may eventually require evaluation to very high precision. This usually makes such computations prohibitively expensive for large numerical problems. But it is perfectly appropriate for use in a desk calculator, for small numerical problems, for the evaluation of expressions computated by a symbolic algebra system, for testing of accuracy claims for floating point code on small inputs, or the like.

We expect that the vast majority of uses will ignore the particular implementation, and the member functons approximate and get_appr. Such applications will treat CReal as a conventional numerical type, with an interface modelled on java.math.BigInteger. No subclasses of CReal will be explicitly mentioned by such a program.

All standard arithmetic operations, as well as a few algebraic and transcendal functions are provided. Constructive reals are immutable; thus all of these operations return a new constructive real.

A few uses will require explicit construction of approximation functions. The requires the construction of a subclass of CReal with an overridden approximate function. Note that approximate should only be defined, but never called. get_appr provides the same functionality, but adds the caching necessary to obtain reasonable performance.

Any operation may also throw an exception if the precision request generated during any subcalculation overflows a 28-bit integer. (This should be extremely unlikely, except as an outcome of a division by zero, or other erroneous computation.)

Members

(static) E :CReal

The base of the natural logarithm.

(static) ln2 :CReal

Natural log of 2.

ln(2) = 7*ln(10/9) - 2*ln(25/24) + 3*ln(81/80).

(static) ONE :CReal

One.

(static) PI :CReal

The ratio of a circle's circumference to its diameter.

(static) ZERO :CReal

Zero.

Methods

(static) atan_reciprocal(n : {integer}) → {CReal}

Atan of integer reciprocal: atan(1/n).

(static) valueOf(n : {number, string}) → {CReal}

Construct a CReal from a number or string.

abs() → {CReal}

The absolute value of a constructive real. Note that this cannot be written as a conditional.

acos() → {CReal}

The trigonometric arc (incerse) cosine function.

add(x : {CReal}) → {CReal}

Add two constructive reals.

asin() → {CReal}

The trigonometric arc (inverse) sine function.

assumeInt() → {CReal}

Produce a constructive real equivalent to the original, assuming the original was an integer. Undefined results if the original was not an integer. Prevents evaluation of digits to the right of the decimal point, and may thus improve performance.

BigIntValue() → {BigInt}

Return a BigInt which differs by less than one from the constructive real.

compareTo(x : {CReal}, r : {integer}, a : {integer})

Return 0 if x = y to within the indicated tolerance, -1 if x < y, and +1 if x > y. If x and y are indeed equal, it is guaranteed that 0 will be returned. If they differ by less than the tolerance, anything may happen. The tolerance allowed is the maximum of (abs(this)+abs(x))*(2**r) and 2**a

cos() → {CReal}

The trigonometric cosine function.

divide(x : {CReal}) → {CReal}

The quotient of two constructive reals.

exp() → {CReal}

The exponential function, that is e**this.

floatValue() → {number}

Return a float which differs by less than one in the least represented bit from the constructive real. (We're in fact closer to round-to-nearest than that, but we can't and don't promise correct rounding.)

get_appr(precision : {integer}) → {BigInt}

Returns value / 2 ** precision rounded to an integer. The error in the result is strictly less than 1. Produces the same answer as approximate, but uses and maintains a cached approximation. Normally not overridden, and called only from approximate methods in subclasses. Not needed if the provided operations on constructive reals suffice.

intValue() → {integer}

Return an integer which differs by less than one from the constructive real. Behaviour on overflow is undefined.

inverse() → {CReal}

The multiplicative inverse of a constructive real. x.inverse() is equivalent to CReal.valueOf(1).divide(x).

ln() → {CReal}

The natural (base e) logarithm.

max(x : {CReal}) → {CReal}

The maximum of two constructive reals.

min(x : {CReal}) → {CReal}

The minimum of two constructive reals.

msd(n : {integer}) → {integer}

Return ths position of the most significant digit (msd) - this version may return Number.MIN_SAFE_INTEGER if the correct answer is < n.

If n is not given, it uses iter_msd to eventually return a correct answer, unless the constructive real is zero, when it either loops forever or throws a precision overflow error.

multiply(x : {CReal}) → {CReal}

The produce of two constructive reals.

negate() → {CReal}

The additive inverse of a constructive real.

pow(x : {CReal}) → {CReal}

To the power of x.

select(x : {CReal}, y : {CReal}) → {CReal}

The real number x if this < 0, or y otherwise. Requires x = y if this = 0. Since comparisons may diverge, this is often a useful alternative to conditionals.

shiftLeft(n : {integer}) → {CReal}

Multiply a constructive real by 2 ** n.

shiftRight(n : {integer}) → {CReal}

Multiply a constructive real by 2 ** -n.

signum(aopt : {integer}) → {integer}

Return -1 if negative, +1 if positive. Should be called only if this != 0. In the 0 case, this will not terminate correctly; typically it will run until it exhausts memory. If the two constructive reals may be equal, the one or two argument version of signum should be used.

sin() → {CReal}

The trigonometric sine function.

sqrt() → {CReal}

The square root of a constructive real.

subtract(x : {CReal}) → {CReal}

The difference between two constructive reals.

toString(nopt : {integer}, radixopt : {integer}) → {string}

Return a textual representation accurate to n places to the right of the decimal point.

Example
// returns "3.141"
CReal.PI.toString(3)

toStringFloatRep(n : {integer}, radix : {integer}, m : {integer}) → {StringFloatRep}

Return a textual scientific notation representation accurate to n places to the right of the decimal point. n must be non-negative. A value smaller than radix**-m may be displayed as 0. The mantissa component of the result is either "0" or exactly n digits long. The sign component is zero exactly when the mantissa is "0".