# bignum.h | documentation

    #charset "us-ascii"
    #pragma once

    /*
     *   Copyright (c) 2000, 2006 Michael J. Roberts
     *
     *   This file is part of TADS 3.
     *
     *   This header defines the BigNumber intrinsic class.
     */

    /* include our base class definition */
    #include "systype.h"

    /*
     *   The BigNumber intrinsic class lets you perform floating-point and
     *   integer arithmetic with (almost) any desired precision.  BigNumber uses
     *   a decimal representation, which means that decimal values can be
     *   represented exactly (i.e., with no rounding errors, as can happen with
     *   IEEE 'double' and 'float' values that languages like C typically
     *   support).  BigNumber combines a varying-length mantissa with an
     *   exponent; the length of the mantissa determines how many digits of
     *   precision a given BigNumber can store, and the exponent lets you
     *   represent very large or very small values with minimal storage.  You can
     *   specify the desired precision when you create a BigNumber explicitly;
     *   when BigNumber values are created implicitly by computations, the system
     *   chooses a precision based on the inputs to the calculations, typically
     *   equal to the largest of the precisions of the input values.
     *
     *   The maximum precision for a BigNumber is about 64,000 digits, and the
     *   exponent can range from -32768 to +32767.  Since this is a decimal
     *   exponent, this implies an absolute value range from 1.0e-32768 to
     *   1.0e+32767.  The more digits of precision stored in a given BigNumber
     *   value, the more memory the object consumes, and the more time it takes
     *   to perform calculations using the value.
     */
    intrinsic class BigNumber 'bignumber/030001': Object
    {
        /* format to a string */
        formatString(maxDigits?, flags?,
                     wholePlaces?, fracDigits?, expDigits?, leadFiller?);

        /*
         *   compare for equality after rounding to the smaller of my
         *   precision and num's precision
         */
        equalRound(num);

        /*
         *   returns an integer giving the number of digits of precision that
         *   this number stores
         */
        getPrecision();

        /*
         *   Return a new number, with the same value as this number but with
         *   the given number of decimal digits of precision.  If the new
         *   precision is higher than the old precision, this will increase
         *   the precision to the requested new size and add trailing zeros
         *   to the value.  If the new precision is lower than the old
         *   precision, we'll round the number for the reduced precision.
         */
        setPrecision(digits);

        /* get the fractional part */
        getFraction();

        /* get the whole part (truncates the fraction - doesn't round) */
        getWhole();

        /*
         *   round to the given number of digits after the decimal point; if
         *   the value is zero, round to integer; if the value is negative,
         *   round to the given number of places before the decimal point
         */
        roundToDecimal(places);

        /* return the absolute value */
        getAbs();

        /* least integer greater than or equal to this number */
        getCeil();

        /* greatest integer less than or equal to this number */
        getFloor();

        /* get the base-10 scale of the number */
        getScale();

        /*
         *   scale by 10^x - if x is positive, this multiplies the number by
         *   ten the given number of times; if x is negative, this divides the
         *   number by ten the given number of times
         */
        scaleTen(x);

        /* negate - invert the sign of the number */
        negate();

        /*
         *   copySignFrom - combine the absolute value of self with the sign
         *   of x
         */
        copySignFrom(x);

        /* determine if the value is negative */
        isNegative();

        /*
         *   Calculate the integer quotient and the remainder; returns a list
         *   whose first element is the integer quotient (a BigNumber
         *   containing an integer value), and whose second element is the
         *   remainder (the value R such that dividend = quotient*x + R).
         *
         *   Note that the quotient returned will not necessarily have the
         *   same value as the whole part of dividing self by x with the '/'
         *   operator, because this division handles rounding differently.  In
         *   particular, the '/' operator will perform the appropriate
         *   rounding on the quotient if the quotient has insufficient
         *   precision to represent the exact result.  This routine, in
         *   contrast, does NOT round the quotient, but merely truncates any
         *   trailing digits that cannot be represented in the result's
         *   precision.  The reason for this difference is that it ensures
         *   that the relation (dividend=quotient*x+remainder) holds, which
         *   would not always be the case if the quotient were rounded up.
         *
         *   Note also that the remainder will not necessarily be less than
         *   the divisor.  If the quotient cannot be exactly represented
         *   (which occurs if the precision of the quotient is smaller than
         *   its scale), the remainder will be the correct value so that the
         *   relationship above holds, rather than the unique remainder that
         *   is smaller than the divisor.  In all cases where there is
         *   sufficient precision to represent the quotient exactly (to the
         *   units digit only, since the quotient returned from this method
         *   will always be an integer), the remainder will satisfy the
         *   relationship AND will be the unique remainder with absolute value
         *   less than the divisor.
         */
        divideBy(x);

        /*
         *   calculate and return the trigonometric sine of the value (taken
         *   as a radian value)
         */
        sine();

        /*
         *   calculate and return the trigonometric cosine of the value (taken
         *   as a radian value)
         */
        cosine();

        /*
         *   calculate and return the trigonometric tangent of the value
         *   (taken as a radian value)
         */
        tangent();

        /*
         *   interpreting this number as a number of degrees, convert the
         *   value to radians and return the result
         */
        degreesToRadians();

        /*
         *   interpreting this number as a number of radians, convert the
         *   value to degrees and return the result
         */
        radiansToDegrees();

        /*
         *   Calculate and return the arcsine (in radians) of the value.  Note
         *   that the value must be between -1 and +1 inclusive, since sine()
         *   never has a value outside of this range.
         */
        arcsine();

        /*
         *   Calculate and return the arccosine (in radians).  The value must
         *   be between -1 and +1 inclusive.
         */
        arccosine();

        /* calculate and return the arctangent (in radians) */
        arctangent();

        /* calculate the square root and return the result */
        sqrt();

        /*
         *   calculate the natural logarithm of this number and return the
         *   result
         */
        logE();

        /*
         *   raise e (the base of the natural logarithm) to the power of this
         *   value and return the result
         */
        expE();

        /* calculate the base-10 logarithm of the number and return the result */
        log10();

        /*
         *   raise this number to the power of the argument and return the
         *   result
         */
        raiseToPower(x);

        /* calculate the hyperbolic sine, cosine, and tangent */
        sinh();
        cosh();
        tanh();

        /* class method: get the value of pi to a given precision */
        getPi(digits);

        /* class method: get the value of e to a given precision */
        getE(digits);

        /*
         *   Get the type of this number.  This returns a combination of
         *   NumTypeXxx flags, combined with the '|' operator.  This can be used
         *   to check for special values, such as infinites and "not a number"
         *   values.
         */
        numType();
    }

    /* ------------------------------------------------------------------------ */
    /*
     *   flags for formatString
     */

    /* always show a sign, even if positive */
    #define BignumSign          0x0001

    /* always show in exponential format (scientific notation, as in "1.0e20") */
    #define BignumExp           0x0002

    /* always show a sign in the exponent, even if positive */
    #define BignumExpSign      0x0004

    /*
     *   show a zero before the decimal point - this is only relevant in
     *   non-exponential format when the number is between -1 and +1
     */
    #define BignumLeadingZero  0x0008

    /* always show a decimal point */
    #define BignumPoint         0x0010

    /* insert commas to denote thousands, millions, etc */
    #define BignumCommas        0x0020

    /* show a leading space if the number is positive */
    #define BignumPosSpace     0x0040

    /*
     *   use European-style formatting: use a comma instead of a period for
     *   the decimal point, and use periods instead of commas to set off
     *   thousands, millions, etc
     */
    #define BignumEuroStyle     0x0080

    /*
     *   "Compact" format: use the shorter of the regular format and scientific
     *   notation.  If the scientific notation exponent is less than -4 or
     *   greater than or equal to the number of digits after the decimal point,
     *   we'll use scientific notation; otherwise we'll use the plain format.
     */
    #define BignumCompact      0x0100

    /*
     *   maxDigits counts only significant digits; leading zeros aren't counted
     *   against the maximum.
     */
    #define BignumMaxSigDigits 0x0200

    /*
     *   Keep trailing zeros.  If there's a maxDigits value, this keeps enough
     *   trailing zeros so that the number of digits shown equals maxDigits.  By
     *   default, trailing zeros after the decimal point are removed.
     */
    #define BignumKeepTrailingZeros 0x0400

    /* ------------------------------------------------------------------------ */
    /*
     *   Number type flags, for numType()
     */

    /*
     *   Number type: ordinary number.
     */
    #define NumTypeNum  0x0001

    /*
     *   Number type: "Not a number" (NaN).  This indicates that the value is the
     *   result of a calculation with invalid input(s).  Currently there are no
     *   BigNumber calculations that return NaNs, as all functions on invalid
     *   inputs throw errors instead.  But it's possible to construct NaN value,
     *   such as by reading an IEEE 754-2008 NaN value from a file via
     *   unpackBytes().
     */
    #define NumTypeNAN  0x0002

    /*
     *   Number type: positive infinity, negative infinity.  These indicate a
     *   value that overflowed the capacity of the BigNumber type, or a
     *   calculation that yields infinity (e.g., tan(pi/2)).  Currently there are
     *   no BigNumber calculations that return Infinities, as all functions where
     *   an overflow is possible throw errors instead.  But it's possible to
     *   construct an Infinity value, such as by reading an IEEE 754-2008
     *   Infinity value from a file via unpackBytes().
     */
    #define NumTypePInf 0x0004
    #define NumTypeNInf 0x0008
    #define NumTypeInf  (NumTypePInf | NumTypeNInf)

    /*
     *   Number type: zero, positive or negative.  Mathematically, zero is
     *   neither positive nor negative, but the BigNumber type retains a sign for
     *   all values, even zeros.  Negative zeros can come from calculations
     *   that yield negative results with absolute values too small for the
     *   internal representation.  It's also possible to construct a negative
     *   zero, such as by reading an IEEE 754-2008 negative zero value from a
     *   file via unpackBytes().
     */
    #define NumTypePZero  0x0010
    #define NumTypeNZero  0x0020
    #define NumTypeZero (NumTypePZero | NumTypeNZero)

Adv3Lite Library Reference Manual
Generated on 13/06/2025 from adv3Lite version 2.2.1