# BigNumber

The T3 VM's basic numeric type is the integer type. While this is largely adequate for writing interactive fiction, it's sometimes useful to have access to floating-point and high-precision integer arithmetic. The BigNumber type provides this functionality.

BigNumber can represent values with enormous precision, storing up
to 65,000 decimal digits in a value; and can represent a huge range of
values, with absolute values up to 10^{32767} and down to
10^{-32767}. These limits are so extreme that real-world
calculations should practically never bump up against them.
Furthermore, the BigNumber type can store values with whatever
precision you actually need for each particular value, up to the
limits; a program can use this flexibility to strike the balance it
requires between numerical precision and performance.

For reasons that are probably obvious, the more precision a BigNumber value stores, the more memory it uses and the more time it takes to perform calculations with the number. BigNumber lets you specify how much precision to use, letting you balance precision against speed and memory use.

Note that the BigNumber type is not the "double" or IEEE floating point type that you might have encountered in other programming languages. The BigNumber type is actually a custom type implemented entirely in the T3 VM. This has several advantages over "doubles":

- Doubles can have subtle, sometimes vexing variations from one computer to another. Many programmers treat doubles as fuzzy and capricious approximations, chalking up any unexpected variations to unfathomable hardware internals. BigNumber, in contrast, is portable, and behaves exactly the same way on every computer, down to the last digit.
- BigNumber uses a decimal rather than binary encoding, which means that any value that can be written in decimal can be represented exactly as a BigNumber, without any rounding error. Most people are accustomed to writing their numbers in decimal, so this makes BigNumber a "what you see is what you get" type. Some values that can be represented exactly in decimal can't be represented exactly in a binary encoding. For example, 1/5 is an endlessly repeating bit pattern in binary, much as 1/3 is an endless sequence in decimal (0.333333...), which means 1/5 can't be exactly represented with a binary double. This can be counterintuitive, because 1/5 is such a nice, round value - 0.2 - in decimal. Of course, numbers like 1/3 can't be expressed exactly in a decimal encoding, so using decimal doesn't eliminate this issue; but we tend to be already accustomed to which fractions can and can't be represented exactly in decimal, so it's at least somewhat more intuitive when rounding is required. Furthermore, since numbers are usually entered and displayed in decimal, keeping them in decimal internally avoids compounding any rounding errors on input and output.
- BigNumber allows for effectively unlimited precision. Doubles have a fixed precision - only about 16 decimal digits. The nearly unlimited precision of BigNumber enables calculations involving very large integers, for example, or precise calculations where very large and very small values are combined.

We don't mean to suggest that BigNumbers are superior to doubles in
every way. Doubles do have some advantages of their own, the big one
being speed. Doubles are implemented in hardware on many
platforms, which is nearly always much faster than a software
implementation. Even when doubles are implemented in software, they
tend to be faster than a type like BigNumber, because fixed-precision
algorithms are inherently simpler. You probably wouldn't want to use
BigNumbers in an intensive number-crunching scientific application.
But that's not the kind of program TADS is designed for, so we think
the tradeoff - greater flexibility, slower performance - is a
reasonable one. Plus, it's rather neat to be able to calculate
*pi* to a thousand digits with a couple of lines of code.

## Working with BigNumber values

You must #include <bignum.h> in your source files to use the BigNumber class. This file defines the BigNumber class interface.

You can write a BigNumber value as a floating-point constant. This is a numeric constant that contains a decimal point or an exponent, or both. Syntactically, that means one of these formats:

