API

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

CONSTRUCTOR
- Methods
  - Abs
  - Acos
  - Acosh
  - Add
  - Asin
  - Asinh
  - Atan2
  - Cbrt
  - Ceil
  - Clamp
  - Clone
  - Cos
  - Cosh
  - Div
  - Exp
  - Floor
  - Hypot
  - IsDecimalInstance
  - Ln
  - Log
  - Log2
  - Log10
  - Max
  - Min
  - Mod
  - Mul
  - Pow
  - Random
  - Round
  - Sign
  - Sin
  - Sinh
  - Sqrt
  - Sub
  - Sum
  - Tan
  - Tanh
  - Trunc
Config Properties
- Precision
- Rounding
- MinE
- MaxE
- ToExpNeg
- ToExpPos
- Modulo
- Crypto
- Rounding modes
INSTANCE
Errors
Pi

CONSTRUCTOR

new BigDecimalFactory(config)
//config: BigDecimalConfig (optional)

Returns a new BigDecimalFactory object instance.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
x = bigDecimalFactory.BigDecimal(9)                       // "9"
y = bigDecimalFactory.BigDecimal(x)                       // "9"

Methods

The methods of a BigDecimalFactory.

Abs

Abs(x)
//x : number|string|BigDecimal

See AbsoluteValue.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Abs(x)
b = new BigDecimal(x).Abs()
a.Equals(b)                    // true

Acos

Acos(x)
//x : number|string|BigDecimal

See InverseCosine.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Acos(x)
b = new BigDecimal(x).Acos()
a.Equals(b)                    // true

Acosh

Acosh(x)
//x : number|string|BigDecimal

See InverseHyperbolicCosine.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Acosh(x)
b = new BigDecimal(x).Acosh()
a.Equals(b)                    // true

Add

Add(x, y)
//x : number|string|BigDecimal
//y : number|string|BigDecimal

See plus.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Add(x, y)
b = new BigDecimal(x).Add(y)
a.Equals(b)                    // true

Asin

Asin(x)
//x : number|string|BigDecimal

See InverseSine.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Asin(x)
b = new BigDecimal(x).Asin()
a.Equals(b)                    // true

Asinh

Asinh(x)
//x : number|string|BigDecimal

See InverseHyperbolicSine.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Asinh(x)
b = new BigDecimal(x).Asinh()
a.Equals(b)                    // true

Atan

Atan(x)
//x : number|string|BigDecimal

See InverseTangent.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Atan(x)
b = new BigDecimal(x).Atan()
a.Equals(b)                    // true

Atanh

Atanh(x)
//x : number|string|BigDecimal

See InverseHyperbolicTangent.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Atanh(x)
b = new BigDecimal(x).Atanh()
a.Equals(b)                    // true

Atan2

Atan2(x, y)
//x : number|string|BigDecimal
//y : number|string|BigDecimal

Returns a new BigDecimal whose value is the inverse tangent in radians of the quotient of y and x, rounded to precision significant digits using rounding mode rounding.

The signs of y and x are used to determine the quadrant of the result.

Domain: [-Infinity, Infinity]

Range: [-pi, pi]

See Pi.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
r = bigDecimalFactory.Atan2(y, x)

Cbrt

Cbrt(x)
//x : number|string|BigDecimal

See CubeRoot.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Cbrt(x)
b = new BigDecimal(x).Cbrt()
a.Equals(b)                    // true

Ceil

Ceil(x)
//x : number|string|BigDecimal

See Ceil.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Ceil(x)
b = new BigDecimal(x).Ceil()
a.Equals(b)                    // true

Clamp

Clamp(min, max)
//min : number|string|BigDecimal
//max : number|string|BigDecimal

See ClampedTo.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
bigDecimalFactory.Clamp(10.1, 0, 10)     // "10"

Clone

Clone()

Returns a new independent BigDecimalFactory with the same settings as this BigDecimalFactory.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig() {
    Precision = 5
})
bigDecimalFactory2 = bigDecimalFactory.Clone()
bigDecimalFactory2.Config.Precision = 9

a = bigDecimalFactory.BigDecimal(1)
b = bigDecimalFactory.BigDecimal(1)

a.div(3)                           // 0.33333
b.div(3)                           // 0.333333333

Cos

Cos(x)
//x : number|string|BigDecimal

See Cosine.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Cos(x)
b = new BigDecimal(x).Cos()
a.Equals(b)                    // true

Cosh

Cosh(x)
//x : number|string|BigDecimal

See HyperbolicCosine.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Cosh(x)
b = new BigDecimal(x).Cosh()
a.Equals(b)                    // true

Div

Div(x, y)
//x : number|string|BigDecimal
//y : number|string|BigDecimal

See DividedBy.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Div(x, y)
b = new BigDecimal(x).Div(y)
a.Equals(b)                    // true

Exp

Exp(x)
//x : number|string|BigDecimal

See NaturalExponential.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Exp(x)
b = new BigDecimal(x).Exp()
a.Equals(b)                    // true

Floor

Floor(x)
//x : number|string|BigDecimal

See Floor.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Floor(x)
b = new BigDecimal(x).Floor()
a.Equals(b)                    // true

Hypot

Hypot([x [, y, ...]])
//x : number|string|BigDecimal
//y : number|string|BigDecimal

Returns a new BigDecimal whose value is the square root of the sum of the squares of the arguments, rounded to precision significant digits using rounding mode rounding.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
r = bigDecimalFactory.Hypot(x, y)

Ln

Ln(x)
//x : number|string|BigDecimal

See NaturalLogarithm.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Ln(x)
b = new BigDecimal(x).Ln()
a.Equals(b)                    // true

IsDecimalInstance

IsDecimalInstance(object)
//object : any

Returns true if object is a BigDecimal instance, or false if it is not.

a = new BigDecimal(1)
b = new { x = 1, y = 2 }
BigDecimalFactory.IsDecimalInstance(a)           // true
BigDecimalFactory.IsDecimalInstance(b)           // false

Log

Log(x [, base])
//x : number|string|BigDecimal
//base : number|string|BigDecimal

See Logarithm.

The default base is 10, which is not the same as C#'s Math.Log(), which returns the natural logarithm (base e).

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Log(x, y)
b = new BigDecimal(x).Log(y)
a.Equals(b)                    // true

Log2

Log2(x)
//x : number|string|BigDecimal

