hledger-lib-1.3: Core data types, parsers and functionality for the hledger accounting tools

Safe Haskell | None
Language | Haskell2010

Hledger.Data.Amount

Contents

- 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

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
- nullamt :: Amount
- missingamt :: Amount
- num :: Quantity -> Amount
- usd :: DecimalRaw Integer -> Amount
- eur :: DecimalRaw Integer -> Amount
- gbp :: DecimalRaw Integer -> Amount
- hrs :: Quantity -> Amount
- at :: Amount -> Amount -> Amount
- (@@) :: Amount -> Amount -> Amount
- amountWithCommodity :: CommoditySymbol -> Amount -> Amount
- costOfAmount :: Amount -> Amount
- divideAmount :: Amount -> Quantity -> Amount
- amountstyle :: AmountStyle
- showAmount :: Amount -> String
- cshowAmount :: Amount -> String
- showAmountWithZeroCommodity :: Amount -> String
- showAmountDebug :: Amount -> String
- showAmountWithoutPrice :: Amount -> String
- maxprecision :: Int
- maxprecisionwithpoint :: Int
- setAmountPrecision :: Int -> Amount -> Amount
- withPrecision :: Amount -> Int -> Amount
- canonicaliseAmount :: Map CommoditySymbol AmountStyle -> Amount -> Amount
- nullmixedamt :: MixedAmount
- missingmixedamt :: MixedAmount
- mixed :: [Amount] -> MixedAmount
- amounts :: MixedAmount -> [Amount]
- filterMixedAmount :: (Amount -> Bool) -> MixedAmount -> MixedAmount
- filterMixedAmountByCommodity :: CommoditySymbol -> MixedAmount -> MixedAmount
- normaliseMixedAmountSquashPricesForDisplay :: MixedAmount -> MixedAmount
- normaliseMixedAmount :: MixedAmount -> MixedAmount
- costOfMixedAmount :: MixedAmount -> MixedAmount
- divideMixedAmount :: MixedAmount -> Quantity -> MixedAmount
- averageMixedAmounts :: [MixedAmount] -> MixedAmount
- isNegativeAmount :: Amount -> Bool
- isNegativeMixedAmount :: MixedAmount -> Maybe Bool
- isZeroAmount :: Amount -> Bool
- isReallyZeroAmount :: Amount -> Bool
- isZeroMixedAmount :: MixedAmount -> Bool
- isReallyZeroMixedAmount :: MixedAmount -> Bool
- isReallyZeroMixedAmountCost :: MixedAmount -> Bool
- showMixedAmount :: MixedAmount -> String
- showMixedAmountOneLine :: MixedAmount -> String
- showMixedAmountDebug :: MixedAmount -> String
- showMixedAmountWithoutPrice :: MixedAmount -> String
- showMixedAmountOneLineWithoutPrice :: MixedAmount -> String
- cshowMixedAmountWithoutPrice :: MixedAmount -> String
- cshowMixedAmountOneLineWithoutPrice :: MixedAmount -> String
- showMixedAmountWithZeroCommodity :: MixedAmount -> String
- showMixedAmountWithPrecision :: Int -> MixedAmount -> String
- setMixedAmountPrecision :: Int -> MixedAmount -> MixedAmount
- canonicaliseMixedAmount :: Map CommoditySymbol AmountStyle -> MixedAmount -> MixedAmount
- ltraceamount :: String -> MixedAmount -> MixedAmount
- tests_Hledger_Data_Amount :: Test

# Amount

amount :: Amount #

The empty simple amount.

nullamt :: Amount #

The empty simple amount.

missingamt :: Amount #

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

num :: Quantity -> Amount #

usd :: DecimalRaw Integer -> Amount #

eur :: DecimalRaw Integer -> Amount #

gbp :: DecimalRaw Integer -> Amount #

hrs :: Quantity -> Amount #

at :: Amount -> Amount -> Amount #

(@@) :: Amount -> Amount -> 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

