Macaw.Data.Format (macaw_data v0.18.0)

View Source

How a value is written for a person (spec/05): a format is data, read once from the text it is written in and applied to any number of values.

A number's format is a d3-format specifier, [[fill]align][sign][symbol][0][width][,][.precision][~][type] (spec/05 §2), read by parse/2 into a %Macaw.Data.Format{} that holds no function, so it can be compared, digested and carried, and written by number/2:

iex> {:ok, format} = Macaw.Data.Format.parse(",.2f")
iex> Macaw.Data.Format.number(format, 1234567.891)
"1,234,567.89"

iex> Macaw.Data.Format.number(Macaw.Data.Format.parse!(".3s"), 42_000_000)
"42.0M"

iex> Macaw.Data.Format.number(Macaw.Data.Format.parse!("($,.2f"), -1234.5)
"($1,234.50)"

iex> Macaw.Data.Format.parse("..2f")
{:error, [{[], {:specifier, "..2f"}}]}

The digits are d3's, byte for byte over visualize's conformance set, which carries d3's own cases; where this differs from d3 (an integer's exact digits, a width bound), spec/05 §2 says so. The locale is a Macaw.Data.Format.Locale, English by default.

Summary

Types

A fault at a place (spec/00 §5).

t()

A parsed format: the text it was read from, each part of the grammar as d3 normalizes it, the affixes its symbol and type write under its locale, and the locale.

Functions

A field's default format, from its measure (spec/05 §6): {:ok, format} or {:error, faults}, each fault at its key.

As for_measure/2, the format alone, raising Macaw.Data.Error with the faults in format_error/1's words.

The words of a reason this module answers, for a person (spec/00 §5).

Writes a value by a measure's format (spec/05 §6): a string, whatever the value; a value that is no number is the locale's not-a-number.

Writes a value by a format (spec/05 §1): a string, whatever the value.

Reads a d3-format specifier (spec/05 §1, §2): {:ok, format} or {:error, faults}.

As parse/2, the format alone, raising Macaw.Data.Error with the faults in format_error/1's words.

Reads a strftime pattern into a time's format (spec/05 §5): {:ok, format}, or {:error, faults} for a term that is no string ({[], {:type, :pattern}}) or options parse/2 refuses. Every string is a pattern: a % before a character that is no directive is written as it stands.

As parse_time/2, the format alone, raising Macaw.Data.Error with the faults in format_error/1's words.

Writes a time by a time's format (spec/05 §5), as visualize's Visualize.Format.time/2 writes it: a DateTime by its own wall clock and zone, a NaiveDateTime and a Date (at midnight) with no zone, an integer as Unix microseconds in UTC. Any other value, and an integer past a DateTime's range, is the locale's not-a-number.

Types

fault()

@type fault() :: {[term()], term()}

A fault at a place (spec/00 §5).

t()

@type t() :: %Macaw.Data.Format{
  align: String.t(),
  comma: boolean(),
  fill: String.t(),
  locale: Macaw.Data.Format.Locale.t(),
  precision: non_neg_integer(),
  prefix: String.t(),
  sign: String.t(),
  specifier: String.t(),
  suffix: String.t(),
  symbol: String.t(),
  trim: boolean(),
  type: String.t(),
  width: non_neg_integer() | nil,
  zero: boolean()
}

A parsed format: the text it was read from, each part of the grammar as d3 normalizes it, the affixes its symbol and type write under its locale, and the locale.

Functions

for_measure(measure, opts \\ [])

@spec for_measure(
  term(),
  keyword()
) :: {:ok, Macaw.Data.Format.Measure.t()} | {:error, [fault(), ...]}

A field's default format, from its measure (spec/05 §6): {:ok, format} or {:error, faults}, each fault at its key.

The measure, %{unit: code, quantity: quantity} with either or both absent, is completed by Macaw.Data.Quantity.resolve/1, and its quantity chooses the writing: a duration compound, a currency by its code, a ratio a percent, a count rounded and grouped, any other quantity rescaled within its unit's family, a number with no measure by its notation.

Options

  • :precision - decimals, 0 to 20, default 2 (a currency's: its code's minor units)
  • :system - one of Macaw.Data.Quantity.systems/0, default :as_posted
  • :style - a duration's, :compound (default) or :magnitude
  • :notation - a number's with no measure: :auto (default), :plain, :grouped, :si or {:si, e}
  • :domain - numbers whose greatest magnitude chooses the :auto notation for every value
  • :format - a d3 specifier that overrides the number
  • :locale - a Macaw.Data.Format.Locale, default English

Examples

iex> {:ok, format} = Macaw.Data.Format.for_measure(%{unit: "s"})
iex> Macaw.Data.Format.measure(format, 5040)
"1h 24m"