Returns a new BigDecimal whose value is the base 2 logarithm of x, rounded to precision significant digits using rounding mode rounding.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
r = bigDecimalFactory.Log2(x)

Log10

Log10(x)
//x : number|string|BigDecimal

Returns a new BigDecimal whose value is the base 10 logarithm of x, rounded to precision significant digits using rounding mode rounding.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
r = bigDecimalFactory.Log10(x)

Max

Max(x [, y, ...])
//x : number|string|BigDecimal
//y : number|string|BigDecimal

Returns a new BigDecimal whose value is the maximum of the arguments.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
r = bigDecimalFactory.Max(x, y, z)

Min

Min(x [, y, ...])
//x : number|string|BigDecimal
//y : number|string|BigDecimal

Returns a new BigDecimal whose value is the minimum of the arguments.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
r = bigDecimalFactory.Min(x, y, z)

Mod

Mod(x, y)
//x : number|string|BigDecimal
//y : number|string|BigDecimal

See Modulo.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Mod(x, y)
b = new BigDecimal(x).Mod(y)
a.Equals(b)                    // true

Mul

Mul(x, y)
//x : number|string|BigDecimal
//y : number|string|BigDecimal

See Times.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Mul(x, y)
b = new BigDecimal(x).Mul(y)
a.Equals(b)                    // true

Pow

Pow(base, exponent)
//base : number|string|BigDecimal
//exponent : number|string|BigDecimal

See ToPower.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Pow(x, y)
b = new BigDecimal(x).Pow(y)
a.Equals(b)                    // true

Random

Random([dp])
//dp : number : integer, 0 to 1e+9 inclusive

Returns a new BigDecimal with a pseudo-random value equal to or greater than 0 and less than 1.

The return value will have dp decimal places (or less if trailing zeros are produced). If dp is omitted then the number of decimal places will default to the current precision setting.

If the value of this BigDecimal Config's crypto property is true, the random digits of the return value are generated by System.Security.Cryptography.RandomNumberGenerator, otherwise, if the the value of the property is false the return value is generated by System.Random (fastest).

If the crypto methods is used, the value of the returned BigDecimal should be cryptographically-secure and statistically indistinguishable from a random value.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig() {
    Precision = 10
})
bigDecimalFactory.Random()                    // "0.4117936847"
bigDecimalFactory.Random(20)                  // "0.78193327636914089009"

Round

Round(x)
//x : number|string|BigDecimal

See Round.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Round(x)
b = new BigDecimal(x).Round()
a.Equals(b)                    // true

Sign

Sign(x)
//x : number|string|BigDecimal

Returns
`1`	if the value of `x` is non-zero and its sign is positive
`-1`	if the value of `x` is non-zero and its sign is negative
`0`	if the value of `x` is positive zero
`-0`	if the value of `x` is negative zero
`null`	if the value of `x` is `NaN`

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
r = bigDecimalFactory.Sign(x)

Sin

Sin(x)
//x : number|string|BigDecimal

See Sine.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Sin(x)
b = new BigDecimal(x).Sin()
a.Equals(b)                    // true

Sinh

Sinh(x)
//x : number|string|BigDecimal

See HyperbolicSine.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Sinh(x)
b = new BigDecimal(x).Sinh()
a.Equals(b)                    // true

Sqrt

Sqrt(x)
//x : number|string|BigDecimal

See SquareRoot.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Sqrt(x)
b = new BigDecimal(x).Sqrt()
a.Equals(b)                    // true

Sub

Sub(x, y)
//x : number|string|BigDecimal
//y : number|string|BigDecimal

See Minus.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Sub(x, y)
b = new BigDecimal(x).Sub(y)
a.Equals(b)                    // true

Sum

Sum(x [, y, ...])
//x : number|string|BigDecimal
//y : number|string|BigDecimal

Returns a new Decimal whose value is the sum of the arguments, rounded to precision significant digits using rounding mode rounding.

Only the result is rounded, not the intermediate summations.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
x = 5
y = "16"
z = bigDecimalFactory.BigDecimal(-11)
bigDecimalFactory.Sum(x, y, z)           // "10"

Tan

Tan(x)
//x : number|string|BigDecimal

See Tangent.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Tan(x)
b = new BigDecimal(x).Tan()
a.Equals(b)                    // true

Tanh

Tanh(x)
//x : number|string|BigDecimal

See HyperbolicTangent.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Tanh(x)
b = new BigDecimal(x).Tanh()
a.Equals(b)                    // true

Trunc

Trunc(x)
//x : number|string|BigDecimal

See Truncated.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
a = bigDecimalFactory.Trunc(x)
b = new BigDecimal(x).Trunc()
a.Equals(b)                    // true

Config Properties

The properties of a BigDecimal Config.

Configuration properties

The values of the configuration properties Precision, Rounding, MinE, MaxE, ToExpNeg, ToExpPos, Modulo, and Crypto are set using the Config.

new BigDecimalConfig() {
    Precision = 0
}
// "[DecimalError] Invalid argument: Precision: 0"

Precision

number: integer, 1 to 1e+9 inclusive

Default value: 20

The maximum number of significant digits of the result of an operation.

All functions which return a BigDecimal will round the return value to precision significant digits except BigDecimal, AbsoluteValue, Ceil, Floor, Negated, Round, ToDecimalPlaces, ToNearest and Truncated.

See Pi for the precision limit of the trigonometric methods.

new BigDecimalConfig() {
    Precision = 5
}

Rounding

RoundingMode

Default value: RoundingMode.ROUND_HALF_UP

The default rounding mode used when rounding the result of an operation to Precision significant digits, and when rounding the return value of the Round, ToBinary, ToDecimalPlaces, ToExponential, ToFixed, ToHexadecimal, ToNearest, ToOctal, ToPrecision and ToSignificantDigits methods.

The rounding modes are available as enumerated properties of the constructor.

new BigDecimalConfig() {
    Rounding = RoundingMode.ROUND_UP
}

MinE

number: integer, -9e15 to 0 inclusive

Default value: -9e15

The negative exponent limit, i.e. the exponent value below which underflow to zero occurs.

If the BigDecimal to be returned by a calculation would have an exponent lower than MinE then the value of that BigDecimal becomes zero.

JavaScript numbers underflow to zero for exponents below -324.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig() {
    MinE = -500
})
bigDecimalFactory.BigDecimal("1e-500")              // "1e-500"
bigDecimalFactory.BigDecimal("9.9e-501")            // "0"

