@spec abs(t()) :: t()

The absolute value of given number. Sets the number's sign to positive.

Examples

iex> Decimal.abs(Decimal.new("1"))
Decimal.new("1")

iex> Decimal.abs(Decimal.new("-1"))
Decimal.new("1")

iex> Decimal.abs(Decimal.new("NaN"))
Decimal.new("NaN")

@spec add(decimal(), decimal()) :: t()

Adds two numbers together.

Exceptional conditions

• If one number is -Infinity and the other +Infinity, :invalid_operation will be signalled.

Examples

iex> Decimal.add(1, "1.1")
Decimal.new("2.1")

iex> Decimal.add(1, "Inf")
Decimal.new("Infinity")

@spec apply_context(t()) :: t()

Applies the context to the given number rounding it to specified precision.

@spec cast(term()) :: {:ok, t()} | :error

Creates a new decimal number from an integer, string, float, or existing decimal number.

Because conversion from a floating point number is not exact, it's recommended to instead use new/1 or from_float/1 when the argument's type is certain. See from_float/1.

Examples

iex> {:ok, decimal} = Decimal.cast(3)
iex> decimal
Decimal.new("3")

iex> Decimal.cast("bad")
:error

@spec cast(term(), [parse_option()]) :: {:ok, t()} | :error

Creates a new decimal number from an integer, string, float, or existing decimal number with parsing limits.

Options are the same as parse/2.

@spec compare(decimal(), decimal()) :: compare_result()

Compares two numbers numerically. If the first number is greater than the second :gt is returned, if less than :lt is returned, if both numbers are equal :eq is returned.

Neither number can be a NaN. A NaN has no order, so it signals :invalid_operation and raises Decimal.Error even when that signal is not trapped.

Examples

iex> Decimal.compare("1.0", 1)
:eq

iex> Decimal.compare("Inf", -1)
:gt

@spec compare(decimal :: decimal(), decimal :: decimal(), threshold :: decimal()) ::
  compare_result()

Compares two numbers numerically using a threshold. The numbers are considered equal when the second number lies between the first number minus the threshold and the first number plus the threshold, inclusive. Otherwise the result is the same as for compare/2.

The comparison is exact: the bounds are not rounded to the context precision.

The threshold cannot be negative, and none of the numbers can be a NaN. A NaN signals :invalid_operation and raises Decimal.Error like compare/2.

Examples

iex> Decimal.compare("1.1", 1, "0.2")
:eq

iex> Decimal.compare("1.2", 1, "0.1")
:gt

iex> Decimal.compare("1.0", "1.2", "0.1")
:lt

@spec div(decimal(), decimal()) :: t()

Divides two numbers.

Exceptional conditions

• If both numbers are ±Infinity :invalid_operation is signalled.
• If both numbers are ±0 :invalid_operation is signalled.
• If second number (denominator) is ±0 :division_by_zero is signalled.

Examples

iex> Decimal.div(3, 4)
Decimal.new("0.75")

iex> Decimal.div("Inf", -1)
Decimal.new("-Infinity")

@spec div_int(decimal(), decimal()) :: t()

Divides two numbers and returns the integer part.

Exceptional conditions

• If both numbers are ±Infinity :invalid_operation is signalled.
• If both numbers are ±0 :invalid_operation is signalled.
• If second number (denominator) is ±0 :division_by_zero is signalled.

Examples

iex> Decimal.div_int(5, 2)
Decimal.new("2")

iex> Decimal.div_int("Inf", -1)
Decimal.new("-Infinity")

@spec div_rem(decimal(), decimal()) :: {t(), t()}

Integer division of two numbers and the remainder. Should be used when both div_int/2 and rem/2 is needed. Equivalent to: {Decimal.div_int(x, y), Decimal.rem(x, y)}.

Exceptional conditions

• If both numbers are ±Infinity :invalid_operation is signalled.
• If both numbers are ±0 :invalid_operation is signalled.
• If second number (denominator) is ±0 :division_by_zero is signalled.