digit ... ( E | e ) [ + | - ] digit ... [ digit ... ] . ( digit ... ) [ ( E | e ) [ + | - ] digit ... digit ... . [ ( E | e ) [ + | - ] digit ... ]

For example:

x = 3.14159265;

This syntax actually creates a BigNumber object that represents
the given number. The compiler assigns the BigNumber's precision
based on the number of significant digits in the constant value:
this is the number of digits, ignoring leading zeros. For
example, 0.00001 has only one digit of precision, since the
leading zeros are ignored, whereas 0.00001000 has a precision
of four digits, since trailing zeros are significant. The
one exception to the leading-zero rule is that if the value is
actually zero, *all* of the zeros in the constant are
significant: so 0.0000000 has a precision of 8 digits.

You can also use the new operator to create a BigNumber. Pass the value for the number either as an integer or as a character string. You can optionally specify the precision to use for the value; if you don't specify a precision, the system infers a precision from the value. If the source value is a string, the implied precision is the number of significant digits, the same as for a constant BigNumber value; if the source is an integer, the default precision is 32 digits.

x = new BigNumber(100); x = new BigNumber(100, 10); // set precision to 10 digits y = new BigNumber('3.14159265'); z = new BigNumber('1.06e-30'); z = new BigNumber('1.06e-30', 8); // precision is 8 digits

If you specify a string value, you can use a decimal point, and you
can also use an 'E' to specify a base-ten exponent. So, the fourth
value above should be read as 1.06×10^{-30}.

Using the new operator has the advantage that you can explicitly specify the precision you want for the new value. If you do, it overrides the default precision that would otherwise be inferred from the source value.

You can perform addition, subtraction, multiplication, division, and negation on BigNumber values using the standard operators. You can also use integer values with BigNumber values in calculations, although the BigNumber value must always be the first operand in an expression involving both a BigNumber and an integer.

x = y + z; x = (y + z) * (y - z) / 2;

Similarly, you can compare BigNumber values using the normal comparison operators:

if (x > y) // ...

You can convert a BigNumber to a string using the toString() function in the tads-gen intrinsic function set. toString() uses a default formatting, though, so if you want control over the format, you should use the formatString() method of the BigNumber object itself.

You can convert a BigNumber to a regular integer value using the toInteger() function from the tads-gen function set. Note that toInteger() throws an error if passed a BigNumber value that's too large to represent as a 32-bit integer. The integer type can only store values from -2,147,483,648 to +2,147,483,647. toInteger() rounds numbers with fractional parts to the nearest integer.

You can't use operators other than those listed above with BigNumber values. You can't use a BigNumber as an operand for any of the bitwise operators (&, |, ~). You also can't use a BigNumber with the integer modulo operator (%), but you can obtain similar functionality from the divideBy() method.

You can't use BigNumber values in function and method calls that require integer arguments. You must explicitly convert a BigNumber value to an integer with the toInteger() function if you want to pass it to a method or function that takes an integer value; the compiler does not perform these conversions for you automatically.

Because BigNumber values are, for most purposes, simply object references, you can use them where you can use other objects; you can, for example, store a BigNumber in a list, or assign it to an object property.

## Rounding

BigNumber works with numbers of the precision you tell it to. This means that some calculations won't return all of the digits in the full mathematical result, since BigNumber has to round the result to fit into the precision you specify.

For example, mathematically, 1.7*0.25 = 0.425. But the expression 1.7*0.25 will yield the BigNumber value 0.42. The BigNumber calculation loses digits, compared to the mathematically exact result.

Why is this? It's because BigNumber calculations generally yield results using the same precision as the most precise operand. In the case of 1.7*0.25, we have two operands, 1.7 and 0.25, each with two digits of precision. (Remember that leading zeros don't count as significant digits, so 0.25 only has two digits of precision.) So the precision of the result will also be two digits.

Internally, BigNumber performs the calculation with a couple of extra "guard digits", to ensure more accurate results. When returning the final value of the calculation, though, the result must be rounded to the result precision. So BigNumber actually calculates the value 0.4250 internally, then rounds it to two digits before returning the final result.

BigNumber uses a standard rounding method known as "round to
nearest, ties to even". This method does the obvious thing for most
values, by rounding them up or down to the nearest digit. For
example, rounding 1.3 to integer yields 1, and rounding 1.7 yields 2.
The only tricky part is that when rounding a value that's exactly
halfway between two digits, we round to the nearest *even* digit.
So rounding 1.5 to integer rounds up to 2, since that's the nearest
even digit, but rounding 2.5 to integer rounds down to 2, since that's
once again the nearest even digit.

For our example of rounding 0.4250 to two digits, we're at one of these halfway points, so we invoke the "even digit" rule and round to 0.42 (not 0.43, since 3 is odd).

If we instead calculate 1.9*0.25, the mathematical result is 0.4750, which again rounds to the nearest even digit, giving us 0.48.