bigDecimalFactory.Config.MinE = -3
bigDecimalFactory.BigDecimal(0.001)                 // "0.01"       e is -3
bigDecimalFactory.BigDecimal(0.0001)                // "0"          e is -4

The smallest possible magnitude of a non-zero BigDecimal is 1e-9000000000000000

MaxE

number: integer, 0 to 9e15 inclusive

Default value: 9e15

The positive exponent limit, i.e. the exponent value above which overflow to Infinity occurs.

If the BigDecimal to be returned by a calculation would have an exponent higher than MaxE then the value of that BigDecimal becomes Infinity.

JavaScript numbers overflow to Infinity for exponents above 308.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig() {
    MaxE = 500
})
bigDecimalFactory.BigDecimal("9.999e500")           // "9.999e+500"
bigDecimalFactory.BigDecimal("1e501")               // "Infinity"

bigDecimalFactory.Config.MaxE = 4
bigDecimalFactory.BigDecimal(99999)                 // "99999"      e is 4
bigDecimalFactory.BigDecimal(100000)                // "Infinity"

The largest possible magnitude of a finite BigDecimal is 9.999...e+9000000000000000

ToExpNeg

number: integer, -9e15 to 0 inclusive

Default value: -7

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

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig() {
    ToExpNeg = -7
})
bigDecimalFactory.BigDecimal(0.00000123)           // "0.00000123"       e is -6
bigDecimalFactory.BigDecimal(0.000000123)          // "1.23e-7"

// Always return exponential notation:
bigDecimalFactory.Config.ToExpNeg = 0

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

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

ToExpPos

number: integer, 0 to 9e15 inclusive

Default value: 20

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

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig() {
    ToExpPos = 2
})
bigDecimalFactory.BigDecimal(12.3)           // "12.3"        e is 1
bigDecimalFactory.BigDecimal(123)            // "1.23e+2"

// Always return exponential notation:
bigDecimalFactory.Config.ToExpPos = 0

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

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

Modulo

number: integer, 0 to 9 inclusive

Default value: 1 (ROUND_DOWN)

The modulo mode used when calculating the modulus: a mod n.

The quotient, q = a / n, is calculated according to the rounding mode that corresponds to the chosen modulo mode.

The remainder, r, is calculated as: r = a - n * q.

The modes that are most commonly used for the modulus/remainder operation are shown in the following table. Although the other rounding modes can be used, they may not give useful results.