Examples

iex> Decimal.div_rem(5, 2)
{Decimal.new(2), Decimal.new(1)}

@spec eq?(decimal(), decimal()) :: boolean()

Compares two numbers numerically and returns true if they are equal, otherwise false. If one of the operands is a quiet NaN this operation will always return false.

Examples

iex> Decimal.eq?("1.0", 1)
true

iex> Decimal.eq?(1, -1)
false

@spec eq?(decimal :: decimal(), decimal :: decimal(), threshold :: decimal()) ::
  boolean()

It compares the equality of two numbers. If the second number is within the range of first - threshold and first + threshold, it returns true; otherwise, it returns false.

Examples

iex> Decimal.eq?("1.0", 1, "0")
true

iex> Decimal.eq?("1.2", 1, "0.1")
false

iex> Decimal.eq?("1.2", 1, "0.2")
true

iex> Decimal.eq?(1, -1, "0.0")
false

@spec equal?(decimal(), decimal()) :: boolean()

Compares two numbers numerically and returns true if they are equal, otherwise false. If one of the operands is a quiet NaN this operation will always return false.

Examples

iex> Decimal.equal?("1.0", 1)
true

iex> Decimal.equal?(1, -1)
false

@spec from_float(float()) :: t()

Creates a new decimal number from a floating point number.

Floating point numbers use a fixed number of binary digits to represent a decimal number which has inherent inaccuracy as some decimal numbers cannot be represented exactly in limited precision binary.

Floating point numbers will be converted to decimal numbers with :io_lib_format.fwrite_g/1. Since this conversion is not exact and because of inherent inaccuracy mentioned above, we may run into counter-intuitive results:

iex> Enum.reduce([0.1, 0.1, 0.1], &+/2)
0.30000000000000004

iex> Enum.reduce([Decimal.new("0.1"), Decimal.new("0.1"), Decimal.new("0.1")], &Decimal.add/2)
Decimal.new("0.3")

For this reason, it's recommended to build decimals with new/1, which is always precise, instead.

Examples

iex> Decimal.from_float(3.14)
Decimal.new("3.14")

@spec gt?(decimal(), decimal()) :: boolean()

Compares two numbers numerically and returns true if the first argument is greater than the second, otherwise false. If one the operands is a quiet NaN this operation will always return false.

Examples

iex> Decimal.gt?("1.3", "1.2")
true

iex> Decimal.gt?("1.2", "1.3")
false

@spec gte?(decimal(), decimal()) :: boolean()

Compares two numbers numerically and returns true if the first argument is greater than or equal the second, otherwise false.

If one the operands is a quiet NaN this operation will always return false.

Examples

iex> Decimal.gte?("1.3", "1.3")
true

iex> Decimal.gte?("1.3", "1.2")
true

iex> Decimal.gte?("1.2", "1.3")
false

@spec inf?(t()) :: boolean()

Returns true if number is ±Infinity, otherwise false.

Examples

iex> Decimal.inf?(Decimal.new("+Infinity"))
true

iex> Decimal.inf?(Decimal.new("-Infinity"))
true

iex> Decimal.inf?(Decimal.new("1.5"))
false

@spec integer?(decimal()) :: boolean()

Returns true when the given decimal has no significant digits after the decimal point.

Examples

iex> Decimal.integer?("1.00")
true

iex> Decimal.integer?("1.10")
false

Returns true if argument is a decimal number, otherwise false.

Examples

iex> Decimal.is_decimal(Decimal.new(42))
true

iex> Decimal.is_decimal(42)
false

Allowed in guard tests on OTP 21+.

@spec lt?(decimal(), decimal()) :: boolean()

Compares two numbers numerically and returns true if the first number is less than the second number, otherwise false. If one of the operands is a quiet NaN this operation will always return false.

Examples

iex> Decimal.lt?("1.1", "1.2")
true

iex> Decimal.lt?("1.4", "1.2")
false

@spec lte?(decimal(), decimal()) :: boolean()