iex> Macaw.Data.Format.measure(Macaw.Data.Format.for_measure!(%{unit: "{iso4217:JPY}"}), 1240)
"¥1,240"

iex> Macaw.Data.Format.measure(Macaw.Data.Format.for_measure!(%{unit: "kg"}, system: :us), 80)
"176.37 lb"

iex> Macaw.Data.Format.measure(Macaw.Data.Format.for_measure!(%{}, domain: [0, 9_000_000]), 4_500_000)
"4.5M"

iex> Macaw.Data.Format.for_measure(%{unit: "By", quantity: :duration}, precision: -1)
{:error, [{[:measure], {:quantity, :duration, "By"}}, {[:precision], {:type, :precision}}]}

for_measure!(measure, opts \\ [])

@spec for_measure!(
  term(),
  keyword()
) :: Macaw.Data.Format.Measure.t()

As for_measure/2, the format alone, raising Macaw.Data.Error with the faults in format_error/1's words.

format_error(reason)

@spec format_error(term()) :: String.t()

The words of a reason this module answers, for a person (spec/00 §5).

iex> Macaw.Data.Format.format_error({:width, 1024})
"is wider than 1024 characters, the most a format writes"

measure(format, value)

@spec measure(Macaw.Data.Format.Measure.t(), term()) :: String.t()

Writes a value by a measure's format (spec/05 §6): a string, whatever the value; a value that is no number is the locale's not-a-number.

iex> Macaw.Data.Format.measure(Macaw.Data.Format.for_measure!(%{quantity: :ratio}), 0.914)
"91.40%"

number(format, value)

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

Writes a value by a format (spec/05 §1): a string, whatever the value.

A value that is no number is the locale's not-a-number, NaN in English, padded and aligned as the format says; under the c type a string, a number or an atom is written as text.

iex> Macaw.Data.Format.number(Macaw.Data.Format.parse!(">6.2f"), nil)
"   NaN"

parse(specifier, opts \\ [])

@spec parse(
  term(),
  keyword()
) :: {:ok, t()} | {:error, [fault(), ...]}

Reads a d3-format specifier (spec/05 §1, §2): {:ok, format} or {:error, faults}.

A string that is no specifier is {[], {:specifier, text}}, a term that is no string {[], {:type, :specifier}}, a width over 1,024 {[], {:width, 1024}}.

Options

Examples

iex> {:ok, format} = Macaw.Data.Format.parse("+.1%")
iex> {format.sign, format.precision, format.type, format.suffix}
{"+", 1, "%", "%"}

iex> Macaw.Data.Format.parse("08.2f") == Macaw.Data.Format.parse("08.2f")
true

parse!(specifier, opts \\ [])

@spec parse!(
  term(),
  keyword()
) :: t()

As parse/2, the format alone, raising Macaw.Data.Error with the faults in format_error/1's words.

parse_time(pattern, opts \\ [])

@spec parse_time(
  term(),
  keyword()
) :: {:ok, Macaw.Data.Format.Time.t()} | {:error, [fault(), ...]}

Reads a strftime pattern into a time's format (spec/05 §5): {:ok, format}, or {:error, faults} for a term that is no string ({[], {:type, :pattern}}) or options parse/2 refuses. Every string is a pattern: a % before a character that is no directive is written as it stands.

Options

Examples

iex> {:ok, format} = Macaw.Data.Format.parse_time("%Y-%m-%d %H:%M")
iex> Macaw.Data.Format.time(format, ~U[2026-11-12 08:05:00Z])
"2026-11-12 08:05"

parse_time!(pattern, opts \\ [])

@spec parse_time!(
  term(),
  keyword()
) :: Macaw.Data.Format.Time.t()

As parse_time/2, the format alone, raising Macaw.Data.Error with the faults in format_error/1's words.

time(format, value)

@spec time(Macaw.Data.Format.Time.t(), term()) :: String.t()

Writes a time by a time's format (spec/05 §5), as visualize's Visualize.Format.time/2 writes it: a DateTime by its own wall clock and zone, a NaiveDateTime and a Date (at midnight) with no zone, an integer as Unix microseconds in UTC. Any other value, and an integer past a DateTime's range, is the locale's not-a-number.

iex> format = Macaw.Data.Format.parse_time!("%a %e %b %I:%M %p [%Z]")
iex> Macaw.Data.Format.time(format, ~N[2024-03-03 14:05:09])
"Sun  3 Mar 02:05 PM []"
iex> Macaw.Data.Format.time(format, 1_709_474_709_000_000)
"Sun  3 Mar 02:05 PM [UTC]"