hledger-lib-1.30: A reusable library providing the core functionality of hledger

Safe Haskell | Safe-Inferred
Language | Haskell2010

Hledger.Data.Amount

Contents

- Commodity
- Amount
  - arithmetic
  - rendering
- MixedAmount
  - arithmetic
  - rendering
- misc.
- Orphan instances

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

- showCommoditySymbol :: Text -> Text
- isNonsimpleCommodityChar :: Char -> Bool
- quoteCommoditySymbolIfNeeded :: Text -> Text
- nullamt :: Amount
- missingamt :: Amount
- num :: Quantity -> Amount
- usd :: DecimalRaw Integer -> Amount
- eur :: DecimalRaw Integer -> Amount
- gbp :: DecimalRaw Integer -> Amount
- per :: Quantity -> Amount
- hrs :: Quantity -> Amount
- at :: Amount -> Amount -> Amount
- (@@) :: Amount -> Amount -> Amount
- amountWithCommodity :: CommoditySymbol -> Amount -> Amount
- amountCost :: Amount -> Amount
- amountIsZero :: Amount -> Bool
- amountLooksZero :: Amount -> Bool
- divideAmount :: Quantity -> Amount -> Amount
- multiplyAmount :: Quantity -> Amount -> Amount
- data AmountDisplayOpts = AmountDisplayOpts {
  - displayPrice :: Bool
  - displayZeroCommodity :: Bool
  - displayThousandsSep :: Bool
  - displayColour :: Bool
  - displayOneLine :: Bool
  - displayMinWidth :: Maybe Int
  - displayMaxWidth :: Maybe Int
  - displayOrder :: Maybe [CommoditySymbol]
  }
- noColour :: AmountDisplayOpts
- noPrice :: AmountDisplayOpts
- oneLine :: AmountDisplayOpts
- csvDisplay :: AmountDisplayOpts
- amountstyle :: AmountStyle
- styleAmount :: Map CommoditySymbol AmountStyle -> Amount -> Amount
- styleAmountExceptPrecision :: Map CommoditySymbol AmountStyle -> Amount -> Amount
- amountUnstyled :: Amount -> Amount
- showAmountB :: AmountDisplayOpts -> Amount -> WideBuilder
- showAmount :: Amount -> String
- showAmountPrice :: Amount -> WideBuilder
- cshowAmount :: Amount -> String
- showAmountWithZeroCommodity :: Amount -> String
- showAmountDebug :: Amount -> String
- showAmountWithoutPrice :: Amount -> String
- amountSetPrecision :: AmountPrecision -> Amount -> Amount
- withPrecision :: Amount -> AmountPrecision -> Amount
- amountSetFullPrecision :: Amount -> Amount
- setAmountInternalPrecision :: Word8 -> Amount -> Amount
- withInternalPrecision :: Amount -> Word8 -> Amount
- setAmountDecimalPoint :: Maybe Char -> Amount -> Amount
- withDecimalPoint :: Amount -> Maybe Char -> Amount
- amountStripPrices :: Amount -> Amount
- canonicaliseAmount :: Map CommoditySymbol AmountStyle -> Amount -> Amount
- nullmixedamt :: MixedAmount
- missingmixedamt :: MixedAmount
- isMissingMixedAmount :: MixedAmount -> Bool
- mixed :: Foldable t => t Amount -> MixedAmount
- mixedAmount :: Amount -> MixedAmount
- maAddAmount :: MixedAmount -> Amount -> MixedAmount
- maAddAmounts :: Foldable t => MixedAmount -> t Amount -> MixedAmount
- amounts :: MixedAmount -> [Amount]
- amountsRaw :: MixedAmount -> [Amount]
- maCommodities :: MixedAmount -> Set CommoditySymbol
- filterMixedAmount :: (Amount -> Bool) -> MixedAmount -> MixedAmount
- filterMixedAmountByCommodity :: CommoditySymbol -> MixedAmount -> MixedAmount
- mapMixedAmount :: (Amount -> Amount) -> MixedAmount -> MixedAmount
- unifyMixedAmount :: MixedAmount -> Maybe Amount
- mixedAmountStripPrices :: MixedAmount -> MixedAmount
- mixedAmountCost :: MixedAmount -> MixedAmount
- maNegate :: MixedAmount -> MixedAmount
- maPlus :: MixedAmount -> MixedAmount -> MixedAmount
- maMinus :: MixedAmount -> MixedAmount -> MixedAmount
- maSum :: Foldable t => t MixedAmount -> MixedAmount
- divideMixedAmount :: Quantity -> MixedAmount -> MixedAmount
- multiplyMixedAmount :: Quantity -> MixedAmount -> MixedAmount
- averageMixedAmounts :: [MixedAmount] -> MixedAmount
- isNegativeAmount :: Amount -> Bool
- isNegativeMixedAmount :: MixedAmount -> Maybe Bool
- mixedAmountIsZero :: MixedAmount -> Bool
- maIsZero :: MixedAmount -> Bool
- maIsNonZero :: MixedAmount -> Bool
- mixedAmountLooksZero :: MixedAmount -> Bool
- styleMixedAmount :: Map CommoditySymbol AmountStyle -> MixedAmount -> MixedAmount
- mixedAmountUnstyled :: MixedAmount -> MixedAmount
- showMixedAmount :: MixedAmount -> String
- showMixedAmountOneLine :: MixedAmount -> String
- showMixedAmountDebug :: MixedAmount -> String
- showMixedAmountWithoutPrice :: Bool -> MixedAmount -> String
- showMixedAmountOneLineWithoutPrice :: Bool -> MixedAmount -> String
- showMixedAmountElided :: Int -> Bool -> MixedAmount -> String
- showMixedAmountWithZeroCommodity :: MixedAmount -> String
- showMixedAmountB :: AmountDisplayOpts -> MixedAmount -> WideBuilder
- showMixedAmountLinesB :: AmountDisplayOpts -> MixedAmount -> [WideBuilder]
- wbToText :: WideBuilder -> Text
- wbUnpack :: WideBuilder -> String
- mixedAmountSetPrecision :: AmountPrecision -> MixedAmount -> MixedAmount
- mixedAmountSetFullPrecision :: MixedAmount -> MixedAmount
- canonicaliseMixedAmount :: Map CommoditySymbol AmountStyle -> MixedAmount -> MixedAmount
- tests_Amount :: TestTree

