Macaw.Data.Format (macaw_data v0.18.0)
View SourceHow 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).
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
A fault at a place (spec/00 §5).
@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
@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 ofMacaw.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,:sior{:si, e}:domain- numbers whose greatest magnitude chooses the:autonotation for every value:format- a d3 specifier that overrides the number:locale- aMacaw.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}}]}
@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.
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"
@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%"
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"
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
:locale- aMacaw.Data.Format.Locale, defaultMacaw.Data.Format.Locale.english/0
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
As parse/2, the format alone, raising Macaw.Data.Error with the faults in format_error/1's words.
@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
:locale- aMacaw.Data.Format.Locale, defaultMacaw.Data.Format.Locale.english/0
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"
@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.
@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]"