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

Leading '-' and '+' characters are considered.

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

> denseToDecimal Round True (Just ',') '.' 2 (1 % 1)
     (dense' (123456 % 100) :: Dense "USD")
Just "+1,234.56"

> denseToDecimal Round True (Just ',') '.' 2 (100 % 1)
     (dense' (123456 % 100) :: Dense "USD")
Just "+123,456.00"

This function returns Nothing if the scale is less than 1, or if it's not possible to reliably render the decimal string due to a bad choice of separators. That is, if the separators are digits or equal among themselves, this function returns Nothing.

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., Scale "GBP" ~ '(100, 1)), then you can use:

discrete 2105 :: Discrete "GBP" "penny"

Because 2015 / 100 == 20.15.

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.

Leading '-' and '+' characters are considered.

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 a b c d e f (dis :: Discrete' currency scale)
    == denseToDecimal a b c d e f (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. Use the Rational parameter to this function for modifying that behavior.

Please refer to denseToDecimal for further documentation.

This function returns Nothing if the scale is less than 1, or if it's not possible to reliably render the decimal string due to a bad choice of separators. That is, if the separators are digits or equal among themselves, this function returns Nothing.

Scale 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 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 Scale "USD" "cent" = '(100, 1)

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

type instance Scale "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 Scale "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.

If there exists a canonical smallest unit that can fully represent the currency in all its denominations, then an instance Scale currency currency exists.

type instance Scale "USD" "USD" = Scale "USD" "cent"

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 Scale "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 Scale "XAU" "milligram" = '(31103477, 1000)

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