Compares two numbers numerically and returns true if the first number is less than or equal the second number, otherwise false.

If one of the operands is a quiet NaN this operation will always return false.

Examples

iex> Decimal.lte?("1.1", "1.1")
true

iex> Decimal.lte?("1.1", "1.2")
true

iex> Decimal.lte?("1.4", "1.2")
false

@spec max(decimal(), decimal()) :: t()

Compares two values numerically and returns the maximum. Unlike most other functions in Decimal if a number is NaN the result will be the other number. Only if both numbers are NaN will NaN be returned.

Examples

iex> Decimal.max(1, "2.0")
Decimal.new("2.0")

iex> Decimal.max(1, "NaN")
Decimal.new("1")

iex> Decimal.max("NaN", "NaN")
Decimal.new("NaN")

@spec min(decimal(), decimal()) :: t()

Compares two values numerically and returns the minimum. Unlike most other functions in Decimal if a number is NaN the result will be the other number. Only if both numbers are NaN will NaN be returned.

Examples

iex> Decimal.min(1, "2.0")
Decimal.new("1")

iex> Decimal.min(1, "NaN")
Decimal.new("1")

iex> Decimal.min("NaN", "NaN")
Decimal.new("NaN")

@spec mult(decimal(), decimal()) :: t()

Multiplies two numbers.

Exceptional conditions

• If one number is ±0 and the other is ±Infinity :invalid_operation is signalled.

Examples

iex> Decimal.mult("0.5", 3)
Decimal.new("1.5")

iex> Decimal.mult("Inf", -1)
Decimal.new("-Infinity")

@spec nan?(t()) :: boolean()

Returns true if number is NaN, otherwise false.

Examples

iex> Decimal.nan?(Decimal.new("NaN"))
true

iex> Decimal.nan?(Decimal.new(42))
false

@spec negate(decimal()) :: t()

Negates the given number.

Examples

iex> Decimal.negate(1)
Decimal.new("-1")

iex> Decimal.negate("-Inf")
Decimal.new("Infinity")

@spec negative?(t()) :: boolean()

Returns true if given number is negative, otherwise false.

Examples

iex> Decimal.negative?(Decimal.new("-42"))
true

iex> Decimal.negative?(Decimal.new("42"))
false

iex> Decimal.negative?(Decimal.new("0"))
false

iex> Decimal.negative?(Decimal.new("NaN"))
false

@spec new(decimal()) :: t()

Creates a new decimal number from an integer or a string representation.

A decimal number will always be created exactly as specified with all digits kept - it will not be rounded with the context.

A string is parsed with the limits of parse/2, which opts can override. An integer is taken as given, without limits, so the result may have more digits than the context and to_string/2 accept. Use cast/2 to apply the parse limits to an integer from untrusted input.

Backus–Naur form

sign           ::=  "+" | "-"
digit          ::=  "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
indicator      ::=  "e" | "E"
digits         ::=  digit [digit]...
decimal-part   ::=  digits "." [digits] | ["."] digits
exponent-part  ::=  indicator [sign] digits
infinity       ::=  "Infinity" | "Inf"
nan            ::=  "NaN" [digits]
numeric-value  ::=  decimal-part [exponent-part] | infinity
numeric-string ::=  [sign] numeric-value | [sign] nan

Floats

See also from_float/1.

Examples

iex> Decimal.new(1)
Decimal.new("1")

iex> Decimal.new("3.14")
Decimal.new("3.14")

iex> Decimal.new("1.79769313486231581e308")
Decimal.new("1.79769313486231581e308")

iex> Decimal.new("2.22507385850720139e-308")
Decimal.new("2.22507385850720139e-308")

iex> Decimal.new("1.01234567890123457890123457890123456789", max_digits: 39)
Decimal.new("1.01234567890123457890123457890123456789", max_digits: 39)

@spec new(sign :: 1 | -1, coef :: non_neg_integer() | :NaN | :inf, exp :: integer()) ::
  t()

