@spec currency(number(), keyword()) :: String.t()

Formats currency (spec/05 §2.6): by a symbol, or by an ISO 4217 code.

With :code, the code writes itself: its minor units are the precision, the locale's separators group it, and the locale's symbol for the code goes before the number after the sign — or the code after the number, for a code the locale has no symbol for.

Options

• :symbol - currency symbol (default: "$"); not with :code
• :precision - decimal places (default: 2, or the code's minor units)
• :code - an ISO 4217 code of Visualize.Unit's table (spec/05 §4.1)
• :locale - with :code, default "en"

Examples

iex> Visualize.Format.currency(1240, code: "USD")
"$1,240.00"

iex> Visualize.Format.currency(1240, code: "JPY")
"¥1,240"

iex> Visualize.Format.currency(-1240.5, code: "CHF")
"-1,240.50 CHF"

@spec duration(number()) :: String.t()

A length of time in seconds, in the unit its magnitude chooses (spec/05 §2.9, #191): the largest of d, h, m, s, ms the value reaches — a whole count as it is, one that is whole in the next finer unit as both, any other to one decimal.

Examples

iex> Enum.map([45, 150, 5400, 5430, 3660, 2.5, 0.25, 0, -90], &Visualize.Format.duration/1)
["45s", "2m30s", "1h30m", "1.5h", "1h1m", "2.5s", "250ms", "0s", "−1m30s"]

@spec duration(number(), keyword()) :: String.t()

A length of time in seconds, in a style (spec/05 §2.9): :magnitude, the default, is duration/1; :compound is the label and tooltip form — the two largest non-zero whole units of d, h, m, s from a second up (1h 24m), milliseconds below a second and nanoseconds below a microsecond, each to :precision decimals (default 2) with trailing zeros trimmed (840ms). An axis keeps a single scaled unit.

Options

• :style - :magnitude (default) or :compound
• :precision - the compound style's decimals below a second (default 2)
• :locale - default "en"

Examples

iex> Enum.map([5040, 0.84, 3603, 0, -90], &Visualize.Format.duration(&1, style: :compound))
["1h 24m", "840ms", "1h 3s", "0s", "-1m 30s"]

@spec exponential(number(), keyword()) :: String.t()

Formats a number in exponential notation.

@spec fixed(number(), integer()) :: String.t()

Formats a number with fixed decimal places.

@spec formatter(String.t()) :: (number() -> String.t())

Creates a number formatter function from a d3-format specifier.

The specifier grammar is d3-format's:

[[fill]align][sign][symbol][0][width][,][.precision][~][type]

• fill is any character, used with align: > right (default), < left, ^ center, = after the sign and symbol.
• sign: - (minus for negatives only, default), + (plus or minus), ( (parentheses for negatives), space (space for positives).
• symbol: $ for a currency prefix, # for the 0b/0o/0x prefix of the b/o/x/X types.
• 0 pads with zeros after the sign and symbol; width is the minimum output width; , groups thousands; .precision is the number of digits after the point (e, f, %) or of significant digits (g, r, s, p); ~ trims insignificant trailing zeros.
• type: e exponential, f fixed, g general (either, by magnitude), r rounded to significant digits, s SI prefix, % percentage fixed, p percentage rounded, d integer, b/o/x/X integer in base 2/8/16, c the value as a string, n for ,g; no type is ~g with a default precision of 12.

Examples

Visualize.Format.formatter(".2s").(1234567)     # => "1.2M"
Visualize.Format.formatter(",.0f").(1234567)    # => "1,234,567"
Visualize.Format.formatter("+.1%").(0.123)      # => "+12.3%"
Visualize.Format.formatter("($.2f").(-12.5)     # => "($12.50)"
Visualize.Format.formatter("08.2f").(3.14159)   # => "00003.14"
Visualize.Format.formatter("#x").(255)          # => "0xff"

An invalid specifier raises ArgumentError.

@spec number(number(), keyword()) :: String.t()

Formats a number with thousands separators.

Options

• :precision - decimal places (default: auto)
• :separator - thousands separator (default: ",")
• :decimal - decimal separator (default: ".")

@spec percent(number(), keyword()) :: String.t()

Formats a number as a percentage.

Options

• :precision - decimal places (default: 1)
• :multiply - multiply by 100 (default: true)

@spec si(number(), keyword()) :: String.t()

Formats a number with SI prefix (k, M, G, etc.).

Options

• :precision - significant digits (default: 3)

@spec time(DateTime.t() | Date.t() | NaiveDateTime.t(), String.t()) :: String.t()

Formats a date/time value with strftime-style directives.

A Date has the time fields at zero. An unknown directive passes through verbatim.