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

Safe Haskell | None

Hledger.Data.Amount

Contents

- Amount
  - arithmetic
  - rendering
- MixedAmount
  - arithmetic
  - rendering
- misc.

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 :: Amount
- nullamt :: Amount
- missingamt :: Amount
- num :: Quantity -> Amount
- usd :: Quantity -> Amount
- eur :: Quantity -> Amount
- gbp :: Quantity -> Amount
- hrs :: Quantity -> Amount
- at :: Amount -> Amount -> Amount
- (@@) :: Amount -> Amount -> Amount
- amountWithCommodity :: Commodity -> Amount -> Amount
- costOfAmount :: Amount -> Amount
- divideAmount :: Amount -> Double -> Amount
- sumAmounts :: [Amount] -> MixedAmount
- amountstyle :: AmountStyle
- showAmount :: Amount -> String
- showAmountDebug :: Amount -> String
- showAmountWithoutPrice :: Amount -> String
- maxprecision :: Int
- maxprecisionwithpoint :: Int
- setAmountPrecision :: Int -> Amount -> Amount
- withPrecision :: Amount -> Int -> Amount
- canonicaliseAmount :: Map Commodity AmountStyle -> Amount -> Amount
- canonicalStyles :: [Amount] -> Map Commodity AmountStyle
- nullmixedamt :: MixedAmount
- missingmixedamt :: MixedAmount
- mixed :: Amount -> MixedAmount
- amounts :: MixedAmount -> [Amount]
- normaliseMixedAmountPreservingFirstPrice :: MixedAmount -> MixedAmount
- normaliseMixedAmountPreservingPrices :: MixedAmount -> MixedAmount
- costOfMixedAmount :: MixedAmount -> MixedAmount
- divideMixedAmount :: MixedAmount -> Double -> MixedAmount
- isNegativeMixedAmount :: MixedAmount -> Maybe Bool
- isZeroMixedAmount :: MixedAmount -> Bool
- isReallyZeroMixedAmount :: MixedAmount -> Bool
- isReallyZeroMixedAmountCost :: MixedAmount -> Bool
- showMixedAmount :: MixedAmount -> String
- showMixedAmountDebug :: MixedAmount -> String
- showMixedAmountWithoutPrice :: MixedAmount -> String
- showMixedAmountWithPrecision :: Int -> MixedAmount -> String
- setMixedAmountPrecision :: Int -> MixedAmount -> MixedAmount
- canonicaliseMixedAmount :: Map Commodity AmountStyle -> MixedAmount -> MixedAmount
- ltraceamount :: String -> MixedAmount -> MixedAmount
- tests_Hledger_Data_Amount :: Test

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

num :: Quantity -> Amount Source

usd :: Quantity -> Amount Source

eur :: Quantity -> Amount Source

gbp :: Quantity -> Amount Source

hrs :: Quantity -> Amount Source

at :: Amount -> Amount -> Amount Source

Set an amount's unit price.

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

Set an amount's total price.

amountWithCommodity :: Commodity -> Amount -> Amount Source

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

## arithmetic

costOfAmount :: Amount -> Amount Source

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

Divide an amount's quantity by a constant.

sumAmounts :: [Amount] -> MixedAmount Source

A more complete amount adding operation.

## rendering

amountstyle :: AmountStyle Source

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".

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.

maxprecision :: Int Source

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

maxprecisionwithpoint :: Int Source

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

setAmountPrecision :: Int -> Amount -> Amount Source

Set an amount's display precision.

withPrecision :: Amount -> Int -> Amount Source

Set an amount's display precision, flipped.

canonicaliseAmount :: Map Commodity AmountStyle -> Amount -> Amount Source

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

canonicalStyles :: [Amount] -> Map Commodity AmountStyle Source

Given a list of amounts in parse order, build a map from commodities to canonical display styles for amounts in that commodity.

# MixedAmount

nullmixedamt :: MixedAmount Source

The empty mixed amount.

missingmixedamt :: MixedAmount Source

mixed :: Amount -> MixedAmount Source

amounts :: MixedAmount -> [Amount]Source

Get a mixed amount's component amounts.

normaliseMixedAmountPreservingFirstPrice :: MixedAmount -> MixedAmount Source

Simplify a mixed amount's component amounts: combine amounts with the same commodity, using the first amount's price for subsequent amounts in each commodity (ie, this function alters the amount and is best used as a rendering helper.). Also remove any zero amounts and replace an empty amount list with a single zero amount.

normaliseMixedAmountPreservingPrices :: MixedAmount -> MixedAmount Source

Simplify a mixed amount's component amounts: we can combine amounts with the same commodity and unit price. Also remove any zero or missing amounts and replace an empty amount list with a single zero amount.

## arithmetic

costOfMixedAmount :: MixedAmount -> MixedAmount Source

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

divideMixedAmount :: MixedAmount -> Double -> MixedAmount Source

Divide a mixed amount's quantities by a constant.

isNegativeMixedAmount :: MixedAmount -> Maybe Bool Source

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

isZeroMixedAmount :: MixedAmount -> Bool Source

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

isReallyZeroMixedAmount :: MixedAmount -> Bool Source

Is this mixed amount really zero ? See isReallyZeroAmount.

isReallyZeroMixedAmountCost :: MixedAmount -> Bool Source

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

## rendering

showMixedAmount :: MixedAmount -> String Source

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

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

showMixedAmountWithoutPrice :: MixedAmount -> String Source

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

showMixedAmountWithPrecision :: Int -> 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.

setMixedAmountPrecision :: Int -> MixedAmount -> MixedAmount Source

Set the display precision in the amount's commodities.

canonicaliseMixedAmount :: Map Commodity 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.

tests_Hledger_Data_Amount :: Test Source