Creates a new decimal number from the sign, coefficient and exponent such that the number will be: sign * coefficient * 10 ^ exponent.

A decimal number will always be created exactly as specified with all digits kept - it will not be rounded with the context. The parse limits do not apply; use cast/2 on the result to check it against them.

Examples

iex> Decimal.new(1, 42, 0)
Decimal.new("42")

@spec normalize(t()) :: t()

Normalizes the given decimal: removes trailing zeros from coefficient while keeping the number numerically equivalent by increasing the exponent.

Examples

iex> Decimal.normalize(Decimal.new("1.00"))
Decimal.new("1")

iex> Decimal.normalize(Decimal.new("1.01"))
Decimal.new("1.01")

@spec parse(binary()) :: {t(), binary()} | :error

Parses a binary into a decimal.

If successful, returns a tuple in the form of {decimal, remainder_of_binary}, otherwise :error.

Inputs whose digit count or exponent magnitude exceed the default limits (34 digits, 6144 absolute exponent) return :error. Use parse/2 to override the limits.

Examples

iex> Decimal.parse("3.14")
{%Decimal{coef: 314, exp: -2, sign: 1}, ""}

iex> Decimal.parse("3.14.15")
{%Decimal{coef: 314, exp: -2, sign: 1}, ".15"}

iex> Decimal.parse("-1.1e3")
{%Decimal{coef: 11, exp: 2, sign: -1}, ""}

iex> Decimal.parse("bad")
:error

@spec parse(binary(), [parse_option()]) :: {t(), binary()} | :error

Parses a binary into a decimal with explicit limits.

The following options are supported:

• :max_digits - maximum number of significant decimal digits in the parsed coefficient. Leading zeros are not counted, but trailing zeros are. Defaults to 34. Pass :infinity to disable.
• :max_exponent - maximum absolute value of the parsed decimal exponent, after fractional digits are accounted for. Defaults to 6144. Pass :infinity to disable.

Returns :error when a parsed number exceeds the configured limits.

@spec positive?(t()) :: boolean()

Returns true if given number is positive, otherwise false.

Examples

iex> Decimal.positive?(Decimal.new("42"))
true

iex> Decimal.positive?(Decimal.new("-42"))
false

iex> Decimal.positive?(Decimal.new("0"))
false

iex> Decimal.positive?(Decimal.new("NaN"))
false

@spec rem(decimal(), decimal()) :: t()

Remainder of integer division of two numbers. The result will have the sign of the first number.

Exceptional conditions

• If both numbers are ±Infinity :invalid_operation is signalled.
• If both numbers are ±0 :invalid_operation is signalled.
• If second number (denominator) is ±0 :division_by_zero is signalled.

Examples

iex> Decimal.rem(5, 2)
Decimal.new("1")

@spec round(decimal(), integer(), rounding()) :: t()

Rounds the given number to specified decimal places with the given strategy (default is to round to nearest one). If places is negative, at least that many digits to the left of the decimal point will be zero.

This is the quantize operation of the General Decimal Arithmetic spec, so the result always has the exponent -places. :rounded is signalled when digits of a nonzero coefficient are discarded, and :inexact when any of them is nonzero.

:invalid_operation is signalled and the result is NaN when the number is ±Infinity, when -places is outside the exponent range of the context, emin - precision + 1 to emax, or when the result would need more digits than the precision or an adjusted exponent above emax. The signal is trapped by default, raising Decimal.Error.

See Decimal.Context for more information about rounding algorithms.

Examples

iex> Decimal.round("1.234")
Decimal.new("1")

iex> Decimal.round("1.234", 1)
Decimal.new("1.2")

iex> Decimal.round("1.5", 40)
** (Decimal.Error) invalid_operation: result has more digits than the precision

@spec scale(t()) :: non_neg_integer()

Returns the scale of the decimal.

A decimal's scale is the number of digits after the decimal point. This includes trailing zeros; see normalize/1 to remove them.

Examples

iex> Decimal.scale(Decimal.new("42"))
0

