hledger-lib-1.31: A reusable library providing the core functionality of hledger
Safe HaskellSafe-Inferred
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

A mixed amount is always "normalised", it has no more than one amount in each commodity and price. When calling amounts it will have no zero amounts, or just a single zero amount and no other amounts.

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

Commodity

showCommoditySymbol :: Text -> Text #

Show space-containing commodity symbols quoted, as they are in a journal.

isNonsimpleCommodityChar :: Char -> Bool #

Amount

nullamt :: Amount #

The empty simple amount - a zero with no commodity symbol or cost and the default amount display style.

missingamt :: Amount #

A special amount used as a marker, meaning "no explicit amount provided here, infer it when needed". It is nullamt with commodity symbol AUTO.

usd :: DecimalRaw Integer -> Amount #

eur :: DecimalRaw Integer -> Amount #

gbp :: DecimalRaw Integer -> Amount #

amountWithCommodity :: CommoditySymbol -> Amount -> Amount #

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

arithmetic

amountCost :: Amount -> Amount #

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 in the Journal (though this is currently not enforced)

amountIsZero :: Amount -> Bool #

Is this Amount (and its total price, if it has one) exactly zero, ignoring its display precision ?

amountLooksZero :: Amount -> Bool #

Do this Amount and (and its total price, if it has one) appear to be zero when rendered with its display precision ? The display precision should usually have a specific value here; if unset, it will be treated like NaturalPrecision.

divideAmount :: Quantity -> Amount -> Amount #

Divide an amount's quantity (and its total price, if it has one) by a constant.

multiplyAmount :: Quantity -> Amount -> Amount #

Multiply an amount's quantity (and its total price, if it has one) by a constant.

rendering

data AmountDisplayOpts #

Options for the display of Amount and MixedAmount. (See also Types.AmountStyle)

Constructors

AmountDisplayOpts 

Fields

Instances

Instances details
Show AmountDisplayOpts # 
Instance details

Defined in Hledger.Data.Amount

Default AmountDisplayOpts #

By default, display Amount and MixedAmount using noColour amount display options.

Instance details

Defined in Hledger.Data.Amount

noColour :: AmountDisplayOpts #

Display amounts without colour, and with various other defaults.

noPrice :: AmountDisplayOpts #

Display Amount and MixedAmount with no prices.

oneLine :: AmountDisplayOpts #

Display Amount and MixedAmount on one line with no prices.

csvDisplay :: AmountDisplayOpts #

Display Amount and MixedAmount in a form suitable for CSV output.

amountstyle :: AmountStyle #

Default amount style

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

Deprecated: please use amountSetMainStyle (or amountSetStyles) instead

Canonicalise an amount's display style using the provided commodity style map. Its cost amount, if any, is not affected.

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

Deprecated: please use amountSetStyles instead

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. Also do the same for the cost amount if any, but leave its precision unchanged.

amountSetStyles :: Map CommoditySymbol AmountStyle -> Amount -> Amount #

