hledger-lib-1.20.1: A reusable library providing the core functionality of hledger
Safe HaskellNone
LanguageHaskell2010

Hledger.Data.Amount

Description

A simple Amount is some quantity of money, shares, or anything else. It has a (possibly null) CommoditySymbol 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

amount :: Amount Source #

The empty simple amount.

nullamt :: Amount Source #

The empty simple amount.

missingamt :: Amount Source #

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

amountWithCommodity :: CommoditySymbol -> Amount -> Amount Source #

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

arithmetic

amountCost :: Amount -> Amount Source #

Convert a amount to its "cost" or "selling price" in another commodity, using its attached transaction price if it has one. Notes:

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

amountIsZero :: Amount -> Bool Source #

Is this amount exactly zero, ignoring its display precision ?

amountLooksZero :: Amount -> Bool Source #

Does mixed amount appear to be zero when rendered with its display precision ?

divideAmount :: Quantity -> Amount -> Amount Source #

Divide an amount's quantity by a constant.

multiplyAmount :: Quantity -> Amount -> Amount Source #

Multiply an amount's quantity by a constant.

divideAmountAndPrice :: Quantity -> Amount -> Amount Source #

Divide an amount's quantity (and its total price, if it has one) by a constant. The total price will be kept positive regardless of the multiplier's sign.

multiplyAmountAndPrice :: Quantity -> Amount -> Amount Source #

Multiply an amount's quantity (and its total price, if it has one) by a constant. The total price will be kept positive regardless of the multiplier's sign.

amountTotalPriceToUnitPrice :: Amount -> Amount Source #

Replace an amount's TotalPrice, if it has one, with an equivalent UnitPrice. Has no effect on amounts without one. Also increases the unit price's display precision to show one extra decimal place, to help keep transaction amounts balancing. Does Decimal division, might be some rounding/irrational number issues.

rendering

amountstyle :: AmountStyle Source #

Default amount style

styleAmount :: Map CommoditySymbol AmountStyle -> Amount -> Amount Source #

Given a map of standard commodity display styles, apply the appropriate one to this amount. If there's no standard style for this amount's commodity, return the amount unchanged.

styleAmountExceptPrecision :: Map CommoditySymbol AmountStyle -> Amount -> Amount Source #

Like styleAmount, but keep the number of decimal places unchanged.

amountUnstyled :: Amount -> Amount Source #

Reset this amount's display style to the default.

showAmount :: Amount -> String Source #

Get the string representation of an amount, based on its commodity's display settings. String representations equivalent to zero are converted to just "0". The special "missing" amount is displayed as the empty string.

cshowAmount :: Amount -> String Source #

Colour version. For a negative amount, adds ANSI codes to change the colour, currently to hard-coded red.

showAmountWithZeroCommodity :: Amount -> String Source #

Like showAmount, but show a zero amount's commodity if it has one.

showAmountDebug :: Amount -> String Source #

Get a string representation of an amount for debugging, appropriate to the current debug level. 9 shows maximum detail.

showAmountWithoutPrice :: Amount -> String Source #

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

setAmountPrecision :: AmountPrecision -> Amount -> Amount Source #

Set an amount's display precision.

withPrecision :: Amount -> AmountPrecision -> Amount Source #

Set an amount's display precision, flipped.

setFullPrecision :: Amount -> Amount Source #

Increase an amount's display precision, if needed, to enough decimal places to show it exactly (showing all significant decimal digits, excluding trailing zeros).

setAmountInternalPrecision :: Word8 -> Amount -> Amount Source #

Set an amount's internal precision, ie rounds the Decimal representing the amount's quantity to some number of decimal places. Rounding is done with Data.Decimal's default roundTo function: "If the value ends in 5 then it is rounded to the nearest even value (Banker's Rounding)". Does not change the amount's display precision. Intended only for internal use, eg when comparing amounts in tests.

withInternalPrecision :: Amount -> Word8 -> Amount Source #

