Dense represents a dense monetary value for currency (usually a ISO-4217 currency code, but not necessarily) as a rational number.

While monetary values associated with a particular currency are discrete (e.g., an exact number of coins and bills), you can still treat monetary values as dense while operating on them. For example, the half of USD 3.41 is USD 1.705, which is not an amount that can't be represented as a number of USD cents (the smallest unit that can represent USD amounts). Nevertheless, if you do manage to represent USD 1.705 somehow, and you eventually multiply USD 1.705 by 4 for example, then you end up with USD 6.82, which is again a value representable as USD cents. In other words, Dense monetary values allow us to perform precise calculations deferring the conversion to a Discrete monetary values as much as posible. Once you are ready to approximate a Dense value to a Discrete value you can use one discreteFromDense. Otherwise, using toRational you can obtain a precise Rational representation.

Dense currency identifier.

> denseCurrency (dense' 4 :: Dense "USD")
"USD"

Build a Dense monetary value from a Rational value.

For example, if you want to represent USD 12.52316, then you can use:

dense (125316 % 10000)

Notice that dense returns Nothing in case the given Rational's denominator is zero, which although unlikely, it is possible if the Rational was unsafely constructed. When dealing with hardcoded or trusted Rational values, you can use dense' instead of dense which unsafely constructs a Dense.

Unsafely build a Dense monetary value from a Rational value. Contrary to dense, this function *crashes* if the given Rational has zero as a denominator, which is something very unlikely to happen unless the given Rational was itself unsafely constructed. Other than that, dense and dense' behave the same.

Prefer to use dense when dealing with Rational inputs from untrusted sources.

denominator x /= 0
  ⇒ dense x == Just (dense' x)

denominator x == 0
  ⇒ undefined == dense' x

Convert currency Discrete monetary value into a Dense monetary value.

Parses a decimal representation of a Dense.

Render a Dense monetary amount as a decimal number in a potentially lossy manner.

> denseToDecimal defaultDecimalConf Round
     (dense' (123456 % 100) :: Dense "USD")
"1234.56"

Discrete represents a discrete monetary value for a currency expresed as an integer amount of a particular unit. For example, with currency ~ "USD" and unit ~ "cent" you can represent United States Dollars to their full extent.

currency is usually a ISO-4217 currency code, but not necessarily.

Construct Discrete values using discrete, fromIntegral, fromInteger, discreteFromDense, discreteFromDecimal.

For example, if you want to represent GBP 21.05, where the smallest represetable unit for a GBP (United Kingdom Pound) is the penny, and 100 pennies equal 1 GBP (i.e., UnitScale "GBP" "penny" ~ '(100, 1)), then you can use:

discrete 2105 :: Discrete "GBP" "penny"

Because 2105 / 100 == 21.05.

Discrete' represents a discrete monetary value for a currency expresed as amount of scale, which is a rational number expressed as (numerator, denominator).

You'll be using Discrete instead of Discrete' most of the time, which mentions the unit name (such as cent or centavo) instead of explicitely mentioning the unit scale.

Construct a Discrete value.

Discrete currency identifier.

> discreteCurrency (discrete 4 :: Discrete "USD" "cent")
"USD"

Approximate a Dense value x to the nearest value fully representable a given scale.

If the given Dense doesn't fit entirely in the scale, then a non-zero Dense reminder is returned alongside the Discrete approximation.

Proof that discreteFromDense doesn't lose money:

x == case discreteFromDense a x of
        (y, z) -> denseFromDiscrete y + z

Parses a decimal representation of a Discrete.

Notice that parsing will fail unless the entire precision of the decimal number can be represented in the desired scale.

Render a Discrete' monetary amount as a decimal number in a potentially lossy manner.

This is simply a convenient wrapper around denseToDecimal:

discreteToDecimal ds a (dis :: Discrete' currency scale)
    == denseToDecimal ds a (denseFromDiscrete dis :: Dense currency)

In particular, the scale in Discrete' currency scale has no influence over the scale in which the decimal number is rendered. Change the scale with decimalConf_scale in order to modify that behavior.

Please refer to denseToDecimal for further documentation.

This is the term-level representation of the “scale” we represent as (Nat, Nat) elsewhere in the type system (e.g., in GoodScale or UnitScale).

See UnitScale for a detailed description.

Construct a Scale from a positive, non-zero rational number.

Obtain the Rational representation of a Scale.

Term-level representation of a currrency scale.

For example, the Scale for "USD" in "cent"s is 100/1. We can obtain a term-level representation for it using any of the following:

> scale (Proxy :: Proxy (UnitScale "USD" "cent"))
Scale (100 % 1)

> scale (Proxy :: CurrencyScale "USD")
Scale (100 % 1)

> scale (x :: Discrete "USD" "cent")
Scale (100 % 1)

The returned Rational is statically guaranteed to be a positive number.

UnitScale currency unit is an rational number (expressed as '(numerator, denominator)) indicating how many pieces of unit fit in currency.

currency is usually a ISO-4217 currency code, but not necessarily.

The resulting (Nat, Nat), which is the type-level representation for what at the term-level we call Scale, will determine how to convert a Dense value into a Discrete value and vice-versa.

For example, there are 100 USD cents in 1 USD, so the scale for this relationship is:

type instance UnitScale "USD" "cent" = '(100, 1)

As another example, there is 1 dollar in USD, so the scale for this relationship is:

type instance UnitScale "USD" "dollar" = '(1, 1)

When using Discrete values to represent money, it will be impossible to represent an amount of currency smaller than unit. So, if you decide to use UnitScale "USD" "dollar" as your scale, you will not be able to represent values such as USD 3.50 or USD 21.87 becacuse they are not exact multiples of a dollar.

For some monetary values, such as precious metals, there is no smallest representable unit, since you can repeatedly split the precious metal many times before it stops being a precious metal. Nevertheless, for practical purposes we can make a sane arbitrary choice of smallest unit. For example, the base unit for XAU (Gold) is the troy ounce, which is too big to be considered the smallest unit, but we can arbitrarily choose the milligrain as our smallest unit, which is about as heavy as a single grain of table salt and should be sufficiently precise for all monetary practical purposes. A troy ounce equals 480000 milligrains.

type instance UnitScale "XAU" "milligrain" = '(480000, 1)

You can use other units such as milligrams for measuring XAU, for example. However, since the amount of milligrams in a troy ounce (31103.477) is not integral, we need to use rational with a denominator different than 1 to express it.

type instance UnitScale "XAU" "milligram" = '(31103477, 1000)

If you try to obtain the UnitScale of a currency without an obvious smallest representable unit, like XAU, you will get a compile error.