Property	Value	Description
ROUND_UP	0	The remainder is positive if the dividend is negative, else is negative
ROUND_DOWN	1	The remainder has the same sign as the dividend.
This uses truncating division and matches the behaviour of JavaScript's remainder operator `%`.
ROUND_FLOOR	3	The remainder has the same sign as the divisor. (This matches Python's `%` operator)
ROUND_HALF_EVEN	6	The IEEE 754 remainder function
EUCLID	9	The remainder is always positive. Euclidian division: `q = sign(x) * floor(a / abs(x))`.

The rounding/modulo modes are available as enumerated properties of the BigDecimal Config.

new BigDecimalConfig() {
    Modulo = 9
}

Crypto

boolean: true/false

Default value: false

The value that determines whether cryptographically-secure pseudo-random number generation is used.

See Random.

new BigDecimalConfig() {
    Crypto = true
}

Rounding modes

Rounding modes 0 to 6 (inclusive) are the same as those of Java's BigDecimal class.

Property	Value	Description
ROUND_UP	0	Rounds away from zero
ROUND_DOWN	1	Rounds towards zero
ROUND_CEIL	2	Rounds towards Infinity
ROUND_FLOOR	3	Rounds towards -Infinity
ROUND_HALF_UP	4	Rounds towards nearest neighbour. If equidistant, rounds away from zero
ROUND_HALF_DOWN	5	Rounds towards nearest neighbour. If equidistant, rounds towards zero
ROUND_HALF_EVEN	6	Rounds towards nearest neighbour. If equidistant, rounds towards even neighbour
ROUND_HALF_CEIL	7	Rounds towards nearest neighbour. If equidistant, rounds towards Infinity
ROUND_HALF_FLOOR	8	Rounds towards nearest neighbour. If equidistant, rounds towards -Infinity
EUCLID	9	Not a rounding mode, see `Modulo`

new BigDecimalConfig() {
    Rounding = RoundingMode.ROUND_CEIL
}

INSTANCE

new BigDecimal(value, config)
//value : number|string|BigDecimal
//config: BigDecimalConfig (optional)

A legitimate value is an integer or float, including ±0, or is ±Infinity, or NaN.

The number of digits of value is not limited, except by C#'s maximum array size and, in practice, the processing time required.

The allowable range of value is defined in terms of a maximum exponent, see MaxE, and a minimum exponent, see MinE.

As well as in decimal, a string value may be expressed in binary, hexadecimal or octal, if the appropriate prefix is included: 0x or 0X for hexadecimal, 0b or 0B for binary, and 0o or 0O for octal.

Both decimal and non-decimal string values may use exponential (floating-point), as well as normal (fixed-point) notation.

In exponential notation, e or E defines a power-of-ten exponent for decimal values, and p or P defines a power-of-two exponent for non-decimal values, i.e. binary, hexadecimal or octal.

Returns a new BigDecimal object instance.

Throws on an invalid value.

x = new BigDecimal(9)                       // "9"
y = new BigDecimal(x)                       // "9"

new BigDecimal("5032485723458348569331745.33434346346912144534543")
new BigDecimal("4.321e+4")                  // "43210"
new BigDecimal("-735.0918e-430")            // "-7.350918e-428"
new BigDecimal("5.6700000")                 // "5.67"
new BigDecimal(double.PositiveInfinity)     // "Infinity"
new BigDecimal(double.NaN)                  // "NaN"
new BigDecimal(".5")                        // "0.5"
new BigDecimal("-0b10110100.1")             // "-180.5"
new BigDecimal("0xff.8")                    // "255.5"

new BigDecimal(0.046875)                    // "0.046875"
new BigDecimal("0.046875000000")            // "0.046875"
new BigDecimal("0.046_875_000_000")         // "0.046875"

new BigDecimal(4.6875e-2)                   // "0.046875"
new BigDecimal("468.75e-4")                 // "0.046875"

new BigDecimal("0b0.000011")                // "0.046875"
new BigDecimal("0o0.03")                    // "0.046875"
new BigDecimal("0x0.0c")                    // "0.046875"

new BigDecimal("0b1.1p-5")                  // "0.046875"
new BigDecimal("0o1.4p-5")                  // "0.046875"
new BigDecimal("0x1.8p-5")                  // "0.046875"

Instance Methods

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

A BigDecimal instance is immutable in the sense that it is not changed by its methods.

Methods that return a BigDecimal can be chained:

x = new BigDecimal(2).Times('999.999999999999999').DividedBy(4).Ceil()

Methods do not round their arguments before execution.

The treatment of ±0, ±Infinity and NaN is consistent with how JavaScript treats these values.

Many method names have a shorter alias. (Internally, the library always uses the shorter method names.)

AbsoluteValue (Abs)

Abs()

Returns a new BigDecimal whose value is the absolute value, i.e. the magnitude, of the value of this BigDecimal.

The return value is not affected by the value of the precision setting.

x = new BigDecimal(-0.8)
y = x.AbsoluteValue()         // "0.8"
z = y.Abs()                   // "0.8"

Ceil

Ceil()

Returns a new BigDecimal whose value is the value of this BigDecimal rounded to a whole number in the direction of positive Infinity.

The return value is not affected by the value of the precision setting.

x = new BigDecimal(1.3)
x.Ceil()                      // "2"
y = new BigDecimal(-1.8)
y.Ceil()                      // "-1"

ClampedTo (Clamp)

Clamp(min, max)
//min : number|string|BigDecimal
//max : number|string|BigDecimal

Returns a new BigDecimal whose value is the value of this BigDecimal clamped to the range delineated by min and max.

The return value is not affected by the value of the precision setting.

x = new BigDecimal(5)
min = new BigDecimal(100)
max = new BigDecimal(double.PositiveInfinity)
x.ClampedTo(min, max)         // "100"
x.Clamp(-10, -0.1)            // "-0.1"

ComparedTo (Cmp)

Cmp(x)
//x : number|string|BigDecimal

Returns
`1`	if the value of this BigDecimal is greater than the value of `x`
`-1`	if the value of this BigDecimal is less than the value of `x`
`0`	if this BigDecimal and `x` have the same value
`null`	if the value of either this BigDecimal or `x` is `NaN`

x = new BigDecimal(double.PositiveInfinity)
y = new BigDecimal(5)
x.ComparedTo(y)                // 1
x.ComparedTo(x.Minus(1))       // 0
y.Cmp(double.NaN)              // null

Cosine (Cos)

Cos()

Returns a new BigDecimal whose value is the cosine of the value in radians of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

Domain: [-Infinity, Infinity]

Range: [-1, 1]

See Pi for the precision limit of this method.

x = new BigDecimal(0.25)
x.Cosine()                      // "0.96891242171064478414"
y = new BigDecimal(-0.25)
y.Cos()                         // "0.96891242171064478414"

CubeRoot (Cbrt)

Cbrt()

Returns a new BigDecimal whose value is the cube root of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

The return value will be correctly rounded, i.e. rounded as if the result was first calculated to an infinite number of correct digits before rounding.

x = new BigDecimal(125)
x.CubeRoot()                    // "5"
y = new BigDecimal(3)
y.Cbrt()                        // "1.4422495703074083823"

DecimalPlaces (Dp)

Dp()

Returns the number of decimal places, i.e. the number of digits after the decimal point, of the value of this BigDecimal.

x = new BigDecimal(1.234)
x.DecimalPlaces()              // "3"
y = new BigDecimal(987.654321)
y.Dp()                         // "6"

DividedBy (Div)

Div(x)
//x : number|string|BigDecimal

Returns a new BigDecimal whose value is the value of this BigDecimal divided by x, rounded to precision significant digits using rounding mode rounding.

x = new BigDecimal(355)
y = new BigDecimal(113)
x.DividedBy(y)             // "3.14159292035398230088"
x.Div(5)                   // "71"

DividedToIntegerBy (DivToInt)

DivToInt(x)
//x : number|string|BigDecimal

Return a new BigDecimal whose value is the integer part of dividing this BigDecimal by x, rounded to precision significant digits using rounding mode rounding.

x = new BigDecimal(5)
y = new BigDecimal(3)
x.DividedToIntegerBy(y)     // "1"
x.DivToInt(0.7)             // "7"

Equals (Eq)

Eq(x)
//x : number|string|BigDecimal

Returns true if the value of this BigDecimal equals the value of x, otherwise returns false.

Note: This method uses the Cmp method internally.

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

Floor

Floor()

Returns a new BigDecimal whose value is the value of this BigDecimal rounded to a whole number in the direction of negative Infinity.

The return value is not affected by the value of the precision setting.

x = new BigDecimal(1.8)
x.Floor()                   // "1"
y = new BigDecimal(-1.3)
y.Floor()                   // "-2"

GreaterThan (Gt)

Gt(x)
//x : number|string|BigDecimal

Returns true if the value of this BigDecimal is greater than the value of x, otherwise returns false.

Note: This method uses the Cmp method internally.

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

GreaterThanOrEqualTo (Gte)

Gte(x)
//x : number|string|BigDecimal

Returns true if the value of this BigDecimal is greater than or equal to the value of x, otherwise returns false.

Note: This method uses the Cmp method internally.

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

HyperbolicCosine (Cosh)

Cosh()

Returns a new BigDecimal whose value is the hyperbolic cosine of the value in radians of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

Domain: [-Infinity, Infinity]

Range: [1, Infinity]

See Pi for the precision limit of this method.

x = new BigDecimal(1)
x.HyperbolicCosine()                     // "1.5430806348152437785"
y = new BigDecimal(0.5)
y.Cosh()                                 // "1.1276259652063807852"

HyperbolicSine (Sinh)

Sinh()

Returns a new BigDecimal whose value is the hyperbolic sine of the value in radians of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

Domain: [-Infinity, Infinity]

Range: [-Infinity, Infinity]

See Pi for the precision limit of this method.

x = new BigDecimal(1)
x.HyperbolicSine()                       // "1.1752011936438014569"
y = new BigDecimal(0.5)
y.Sinh()                                 // "0.52109530549374736162"

HyperbolicTangent (Tanh)

Tanh()

Returns a new BigDecimal whose value is the hyperbolic tangent of the value in radians of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

Domain: [-Infinity, Infinity]

Range: [-1, 1]

See Pi for the precision limit of this method.

x = new BigDecimal(1)
x.HyperbolicTangent()                    // "0.76159415595576488812"
y = new BigDecimal(0.5)
y.Tanh()                                 // "0.4621171572600097585"

InverseCosine (Acos)

Acos()

Returns a new BigDecimal whose value is the inverse cosine in radians of the value of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

Domain: [-1, 1]

Range: [0, pi]

See Pi for the precision limit of this method.

x = new BigDecimal(0)
x.InverseCosine()                        // "1.5707963267948966192"
y = new BigDecimal(0.5)
y.Acos()                                 // "1.0471975511965977462"

InverseHyperbolicCosine (Acosh)

Acosh()

Returns a new BigDecimal whose value is the inverse hyperbolic cosine in radians of the value of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

Domain: [1, Infinity]

Range: [0, Infinity]

See Pi for the precision limit of this method.

x = new BigDecimal(5)
x.InverseHyperbolicCosine()              // "2.2924316695611776878"
y = new BigDecimal(50)
y.Acosh()                                // "4.6050701709847571595"

InverseHyperbolicSine (Asinh)

Asinh()

Returns a new BigDecimal whose value is the inverse hyperbolic sine in radians of the value of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

Domain: [-Infinity, Infinity]

Range: [-Infinity, Infinity]

See Pi for the precision limit of this method.

x = new BigDecimal(5)
x.InverseHyperbolicSine()                // "2.3124383412727526203"
y = new BigDecimal(50)
y.Asinh()                                // "4.6052701709914238266"

InverseHyperbolicTangent (Atanh)

Atanh()

Returns a new BigDecimal whose value is the inverse hyperbolic tangent in radians of the value of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

Domain: [-1, 1]

Range: [-Infinity, Infinity]

See Pi for the precision limit of this method.

x = new BigDecimal(0.5)
x.InverseHyperbolicTangent()             // "0.5493061443340548457"
y = new BigDecimal(0.75)
y.Atanh()                                // "0.97295507452765665255"

InverseSine (Asin)

Asin()

Returns a new BigDecimal whose value is the inverse sine in radians of the value of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

Domain: [-1, 1]

Range: [-pi/2, pi/2]

See Pi for the precision limit of this method.

x = new BigDecimal(0.5)
x.InverseSine()                          // "0.52359877559829887308"
y = new BigDecimal(0.75)
y.Asin()                                 // "0.84806207898148100805"

InverseTangent (Atan)

Atan()

Returns a new BigDecimal whose value is the inverse tangent in radians of the value of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

Domain: [-Infinity, Infinity]

Range: [-pi/2, pi/2]

See Pi for the precision limit of this method.

x = new BigDecimal(0.5)
x.InverseTangent()                       // "0.46364760900080611621"
y = new BigDecimal(0.75)
y.Atan()                                 // "0.6435011087932843868"

IsFinite

IsFinite()

Returns true if the value of this BigDecimal is a finite number, otherwise returns false.

The only possible non-finite values of a BigDecimal are NaN, Infinity and -Infinity.

x = new BigDecimal(1)
x.IsFinite()                             // true
y = new BigDecimal(double.PositiveInfinity)
y.IsFinite()                             // false

IsInteger (IsInt)

IsInt()

Returns true if the value of this BigDecimal is a whole number, otherwise returns false.

x = new BigDecimal(1)
x.IsInteger()                            // true
y = new BigDecimal(123.456)
y.IsInt()                                // false

IsNaN

IsNaN()

Returns true if the value of this BigDecimal is NaN, otherwise returns false.

x = new BigDecimal(double.NaN)
x.IsNaN()                                // true
y = new BigDecimal("Infinity")
y.IsNaN()                                // false

IsNegative (IsNeg)

IsNeg()

Returns true if the value of this BigDecimal is negative, otherwise returns false.

x = new BigDecimal("-0")
x.IsNegative()                           // true
y = new BigDecimal(2)
y.IsNeg()                                // false

Note that zero is signed.

new BigDecimal(0).ValueOf()                 // "0"
new BigDecimal(0).IsNegative()              // false
new BigDecimal(0).Negated().ValueOf()       // "-0"
new BigDecimal(0).Negated().IsNegative()    // true
new BigDecimal("-0").IsNegative()           // true

IsPositive (IsPos)

IsPos()

Returns true if the value of this BigDecimal is positive, otherwise returns false.

x = new BigDecimal(0)
x.IsPositive()                           // true
y = new BigDecimal(-2)
y.IsPos()                                // false

IsZero

IsZero()

Returns true if the value of this BigDecimal is zero or minus zero, otherwise returns false.

x = new BigDecimal("-0")
x.IsZero() && x.IsNeg()                  // true
y = new BigDecimal(double.PositiveInfinity)
y.IsZero()                               // false

LessThan (Lt)

Lt(x)
//x : number|string|BigDecimal

Returns true if the value of this BigDecimal is less than the value of x, otherwise returns false.

Note: This method uses the Cmp method internally.

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

LessThanOrEqualTo (Lte)

Lte(x)
//x : number|string|BigDecimal

Returns true if the value of this BigDecimal is less than or equal to the value of x, otherwise returns false.

Note: This method uses the Cmp method internally.

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

Logarithm (Log)

Log(x)
//x : number|string|BigDecimal

Returns a new BigDecimal whose value is the base x logarithm of the value of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

If x is omitted, the base 10 logarithm of the value of this BigDecimal will be returned.

x = new BigDecimal(1000)
x.Logarithm()                            // "3"
y = new BigDecimal(256)
y.Log(2)                                 // "8"

The return value will almost always be correctly rounded, i.e. rounded as if the result was first calculated to an infinite number of correct digits before rounding. If a result is incorrectly rounded the maximum error will be 1 ulp (unit in the last place).

Logarithms to base 2 or 10 will always be correctly rounded.

See ToPower for the circumstances in which this method may return an incorrectly rounded result, and see NaturalLogarithm for the precision limit.

The performance of this method degrades exponentially with increasing digits.

Minus (Sub)

Minus(x)
//x : number|string|BigDecimal

Returns a new BigDecimal whose value is the value of this BigDecimal minus x, rounded to precision significant digits using rounding mode rounding.

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

Modulo (Mod)

Mod(x)
//x : number|string|BigDecimal

Returns a new BigDecimal whose value is the value of this BigDecimal modulo x, rounded to precision significant digits using rounding mode rounding.

The value returned, and in particular its sign, is dependent on the value of the modulo property of this BigDecimal's Config. If it is 1 (default value), the result will have the same sign as this BigDecimal, and it will match that of C#'s % operator (within the limits of double precision) and BigDecimal's remainder method.

See modulo for a description of the other modulo modes.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
1 % 0.9                                  // 0.09999999999999998
x = bigDecimalFactory.BigDecimal(1)
x.Modulo(0.9)                            // "0.1"

y = bigDecimalFactory.BigDecimal(8)
z = bigDecimalFactory.BigDecimal(-3)
bigDecimalFactory.Config.Modulo = 1
y.Mod(z)                                 // "2"
bigDecimalFactory.Config.Modulo = 3
y.Mod(z)                                 // "-1"

NaturalExponential (Exp)

Exp()

Returns a new BigDecimal whose value is the base e (Euler's number, the base of the natural logarithm) exponential of the value of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

The NaturalLogarithm function is the inverse of this function.

x = new BigDecimal(1)
x.NaturalExponential()                   // "2.7182818284590452354"
y = new BigDecimal(2)
y.Exp()                                  // "7.3890560989306502272"

The return value will be correctly rounded, i.e. rounded as if the result was first calculated to an infinite number of correct digits before rounding. (The mathematical result of the exponential function is non-terminating, unless its argument is 0).

The performance of this method degrades exponentially with increasing digits.

NaturalLogarithm (Ln)

Ln()

Returns a new BigDecimal whose value is the natural logarithm of the value of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

The natural logarithm is the inverse of the NaturalExponential function.

x = new BigDecimal(10)
x.NaturalLogarithm()                     // "2.3026"
y = new BigDecimal("1.23e+30")
y.Ln()                                   // "69.28"

The return value will be correctly rounded, i.e. rounded as if the result was first calculated to an infinite number of correct digits before rounding. (The mathematical result of the natural logarithm function is non-terminating, unless its argument is 1).

Internally, this method is dependent on a constant whose value is the natural logarithm of 10. This LN10 variable in the source code currently has a precision of 1025 digits, meaning that this method can accurately calculate up to 1000 digits.

If more than 1000 digits is required then the precision of LN10 will need to be increased to 25 digits more than is required - though, as the time-taken by this method increases exponentially with increasing digits, it is unlikely to be viable to calculate over 1000 digits anyway.

Negated (Neg)

Neg()

Returns a new BigDecimal whose value is the value of this BigDecimal negated, i.e. multiplied by -1.

The return value is not affected by the value of the precision setting.

x = new BigDecimal(1.8)
x.Negated()                              // "-1.8"
y = new BigDecimal(-1.3)
y.Neg()                                  // "1.3"

Plus (Add)

Plus(x)
//x : number|string|BigDecimal

Returns a new BigDecimal whose value is the value of this BigDecimal plus x, rounded to precision significant digits using rounding mode rounding.

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

Precision (Sd)

Sd([include_zeros])

Returns the number of significant digits of the value of this BigDecimal.

If include_zeros is true or 1 then any trailing zeros of the integer part of a number are counted as significant digits, otherwise they are not.

x = new BigDecimal(1.234)
x.Precision()                            // "4"
y = new BigDecimal(987000)
y.Sd()                                   // "3"
y.Sd(true)                               // "6"

Round

Round()

Returns a new BigDecimal whose value is the value of this BigDecimal rounded to a whole number using rounding mode rounding.

To emulate Math.Round, set rounding to ROUND_HALF_CEIL.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig() {
    Rounding = RoundingMode.ROUND_HALF_UP
})
x = new BigDecimal(1234.5)
x.Round()                                // "1235"

bigDecimalFactory.Config.Rounding = RoundingMode.ROUND_DOWN
x.Round()                                // "1234"
x                                        // "1234.5"

Sine (Sin)

Sin()

Returns a new BigDecimal whose value is the sine of the value in radians of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

Domain: [-Infinity, Infinity]

Range: [-1, 1]

See Pi for the precision limit of this method.

x = new BigDecimal(0.5)
x.Sine()                                 // "0.47942553860420300027"
y = new BigDecimal(0.75)
y.Sin()                                  // "0.68163876002333416673"

SquareRoot (Sqrt)

Sqrt()

Returns a new BigDecimal whose value is the square root of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

The return value will be correctly rounded, i.e. rounded as if the result was first calculated to an infinite number of correct digits before rounding.

This method is much faster than using the ToPower method with an exponent of 0.5.

x = new BigDecimal(16)
x.SquareRoot()                           // "4"
y = new BigDecimal(3)
y.Sqrt()                                 // "1.73205080756887729353"
y.Sqrt().Eq( y.Pow(0.5) )                // true

Tangent (Tan)

Tan()

Returns a new BigDecimal whose value is the tangent of the value in radians of this BigDecimal, rounded to precision significant digits using rounding mode rounding.

Domain: [-Infinity, Infinity]

Range: [-Infinity, Infinity]

See Pi for the precision limit of this method.

x = new BigDecimal(0.5)
x.Tangent()                              // "0.54630248984379051326"
y = new BigDecimal(0.75)
y.Tan()                                  // "0.93159645994407246117"

Times (Mul)

Times(x)
//x : number|string|BigDecimal

Returns a new BigDecimal whose value is the value of this BigDecimal times x, rounded to precision significant digits using rounding mode rounding.

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

ToBinary

ToBinary([sd [, rm]])
//sd : number : integer, 0 to 1e+9 inclusive
//rm : RoundingMode

Returns a string representing the value of this BigDecimal in binary, rounded to sd significant digits using rounding mode rm.

If sd is defined, the return value will use binary exponential notation.

If sd is omitted, the return value will be rounded to precision significant digits.

If rm is omitted, rounding mode rounding will be used.

Throws on an invalid sd or rm value.

x = new BigDecimal(256)
x.ToBinary()                             // "0b100000000"
x.ToBinary(1)                            // "0b1p+8"

ToDecimalPlaces (ToDP)

ToDP([dp [, rm]])
//dp : number : integer, 0 to 1e+9 inclusive
//rm : RoundingMode

Returns a new BigDecimal whose value is the value of this BigDecimal rounded to dp decimal places using rounding mode rm.

If dp is omitted, the return value will have the same value as this BigDecimal.

If rm is omitted, rounding mode rounding is used.

Throws on an invalid dp or rm value.

x = new BigDecimal(12.34567)
x.ToDecimalPlaces(0)                           // "12"
x.ToDecimalPlaces(1, RoundingMode.ROUND_UP)    // "12.4"

y = new BigDecimal(9876.54321)
y.ToDP(3)                                // "9876.543"
y.ToDP(1, RoundingMode.ROUND_UP)         // "9876.6"
y.ToDP(1, RoundingMode.ROUND_DOWN)       // "9876.5"

ToExponential

ToExponential([dp [, rm]])
//dp : number : integer, 0 to 1e+9 inclusive
//rm : RoundingMode

Returns a string representing the value of this BigDecimal in exponential notation rounded using rounding mode rm to dp decimal places, i.e with one digit before the decimal point and dp digits after it.

If the value of this BigDecimal in exponential notation has fewer than dp fraction digits, the return value will be appended with zeros accordingly.

If dp is omitted, 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, rounding mode rounding is used.

Throws on an invalid dp or rm value.

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

ToFixed

ToFixed([dp [, rm]])
//dp : number : integer, 0 to 1e+9 inclusive
//rm : RoundingMode

Returns a string representing the value of this BigDecimal in normal (fixed-point) notation rounded to dp decimal places using rounding mode rm.

If the value of this BigDecimal in normal notation has fewer than dp fraction digits, the return value will be appended with zeros accordingly.

This method will always return normal notation.

If dp is omitted, the return value will be unrounded and in normal notation. ToString returns exponential notation.

If rm is omitted, rounding mode rounding is used.

Throws on an invalid dp or rm value.

y = new BigDecimal(3.456)
y.toFixed()                            // '3.456'
y.toFixed(0)                           // '3'
y.toFixed(2)                           // '3.46'
y.toFixed(2, RoundingMode.ROUND_DOWN)  // '3.45'
y.toFixed(5)                           // '3.45600'

ToFraction

ToFraction([max_denominator])
//max_denominator : number|string|BigDecimal : 1 >= integer < Infinity

Returns an array of two BigDecimals representing the value of this BigDecimal as a simple fraction with an integer numerator and an integer denominator. The denominator will be a positive non-zero value less than or equal to max_denominator.

If a maximum denominator is omitted, the denominator will be the lowest value necessary to represent the number exactly.

Throws on an invalid max_denominator value.

x = new BigDecimal(1.75)
x.ToFraction()                       // "7, 4"

pi = new BigDecimal("3.14159265358")
pi.ToFraction()                      // "157079632679,50000000000"
pi.ToFraction(100000)                // "312689, 99532"
pi.ToFraction(10000)                 // "355, 113"
pi.ToFraction(100)                   // "311, 99"
pi.ToFraction(10)                    // "22, 7"
pi.ToFraction(1)                     // "3, 1"

ToHexadecimal (ToHex)

ToHex([sd [, rm]])
//sd : number : integer, 0 to 1e+9 inclusive
//rm : RoundingMode

Returns a string representing the value of this BigDecimal in hexadecimal, rounded to sd significant digits using rounding mode rm.

If sd is defined, the return value will use binary exponential notation.

If sd is omitted, the return value will be rounded to precision significant digits.

If rm is omitted, rounding mode rounding will be used.

Throws on an invalid sd or rm value.

x = new BigDecimal(256)
x.ToHexadecimal()                        // '0x100'
x.ToHex(1)                               // '0x1p+8'

ToJSON

As ValueOf.

ToNearest

ToNearest([x [, rm]])
//x : number|string|BigDecimal
//rm : RoundingMode

Returns a new BigDecimal whose value is the nearest multiple of x in the direction of rounding mode rm, or rounding if rm is omitted, to the value of this BigDecimal.

The return value will always have the same sign as this BigDecimal, unless either this BigDecimal or x is NaN, in which case the return value will be also be NaN.

The return value is not affected by the value of the precision setting.

x = new BigDecimal(1.39)
x.ToNearest(0.25)                             // "1.5"

y = new BigDecimal(9.499)
y.ToNearest(0.5, RoundingMode.ROUND_UP)       // "9.5"
y.ToNearest(0.5, RoundingMode.ROUND_DOWN)     // "9"

ToNumber

ToNumber()

Returns the value of this BigDecimal converted to a primitive number.

A BigDecimal with the value minus zero will convert to positive zero. (C# has not -0)

x = new BigDecimal(456.789)
x.ToNumber()                   // 456.789

y = new BigDecimal("45987349857634085409857349856430985")
y.ToNumber()                   // 4.598734985763409e+34

z = new BigDecimal("-0")
1 / z.ToNumber()               // Infinity

ToOctal

ToOctal([sd [, rm]])
//sd : number : integer, 0 to 1e+9 inclusive
//rm : RoundingMode

Returns a string representing the value of this BigDecimal in octal, rounded to sd significant digits using rounding mode rm.

If sd is defined, the return value will use binary exponential notation.

If sd is omitted, the return value will be rounded to precision significant digits.

If rm is omitted, rounding mode rounding will be used.

Throws on an invalid sd or rm value.

x = new BigDecimal(256)
x.ToOctal()                              // "0o400"
x.ToOctal(1)                             // "0o1p+8"

ToPower (Pow)

Pow(x)
//x : number|string|BigDecimal

Returns a new BigDecimal whose value is the value of this BigDecimal raised to the power x, rounded to precision significant digits using rounding mode rounding.

The performance of this method degrades exponentially with increasing digits. For non-integer exponents in particular, the performance of this method may not be adequate.

Math.Pow(0.7, 2)               // 0.48999999999999994
x = new BigDecimal(0.7)
x.ToPower(2)                   // "0.49"
new BigDecimal(3).Pow(-2)      // "0.11111111111111111111"

new BigDecimal(1217652.23).Pow("98765.489305603941")
// "4.8227010515242461181e+601039"

Is the pow function guaranteed to be correctly rounded?

The return value will almost always be correctly rounded, i.e. rounded as if the result was first calculated to an infinite number of correct digits before rounding. If a result is incorrectly rounded the maximum error will be 1 ulp (unit in the last place).

For non-integer and larger exponents this method uses the formula

x^y = exp(y*ln(x))

As the mathematical return values of the Exp and Ln functions are both non-terminating (excluding arguments of 0 or 1), the values of the BigDecimals returned by the functions as implemented by this library will necessarily be rounded approximations, which means that there can be no guarantee of correct rounding when they are combined in the above formula.

The return value may, depending on the rounding mode, be incorrectly rounded only if the first 15 rounding digits are 15 zeros (and there are non-zero digits following at some point), or 15 nines, or a 5 or 4 followed by 14 nines.

Therefore, assuming the first 15 rounding digits are each equally likely to be any digit, 0-9, the probability of an incorrectly rounded result is less than 1 in 250,000,000,000,000.

An example of incorrect rounding:

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig() {
    Precision = 20,
	Rounding = RoundingMode.ROUND_DOWN
})
bigDecimalFactory.BigDecimal(28).Pow("6.166675020000903537297764507632802193308677149")
// 839756321.64088511

As the exact mathematical result begins

839756321.6408851099999999999999999999999999998969466049426031167...

and the rounding mode is set to ROUND_DOWN, the correct return value should be

839756321.64088510999

ToPrecision

ToPrecision([sd [, rm]])
//sd : number : integer, 0 to 1e+9 inclusive
//rm : RoundingMode

Returns a string representing the value of this BigDecimal rounded to sd significant digits using rounding mode rm.

If sd is less than the number of digits necessary to represent the integer part of the value in normal (fixed-point) notation, then exponential notation is used.

If sd is omitted, the return value is the same as ToString.

If rm is omitted, rounding mode rounding is used.

Throws on an invalid sd or rm value.

y = new BigDecimal(45.6)
y.ToPrecision()                               // "45.6"
y.ToPrecision(1)                              // "5e+1"
y.ToPrecision(2, RoundingMode.ROUND_UP)       // "46"
y.ToPrecision(2, RoundingMode.ROUND_DOWN)     // "45"
y.ToPrecision(5)                              // "45.600"

ToSignificantDigits (ToSD)

ToSD([sd [, rm]])
//sd : number : integer, 0 to 1e+9 inclusive
//rm : RoundingMode

Returns a new BigDecimal whose value is the value of this BigDecimal rounded to sd significant digits using rounding mode rm.

If sd is omitted, the return value will be rounded to precision significant digits.

If rm is omitted, rounding mode rounding will be used.

Throws on an invalid sd or rm value.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig() {
    Precision = 5,
	Rounding = RoundingMode.ROUND_HALF_UP
})
x = bigDecimalFactory.BigDecimal(9876.54321)