Set an amount's internal precision, flipped. Intended only for internal use, eg when comparing amounts in tests.

setAmountDecimalPoint :: Maybe Char -> Amount -> Amount Source #

Set (or clear) an amount's display decimal point.

withDecimalPoint :: Amount -> Maybe Char -> Amount Source #

Set (or clear) an amount's display decimal point, flipped.

canonicaliseAmount :: Map CommoditySymbol AmountStyle -> Amount -> Amount Source #

Canonicalise an amount's display style using the provided commodity style map.

MixedAmount

nullmixedamt :: MixedAmount Source #

The empty mixed amount.

missingmixedamt :: MixedAmount Source #

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

mixed :: [Amount] -> MixedAmount Source #

Convert amounts in various commodities into a normalised MixedAmount.

amounts :: MixedAmount -> [Amount] Source #

Get a mixed amount's component amounts.

filterMixedAmount :: (Amount -> Bool) -> MixedAmount -> MixedAmount Source #

Filter a mixed amount's component amounts by a predicate.

filterMixedAmountByCommodity :: CommoditySymbol -> MixedAmount -> MixedAmount Source #

Return an unnormalised MixedAmount containing exactly one Amount with the specified commodity and the quantity of that commodity found in the original. NB if Amount's quantity is zero it will be discarded next time the MixedAmount gets normalised.

mapMixedAmount :: (Amount -> Amount) -> MixedAmount -> MixedAmount Source #

Apply a transform to a mixed amount's component Amounts.

normaliseMixedAmountSquashPricesForDisplay :: MixedAmount -> MixedAmount Source #

Like normaliseMixedAmount, but combine each commodity's amounts into just one by throwing away all prices except the first. This is only used as a rendering helper, and could show a misleading price.

normaliseMixedAmount :: MixedAmount -> MixedAmount Source #

Simplify a mixed amount's component amounts:

  • amounts in the same commodity are combined unless they have different prices or total prices
  • multiple zero amounts, all with the same non-null commodity, are replaced by just the last of them, preserving the commodity and amount style (all but the last zero amount are discarded)
  • multiple zero amounts with multiple commodities, or no commodities, are replaced by one commodity-less zero amount
  • an empty amount list is replaced by one commodity-less zero amount
  • the special "missing" mixed amount remains unchanged

unifyMixedAmount :: MixedAmount -> Maybe Amount Source #

Unify a MixedAmount to a single commodity value if possible. Like normaliseMixedAmount, this consolidates amounts of the same commodity and discards zero amounts; but this one insists on simplifying to a single commodity, and will return Nothing if this is not possible.

arithmetic

mixedAmountCost :: MixedAmount -> MixedAmount Source #

Convert all component amounts to cost/selling price where possible (see amountCost).

divideMixedAmount :: Quantity -> MixedAmount -> MixedAmount Source #

Divide a mixed amount's quantities by a constant.

multiplyMixedAmount :: Quantity -> MixedAmount -> MixedAmount Source #

Multiply a mixed amount's quantities by a constant.

divideMixedAmountAndPrice :: Quantity -> MixedAmount -> MixedAmount Source #

Divide a mixed amount's quantities (and total prices, if any) by a constant. The total prices will be kept positive regardless of the multiplier's sign.

multiplyMixedAmountAndPrice :: Quantity -> MixedAmount -> MixedAmount Source #

Multiply a mixed amount's quantities (and total prices, if any) by a constant. The total prices will be kept positive regardless of the multiplier's sign.

averageMixedAmounts :: [MixedAmount] -> MixedAmount Source #

Calculate the average of some mixed amounts.

isNegativeAmount :: Amount -> Bool Source #

Is this amount negative ? The price is ignored.

isNegativeMixedAmount :: MixedAmount -> Maybe Bool Source #

Is this mixed amount negative, if we can tell that unambiguously? Ie when normalised, are all individual commodity amounts negative ?

mixedAmountIsZero :: MixedAmount -> Bool Source #

