@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 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.

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. If the first number added to the threshold is greater than the second number, and the first number subtracted by the threshold is smaller than the second number, then the two numbers are considered equal.

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(), thresrold :: 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.

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")

@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.

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.

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 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.

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")

@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. Fails if the decimal cannot be converted to a float.

Examples

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

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

Returns the decimal represented as an integer.

Fails when loss of precision will occur.

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.

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

Converts given number to its string representation.

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"