Module decimal | Tarantool

Module decimal¶

The `decimal` module has functions for working with exact numbers. This is important when numbers are large or even the slighest inaccuracy is unacceptable. For example Lua calculates `0.16666666666667 * 6` with floating-point so the result is 1. But with the decimal module (using `decimal.new` to convert the number to decimal type) `decimal.new('0.16666666666667') * 6` is 1.00000000000002.

To construct a decimal number, bring in the module with `require('decimal')` and then use `decimal.new(n)` or any function in the decimal module: abs(n) exp(n) ln(n) log10(n) new(n) precision(n) rescale(decimal-number, new-scale) scale(n) sqrt(n) trim(decimal-number), where n can be a string or a non-decimal number or a decimal number. If it is a string or a non-decimal number, Tarantool converts it to a decimal number before working with it. It is best to construct from strings, and to convert back to strings after calculations, because Lua numbers have only 15 digits of precision. Decimal numbers have 38 digits of precision, that is, the total number of digits before and after the decimal point can be 38. Tarantool supports the usual arithmetic and comparison operators + - * / % ^ < > <= >= ~= ==. If an operation has both decimal and non-decimal operands, then the non-decimal operand is converted to decimal before the operation happens.

Use `tostring(decimal-number)` to convert back to a string.

A decimal operation will fail if overflow happens (when a number is greater than 10^38 - 1 or less than -10^38 - 1). A decimal operation will fail if arithmetic is impossible (such as division by zero or square root of minus 1). A decimal operation will not fail if rounding of post-decimal digits is necessary to get 38-digit precision.

`decimal.``abs`(string-or-number-or-decimal-number)

Returns absolute value of a decimal number. For example if a is -1 then `decimal.abs(a)` returns 1.

`decimal.``exp`(string-or-number-or-decimal-number)

Returns e raised to the power of a decimal number. For example if a is 1 then `decimal.exp(a)` returns 2.7182818284590452353602874713526624978. Compare `math.exp(1)` from the Lua math library, which returns 2.718281828459.

`decimal.``ln`(string-or-number-or-decimal-number)

Returns natural logarithm of a decimal number. For example if a is 1 then `decimal.ln(a)` returns 0.

`decimal.``log10`(string-or-number-or-decimal-number)

Returns base-10 logarithm of a decimal number. For example if a is 100 then `decimal.log10(a)` returns 2.

`decimal.``new`(string-or-number-or-decimal-number)

Returns the value of the input as a decimal number. For example if a is 1E-1 then `decimal.new(a)` returns 0.1.

`decimal.``precision`(string-or-number-or-decimal-number)

Returns the number of digits in a decimal number. For example if a is 123.4560 then `decimal.precision(a)` returns 7.

`decimal.``rescale`(decimal-number, new-scale)

Returns the number after possible rounding or padding. If the number of post-decimal digits is greater than new-scale, then rounding occurs. The rounding rule is: round half away from zero. If the number of post-decimal digits is less than new-scale, then padding of zeros occurs. For example if a is -123.4550 then `decimal.rescale(a, 2)` returns -123.46, and `decimal.rescale(a, 5)` returns -123.45500.

`decimal.``scale`(string-or-number-or-decimal-number)

Returns the number of post-decimal digits in a decimal number. For example if a is 123.4560 then `decimal.scale(a)` returns 4.

`decimal.``sqrt`(string-or-number-or-decimal-number)

Returns the square root of a decimal number. For example if a is 2 then `decimal.sqrt(a)` returns 1.4142135623730950488016887242096980786.

`decimal.``trim`(decimal-number)

Returns a decimal number after possible removing of trailing post-decimal zeros. For example if a is 2.20200 then `decimal.trim(a)` returns 2.202.