hledger-lib-0.16: Core data types, parsers and utilities for the hledger accounting tool.

Hledger.Data.Amount

Contents

Description

A simple Amount is some quantity of money, shares, or anything else. It has a (possibly null) Commodity and a numeric quantity:

  $1 
  -50
  EUR 3.44 
  GOOG 500
  1.5h
  90 apples
  0 

It may also have an assigned Price, representing this amount's per-unit or total cost in a different commodity. If present, this is rendered like so:

  EUR 2 @ $1.50  (unit price)
  EUR 2 @@ $3   (total price)

A MixedAmount is zero or more simple amounts, so can represent multiple commodities; this is the type most often used:

  0
  $50 + EUR 3
  16h + $13.55 + AAPL 500 + 6 oranges

When a mixed amount has been "normalised", it has no more than one amount in each commodity and no zero amounts; or it has just a single zero amount and no others.

Limited arithmetic with simple and mixed amounts is supported, best used with similar amounts since it mostly ignores assigned prices and commodity exchange rates.

Synopsis

Amount

nullamt :: AmountSource

The empty simple amount.

amountWithCommodity :: Commodity -> Amount -> AmountSource

Convert an amount to the specified commodity, ignoring and discarding any assigned prices and assuming an exchange rate of 1.

canonicaliseAmountCommodity :: Maybe (Map String Commodity) -> Amount -> AmountSource

Replace an amount's commodity with the canonicalised version from the provided commodity map.

setAmountPrecision :: Int -> Amount -> AmountSource

Set the display precision in the amount's commodity.

arithmetic

costOfAmount :: Amount -> AmountSource

Convert an amount to the commodity of its assigned price, if any. Notes:

  • price amounts must be MixedAmounts with exactly one component Amount (or there will be a runtime error)
  • price amounts should be positive, though this is not currently enforced

divideAmount :: Amount -> Double -> AmountSource

Divide an amount's quantity by a constant.

rendering

showAmount :: Amount -> StringSource

Get the string representation of an amount, based on its commodity's display settings. String representations equivalent to zero are converted to just "0".

showAmountDebug :: Amount -> StringSource

Get the unambiguous string representation of an amount, for debugging.

showAmountWithoutPrice :: Amount -> StringSource

Get the string representation of an amount, without any @ price.

maxprecision :: IntSource

For rendering: a special precision value which means show all available digits.

maxprecisionwithpoint :: IntSource

For rendering: a special precision value which forces display of a decimal point.

MixedAmount

nullmixedamt :: MixedAmountSource

The empty mixed amount.

missingamt :: MixedAmountSource

A temporary value for parsed transactions which had no amount specified.

amounts :: MixedAmount -> [Amount]Source

Get a mixed amount's component amounts.

normaliseMixedAmount :: MixedAmount -> MixedAmountSource

Simplify a mixed amount's component amounts: combine amounts with the same commodity, remove any zero amounts, and replace an empty amount list with a single zero amount. Unlike normaliseMixedAmountPreservingPrice, this one discards all but the first price encountered in each commodity. (This is used more for display than arithmetic, but seems a bit odd. XXX)

canonicaliseMixedAmountCommodity :: Maybe (Map String Commodity) -> MixedAmount -> MixedAmountSource

Replace a mixed amount's commodity with the canonicalised version from the provided commodity map.

setMixedAmountPrecision :: Int -> MixedAmount -> MixedAmountSource

Set the display precision in the amount's commodities.

arithmetic

costOfMixedAmount :: MixedAmount -> MixedAmountSource

Convert a mixed amount's component amounts to the commodity of their assigned price, if any.

divideMixedAmount :: MixedAmount -> Double -> MixedAmountSource

Divide a mixed amount's quantities by a constant.

isNegativeMixedAmount :: MixedAmount -> Maybe BoolSource

Is this mixed amount negative, if it can be normalised to a single commodity ?

isZeroMixedAmount :: MixedAmount -> BoolSource

Does this mixed amount appear to be zero when displayed with its given precision ?

isReallyZeroMixedAmountCost :: MixedAmount -> BoolSource

Is this mixed amount really zero, after converting to cost commodities where possible ?

rendering

showMixedAmount :: MixedAmount -> StringSource

Get the string representation of a mixed amount, showing each of its component amounts. NB a mixed amount can have an empty amounts list in which case it shows as "".

showMixedAmountDebug :: MixedAmount -> StringSource

Get an unambiguous string representation of a mixed amount for debugging.

showMixedAmountWithoutPrice :: MixedAmount -> StringSource

Get the string representation of a mixed amount, but without any @ prices.

showMixedAmountWithPrecision :: Int -> MixedAmount -> StringSource

Get the string representation of a mixed amount, showing each of its component amounts with the specified precision, ignoring their commoditys' display precision settings.

misc.