x.ToSignificantDigits()                          // "9876.5"
x.ToSignificantDigits(6)                         // "9876.54"
x.ToSignificantDigits(6, RoundingMode.ROUND_UP)  // "9876.55"
x.ToSD(2)                                        // "9900"
x.ToSD(2, 1)                                     // "9800"
x                                                // "9876.54321"

ToString

ToString()

Returns a string representing the value of this BigDecimal.

If this BigDecimal has a positive exponent that is equal to or greater than ToExpPos, or a negative exponent equal to or less than ToExpNeg, then exponential notation will be returned.

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
x = bigDecimalFactory.BigDecimal(750000)
x.ToString()                             // "750000"
bigDecimalFactory.Config.ToExpPos = 5
x.ToString()                             // "7.5e+5"

bigDecimalFactory.Config.Precision = 4
y = bigDecimalFactory.BigDecimal("1.23456789")
y.ToString()                             // "1.23456789"

Truncated (Trunc)

Trunc()

Returns a new BigDecimal whose value is the value of this BigDecimal truncated to a whole number.

The return value is not affected by the value of the precision setting.

x = new BigDecimal(123.456)
x.Truncated()                            // "123"
y = new BigDecimal(-12.3)
y.Trunc()                                // "-12"

ValueOf

ValueOf()

