Import: decimal

The decimal import provides functions for operating on numbers represented as decimals.

Binary floating-point numbers provided by the float type are unable to fully represent numbers like 1.1 and 2.2. The decimal import can represent these numbers exactly, and so should be used when exactness is required.

Decimals are created through the new function, which takes any type that can represent a number. Arguments to the decimal operators can also take a value of any of these types. The full list is:

float
int
string
existing decimal value

decimal.infinity(sign)

Creates an infinite-value decimal. Infinite-value decimals are always larger or smaller, depending on sign, than any non-infinite decimals.

decimal.infinity(1)  // +Infinity
decimal.infinity(-1) // -Infinity

Also available as decimal.inf.

decimal.nan

A decimal representing a "not-a-number" value. NaNs are not equal to any other number, even themselves.

decimal.new(-1).sqrt()               // NaN
decimal.new(0).mul(decimal.inf(1))   // NaN
decimal.nan.is(decimal.nan)          // false

decimal.is_infinite(d)

Evaluates to true if the decimal is infinite.

decimal.is_infinite(100)          // false
decimal.is_infinite("Infinity")   // true

Also available as decimal.is_inf, decimal.isinf and decimal.isinfinite.

decimal.is_nan(d)

Evaluates to true if the decimal is not-a-number.

decimal.is_nan("NaN") // true

Also available as decimal.isnan.

decimal.new(v)

Constructs a decimal from another value.

decimal.new("1.1")           // Constructs a decimal from a string.
decimal.new(2.2)             // Constructs a decimal from a float.
decimal.new(3)               // Constructs a decimal from an integer.
decimal.new("1.1234E+400")   // Constructs a decimal from a string using E-notation.

Type: number

Numbers are represented internally by a sign, coefficient, and exponent. The value is calculated with the formula sign * coefficient * 10^exponent. Exponent is limited to 32 bits, and the coefficient is limited by the total precision.

The maximum precision a number can represent is 100 digits. This includes both before and after the decimal place.

number.string

A string representation of the decimal.

decimal.new(1.5).string   // 1.5

number.sign

A number between -1 and +1 representing the sign of the decimal.

decimal.new(1.5).sign   // 1

number.coefficient

The coefficient component of the decimal.

decimal.new(1.5).coefficient    // 15

number.exponent

The exponent component of the decimal.

decimal.new(1.5).exponent   // -1

number.float

A floating-point representation of the decimal.

decimal.new(1.5).float    // 1.500000

number.int

An integer representation of the decimal. This always rounds down to the nearest integer.

decimal.new(1.5).int    // 1

number.is(v)

Test for equality with another value.

decimal.new(1.5).is(1)    // false

number.is_not(v)

Test for inequality with another value.

decimal.new(1.5).is_not(1)    // true

number.less_than(v)

Test that the decimal is less than another value. Can also be called as number.lt(v)

decimal.new(1.5).less_than(1)   // false

number.less_than_or_equals(v)

Test that the decimal is less than or equals to another value. Can also be called as number.lte(v)

decimal.new(1.5).less_than_or_equals(1)   // false

number.greater_than(v)

Test that the decimal is greater than another value. Can also be called as number.gt(v)

decimal.new(1.5).greater_than(1)   // true

number.greater_than_or_equals(v)

Test that the decimal is greater than or equals to another value. Can also be called as number.gte(v)

decimal.new(1.5).greater_than_or_equals(1)   // true

number.add(v)

Add another number to the decimal.

decimal.new(1.5).add(1)   // 2.5

number.subtract(v)

Subtract another number from the decimal. Can also be called as number.sub(v)

decimal.new(1.5).subtract(1)   // 0.5

number.multiply(v)

Multiply the decimal by a number. Can also be called as number.mul(v)

decimal.new(1.5).multiply(2)   // 3.0

number.divide(v)

Divide the decimal by a number. Can also be called as number.div(v)

decimal.new(3.0).divide(1.5)   // 2

number.modulo(v)

Find the remainder after dividing the decimal by a number. Can also be called as mod, remainder, or rem.

decimal.new(1.5).modulo(1)   // 0.5

number.power(v)

Raise the decimal to a power. Can also be called as number.pow(v)

decimal.new(1.5).power(2)   // 2.25

number.exp()

The natural exponent of the decimal. This calculates e^number.

decimal.new(1.5).exp()   // 4.4816...

number.loge()

The natural logarithm of the decimal. Can also be called as number.ln()

decimal.new(1.5).loge()   // 0.4054...

number.log10()

The base-10 logarithm of the decimal. Can also be called as number.log()

decimal.new(1.5).log10()   // 0.1760...

number.square_root()

The square root of the decimal. Can also be called as number.sqrt()

decimal.new(1.5).square_root()   // 1.2247...

number.ceiling()

Round the decimal to the smallest integer greater or equal to itself. Can also be called as number.ceil()

decimal.new(1.5).ceiling()   // 2

number.floor()

Round the decimal to the largest integer less than or equal to itself.

decimal.new(1.5).floor()   // 1

number.absolute()

The absolute value of the decimal. Can also be called as number.abs()

decimal.new(1.5).absolute()   // 1.5
decimal.new(-1.5).absolute()  // 1.5

number.negate()

The negated value of the decimal. A positive decimal will become negative, and a negative decimal will become positive. Can also be called as number.neg()

decimal.new(1.5).negate()   // -1.5
decimal.new(-1.5).negate()  // 1.5