AuroraMeter.Credits.Money (Aurora Meter v0.4.0)

Conversions between the ledger's integer micro-dollars and the units the rest of the world uses.

AuroraMeter.Credits stores every amount as an integer number of micro-dollars (1 µ$ = 1e-6 USD, so 1_000_000 is one dollar and 10_000 is one cent). Integers keep the ledger exact under concurrency and let a price of a few thousandths of a cent — a token, a request, a byte — be charged without rounding. Convert at the edges:

iex> AuroraMeter.Credits.Money.from_cents(1_235)
12_350_000

iex> AuroraMeter.Credits.Money.to_cents(12_350_000)
1_235

iex> AuroraMeter.Credits.Money.from_decimal(Decimal.new("12.35"))
12_350_000

iex> AuroraMeter.Credits.Money.format(12_350_000)
"$12.35"

iex> AuroraMeter.Credits.Money.format_compact(1_234_000_000)
"$1.2k"

Summary

Types

micro()

An amount in micro-dollars.

Functions

format(micro, opts \\ [])

Formats micro-dollars as a dollar string with :precision decimals (default 2), rounding half away from zero; negative amounts as "-$1.00".

format_compact(micro)

Formats micro-dollars as a short label for a chart axis or a stat tile: thousands, millions and billions collapse to one decimal ("$1.2k", "$3M"), ordinary amounts render as dollars and cents ("$0.07"), and a sub-cent amount keeps just enough precision to stay non-zero ("$0.000015") rather than rounding away to "$0.00".

from_cents(cents)

Converts cents to micro-dollars.

from_decimal(dollars)

Converts a Decimal amount of dollars to micro-dollars, rounding half up at the sixth decimal place.

to_cents(micro, opts \\ [])

Converts micro-dollars to whole cents, rounding with :round (default, half away from zero), :floor or :ceil.

Types

micro()

@type micro() :: integer()

An amount in micro-dollars.

Functions

format(micro, opts \\ [])

@spec format(micro(), [{:precision, 0..6}]) :: String.t()

Formats micro-dollars as a dollar string with :precision decimals (default 2), rounding half away from zero; negative amounts as "-$1.00".

Examples

iex> AuroraMeter.Credits.Money.format(12_350_000)
"$12.35"

iex> AuroraMeter.Credits.Money.format(-1_000_000)
"-$1.00"

iex> AuroraMeter.Credits.Money.format(15, precision: 6)
"$0.000015"

iex> AuroraMeter.Credits.Money.format(1_999_999, precision: 0)
"$2"

format_compact(micro)

@spec format_compact(micro()) :: String.t()

Use format/2 wherever the exact amount matters; this is for the places where space matters more than the last decimal.

Examples

iex> AuroraMeter.Credits.Money.format_compact(1_234_000_000)
"$1.2k"

iex> AuroraMeter.Credits.Money.format_compact(70_000)
"$0.07"

iex> AuroraMeter.Credits.Money.format_compact(0)
"$0"

iex> AuroraMeter.Credits.Money.format_compact(2_000_000_000)
"$2k"

iex> AuroraMeter.Credits.Money.format_compact(-4_500_000_000_000)
"-$4.5M"

iex> AuroraMeter.Credits.Money.format_compact(15)
"$0.000015"

from_cents(cents)

@spec from_cents(integer()) :: micro()

Converts cents to micro-dollars.

Examples

iex> AuroraMeter.Credits.Money.from_cents(100)
1_000_000

iex> AuroraMeter.Credits.Money.from_cents(-50)
-500_000

from_decimal(dollars)

@spec from_decimal(Decimal.t()) :: micro()

Converts a Decimal amount of dollars to micro-dollars, rounding half up at the sixth decimal place.

Examples

iex> AuroraMeter.Credits.Money.from_decimal(Decimal.new("0.000015"))
15

iex> AuroraMeter.Credits.Money.from_decimal(Decimal.new("-2.5"))
-2_500_000

to_cents(micro, opts \\ [])

@spec to_cents(micro(), [{:rounding, :round | :floor | :ceil}]) :: integer()

Converts micro-dollars to whole cents, rounding with :round (default, half away from zero), :floor or :ceil.

Examples

iex> AuroraMeter.Credits.Money.to_cents(1_234_999)
123

iex> AuroraMeter.Credits.Money.to_cents(1_235_000)
124

iex> AuroraMeter.Credits.Money.to_cents(1_230_001, rounding: :ceil)
124

iex> AuroraMeter.Credits.Money.to_cents(-1_235_000, rounding: :floor)
-124