As ToString, but zero is signed.

x = new BigDecimal("-0")
x.ValueOf()                              // "-0"

Instance Properties

The value of a BigDecimal is stored in a normalised base 10000000 floating point format.

A BigDecimal instance is an object with three properties:

Property	Description	Type	Value
d	digits	number[]	Array of integers, each `0` `-1e7`, or `null`
e	exponent	number	Integer, `-9e15` to `9e15` inclusive, or `null`
s	sign	number	`-1`, `1`, or `null`

All the properties are best considered to be read-only.

As with C# numbers, the original exponent and fractional trailing zeros of a value are not preserved.

x = new BigDecimal(0.123)                // "0.123"
x.ToExponential()                        // "1.23e-1"
x.d                                      // [ 1230000 ]
x.e                                      // -1
x.s                                      // 1

z = new BigDecimal('-123.4567000e+2')    // "-12345.67"
z.ToExponential()                        // "-1.234567e+4"
z.d                                      // [ 12345, 6700000 ]
z.e                                      // 4
z.s                                      // -1

Zero, NaN and Infinity

The table below shows how ±0, NaN and ±Infinity are stored.

	±0	NaN	±Infinity
d	[0]	null	null
e	0	null	null
s	±1	null	±1

y = new BigDecimal("-0")
y.d                                      // "0" ( [0].ToString() )
y.e                                      //  0
y.s                                      // -1
y.ToString()                             // "0"
y.ValueOf()                              // "-0"

