Skip to content

API

Jump to bottom
XeroXP edited this page Jul 12, 2022 · 7 revisions

API

For brevity, var, semicolons and ToString calls have been omitted in the examples below.

CONSTRUCTOR

new Big(n, config)
//n : number|string|Big : a decimal value
//config: BigConfig (optional)

By default, the argument n can be a number, string or Big number, but if Big.Config.STRICT is set to true an error will be thrown if n is not a string or Big number.

Note that primitive numbers are accepted purely as a convenience so that quotes don't need to be typed for numeric literals of up to 15 significant digits, and that a Big number is created from a number's toString value rather than from its underlying binary floating point value.

Infinity and hexadecimal literal strings, e.g. "0xff", are not valid.

String values in octal literal form will be interpreted as decimals, e.g. "011" is 11, not 9.

String values may be in exponential, as well as normal notation.

There is no limit to the number of digits of a string value (other than that of C#'s maximum array size), but the largest recommended exponent magnitude is 1000000.

Returns a new Big number with value n.

Throws if n is invalid.

x = new Big(9);                       // "9"
y = new Big(x);                       // "9"
new Big("5032485723458348569331745.33434346346912144534543");
new Big("4.321e+4");                  // "43210"
new Big("-735.0918e-430");            // "-7.350918e-428'
new Big(435.345);                     // "435.345"

Properties

DP

number : integer, 0 to 1e+6 inclusive

Default value: 20

The maximum number of decimal places of the results of operations involving division. It is relevant only to the Div and Sqrt methods, and the Pow method when the exponent is negative.

The value will be checked for validity when one of the above methods is called. An error will be thrown if the value is found to be invalid.

DP = 40

RM

number : 0, 1, 2 or 3

Default value: 1

The rounding mode used in operations involving division and by Round, ToExponential, ToFixed and ToPrecision.

Property Value Description BigDecimal equivalent
RoundingMode.ROUND_DOWN 0 Rounds towards zero. I.e. truncate, no rounding. ROUND_DOWN
RoundingMode.roundHalfUp 1 Rounds towards nearest neighbour. If equidistant, rounds away from zero. ROUND_HALF_UP
RoundingMode.ROUND_HALF_EVEN 2 Rounds towards nearest neighbour. If equidistant, rounds towards even neighbour. ROUND_HALF_EVEN
RoundingMode.ROUND_UP 3 Rounds away from zero. ROUND_UP

The value will be checked for validity when one of the above methods is called. An error will be thrown if the value is found to be invalid.

RM = RoundingMode.ROUND_DOWN
RM = RoundingMode.ROUND_UP

NE

number : integer, -1e+6 to 0 inclusive

Default value: -7

The negative exponent value at and below which ToString returns exponential notation.

var bigFactory = new BigFactory(new BigConfig()
{
    NE = -7
});
x = bigFactory.Big(0.00000123);            // "0.00000123"       e is -6
x = bigFactory.Big(0.000000123);           // "1.23e-7"

JavaScript numbers use exponential notation for negative exponents of -7 and below.

Regardless of the value of Big.Config.NE, the ToFixed method will always return a value in normal notation and the ToExponential method will always return a value in exponential form.

PE

number : integer, 0 to 1e+6 inclusive

Default value: 21

The positive exponent value at and above which ToString returns exponential notation.

var bigFactory = new BigFactory(new BigConfig()
{
    PE = -7
});
x = bigFactory.Big(12.3);                  // "12.3"        e is 1
x = bigFactory.Big(123);                   // "1.23e+2"

JavaScript numbers use exponential notation for positive exponents of 21 and above.

Regardless of the value of Big.Config.PE, the ToFixed method will always return a value in normal notation and the ToExponential method will always return a value in exponential form.

STRICT

true|false

Default value: false

When set to true, an error will be thrown if a primitive number is passed to the Big constructor, or if ValueOf is called, or if ToNumber is called on a Big which cannot be converted to a primitive number without a loss of precision.

var bigFactory = new BigFactory(new BigConfig()
{
    STRICT = true
});
x = bigFactory.Big(1);             // "TypeError: [BigSharp] String expected"
y = bigFactory.Big("1.000000000000000000001");
y.ToNumber();                      // "Error: [BigSharp] Imprecise conversion"

bigFactory.Config.STRICT = false;
x = bigFactory.Big(0.1);
y = bigFactory.Big("1.000000000000000000001");
2 + y.ToString();                  // "21.000000000000000000001"
y.ToNumber();                      // 1

INSTANCE

Methods

The methods inherited by a Big number instance from its constructor's prototype object.

A Big number is immutable in the sense that it is not changed by its methods.

Abs

Abs()

Returns a Big number whose value is the absolute value, i.e. the magnitude, of this Big number.

x = new Big(-0.8)
x.Abs()                     // "0.8"

Cmp

Cmp(n)
//n : number|string|Big
Returns
1 If the value of this Big number is greater than the value of n
-1 If the value of this Big number is less than the value of n
0 If this Big number and n have the same value

Throws if n is invalid.

x = new Big(6)
y = new Big(5)
x.Cmp(y)                   // 1
y.Cmp(x.Minus(1))          // 0

Div

Div(n)
//n : number|string|Big

Returns a Big number whose value is the value of this Big number divided by n.

If the result has more fraction digits than is specified by Big.Config.DP, it will be rounded to Big.Config.DP decimal places using rounding mode Big.Config.RM.

Throws if n is zero or otherwise invalid.

var bigFactory = new BigFactory(new BigConfig())
x = bigFactory.Big(355)
y = bigFactory.Big(113)
x.Div(y)                   // "3.14159292035398230088"
bigFactory.Config.DP = 2
x.Div(y)                   // "3.14"
x.Div(5)                   // "71"

Eq

Eq(n)
//n : number|string|Big

Returns true if the value of this Big number equals the value of n, otherwise returns false.

Throws if n is invalid.

x = new Big(0)
x.Eq("1e-324")             // false
new Big("-0").Eq(x)        // true  ( -0 === 0 )

Gt

Gt(n) ⇒ boolean
//n : number|string|Big

Returns true if the value of this Big number is greater than the value of n, otherwise returns false.

Throws if n is invalid.

0.1 > 0.3 - 0.2              // true
x = new Big(0.1)
x.Gt(Big(0.3).Minus(0.2))    // false
new Big(0).Gt(x)             // false

Gte

Gte(n)
//n : number|string|Big

Returns true if the value of this Big number is greater than or equal to the value of n, otherwise returns false.

Throws if n is invalid.

0.3 - 0.2 >= 0.1               // false
x = new Big(0.3).Minus(0.2)
x.Gte(0.1)                     // true
new Big(1).Gte(x)              // true

Lt

Lt(n)
//n : number|string|Big

Returns true if the value of this Big number is less than the value of n, otherwise returns false.

Throws if n is invalid.

0.3 - 0.2 < 0.1                // true
x = new Big(0.3).Minus(0.2)
x.Lt(0.1)                      // false
new Big(0).Lt(x)               // true

Lte

lte(n)
//n : number|string|Big

Returns true if the value of this Big number is less than or equal to the value of n, otherwise returns false.

Throws if n is invalid.

0.1 <= 0.3 - 0.2               // false
x = new Big(0.1)
x.Lte(new Big(0.3).Minus(0.2)) // true
new Big(-1).Lte(x)             // true

Minus

Minus(n)
//n : number|string|Big

Returns a Big number whose value is the value of this Big number minus n.

Throws if n is invalid.

0.3 - 0.1                  // 0.19999999999999998
x = new Big(0.3)
x.Minus(0.1)               // "0.2"

Mod

Mod(n)
//n : number|string|Big

Returns a Big number whose value is the value of this Big number modulo n, i.e. the integer remainder of dividing this Big number by n.

The result will have the same sign as this Big number, and it will match that of C#'s % operator (within the limits of its precision) and BigDecimal's remainder method.

Throws if n is zero or otherwise invalid.

1 % 0.9                    // 0.09999999999999998
x = new Big(1)
x.Mod(0.9)                 // "0.1"

Neg

Neg()

Returns a Big number whose value is the value of this Big number negated.

x = new Big(0.3)
x.Neg()                    // "-0.3"
x.Neg().Neg()              // "0.3"

Plus

Plus(n)
//n : number|string|Big

Returns a Big number whose value is the value of this Big number plus n.

Throws if n is invalid.

0.1 + 0.2                      // 0.30000000000000004
x = new Big(0.1)
y = x.Plus(0.2)                // "0.3"
new Big(0.7).Plus(x).Plus(y)   // "1.1"

Pow

Pow(n)
//n : number : integer, -1e+6 to 1e+6 inclusive

Returns a Big number whose value is the value of this Big number raised to the power n.

Here, n must be Int32, because only small integers are allowed.

If n is negative and the result has more fraction digits than is specified by Big.Config.DP, it will be rounded to Big.Config.DP decimal places using rounding mode Big.Config.RM.

Throws if n is invalid.

Note: High value exponents may cause this method to be slow to return.

var bigFactory = new BigFactory(new BigConfig())
Math.Pow(0.7, 2)                 // 0.48999999999999994
x = bigFactory.Big(0.7)
x.Pow(2)                         // "0.49"
bigFactory.Config.DP = 20
bigFactory.Big(3).Pow(-2)        // "0.11111111111111111111"

bigFactory.Big(123.456).Pow(1000).ToString().Length     // 5099
bigFactory.Big(2).Pow(1e+6)       // Time taken: 9 minutes 34 secs.

Prec

Prec(sd, rm)
//sd? : number : integer, 1 to 1e+6 inclusive
//rm? : number : 0, 1, 2 or 3

Returns a Big number whose value is the value of this Big number rounded to a maximum precision of sd significant digits using rounding mode rm, or Big.Config.RM if rm is omitted or undefined.

Throws if sd or rm is invalid.

down = RoundingMode.ROUND_DOWN
half_up = RoundingMode.ROUND_HALF_UP
x = new Big("9876.54321")
x.Prec(2)                 // "9900"
x.Prec(7)                 // "9876.543"
x.Prec(20)                // "9876.54321"
x.Prec(1, down)           // "9000"
x.Prec(1, half_up)        // "10000"
x                         // "9876.54321"

Round

Round(dp, rm)
//dp? : number : integer, -1e+6 to 1e+6 inclusive
//rm? : number : 0, 1, 2 or 3

Returns a Big number whose value is the value of this Big number rounded using rounding mode rm to a maximum of dp decimal places, or, if dp is negative, to an integer which is a multiple of 10**-dp.

if dp is omitted or is undefined, the return value is the value of this Big number rounded to a whole number.

if rm is omitted or is undefined, the current Big.Config.RM setting is used.

Throws if dp or rm is invalid.

x = 123.45
Math.Round(x)                            // 123

y = new Big(x)
y.Round()                                // "123"
y.Round(2)                               // "123.45"
y.Round(10)                              // "123.45"
y.Round(1, RoundingMode.ROUND_DOWN)      // "123.4"
y.Round(1, RoundingMode.ROUND_HALF_UP)   // "123.5"
y.Round(1, RoundingMode.ROUND_HALF_EVEN) // "123.4"
y.Round(1, RoundingMode.ROUND_UP)        // "123.5"
y.Round(-1, RoundingMode.ROUND_DOWN)     // "120"
y.Round(-2, RoundingMode.ROUND_UP)       // "200"
y                                        // "123.45"

Sqrt

Sqrt()

Returns a Big number whose value is the square root of this Big number.

If the result has more fraction digits than is specified by Big.Config.DP, it will be rounded to Big.Config.DP decimal places using rounding mode Big.Config.RM.

Throws if this Big number is negative.

x = new Big(16)
x.Sqrt()                   // "4"
y = new Big(3)
y.Sqrt()                   // "1.73205080756887729353"

Times

Times(n)
//n : number|string|Big

Returns a Big number whose value is the value of this Big number times n.

Throws if n is invalid.

0.6 * 3                    // 1.7999999999999998
x = new Big(0.6)
y = x.Times(3)             // "1.8"
new Big("7e+500").Times(y) // "1.26e+501"

ToExponential

ToExponential(dp, rm)
//dp? : number : integer, 0 to 1e+6 inclusive
//rm? : number : 0, 1, 2 or 3

Returns a string representing the value of this Big number in exponential notation to a fixed number of dp decimal places.

If the value of this Big number in exponential notation has more digits to the right of the decimal point than is specified by dp, the return value will be rounded to dp decimal places using rounding mode rm.

If the value of this Big number in exponential notation has fewer digits to the right of the decimal point than is specified by dp, the return value will be appended with zeros accordingly.

If dp is omitted or is undefined, the number of digits after the decimal point defaults to the minimum number of digits necessary to represent the value exactly.

if rm is omitted or is undefined, the current Big.Config.RM setting is used.

Throws if dp or rm is invalid.

x = 45.6
y = new Big(x)
x.ToExponential()                           // "4.56e+1"
y.ToExponential()                           // "4.56e+1"
x.ToExponential(0)                          // "5e+1"
y.ToExponential(0)                          // "5e+1"
x.ToExponential(1)                          // "4.6e+1"
y.ToExponential(1)                          // "4.6e+1"
y.ToExponential(1, RoundingMode.ROUND_DOWN) // "4.5e+1"
x.ToExponential(3)                          // "4.560e+1"
y.ToExponential(3)                          // "4.560e+1"

ToFixed

ToFixed(dp, rm)
//dp? : number : integer, 0 to 1e+6 inclusive
//rm? : number : 0, 1, 2 or 3

Returns a string representing the value of this Big number in normal notation to a fixed number of dp decimal places.

If the value of this Big number in normal notation has more digits to the right of the decimal point than is specified by dp, the return value will be rounded to dp decimal places using rounding mode rm.

If the value of this Big number in normal notation has fewer fraction digits then is specified by dp, the return value will be appended with zeros accordingly.

This method will always return normal notation.

If dp is omitted or is undefined, the return value is simply the value in normal notation.

if rm is omitted or is undefined, the current Big.Config.RM setting is used.

Throws if dp or rm is invalid.

x = 45.6
y = new Big(x)
x.ToFixed()                // "46"
y.ToFixed()                // "45.6"
y.ToFixed(0)               // "46"
x.ToFixed(3)               // "45.600"
y.ToFixed(3)               // "45.600"

ToJSON

ToJSON()

As ToString.

ToPrecision

ToPrecision(sd, rm)
//sd? : number : integer, 1 to 1e+6 inclusive
//rm? : number : 0, 1, 2 or 3

Returns a string representing the value of this Big number to the specified number of sd significant digits.

If the value of this Big number has more digits than is specified by sd, the return value will be rounded to sd significant digits using rounding mode rm.

If the value of this Big number has fewer digits than is specified by sd, the return value will be appended with zeros accordingly.

If sd is less than the number of digits necessary to represent the integer part of the value in normal notation, exponential notation is used.

If sd is omitted or is undefined, the return value is the same as .ToString().

if rm is omitted or is undefined, the current Big.Config.RM setting is used.

Throws if sd or rm is invalid.

x = 45.6
y = new Big(x)
x.ToPrecision()            // "45.6"
y.ToPrecision()            // "45.6"
x.ToPrecision(1)           // "5e+1"
y.ToPrecision(1)           // "5e+1"
x.ToPrecision(5)           // "45.600"
y.ToPrecision(5)           // "45.600"

ToNumber

ToNumber()

Returns a primitive number representing the value of this Big number.

x = new Big("123.45")
x.ToNumber()               // 123.45
y = new Big("1.0000000000000000001")
y.ToNumber()               // 1

If Big.Config.STRICT is true an error will be thrown if ToNumber is called on a Big number which cannot be converted to a primitive number without a loss of precision.

ToString

ToString()

Returns a string representing the value of this Big number.

If this Big number has a positive exponent that is equal to or greater than 21, or a negative exponent equal to or less than -7, exponential notation is returned.

The point at which ToString returns exponential rather than normal notation can be adjusted by changing the value of Big.Config.PE and Big.Config.NE.

x = new Big("9.99e+20")
x.ToString()               // "999000000000000000000"
y = new Big("1E21")
y.ToString()               // "1e+21"

ValueOf

ValueOf()

As ToString except the minus sign is included for negative zero.

x = new Big("-0")
x.ValueOf()                 // "-0"
x.ToString()                // "0"

To prevent accidental usage of Big numbers with arithmetic operators, if Big.Config.STRICT is true any explicit or implicit calls to ValueOf will result in an error.

Instance Properties

A Big number is an object with three properties:

Property Description Type Value
c coefficient* long[] Array of single digits
e exponent long Integer, -1e+6 to 1e+6 inclusive
s sign int -1 or 1

*significand

The value of a Big number is stored in a normalised decimal floating point format which corresponds to the value's ToExponential form, with the decimal point to be positioned after the most significant (left-most) digit of the coefficient.

Note that the original exponent and fractional trailing zeros are not preserved.

x = new Big(0.123)                 // "0.123"
x.ToExponential()                  // "1.23e-1"
x.c                                // "1,2,3"
x.e                                // -1
x.s                                // 1

z = new Big("-123.4567000e+2")     // "-12345.67"
z.ToExponential()                  // "-1.234567e+4"
z.c                                // "1,2,3,4,5,6,7"
z.e                                // 4
z.s                                // -1

A Big number is mutable in the sense that the value of its properties can be changed. For example, to rapidly shift a value by a power of 10:

x = new Big("1234.000")    // "1234"
x.ToExponential()          // "1.234e+3"
x.c                        // "1,2,3,4"
x.e                        // 3

x.e = -5
x                          // "0.00001234"

If changing the coefficient array directly, which is not recommended, be careful to avoid leading or trailing zeros (unless zero itself is being represented).

Minus zero is a valid Big number value, but commonly the minus sign is not shown by ToString.

y = new Big("-0")          // "0"
y.c                        // "0"    [0].ToString()
y.e                        // 0
y.s                        // -1

Errors

The errors that are thrown are instances of BigException. The message of the errors always begins with [BigSharp], for example:

Error: [BigSharp] Invalid value

Method(s) Error message Thrown on/when
Big
Cmp
Div
Eq Gt Gte Lt Lte
Minus
Mod
Plus
Times 		Invalid value Invalid value
String expected Big.Config.STRICT is true
Div Division by zero Division by zero
Invalid decimal places Invalid Big.Config.DP
Invalid rounding mode Invalid Big.Config.RM
Mod Division by zero Modulo zero
Pow Invalid exponent Invalid exponent
Invalid decimal places Invalid Big.Config.DP
Invalid rounding mode Invalid Big.Config.RM
Prec Invalid precision Invalid sd
Invalid rounding mode Invalid rm/Big.Config.RM
Round Invalid decimal places Invalid dp
Invalid rounding mode Invalid rm/Big.Config.RM
Sqrt No square root Negative number
Invalid decimal places Invalid Big.Config.DP
Invalid rounding mode Invalid Big.Config.RM
ToExponential Invalid decimal places Invalid dp
Invalid rounding mode Invalid rm/Big.Config.RM
ToFixed Invalid decimal places Invalid dp
Invalid rounding mode Invalid rm/Big.Config.RM
ToNumber Imprecise conversion Big.Config.STRICT is true
ToPrecision Invalid precision Invalid sd
Invalid rounding mode Invalid rm/Big.Config.RM
ValueOf ValueOf disallowed Big.Config.STRICT is true
Clone this wiki locally