One more example: 1.9*0.33 yields 0.6270 mathematically. In this case, we're not at a halfway point, so this yields the obvious rounded value of 0.63.

## Calling methods on BigNumber values

The BigNumber class provides a number of methods for manipulating values. Note that all of the methods that perform calculations return new BigNumber values. A BigNumber object's value is immutable once the object is created, so all calculations performed on these objects return new objects representing the result values.

These functions are all methods called on a BigNumber object. For example, to calculate the absolute value of a BigNumber value x, we would code this:

y = x.getAbs();

Some of the methods take an argument giving a value to be combined with the target number. For example, to get the remainder of dividing 10 by 3, we'd write this:

x = new BigNumber('10.0000'); y = new BigNumber('3.00000'); rem = x.divideBy(y)[2]; // second list item is remainder

## BigNumber methods

arccosine()

arcsine()

arctangent()

copySignFrom(*x*)

cosh()

cosine()

degreesToRadians()

*pi*/180).

divideBy(*x*)

*remainder*satisfying the relationship

*dividend*=

*quotient**

*divisor*+

*remainder*.

Note that the quotient returned from divideBy() is not
necessarily equal to the whole part of the result of the division
(/) operator applied to the same values. If the precision of the
result (which is, as with all calculations, equal to the larger of the
precisions of the operands) is insufficient to represent exactly the
integer quotient result, the quotient returned from this function will
be rounded differently from the quotient returned by the division
operator. The division operator always rounds its result to the
nearest integer; in contrast, divideBy does **not** round the
quotient, but instead truncates any trailing digits beyond the
result's precision. The reason for this difference is that the
truncation ensures that the relationship (dividend = quotient*divisor
+ remainder) always holds for divideBy results, which would not
always be the case if the quotient were rounded.

Also, the remainder will not necessarily be less than the divisor.
If the quotient can't be represented exactly (this occurs if the
precision of the quotient is smaller than its scale), the remainder
will be the correct value so that the relationship (dividend =
quotient*divisor + remainder) holds, rather than the unique remainder
that's smaller than the divisor. In all cases where the result
precision is sufficient to represent the exact integer quotient, the
remainder will satisfy this relationship **and** will be the unique
remainder with absolute values less than the divisor.

equalRound(*num*)

expE()

*e*, the base of the natural logarithm, to the power of this number.

formatString(*maxDigits*?, *flags*?, *wholePlaces*?, *fracDigits*?, *expDigits*?, *leadFiller*?)

*maxDigits* specifies the maximum number of digits to display in the
formatted number; this is an upper bound only, and doesn't force a
minimum number of digits. If necessary, the function uses scientific
notation to make the number fit in the requested number of digits.
The default is the actual precision of the number (that is, the number
of decimal digits actually stored with the number).

*wholePlaces* specifies the minimum number of places to show
before the decimal point; if the number doesn't fill all of the
requested places, the function inserts leading spaces (before the sign
character, if any).

*fracDigits* specifies the number of digits to display after
the decimal point. This specifies the maximum to display, and also
the minimum; if the number doesn't have enough digits to display, the
method adds trailing zeros, and if there are more digits than
*fracDigits* allows, the method rounds the value for display.

*expDigits* is the number of digits to display in the exponent;
leading zeros are inserted if necessary to fill the requested number
of places.

Each of *maxDigits*, *wholePlaces*, *fracDigits*,
and *expDigits* can be specified as nil or -1, which tells
the method to use the default value, which is simply the number of
digits actually needed for the respective part.

*leadFiller*, if specified, gives a string that is used
instead of spaces to fill the beginning of the string, if required to
satisfy the *wholePlaces* argument. This argument is ignored if
its value is nil. If a string value is provided for this
argument, the characters of the string are inserted, one at a time, to
fill out the *wholePlaces* requirement; if the end of the string
is reached before the full set of padding characters is inserted, the
function starts over again at the beginning of the string. For
example, to insert alternating asterisks and pound signs, you would
specify '*#' for this argument.

*flags* is a combination of the following bit-flag values
(combined with the bit-wise OR operator, |). The default *flags*
value is 0, meaning that none of these options are selected. nil
is equivalent to 0 for the *flags* argument.