costOfAmount :: Amount -> Amount #

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) XXX
- price amounts should be positive, though this is not currently enforced

divideAmount :: Amount -> Quantity -> Amount #

Divide an amount's quantity by a constant.

## rendering

amountstyle :: AmountStyle #

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.

cshowAmount :: Amount -> String #

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

showAmountWithZeroCommodity :: Amount -> String #

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

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.

maxprecision :: Int #

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

maxprecisionwithpoint :: Int #

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

setAmountPrecision :: Int -> Amount -> Amount #

Set an amount's display precision.

withPrecision :: Amount -> Int -> Amount #

Set an amount's display precision, flipped.

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

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

# MixedAmount

nullmixedamt :: MixedAmount #

The empty mixed amount.

missingmixedamt :: MixedAmount #

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

mixed :: [Amount] -> MixedAmount #

Convert amounts in various commodities into a normalised MixedAmount.

amounts :: MixedAmount -> [Amount] #

Get a mixed amount's component 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.

normaliseMixedAmountSquashPricesForDisplay :: MixedAmount -> MixedAmount #

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 #

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

## arithmetic

costOfMixedAmount :: MixedAmount -> MixedAmount #

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

divideMixedAmount :: MixedAmount -> Quantity -> MixedAmount #

Divide a mixed amount's quantities 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 it can be normalised to a single commodity ?

isZeroAmount :: Amount -> Bool #

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

isReallyZeroAmount :: Amount -> Bool #

Is this amount "really" zero, regardless of the display precision ?

isZeroMixedAmount :: MixedAmount -> Bool #

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

isReallyZeroMixedAmount :: MixedAmount -> Bool #

Is this mixed amount "really" zero ? See isReallyZeroAmount.

isReallyZeroMixedAmountCost :: MixedAmount -> Bool #

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

## rendering

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.

showMixedAmountOneLine :: MixedAmount -> String #

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

showMixedAmountDebug :: MixedAmount -> String #

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

showMixedAmountWithoutPrice :: MixedAmount -> String #

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

showMixedAmountOneLineWithoutPrice :: MixedAmount -> String #

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

cshowMixedAmountWithoutPrice :: MixedAmount -> String #

Colour version.

cshowMixedAmountOneLineWithoutPrice :: MixedAmount -> String #

Colour version.

showMixedAmountWithZeroCommodity :: MixedAmount -> String #

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

showMixedAmountWithPrecision :: Int -> MixedAmount -> String #

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

setMixedAmountPrecision :: Int -> MixedAmount -> MixedAmount #

Set the display precision in the amount's commodities.

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

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

# misc.

ltraceamount :: String -> MixedAmount -> MixedAmount #

Compact labelled trace of a mixed amount, for debugging.

tests_Hledger_Data_Amount :: Test #

# Orphan instances

Num MixedAmount # |
Methods (+) :: MixedAmount -> MixedAmount -> MixedAmount # (-) :: MixedAmount -> MixedAmount -> MixedAmount # (*) :: MixedAmount -> MixedAmount -> MixedAmount # negate :: MixedAmount -> MixedAmount # abs :: MixedAmount -> MixedAmount # signum :: MixedAmount -> MixedAmount # fromInteger :: Integer -> MixedAmount #
Num Amount # |
Methods (+) :: Amount -> Amount -> Amount # (-) :: Amount -> Amount -> Amount # (*) :: Amount -> Amount -> Amount # negate :: Amount -> Amount # abs :: Amount -> Amount # signum :: Amount -> Amount # fromInteger :: Integer -> Amount #
Show MarketPrice # |
Methods showsPrec :: Int -> MarketPrice -> ShowS # show :: MarketPrice -> String # showList :: [MarketPrice] -> ShowS #
Show MixedAmount # |
Methods showsPrec :: Int -> MixedAmount -> ShowS # show :: MixedAmount -> String # showList :: [MixedAmount] -> ShowS #
Show Amount # |
Methods showsPrec :: Int -> Amount -> ShowS # show :: Amount -> String # showList :: [Amount] -> ShowS #