Lengths with their units (spec/08 §13, spec/14 §3.9, #651, D-174).
A unit value is {n, unit}: data, stored and compared as a value. The absolute
screen units convert to user units — CSS pixels — at CSS's fixed ratios, 96 px = 1 in =
2.54 cm = 25.4 mm = 72 pt and 1 pc = 12 pt; the relative ones, :em and :pct, are
measured against a font size and a box the caller gives (resolve/2). A bare number is
user units, as it always was.
iex> import Visualize.Units
iex> pt(12)
{12, :pt}
iex> Visualize.Units.to_px(pt(12))
16.0
iex> Visualize.Units.resolve(em(1.5), %{em: 12})
18.0
iex> Visualize.Units.resolve(pct(50), %{box: 30})
15.0The world lengths a scene measures its ground in (#620) — :mm … :mi — are a table of
their own, in meters (to_meters/2, convert_length/3): a world length reaches the
screen only through a scale a scene declares.
Summary
Types
A world length unit (spec/08 §13.3).
A length with its unit.
A screen unit (spec/08 §13.1, §13.2).
Functions
The absolute screen units (spec/08 §13.1).
{n, :cm}.
n of one absolute unit in another.
A world length in another world unit.
{n, :em}: n times a font size, the one the context gives (spec/14 §3.9).
{n, :in}: an inch, 96 user units. Named inch because in is an Elixir operator.
The world length units (spec/08 §13.3).
{n, :mm}.
{n, :pc}: a pica, 12 points.
{n, :pct}: n percent of a box's length, the one the context gives (spec/14 §3.9).
{n, :pt}: a point, 1/72 of an inch.
{n, :px}.
A size in user units: a number as it is, an absolute unit value by to_px/1, an em
against the context's :em (a font size) and a pct against its :box (a length).
Raises ArgumentError naming the unit when the context lacks its measure.
A world length in meters.
A number as it is, an absolute unit value in user units; ArgumentError for a relative
one, which has nothing to be measured against here.
Whether a term is a unit value.
The screen units, absolute then relative.
Types
Functions
@spec absolute_units() :: [unit(), ...]
The absolute screen units (spec/08 §13.1).
{n, :cm}.
n of one absolute unit in another.
iex> Visualize.Units.convert(1, :in, :pt)
72.0@spec convert_length(number(), length_unit(), length_unit()) :: float()
A world length in another world unit.
iex> Visualize.Units.convert_length(2500, :m, :km)
2.5{n, :em}: n times a font size, the one the context gives (spec/14 §3.9).
{n, :in}: an inch, 96 user units. Named inch because in is an Elixir operator.
@spec length_units() :: [length_unit(), ...]
The world length units (spec/08 §13.3).
{n, :mm}.
{n, :pc}: a pica, 12 points.
{n, :pct}: n percent of a box's length, the one the context gives (spec/14 §3.9).
{n, :pt}: a point, 1/72 of an inch.
{n, :px}.
A size in user units: a number as it is, an absolute unit value by to_px/1, an em
against the context's :em (a font size) and a pct against its :box (a length).
Raises ArgumentError naming the unit when the context lacks its measure.
@spec to_meters(number(), length_unit()) :: number()
A world length in meters.
iex> Visualize.Units.to_meters(1, :ft)
0.3048A number as it is, an absolute unit value in user units; ArgumentError for a relative
one, which has nothing to be measured against here.
Whether a term is a unit value.
iex> Visualize.Units.unit?({3, :mm})
true
iex> Visualize.Units.unit?({3, :furlong})
false@spec units() :: [unit(), ...]
The screen units, absolute then relative.