- BignumSign - always show a sign character. Normally, if the number is positive, the function omits the sign character. If this flag is specified, a + sign is shown for a positive number.
- BignumPosSpace - if the number is positive and this flag is set, the function inserts a leading space. (If BignumSign is specified, this flag is ignored.) This function can be used to ensure that positive and negative numbers fill the same number of character positions, even when you don't want to use a + sign with positive numbers.
- BignumExp - always show the number in exponential format
(scientific notation, as in "1.0e+20"). If this is not included, the
function shows the number without an exponent if it will fit in
*maxDigits*digits. - BignumExpSign - always show a sign in the exponent. If this is included, a positive exponent will be shown with a + sign. This flag is ignored unless an exponent is displayed (so specifying this flag doesn't force an exponent to be displayed).
- BignumLeadingZero - always show a zero before the decimal point. This is only important when the number's absolute value is between 0 and 1, and an exponent isn't displayed; without this flag, no digits will precede the decimal point for such values (so 0.25 would be formatted as simply '.25').
- BignumPoint - always show a decimal point. If the number has no fractional digits to display, and this flag is included, a trailing decimal point is displayed. Without this flag, no decimal point is displayed if no digits are displayed after the decimal point.
- BignumCommas - show commas to set off thousands, millions,
billions, and so on. This flag has no effect if the number is shown
in scientific notation. Commas don't count against the
*maxDigits*or*wholePlaces*limits. However, commas do count for leading filler, which ensures that a column of numbers formatted with filler and commas will line up properly. - BignumEuroStyle - use European-style formatting: use periods instead of commas to set off thousands, millions, etc., and use a comma instead of a period to indicate the decimal point.
- BignumCompact - use the shorter of the regular format or the exponential format. If the decimal exponent is less than -4, or greater than or equal to the number of digits after the decimal point, exponential format is used; otherwise the regular format is used.
- BignumMaxSigDigits - treat the
*maxDigits*argument as the maximum number of significant digits to show, not total digits. This doesn't count leading zeros against the*maxDigits*limit. - BignumKeepTrailingZeros - keep trailing zeros as needed to
fill out the
*maxDigits*size. By default, trailing zeros after the decimal point are removed. This is ignored if there's no*maxDigits*value.

getAbs()

getCeil()

getE(*digits*)

*e*(the base of the natural logarithm, approximately 2.781828183) to the given number of digits of precision. This is a static method, so you can call this method directly on the BigNumber class itself:

x = BigNumber.getE(10);

The BigNumber class internally caches the value of *e* to the
highest precision calculated so far during the program's execution, so
this routine only needs to compute the value when it is called with a
higher precision than that of the previously cached value.

getFloor()

getFraction()

getPi(*digits*)

*pi*(

*pi*, the mathematical constant defined as the ratio of a circle's circumfrence to its diameter, approximately 3.14159265) to the given number of digits of precision. This is a static method, so you can call this method directly on the BigNumber class itself:

x = BigNumber.getPi(10);

The BigNumber class internally caches the value of *pi* to the
highest precision calculated so far during the program's execution, so
this routine only needs to compute the value when it is called with a
higher precision than that of the cached value.

getPrecision()

getScale()

getWhole()

isNegative()

log10()

logE()

negate()

numType()

The return value is an integer with a combination of the following bit flags. Multiple flags may be returned, combined with |. Use & to test for a flag: (n.numType() & NumTypeNAN) is non-zero if the "not a number" flag is set.

- NumTypeNum - an ordinary number.
- NumTypeNAN - Not a Number (NaN). This value is used in some floating point systems as the result from a calculation with an invalid input, such as sqrt(-1). BigNumber doesn't currently return this from any calculations, since any BigNumber function given an invalid argument value will instead throw an error. However, it's possible to construct BigNumber NaN values, such as by reading an IEEE 754-2008 NaN from a file via unpackBytes().
- NumTypePInf - positive infinity. This is used in some floating point systems to represent overflows or the results of transcendental functions with infinite values, such as tan(pi/2). As with NaN, BigNumber calculations never return infinities; they throw overflow errors instead. However, you can construct Infinity values, such as by reading IEEE 754-2008 infinities via unpackBytes().
- NumTypeNInf - negative infinity.
- NumTypeInf == NumTypePInf | NumTypeNInf. This is defined for your convenience, so that you can test for any infinity with a simpler expression; e.g., (n.numType() & NumTypeInf) != 0. Any given number will have only one of the positive or negative infinity flags set.
- NumTypePZero - positive zero. Mathmetically, zero is neither positive nor negative, but the BigNumber representation retains a sign for all numbers, even zero. If this flag is set, NumTypeNum will also be set, since zero is an ordinary number.
- NumTypeNZero - negative zero. A negative zero can result from a calculation that yields a negative value with an absolute value too small to store in the available precision. It can also be constructed by unpacking a negative zero IEEE 754-2008 value. The NumTypeNum flag will always be set if this flag is set.
- NumTypeZero == NumTypePZero | NumTypeNZero. This is defined for your convenience, so that you can test for any zero with a simpler expression; e.g., n.numType() & NumTypeZero) != 0. Any given number will have only one of the positive or negative zero flags set.

radiansToDegrees()

*pi*).