# Commodity

showCommoditySymbol :: Text -> Text Source #

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

isNonsimpleCommodityChar :: Char -> Bool Source #

quoteCommoditySymbolIfNeeded :: Text -> Text Source #

# Amount

nullamt :: Amount Source #

The empty simple amount.

missingamt :: Amount Source #

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

num :: Quantity -> Amount Source #

usd :: DecimalRaw Integer -> Amount Source #

eur :: DecimalRaw Integer -> Amount Source #

gbp :: DecimalRaw Integer -> Amount Source #

per :: Quantity -> Amount Source #

hrs :: Quantity -> Amount Source #

at :: Amount -> Amount -> Amount Source #

(@@) :: Amount -> Amount -> Amount Source #

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

amountIsZero :: Amount -> Bool Source #

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

amountLooksZero :: Amount -> Bool Source #

Do this Amount and (and its total price, if it has one) appear to be zero when rendered with its display precision ?

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

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

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

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

## rendering

data AmountDisplayOpts Source #

Options for the display of Amount and MixedAmount.

Constructors

AmountDisplayOpts |

Fields

- displayPrice :: Bool

  Whether to display the Price of an Amount.

- displayZeroCommodity :: Bool

  If the Amount rounds to 0, whether to display its commodity string.

- displayThousandsSep :: Bool

  Whether to display thousands separators.

- displayColour :: Bool

  Whether to colourise negative Amounts.

- displayOneLine :: Bool

  Whether to display on one line.

- displayMinWidth :: Maybe Int

  Minimum width to pad to

- displayMaxWidth :: Maybe Int

  Maximum width to clip to | Display amounts in this order (without the commodity symbol) and display a 0 in case a corresponding commodity does not exist

- displayOrder :: Maybe [CommoditySymbol]

#### Instances

Instances details

Show AmountDisplayOpts Source # |
Instance details Defined in Hledger.Data.Amount Methods showsPrec :: Int -> AmountDisplayOpts -> ShowS Source # show :: AmountDisplayOpts -> String Source # showList :: [AmountDisplayOpts] -> ShowS Source #
Default AmountDisplayOpts Source # | Display Amount and MixedAmount with no colour.
Instance details Defined in Hledger.Data.Amount Methods def :: AmountDisplayOpts #

noColour :: AmountDisplayOpts Source #

Display Amount and MixedAmount with no colour.

noPrice :: AmountDisplayOpts Source #

Display Amount and MixedAmount with no prices.

oneLine :: AmountDisplayOpts Source #

Display Amount and MixedAmount on one line with no prices.

csvDisplay :: AmountDisplayOpts Source #

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

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. Also apply the style to the price (except for precision)

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.

showAmountB :: AmountDisplayOpts -> Amount -> WideBuilder Source #