Given some commodity display styles, find and apply the appropriate display style to this amount, and do the same for its cost amount if any (and then stop; we assume costs don't have costs). The main amount's display precision is set or not, according to its style; the cost amount's display precision is left unchanged, regardless of its style. If no style is found for an amount, it is left unchanged.

amountSetStylesExceptPrecision :: Map CommoditySymbol AmountStyle -> Amount -> Amount #

Like amountSetStyles, but leave the display precision unchanged in both main and cost amounts.

amountSetMainStyle :: Map CommoditySymbol AmountStyle -> Amount -> Amount #

Find and apply the appropriate display style, if any, to this amount. The display precision is set or not, according to the style.

amountSetCostStyle :: Map CommoditySymbol AmountStyle -> Amount -> Amount #

Find and apply the appropriate display style, if any, to this amount's cost, if any. The display precision is left unchanged, regardless of the style.

amountUnstyled :: Amount -> Amount #

Reset this amount's display style to the default.

showAmountB :: AmountDisplayOpts -> Amount -> WideBuilder #

General function to generate a WideBuilder for an Amount, according the supplied AmountDisplayOpts. This is the main function to use for showing Amounts, constructing a builder; it can then be converted to a Text with wbToText, or to a String with wbUnpack. Some special cases:

  • The special "missing" amount is displayed as the empty string.
  • If an amount is showing digit group separators but no decimal places, we force showing a decimal mark (with nothing after it) to make it easier to parse correctly.

showAmount :: Amount -> String #

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.

showAmount = wbUnpack . showAmountB noColour

cshowAmount :: Amount -> String #

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

cshowAmount = wbUnpack . showAmountB def{displayColour=True}

showAmountWithZeroCommodity :: Amount -> String #

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

showAmountWithZeroCommodity = wbUnpack . showAmountB noColour{displayZeryCommodity=True}

showAmountDebug :: Amount -> String #

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

showAmountWithoutPrice :: Amount -> String #

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

showAmountWithoutPrice = wbUnpack . showAmountB noPrice

amountSetPrecision :: AmountPrecision -> Amount -> Amount #

Set an amount's display precision.

withPrecision :: Amount -> AmountPrecision -> Amount #

Set an amount's display precision, flipped.

amountSetFullPrecision :: Amount -> Amount #

Increase an amount's display precision, if needed, to enough decimal places to show it exactly (showing all significant decimal digits, without trailing zeros). If the amount's display precision is unset, it is will be treated as precision 0.

setAmountInternalPrecision :: Word8 -> Amount -> Amount #

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 mainly for internal use, eg when comparing amounts in tests.

withInternalPrecision :: Amount -> Word8 -> Amount #

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

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

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

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

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

amountStripPrices :: Amount -> Amount #

Strip all prices from an Amount

MixedAmount

nullmixedamt :: MixedAmount #

The empty mixed amount.

missingmixedamt :: MixedAmount #

A special mixed amount used as a marker, meaning "no explicit amount provided here, infer it when needed".

isMissingMixedAmount :: MixedAmount -> Bool #

Does this MixedAmount include the "missing amount" marker ? Note: currently does not test for equality with missingmixedamt, instead it looks for missingamt among the Amounts. missingamt should always be alone, but detect it even if not.

mixed :: Foldable t => t Amount -> MixedAmount #

Convert amounts in various commodities into a mixed amount.

mixedAmount :: Amount -> MixedAmount #

Create a MixedAmount from a single Amount.

maAddAmount :: MixedAmount -> Amount -> MixedAmount #

Add an Amount to a MixedAmount, normalising the result. Amounts with different costs are kept separate.

maAddAmounts :: Foldable t => MixedAmount -> t Amount -> MixedAmount #

Add a collection of Amounts to a MixedAmount, normalising the result. Amounts with different costs are kept separate.

amounts :: MixedAmount -> [Amount] #

Get a mixed amount's component amounts, with some cleanups. The following descriptions are old and possibly wrong:

  • 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

amountsRaw :: MixedAmount -> [Amount] #

Get a mixed amount's component amounts without normalising zero and missing amounts. This is used for JSON serialisation, so the order is important. In particular, we want the Amounts given in the order of the MixedAmountKeys, i.e. lexicographically first by commodity, then by price commodity, then by unit price from most negative to most positive.

amountsPreservingZeros :: MixedAmount -> [Amount] #

Get a mixed amount's component amounts, with some cleanups. This is a new version of amounts, with updated descriptions and optimised for print to show commodityful zeros.

  • If it contains the "missing amount" marker, only that is returned (discarding any additional amounts).
  • Or if it contains any non-zero amounts, only those are returned (discarding any zeroes).
  • Or if it contains any zero amounts (possibly more than one, possibly in different commodities), all of those are returned.
  • Otherwise the null amount is returned.

maCommodities :: MixedAmount -> Set CommoditySymbol #

Get this mixed amount's commodities as a set. Returns an empty set if there are no amounts.

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

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

filterMixedAmountByCommodity :: CommoditySymbol -> MixedAmount -> MixedAmount #

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 #

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

unifyMixedAmount :: MixedAmount -> Maybe Amount #

Unify a MixedAmount to a single commodity value if possible. 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.

mixedAmountStripPrices :: MixedAmount -> MixedAmount #

Remove all prices from a MixedAmount.

arithmetic

mixedAmountCost :: MixedAmount -> MixedAmount #

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

maNegate :: MixedAmount -> MixedAmount #

Negate mixed amount's quantities (and total prices, if any).

maPlus :: MixedAmount -> MixedAmount -> MixedAmount #

Sum two MixedAmount, keeping the cost of the first if any. Amounts with different costs are kept separate (since 2021).

maMinus :: MixedAmount -> MixedAmount -> MixedAmount #

Subtract a MixedAmount from another. Amounts with different costs are kept separate.

maSum :: Foldable t => t MixedAmount -> MixedAmount #

Sum a collection of MixedAmounts. Amounts with different costs are kept separate.

divideMixedAmount :: Quantity -> MixedAmount -> MixedAmount #

Divide a mixed amount's quantities (and total prices, if any) by a constant.

multiplyMixedAmount :: Quantity -> MixedAmount -> MixedAmount #

Multiply a mixed amount's quantities (and total prices, if any) by a constant.

averageMixedAmounts :: [MixedAmount] -> MixedAmount #

Calculate the average of some mixed amounts.

isNegativeAmount :: Amount -> Bool #

Is this amount negative ? The price is ignored.

isNegativeMixedAmount :: MixedAmount -> Maybe Bool #

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

mixedAmountIsZero :: MixedAmount -> Bool #

Is this mixed amount exactly zero, ignoring its display precision? i.e. does it have zero quantity with no price, zero quantity with a total price (which is also zero), and zero quantity for each unit price?

maIsZero :: MixedAmount -> Bool #

Is this mixed amount exactly zero, ignoring its display precision?

A convenient alias for mixedAmountIsZero.

maIsNonZero :: MixedAmount -> Bool #

Is this mixed amount non-zero, ignoring its display precision?

A convenient alias for not . mixedAmountIsZero.

mixedAmountLooksZero :: MixedAmount -> Bool #

Does this mixed amount appear to be zero when rendered with its display precision? i.e. does it have zero quantity with no price, zero quantity with a total price (which is also zero), and zero quantity for each unit price?

rendering

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

Deprecated: please use mixedAmountSetMainStyle (or mixedAmountSetStyles) instead

Canonicalise a mixed amount's display styles using the provided commodity style map. Cost amounts, if any, are not affected.

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

Deprecated: please use mixedAmountSetStyles instead

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

mixedAmountUnstyled :: MixedAmount -> MixedAmount #

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

showMixedAmount :: MixedAmount -> String #

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.

showMixedAmount = wbUnpack . showMixedAmountB noColour

showMixedAmountOneLine :: MixedAmount -> String #

Get the one-line string representation of a mixed amount (also showing any costs).

showMixedAmountOneLine = wbUnpack . showMixedAmountB oneLine

showMixedAmountDebug :: MixedAmount -> String #

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

showMixedAmountWithoutPrice :: Bool -> MixedAmount -> String #

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.

showMixedAmountWithoutPrice c = wbUnpack . showMixedAmountB noPrice{displayColour=c}

showMixedAmountOneLineWithoutPrice :: Bool -> MixedAmount -> String #

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.

showMixedAmountOneLineWithoutPrice c = wbUnpack . showMixedAmountB oneLine{displayColour=c}

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

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.

showMixedAmountElided w c = wbUnpack . showMixedAmountB oneLine{displayColour=c, displayMaxWidth=Just w}

showMixedAmountWithZeroCommodity :: MixedAmount -> String #

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

showMixedAmountWithZeroCommodity = wbUnpack . showMixedAmountB noColour{displayZeroCommodity=True}

showMixedAmountB :: AmountDisplayOpts -> MixedAmount -> WideBuilder #

General function to generate a WideBuilder for a MixedAmount, according to the supplied AmountDisplayOpts. This is the main function to use for showing MixedAmounts, constructing a builder; it can then be converted to a Text with wbToText, or to a String with wbUnpack.

If a maximum width is given then: - If displayed on one line, it will display as many Amounts as can fit in the given width, and further Amounts will be elided. There will always be at least one amount displayed, even if this will exceed the requested maximum width. - If displayed on multiple lines, any Amounts longer than the maximum width will be elided.

showMixedAmountLinesB :: AmountDisplayOpts -> MixedAmount -> [WideBuilder] #

Helper for showMixedAmountB (and postingAsLines, ...) to show a list of Amounts on multiple lines. This returns the list of WideBuilders: one for each Amount, and padded/elided to the appropriate width. This does not honour displayOneLine; all amounts will be displayed as if displayOneLine were False.

wbToText :: WideBuilder -> Text #

Convert a WideBuilder to a strict Text.

wbUnpack :: WideBuilder -> String #

Convert a WideBuilder to a String.

mixedAmountSetPrecision :: AmountPrecision -> MixedAmount -> MixedAmount #

Set the display precision in the amount's commodities.

mixedAmountSetFullPrecision :: MixedAmount -> MixedAmount #

In each component amount, increase the display precision sufficiently to render it exactly (showing all significant decimal digits).

misc.

Orphan instances