raiseToPower(*y*)

*y*and returns the result. If the value of the target number is negative, then

*y*must be an integer: if

*x*< 0, we can rewrite

*x*

^{y}as (-1)

^{y}(-

*x*)

^{y}, and we know that -

*x*> 0 because

*x*< 0. The result of raising -1 to a non-integer exponent cannot be represented as a real number, hence this function throws an error if the target number is negative. Note also that raising zero to any positive exponent yields 0, and raising any value to the power 0 yields 1. Raising 0 to an exponent of 0 is undefined; 0 raised to any negative exponent is equivalent to the inverse of 0 to the absolute value of the exponent, which is the same as 1/0, which throws a divide-by-zero exception.

roundToDecimal(*places*)

*places*is zero, this simply rounds the number to an integer. If

*places*is less than zero, this rounds the number to a power of ten: roundToDecimal(-1) rounds to the nearest multiple of ten, roundToDecimal(-2) rounds to the nearest multiple of 100, and so on. Note that the precision of the result is the same as the precision of the original value; rounding merely affects the value, not the stored precision.

scaleTen(*x*)

^{x}. If

*x*is positive, this multiplies this number's value by ten

*x*times (so if

*x*= 3, the result is this number's value times 1000). If

*x*is negative, this divides this number's value by ten

*x*times. (This is more efficient than explicitly multiplying by ten, because it simply adjusts the number's internal scale factor.)

setPrecision(*digits*)

*digits*is higher than this number's precision, the new value is simply extended with zeros in the added trailing digits. If

*digits*is lower than this number's precision, the value is rounded to the given number of digits of precision.

sine()

Note that the input value must be expressed in radians. If you are
working in degrees, you can convert to radians by multiplying your
degree values by (*pi*/180), since 180 degress equals *pi* radians.
For convenience, you can use the degreesToRadians() function to
perform this conversion.

Note also that this remainder calculation's precision is limited by the precision of the original number itself, so a very large number with insufficient precision to represent at least a few digits after the decimal point (1.234e27, for example) will encounter a possibly significant amount of rounding error, which will affect the accuracy of the result. This should almost never be a problem in practice, because there is usually little reason to compute angle values outside of plus or minus a few times pi, but users should keep this in mind if they are using very large numbers and the trigonometric functions yield unexpected or inaccurate results.

sinh()

sqrt()

tangent()

Note that the tangent of (2*n*+1)**pi*/2, where *n* is
any integer, (i.e., any odd multiple of *pi*/2) is undefined, and that
the limit approaching these values is plus or minus infinity. The
BigNumber class internally calculates the tangent as the sine divided
by the cosine, and as a result it is possible to generate a
divide-by-zero exception by evaluating the tangent at one of these
values. However, in most cases, because the input value cannot be
exactly an odd multiple of *pi*/2 (because it isn't even theoretically
possible to represent *pi* exactly with a finite number of decimal
digits), the tangent will return a number with a very large absolute
value.

tanh()

## Precision and Scale

Each floating-point value that BigNumber represents has two important attributes apart from its value: precision and scale. For the most part, these are internal attributes that you can ignore; however, in certain cases, it's useful to know how BigNumber uses these internally.

The scale of a BigNumber value is a multiplier that determines how
large the number really is. A BigNumber value stores a scale so that
very large and very small numbers can be represented compactly,
without storing all of the digits that would be necessary to write out
the numbers in decimal format. This is the same idea behind
scientific notation, where you write a number as a value between 1 and
10 multiplied by a power of ten; for example, we could write four
hundred fifty billion as 450,000,000,000, or more compactly in
scientific notation as 4.5e11. The "e" means "times ten to the", so
4.5e11 means 4.5 × 10^{11}. (10^{11} is one
hundred billion.) When we write a number in scientific notation, we
only need to write the significant digits, so we can leave out all the
extra trailing zeros of a very large number. We can also use
scientific notation to write numbers with very small absolute values,
by using negative exponents: 9.7e-9 is 9.7 × 10^{-9};
10^{-9 } is 1/(10^{9}), or one one-billionth.
Internally, a BigNumber is stored just like this: it's stored as small
number times a power of ten. The power of ten is what we call the
scale.

The precision of a BigNumber value is the number of decimal digits that the value actually stores. A number's precision determines how many distinct values it can have; the higher the precision, the more values it can store, and hence the finer the distinctions it can make between adjacent representable values. The precision is independent of the scale; if you create a BigNumber value with only one digit of precision, it's not limited to representing the values -9 through +9, because the scale can allow it take on larger or smaller values. So, you can represent arbitrarily large values regardless of a number's precision; however, the precision limits the number of distinct values the number can represent. So, for example, with one digit of precision, the next representable value after 8000 is 9000.

When you create a BigNumber value, you can explicitly assign it a precision by passing a precision specifier to the constructor. If you don't specify a precision, BigNumber uses a default precision. If you create a BigNumber value from an integer, the default precision is 32 digits. This includes "implicit conversions", where the system automatically converts an integer to a BigNumber because the two types are combined with an operator in an expression, such as 3.0 + 1000.

If you create a BigNumber value from a string, the default precision is exactly enough to store the value's significant digits. A significant digit is a non-zero digit, or a zero that follows a non-zero digit.

Here are some examples:

- '0012' has two significant digits (the leading zeros are ignored).
- '1.2000' has five significant digits (the trailing zeros are significant because they follow non-zero digits).
- '.00012' has two significant digits (the leading zeros are ignored, even though they follow the decimal point).
- '000.00012' has two significant digits (leading zeros are ignored, whether they appear before or after the decimal point).
- '1.00012' has six significant digits (the zeros after the decimal point are significant because they follow a non-zero digit).
- '3.20e06' has three significant digits (the digits of the exponent, if specified, are not relevant to the number's precision).

When you use BigNumber values in calculations, the result in almost every case has the same precision as the value operated upon. In calculations involving two or more operands, the result has precision equal to the greatest of the precisions of the operands. For example, if you add a number with three digits of precision to a number with eight digits of precision, the result will have eight digits of precision. This has the desirable effect of preserving the precision of your values in arithmetic, so that the precision you choose for your input data values is carried forward throughout your calculations. For example, consider this calculation:

x = new BigNumber('3.1415'); y = new BigNumber('0.000111'); z = x + y;

The exact arithmetic value of this calculation would be 3.1416111, but this isn't the value that ends up in z, because the precision of the operands limits the precision of the result. The precision of x is 5, because it is created from a string with five significant digits. The precision of y is 3. The result of the addition will have a precision of 5, because that's the larger of the two input precisions. So, the result value stored in z will be 3.1416 - the additional two digits of y are dropped, because they don't fit in the result value's 5 digits of precision.

Precision limitations are fairly intuitive when the precision lost is after the decimal point, but note that digits can also be dropped before a decimal point. Consider this calculation:

x = new BigNumber('7.25e3'); y = new BigNumber('122'); z = x + y;

The value of x is 7.25e3, or 7250; this value has three digits of precision. The value of y also has three digits of precision. The exact result of the calculation is 7372, but the value stored in z will be 7370: the last digit of y is dropped because the result doesn't have enough precision to represent it.

Note that calculations will in most cases round their result values when they must drop precision from operand values. For example:

x = new BigNumber('7.25e3'); y = new BigNumber('127'); z = x + y;

The exact result would be 7377, but the value stored in z will be 7380: the last digit of y is dropped, but the system rounds up the last digit retained because the dropped digit is 5 or higher (in this case, 7).