General function to generate a WideBuilder for an Amount, according the supplied AmountDisplayOpts. The special "missing" amount is displayed as the empty string. 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.

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.

    showAmount = wbUnpack . showAmountB noColour

showAmountPrice :: Amount -> WideBuilder Source #

cshowAmount :: Amount -> String Source #

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 Source #

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

    showAmountWithZeroCommodity = wbUnpack . showAmountB noColour{displayZeryCommodity=True}

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.

    showAmountWithoutPrice = wbUnpack . showAmountB noPrice

amountSetPrecision :: AmountPrecision -> Amount -> Amount Source #

Set an amount's display precision.

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

Set an amount's display precision, flipped.

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

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

Set an amount's internal precision, flipped. Intended mainly 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.

amountStripPrices :: Amount -> Amount Source #

Strip all prices from an Amount

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.

isMissingMixedAmount :: MixedAmount -> Bool Source #

Whether a MixedAmount has a missing amount

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

Convert amounts in various commodities into a mixed amount.

mixedAmount :: Amount -> MixedAmount Source #

Create a MixedAmount from a single Amount.

maAddAmount :: MixedAmount -> Amount -> MixedAmount Source #

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

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

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

amounts :: MixedAmount -> [Amount] Source #

Get 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

amountsRaw :: MixedAmount -> [Amount] Source #

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.

maCommodities :: MixedAmount -> Set CommoditySymbol Source #

Get this mixed amount's commodities as a set. Returns an empty set if there are no 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 `Amount`s.

unifyMixedAmount :: MixedAmount -> Maybe Amount Source #

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 Source #

Remove all prices from a MixedAmount.

## arithmetic

mixedAmountCost :: MixedAmount -> MixedAmount Source #

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

maNegate :: MixedAmount -> MixedAmount Source #

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

maPlus :: MixedAmount -> MixedAmount -> MixedAmount Source #

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

maMinus :: MixedAmount -> MixedAmount -> MixedAmount Source #

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

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

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

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

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

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

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

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 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 Source #

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

A convenient alias for mixedAmountIsZero.

maIsNonZero :: MixedAmount -> Bool Source #

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

A convenient alias for not . mixedAmountIsZero.

mixedAmountLooksZero :: MixedAmount -> Bool Source #

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

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.

    showMixedAmount = wbUnpack . showMixedAmountB noColour

showMixedAmountOneLine :: MixedAmount -> String Source #

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

    showMixedAmountOneLine = wbUnpack . showMixedAmountB oneLine

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.

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

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.

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

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.

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

showMixedAmountWithZeroCommodity :: MixedAmount -> String Source #

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

    showMixedAmountWithZeroCommodity = wbUnpack . showMixedAmountB noColour{displayZeroCommodity=True}

showMixedAmountB :: AmountDisplayOpts -> MixedAmount -> WideBuilder Source #

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] Source #

Helper for showMixedAmountB 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 Source #

Convert a WideBuilder to a strict Text.

wbUnpack :: WideBuilder -> String Source #

Convert a WideBuilder to a String.

mixedAmountSetPrecision :: AmountPrecision -> MixedAmount -> MixedAmount Source #

Set the display precision in the amount's commodities.

mixedAmountSetFullPrecision :: MixedAmount -> MixedAmount Source #

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

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

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

# misc.

tests_Amount :: TestTree Source #

# Orphan instances

Monoid MixedAmount Source # |
Instance details Methods mempty :: MixedAmount Source # mappend :: MixedAmount -> MixedAmount -> MixedAmount Source # mconcat :: [MixedAmount] -> MixedAmount Source #
Semigroup MixedAmount Source # |
Instance details Methods (<>) :: MixedAmount -> MixedAmount -> MixedAmount Source # sconcat :: NonEmpty MixedAmount -> MixedAmount Source # stimes :: Integral b => b -> MixedAmount -> MixedAmount Source #
Num Amount Source # |
Instance details Methods (+) :: Amount -> Amount -> Amount Source # (-) :: Amount -> Amount -> Amount Source # (*) :: Amount -> Amount -> Amount Source # negate :: Amount -> Amount Source # abs :: Amount -> Amount Source # signum :: Amount -> Amount Source # fromInteger :: Integer -> Amount Source #
Num MixedAmount Source # |
Instance details Methods (+) :: MixedAmount -> MixedAmount -> MixedAmount Source # (-) :: MixedAmount -> MixedAmount -> MixedAmount Source # (*) :: MixedAmount -> MixedAmount -> MixedAmount Source # negate :: MixedAmount -> MixedAmount Source # abs :: MixedAmount -> MixedAmount Source # signum :: MixedAmount -> MixedAmount Source # fromInteger :: Integer -> MixedAmount Source #