Is this mixed amount exactly zero, ignoring display precisions ?

mixedAmountLooksZero :: MixedAmount -> Bool Source #

Does this mixed amount appear to be zero when rendered with its display precision ?

mixedAmountTotalPriceToUnitPrice :: MixedAmount -> MixedAmount Source #

Replace each component amount's TotalPrice, if it has one, with an equivalent UnitPrice. Has no effect on amounts without one. Does Decimal division, might be some rounding/irrational number issues.

rendering

styleMixedAmount :: Map CommoditySymbol AmountStyle -> MixedAmount -> MixedAmount Source #

Given a map of standard commodity display styles, apply the appropriate one to each individual amount.

mixedAmountUnstyled :: MixedAmount -> MixedAmount Source #

Reset each individual amount's display style to the default.

showMixedAmount :: MixedAmount -> String Source #

Get the string representation of a mixed amount, after normalising it to one amount per commodity. Assumes amounts have no or similar prices, otherwise this can show misleading prices.

showMixedAmountOneLine :: MixedAmount -> String Source #

Get the one-line string representation of a mixed amount.

showMixedAmountDebug :: MixedAmount -> String Source #

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

showMixedAmountWithoutPrice :: Bool -> MixedAmount -> String Source #

Get the string representation of a mixed amount, without showing any transaction prices. With a True argument, adds ANSI codes to show negative amounts in red.

showMixedAmountOneLineWithoutPrice :: Bool -> MixedAmount -> String Source #

Get the one-line string representation of a mixed amount, but without any @ prices. With a True argument, adds ANSI codes to show negative amounts in red.

showMixedAmountElided :: Int -> Bool -> MixedAmount -> String Source #

Like showMixedAmountOneLineWithoutPrice, but show at most the given width, with an elision indicator if there are more. With a True argument, adds ANSI codes to show negative amounts in red.

showMixedAmountWithZeroCommodity :: MixedAmount -> String Source #

Like showMixedAmount, but zero amounts are shown with their commodity if they have one.

showMixedAmountWithPrecision :: AmountPrecision -> MixedAmount -> String Source #

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

showMixed :: (Amount -> String) -> Maybe Int -> Maybe Int -> Bool -> MixedAmount -> (String, Int) Source #

General function to display a MixedAmount, one Amount on each line. It takes a function to display each Amount, an optional minimum width to pad to, an optional maximum width to display, and a Bool to determine whether to colourise negative numbers. Amounts longer than the maximum width (if given) will be elided. The function also returns the actual width of the output string.

showMixedUnnormalised :: (Amount -> String) -> Maybe Int -> Maybe Int -> Bool -> MixedAmount -> (String, Int) Source #

Like showMixed, but does not normalise the MixedAmount before displaying.

showMixedOneLine :: (Amount -> String) -> Maybe Int -> Maybe Int -> Bool -> MixedAmount -> (String, Int) Source #

General function to display a MixedAmount on a single line. It takes a function to display each Amount, an optional minimum width to pad to, an optional maximum width to display, and a Bool to determine whether to colourise negative numbers. It will display as many Amounts as it can in the maximum width (if given), and further Amounts will be elided. The function also returns the actual width of the output string.

showMixedOneLineUnnormalised :: (Amount -> String) -> Maybe Int -> Maybe Int -> Bool -> MixedAmount -> (String, Int) Source #

Like showMixedOneLine, but does not normalise the MixedAmount before displaying.

setMixedAmountPrecision :: AmountPrecision -> MixedAmount -> MixedAmount Source #

Set the display precision in the amount's commodities.

canonicaliseMixedAmount :: Map CommoditySymbol AmountStyle -> MixedAmount -> MixedAmount Source #

Canonicalise a mixed amount's display styles using the provided commodity style map.

misc.

ltraceamount :: String -> MixedAmount -> MixedAmount Source #

Compact labelled trace of a mixed amount, for debugging.

Orphan instances