Errors

The errors that are thrown are Exception objects whose message property begins with "[DecimalError]".

To determine if an exception is a BigDecimal Error:

try {
    // ...
} catch (BigDecimalException e) {
    // ...
}

Pi

The maximum precision of the trigonometric methods is dependent on the internal value of the constant pi, which is defined as the string PI near the top of the source file.

It has a precision of 1025 digits, meaning that the trigonometric methods can calculate up to just over 1000 digits, but the actual figure depends on the precision of the argument passed to them. To calculate the actual figure use:

maximum_result_precision = 1000 - argument_precision

For example, the following both work fine:

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
bigDecimalFactory.Config.Precision = 991
bigDecimalFactory.Tan(123456789)
bigDecimalFactory.Config.Precision = 9
bigDecimalFactory.Tan(991_digit_number)

as, for each, the result precision plus the argument precision, i.e. 991 + 9 and 9 + 991, is less than or equal to 1000.

If greater precision is required then the value of PI will need to be extended to about 25 digits more than the precision required. The time taken by the methods will then be the limiting factor.

The value can also be shortened to reduce the size of the source file if such high precision is not required.

To get the value of pi:

bigDecimalFactory = new BigDecimalFactory(new BigDecimalConfig())
pi = bigDecimalFactory.Acos(-1)