Visualize.Format.Auto (Visualize v0.4.0)

Copy Markdown View Source

Tick formats derived from what a realised scale already knows: its domain and the tick count (spec/05 §3.1, D-134).

A time domain is formatted by its span and the interval its ticks use — clock times within a day, days within a week, dates within a season, months beyond — and a numeric one by its magnitude — plain below 1,000, grouped from 1,000, one SI prefix from a million. The declarative layer's axis uses these wherever a design gives no format (spec/14 §4.4).

Every function takes locale:, "en" by default and the only locale that ships; any other raises ArgumentError.

Examples

iex> Visualize.Format.Auto.notation([0, 90_000])
:grouped

iex> Visualize.Format.Auto.number({:si, 6}).(2_500_000)
"2.5M"

iex> Visualize.Format.Auto.time_format([~U[2024-03-01 00:00:00Z], ~U[2024-03-01 02:00:00Z]])
"%H:%M"

Summary

Types

notation()

How a numeric domain's ticks are written: by magnitude, or :si per value.

time()

A time value a time scale's domain holds.

Functions

formatter(scale, opts \\ [])

The derived formatter of a realised scale, or nil when the default label serves (a band, ordinal or discretising scale).

notation(domain, opts \\ [])

The notation a numeric domain's magnitude — its greatest |d| — calls for: :plain below 1,000, :grouped below a million, else {:si, e} with e the exponent of the largest SI prefix not above it (spec/05 §3.1).

number(notation, opts \\ [])

The formatter of a notation (spec/05 §3.1): :plain the default label, :grouped it grouped in threes, {:si, e} every value over 10ᵉ with that prefix (zero stays 0), :si each value with its own prefix from k up. A non-number is to_string/1.

time_format(list, opts \\ [])

The Visualize.Format.time/2 specifier for a time domain: by its span, and by whether the interval count ticks use over it is under a day (spec/05 §3.1).

Types

notation()

@type notation() :: :plain | :grouped | {:si, 6..24} | :si

How a numeric domain's ticks are written: by magnitude, or :si per value.

time()

@type time() :: DateTime.t() | NaiveDateTime.t() | Date.t()

A time value a time scale's domain holds.

Functions

formatter(scale, opts \\ [])

@spec formatter(struct(), keyword()) :: (term() -> String.t()) | nil

The derived formatter of a realised scale, or nil when the default label serves (a band, ordinal or discretising scale).

Options

  • :count - the tick count the axis asks for (default 10), which chooses a time scale's interval
  • :locale - default "en"

notation(domain, opts \\ [])

@spec notation([number()], keyword()) :: :plain | :grouped | {:si, 6..24}

The notation a numeric domain's magnitude — its greatest |d| — calls for: :plain below 1,000, :grouped below a million, else {:si, e} with e the exponent of the largest SI prefix not above it (spec/05 §3.1).

Options

  • :locale - default "en"

number(notation, opts \\ [])

@spec number(notation(), keyword()) :: (term() -> String.t())

The formatter of a notation (spec/05 §3.1): :plain the default label, :grouped it grouped in threes, {:si, e} every value over 10ᵉ with that prefix (zero stays 0), :si each value with its own prefix from k up. A non-number is to_string/1.

Options

  • :locale - default "en"

time_format(list, opts \\ [])

@spec time_format([time()], keyword()) :: String.t()

The Visualize.Format.time/2 specifier for a time domain: by its span, and by whether the interval count ticks use over it is under a day (spec/05 §3.1).

Options

  • :count - the tick count (default 10)
  • :locale - default "en"