Decimal number with precision parameter (i.e. number of digits following decimal point) and rounding strategy.

The s type variable is for a phantom type and it is here to provide type level safety of arithmetic operations on Decimals. There is nothing on the type level that is restricting you from adding two decimals with different precision parameter.

This could result in something you didn't anticipate. Precision and rounding strategy of the left operand will be used for the resulting decimal. The second operand is not scaled or rounded down to match the first operand (i.e. 1.2 + 1.25 == 13.7).

But there is a way out of this with the help of a custom phantom type:

type Dollars
    = Dollars


type Pennies
    = Pennies


dollars : Int -> Decimal Dollars Int
dollars =
    Decimal.succeed HalfToEven nat0


pennies : Int -> Decimal Pennies Int
pennies =
    Decimal.succeed HalfToEven nat2


let
    x = pennies 120


    y = dollars 210
in
D.add x y


-- TYPE MISMATCH ----- ~/decimal/tests/DecimalTest.elm


-- The 2nd argument to `add` is not what I expect:


-- 105| D.add x y
--              ^
-- This `y` value is a:


--     Decimal Dollars Int


-- But `add` needs the 2nd argument to be:


--     Decimal Pennies Int

The p is for precision. In more advanced type system this could be arbitrary Intergal type (Integer, Int8, Int16, Int32, Int64 etc.) but in Elm it is difficult to achieve that level of abstraction. To support applicative chaining of operations there is p type variable (wrapped value can be a function).

A Decimal that succeeds without scaling or rounding.

import Numeric.Decimal as Decimal
import Numeric.Decimal.Rounding exposing (RoundingAlgorythm(..))
import Numeric.Nat exposing (nat2)


Decimal.succeed RoundDown nat2 100
    |> Decimal.toString
    -- 1.00

Transform wrapped value with a given function.

import Numeric.Decimal as Decimal
import Numeric.Decimal.Rounding exposing (RoundingAlgorythm(..))
import Numeric.Nat exposing (nat2)


Decimal.map sqrt (Decimal.succeed RoundDown nat2 25)
    |> Decimal.toString
    -- 0.50

Apply a function on two decimal values.

import Numeric.Decimal as Decimal
import Numeric.Decimal.Rounding exposing (RoundingAlgorythm(..))
import Numeric.Nat exposing (nat2)


Decimal.map2 (+)
    (Decimal.succeed RoundDown nat2 234)
    (Decimal.succeed RoundDown nat2 567)
    |> Decimal.toString
    -- 8.01

Apply wrapped function inside Decimal on another decimal value.

import Numeric.Decimal as Decimal
import Numeric.Decimal.Rounding exposing (RoundingAlgorythm(..))
import Numeric.Nat exposing (nat2)


Decimal.succeed RoundDown nat2 (\x -> x + 1)
    |> Decimal.andMap (Decimal.succeed RoundDown nat2 567)
    |> Decimal.toString
    -- 5.68

Convert Int to Decimal while performing necessary scaling.

import Numeric.Decimal as Decimal
import Numeric.Decimal.Rounding exposing (RoundingAlgorythm(..))
import Numeric.Nat exposing (nat3)


Decimal.fromInt RoundDown nat3 7
    |> Decimal.toString
    -- 7.000

Convert a Decimal to another Decimal while checking for Overflow/Underflow.

Convert Rational to Decimal.

Convert from Rational to Decimal while checking for Overflow/Underflow.

Converting Decimal to Rational.

Use different rounding strategy.

Converting Decimal to Float

Parse String to Decimal while chacking for formatting and Overflow/Underflow.

Printing Decimal to String representation.

toInt underlying representation for the decimal number. No rounding will be done.

import Numeric.Decimal as Decimal
import Numeric.Decimal.Rounding exposing (RoundingAlgorythm(..))
import Numeric.Nat exposing (nat2)


Decimal.toInt (Decimal.succeed RoundDown nat2 100) -- 100

Get the toNumerator. Same as toInt.

Get the Decimal denominator. Always will be a power of 10.

import Numeric.Decimal as Decimal
import Numeric.Decimal.Rounding exposing (RoundingAlgorythm(..))
import Numeric.Nat exposing (nat3)


Decimal.succeed RoundDown nat3 8
    |> Decimal.toDenominator
    -- (10 ^ 3) = 1000

Split the number at the decimal point, i.e. whole number and the fraction.

import Numeric.Decimal as Decimal
import Numeric.Decimal.Rounding exposing (RoundingAlgorythm(..))
import Numeric.Nat exposing (nat3)


D.succeed RoundTowardsZero nat3 1234
    |> D.splitDecimal
    -- (1, 234)

Get precision of the Decimal (number of fractional digits)

import Numeric.Decimal as Decimal
import Numeric.Decimal.Rounding exposing (RoundingAlgorythm(..))
import Numeric.Nat exposing (nat1, nat2)


Decimal.succeed RoundDown nat2 123
    |> Decimal.getPrecision
    -- (Nat 2)

Rounding down to a number of decimals.

import Numeric.Decimal as Decimal
import Numeric.Decimal.Rounding exposing (RoundingAlgorythm(..))
import Numeric.Nat exposing (nat1, nat2)


Decimal.succeed RoundDown nat2 123  -- 1.23
    |> Decimal.roundDown nat1
    |> Decimal.toString
    -- 1.2

Increase the precision of a Decimal, use roundDecimal for the inverse.

import Numeric.Decimal as Decimal
import Numeric.Decimal.Rounding exposing (RoundingAlgorythm(..))
import Numeric.Nat exposing (nat2, nat3)


Decimal.succeed RoundDown nat2 123  -- 1.23
    |> Decimal.scaleUp nat3
    |> Decimal.toString
    -- 1.230

Increase the precision of a Decimal while checking for Overflow/Underflow, use roundDecimal if inverse is desired.

Unary negation

Absolute value

Add two Decimals.

Subtract one Decimal from another.

Multiply two Decimals.

Divide two Decimals. Operation can fail if divisor is zero.

Add two Decimals while checking for Overflow/Underflow.

Subtract one Decimal from another while checking for Overflow/Underflow.

Multiply two Decimal while checking for Overflow/Underflow.

Divide two Decimals while checking for Overflow/Underflow and Division by zero.