iex> Decimal.scale(Decimal.new(1, 2, 26))
0

iex> Decimal.scale(Decimal.new("99.12345"))
5

iex> Decimal.scale(Decimal.new("1.50"))
2

@spec sqrt(decimal()) :: t()

Finds the square root.

Examples

iex> Decimal.sqrt("100")
Decimal.new("10")

@spec sub(decimal(), decimal()) :: t()

Subtracts second number from the first. Equivalent to Decimal.add/2 when the second number's sign is negated.

Exceptional conditions

• If one number is -Infinity and the other +Infinity :invalid_operation will be signalled.

Examples

iex> Decimal.sub(1, "0.1")
Decimal.new("0.9")

iex> Decimal.sub(1, "Inf")
Decimal.new("-Infinity")

@spec to_float(t()) :: float()

Returns the decimal converted to a float.

The returned float may have lower precision than the decimal.

Raises if the decimal cannot be converted to a float.

Examples

iex> Decimal.to_float(Decimal.new("1.5"))
1.5

iex> Decimal.to_float(Decimal.new("-1.79769313486231581e308"))
** (Decimal.Error) : negative number smaller than DBL_MAX: Decimal.new("-1.79769313486231581E+308")

iex> Decimal.to_float(Decimal.new("-1.79769313486231581e308"))
** (Decimal.Error) : negative number smaller than DBL_MAX: Decimal.new("-1.79769313486231581E+308")

iex> Decimal.to_float(Decimal.new("2.22507385850720139e-308"))
** (Decimal.Error) : number smaller than DBL_MIN: Decimal.new("2.22507385850720139E-308")

iex> Decimal.to_float(Decimal.new("-2.22507385850720139e-308"))
** (Decimal.Error): negative number bigger than DBL_MIN: Decimal.new("-2.22507385850720139E-308")

iex> Decimal.to_float(Decimal.new("inf"))
** (ArgumentError) Decimal.new("Infinity") cannot be converted to float

@spec to_integer(t()) :: integer()

Returns the decimal represented as an integer.

Raises when loss of precision will occur, or when the decimal is NaN or ±Infinity.

Examples

iex> Decimal.to_integer(Decimal.new("42"))
42

iex> Decimal.to_integer(Decimal.new("1.00"))
1

iex> Decimal.to_integer(Decimal.new("1.10"))
** (ArgumentError) cannot convert Decimal.new("1.1") without losing precision. Use Decimal.round/3 first.

iex> Decimal.to_integer(Decimal.new("Infinity"))
** (ArgumentError) Decimal.new("Infinity") cannot be converted to integer

@spec to_string(t(), :scientific | :normal | :xsd | :raw) :: String.t()

Converts given number to its string representation.

Output is bounded to 6178 digit characters by default; pass options via to_string/3 to override. :scientific is compact for large positive exponents and rarely hits the limit; :normal and :xsd expand proportional to the exponent and will raise ArgumentError when the limit would be exceeded.

Options

• :scientific - number converted to scientific notation.
• :normal - number converted without a exponent.
• :xsd - number converted to the canonical XSD representation.
• :raw - number converted to its raw, internal format.

Examples

iex> Decimal.to_string(Decimal.new("1.00"))
"1.00"

iex> Decimal.to_string(Decimal.new("123e1"), :scientific)
"1.23E+3"

iex> Decimal.to_string(Decimal.new("42.42"), :normal)
"42.42"

iex> Decimal.to_string(Decimal.new("1.00"), :xsd)
"1.0"

iex> Decimal.to_string(Decimal.new("4321.768"), :raw)
"4321768E-3"

@spec to_string(t(), :scientific | :normal | :xsd | :raw, [to_string_option()]) ::
  String.t()

Converts given number to its string representation with explicit limits.

The following options are supported:

• :max_digits - maximum number of digit characters in the output. Sign, decimal point, and exponent markers are not counted. Defaults to 6178. Pass :infinity to disable.

Raises ArgumentError when the configured limit would be exceeded.