Macaw.Data.Quantity (macaw_data v0.18.0)
View SourceA fixed list of quantities, each with its facts: a base unit, a kind, bounds, additivity, and display families by unit system (spec/03 §8–§13).
A quantity is what a unit measures. A unit (a UCUM code, Macaw.Data.Unit) and a
quantity together are a measure, %{unit: code, quantity: quantity}, the two facts a
field description carries. They are facts about the data, not knobs: a measure does
not change a value, it says what the value already is, so a display can choose how to
show it.
The list is fixed and grows by proposal: duration, information, data_rate,
frequency, ratio, count, temperature, length, speed, power, energy,
pressure, area, volume, mass, pace, angle, currency,
electric_potential, electric_current, electric_charge, illuminance,
sound_level, mass_concentration and amount_concentration. spec/03 §8–§13 tables each
one's facts and families.
- Kind is
:linear,:affine(a temperature),:logarithmic(a sound level) or:cyclic(an angle, whose mean is circular). - Bounds are a display hint, never validation: a difference is legitimately negative, so a value outside them is never refused.
- Additivity depends on the aggregation:
additivity/2refines the quantity's defaults across series and over time by the field's metric kind (:gauge,:counter,:rate). - Unit systems are
:metric,:us,:ukand:as_posted; a system picks the family a value is shown in and never touches the data.
Information is decimal by default: UCUM's kBy and Telemetry.Metrics'
:kilobyte are 1,000 bytes, and a unit written with a binary prefix (MiBy) or in
bit belongs to its own family. The data picks it; no setting does.
How a value is drawn in its family (the display unit, tick formats, a value's label in
a locale) is the drawing library's: visualize's Visualize.Quantity keeps it, over this
vocabulary.
The vocabulary half of visualize's Visualize.Quantity.
Examples
iex> Macaw.Data.Quantity.family!(:mass, "kg", :us)
["[oz_av]", "[lb_av]"]
iex> Macaw.Data.Quantity.additivity!(:data_rate)
%{across: true, over_time: false}
iex> Macaw.Data.Quantity.label!(%{unit: "{request}"})
"request"
Summary
Types
How a quantity's values combine (spec/03 §9).
A unit and a quantity, either or both; the two facts a field description carries.
How a field's values were measured, which refines its quantity's additivity.
Why a measure does not resolve.
A unit system: a display preference, never applied to the data.
One of the fixed list of quantities.
Functions
Whether a sum of the quantity's values means anything (spec/03 §10, D-155):
%{across: boolean, over_time: boolean} — summing several series at one instant, and
summing one series over time. The quantity's physical defaults are refined by the
field's metric kind: a :gauge and a :rate never add over time, and a :counter's
increments add over time when the quantity adds across. No quantity (a plain number)
defaults to both.
As additivity/2, the map alone, raising Macaw.Data.Error naming the reason.
The fixed list of quantities (spec/03 §8).
A quantity's base unit, the unit its values are in when no unit is given; nil for a
:currency, whose code the data must say. {:ok, unit}, or {:error, {:unknown_quantity, quantity}} for a quantity not in all/0 (spec/00 §5);
base_unit!/1 answers the unit or raises.
As base_unit/1, the unit alone, raising Macaw.Data.Error naming the quantity.
Where a quantity's values physically lie, in its base unit, {min | nil, max | nil}
(spec/03 §9): a display hint an axis may anchor at, never validation — a value
outside them is never refused.
A quantity's bounds in a unit of it: the base's, converted, as {:ok, bounds}. A unit
without a factor (Cel) takes the base's bounds as they are. A unit that is no code, or
not of the quantity's dimension, is Macaw.Data.Unit.convert/3's {:error, reason}
(spec/00 §5); bounds!/2 answers the bounds or raises.
As bounds/1, the bounds alone, raising Macaw.Data.Error naming the quantity.
As bounds/2, the bounds alone, raising Macaw.Data.Error in Macaw.Data.Unit.format_error/1's words.
The display family a unit of the quantity belongs to, smallest first; [] for a unit
of no family's shape (spec/03 §11). Within the unit's convention (family/3), a unit
belongs to the first family holding a member of its shape — its atoms and exponents,
prefixes aside and a binary prefix kept apart — so the unit picks among a quantity's
families: bits, binary prefixes, hertz, watt-hours, US lengths. No unit means the base
unit.
The display family a system shows a unit of the quantity in (spec/03 §11, D-158): the
family the unit's convention names for :metric, :us or :uk when it names one,
else the unit's own (family/2), which is what :as_posted always is.
As family/2, the family alone, raising Macaw.Data.Error naming the reason.
As family/3, the family alone, raising Macaw.Data.Error naming the reason.
How a quantity's values combine (spec/03 §9): :linear, :affine (a temperature),
:logarithmic (a sound level) or :cyclic (an angle).
As kind/1, the kind alone, raising Macaw.Data.Error naming the quantity.
The label rule (spec/03 §14): the unit, else the quantity, else nothing — the
unit's symbol with its annotations written when it is not empty, else the quantity's
name with spaces for underscores, else nil, as {:ok, label}. A measure resolve/1
refuses is its {:error, reason} (spec/00 §5); label!/1 answers the label or raises.
As label/1, the label alone, raising Macaw.Data.Error naming the reason.
The quantity a code's dimension implies, or nil when none of the list has it. A
dimensionless code holding % is a :ratio, any other a :count, and a code of one
currency alone ({iso4217:USD}) a :currency.
As of_unit/1, the quantity alone, raising Macaw.Data.Error in Macaw.Data.Unit.format_error/1's words.
A measure completed and checked (spec/03 §13): a unit alone implies its quantity, a
quantity alone means its base unit, and a unit whose dimension is not its quantity's is
refused. A :ratio or a :count takes any dimensionless unit, and a :currency a
code of one currency alone.
The unit systems a display may prefer (spec/03 §12), :as_posted the default.
Types
@type kind() :: :linear | :affine | :logarithmic | :cyclic
How a quantity's values combine (spec/03 §9).
@type measure() :: %{ optional(:unit) => Macaw.Data.Unit.code() | nil, optional(:quantity) => t() | nil }
A unit and a quantity, either or both; the two facts a field description carries.
@type metric_kind() :: :gauge | :counter | :rate
How a field's values were measured, which refines its quantity's additivity.
@type reason() :: {:unit, Macaw.Data.Unit.code(), Macaw.Data.Unit.reason()} | {:quantity, t(), Macaw.Data.Unit.code()} | {:unknown_quantity, term()}
Why a measure does not resolve.
@type system() :: :metric | :us | :uk | :as_posted
A unit system: a display preference, never applied to the data.
@type t() ::
:duration
| :information
| :data_rate
| :frequency
| :ratio
| :count
| :temperature
| :length
| :speed
| :power
| :energy
| :pressure
| :area
| :volume
| :mass
| :pace
| :angle
| :currency
| :electric_potential
| :electric_current
| :electric_charge
| :illuminance
| :sound_level
| :mass_concentration
| :amount_concentration
One of the fixed list of quantities.
Functions
@spec additivity(t() | nil, metric_kind() | nil) :: {:ok, %{across: boolean(), over_time: boolean()}} | {:error, reason()}
Whether a sum of the quantity's values means anything (spec/03 §10, D-155):
%{across: boolean, over_time: boolean} — summing several series at one instant, and
summing one series over time. The quantity's physical defaults are refined by the
field's metric kind: a :gauge and a :rate never add over time, and a :counter's
increments add over time when the quantity adds across. No quantity (a plain number)
defaults to both.
Examples
iex> Macaw.Data.Quantity.additivity(:count, :gauge)
{:ok, %{across: true, over_time: false}}
iex> Macaw.Data.Quantity.additivity!(:temperature, :counter)
%{across: false, over_time: false}{:error, {:unknown_quantity, quantity}} for a quantity not in all/0, and
{:error, {:unknown_metric_kind, kind}} for a metric kind not :gauge, :counter or
:rate; additivity!/2 answers the map or raises.
@spec additivity!(t() | nil, metric_kind() | nil) :: %{ across: boolean(), over_time: boolean() }
As additivity/2, the map alone, raising Macaw.Data.Error naming the reason.
@spec all() :: [t(), ...]
The fixed list of quantities (spec/03 §8).
@spec base_unit(t()) :: {:ok, Macaw.Data.Unit.code() | nil} | {:error, reason()}
A quantity's base unit, the unit its values are in when no unit is given; nil for a
:currency, whose code the data must say. {:ok, unit}, or {:error, {:unknown_quantity, quantity}} for a quantity not in all/0 (spec/00 §5);
base_unit!/1 answers the unit or raises.
@spec base_unit!(t()) :: Macaw.Data.Unit.code() | nil
As base_unit/1, the unit alone, raising Macaw.Data.Error naming the quantity.
Where a quantity's values physically lie, in its base unit, {min | nil, max | nil}
(spec/03 §9): a display hint an axis may anchor at, never validation — a value
outside them is never refused.
Examples
iex> Macaw.Data.Quantity.bounds(:duration)
{:ok, {0, nil}}{:error, {:unknown_quantity, quantity}} for a quantity not in all/0; bounds!/1
answers the bounds or raises.
@spec bounds(t(), Macaw.Data.Unit.code()) :: {:ok, {number() | nil, number() | nil}} | {:error, term()}
A quantity's bounds in a unit of it: the base's, converted, as {:ok, bounds}. A unit
without a factor (Cel) takes the base's bounds as they are. A unit that is no code, or
not of the quantity's dimension, is Macaw.Data.Unit.convert/3's {:error, reason}
(spec/00 §5); bounds!/2 answers the bounds or raises.
Examples
iex> Macaw.Data.Quantity.bounds(:ratio, "%")
{:ok, {0.0, 100.0}}
iex> Macaw.Data.Quantity.bounds(:ratio, "s")
{:error, {:dimension, "1", "s"}}
As bounds/1, the bounds alone, raising Macaw.Data.Error naming the quantity.
@spec bounds!(t(), Macaw.Data.Unit.code()) :: {number() | nil, number() | nil}
As bounds/2, the bounds alone, raising Macaw.Data.Error in Macaw.Data.Unit.format_error/1's words.
@spec family(t(), Macaw.Data.Unit.code() | nil) :: {:ok, [Macaw.Data.Unit.code()]} | {:error, term()}
The display family a unit of the quantity belongs to, smallest first; [] for a unit
of no family's shape (spec/03 §11). Within the unit's convention (family/3), a unit
belongs to the first family holding a member of its shape — its atoms and exponents,
prefixes aside and a binary prefix kept apart — so the unit picks among a quantity's
families: bits, binary prefixes, hertz, watt-hours, US lengths. No unit means the base
unit.
Examples
iex> Macaw.Data.Quantity.family(:information, "MiBy")
{:ok, ["By", "KiBy", "MiBy", "GiBy", "TiBy"]}
iex> Macaw.Data.Quantity.family!(:length, "[ft_i]")
["[in_i]", "[ft_i]", "[mi_i]"]{:error, reason} for a quantity not in all/0 ({:unknown_quantity, quantity}) or a
unit that is no code (Macaw.Data.Unit.parse/1's reason); family!/2 raises it.
@spec family(t(), Macaw.Data.Unit.code() | nil, system()) :: {:ok, [Macaw.Data.Unit.code()]} | {:error, term()}
The display family a system shows a unit of the quantity in (spec/03 §11, D-158): the
family the unit's convention names for :metric, :us or :uk when it names one,
else the unit's own (family/2), which is what :as_posted always is.
A quantity read in several conventions — a pressure is gauge, barometric or clinical —
picks the unit's by its exact code first, then by its shape, else the first, so a
system chooses within a convention and never across: a barometric hPa is shown in
inches of mercury under :us, and a blood pressure in mm[Hg] stays in it under every
system.
Examples
iex> Macaw.Data.Quantity.family(:mass, "kg", :uk)
{:ok, ["[oz_av]", "[lb_av]", "[stone_av]"]}
iex> Macaw.Data.Quantity.family!(:duration, "ms", :us)
["ns", "us", "ms", "s", "min", "h", "d"]
iex> Macaw.Data.Quantity.family!(:pressure, "hPa", :us)
["[in_i'Hg]"]
iex> Macaw.Data.Quantity.family(:mass, "kg", :imperial)
{:error, {:unknown_system, :imperial}}A quantity, a unit or a system none of systems/0 is {:error, reason}, as family/2
answers, {:unknown_system, system} for the system; family!/3 raises it.
@spec family!(t(), Macaw.Data.Unit.code() | nil) :: [Macaw.Data.Unit.code()]
As family/2, the family alone, raising Macaw.Data.Error naming the reason.
@spec family!(t(), Macaw.Data.Unit.code() | nil, system()) :: [Macaw.Data.Unit.code()]
As family/3, the family alone, raising Macaw.Data.Error naming the reason.
How a quantity's values combine (spec/03 §9): :linear, :affine (a temperature),
:logarithmic (a sound level) or :cyclic (an angle).
Examples
iex> Macaw.Data.Quantity.kind(:angle)
{:ok, :cyclic}
iex> Macaw.Data.Quantity.kind(:vibes)
{:error, {:unknown_quantity, :vibes}}{:error, {:unknown_quantity, quantity}} for a quantity not in all/0; kind!/1
answers the kind or raises.
As kind/1, the kind alone, raising Macaw.Data.Error naming the quantity.
The label rule (spec/03 §14): the unit, else the quantity, else nothing — the
unit's symbol with its annotations written when it is not empty, else the quantity's
name with spaces for underscores, else nil, as {:ok, label}. A measure resolve/1
refuses is its {:error, reason} (spec/00 §5); label!/1 answers the label or raises.
Examples
iex> Macaw.Data.Quantity.label(%{unit: "ms"})
{:ok, "ms"}
iex> Macaw.Data.Quantity.label!(%{quantity: :count})
"count"
iex> Macaw.Data.Quantity.label!(%{})
nil
iex> Macaw.Data.Quantity.label(%{unit: "By", quantity: :duration})
{:error, {:quantity, :duration, "By"}}
As label/1, the label alone, raising Macaw.Data.Error naming the reason.
@spec of_unit(Macaw.Data.Unit.code()) :: {:ok, t() | nil} | {:error, term()}
The quantity a code's dimension implies, or nil when none of the list has it. A
dimensionless code holding % is a :ratio, any other a :count, and a code of one
currency alone ({iso4217:USD}) a :currency.
Examples
iex> Macaw.Data.Quantity.of_unit("kW.h")
{:ok, :energy}
iex> Macaw.Data.Quantity.of_unit!("{request}")
:count
@spec of_unit!(Macaw.Data.Unit.code()) :: t() | nil
As of_unit/1, the quantity alone, raising Macaw.Data.Error in Macaw.Data.Unit.format_error/1's words.
@spec resolve(measure()) :: {:ok, %{unit: Macaw.Data.Unit.code() | nil, quantity: t() | nil}} | {:error, reason()}
A measure completed and checked (spec/03 §13): a unit alone implies its quantity, a
quantity alone means its base unit, and a unit whose dimension is not its quantity's is
refused. A :ratio or a :count takes any dimensionless unit, and a :currency a
code of one currency alone.
Examples
iex> Macaw.Data.Quantity.resolve(%{quantity: :duration})
{:ok, %{unit: "s", quantity: :duration}}
iex> Macaw.Data.Quantity.resolve(%{unit: "By", quantity: :duration})
{:error, {:quantity, :duration, "By"}}
@spec systems() :: [system(), ...]
The unit systems a display may prefer (spec/03 §12), :as_posted the default.