Overview
Units of measure: SI declared for typed quantities, and measurements at run time.
(import (std units))
;; Typed: the units are checked at compile time and gone at run time.
(: drag (-> (double kg/m^3) (double m/s) double (double m^2) (double N)))
(defun (drag rho v cd area) (* 0.5 rho v v cd area))
(number-in (drag <1.225 kg/m^3> <120 km/h> 0.28 <2.2 m^2>) N) ; 419.2222
(number-in (+ <6000 m> <50 ft>) mi) ; 3.737697
;; At run time: a unit read from text, which no type knows.
(convert-query "6000 m + 50 ft in mi") ; (Ok "3.737697 mi")
(convert-query "65 mi/(12 mi/h) in h,min") ; (Ok "5 h 25 min")
(convert-query "(2 kg/yr)/(3 m3/s) in ng/l") ; (Ok "21.12539 ng/l")
(match (string->measurement "120 km/h")
((Ok v) (measurement-in v "mph")) ; (Ok 74.56454)
((Err e) (Err e)))
The module is two things. It declares SI with def/dimension,
def/prefix and def/unit, which is what a quantity literal
such as <120 km/h>, a type such as (double m/s) and
number-in read units from: the manual’s section on units of
measure says how those work. And it is a library for units at run time,
for a unit the program reads as text: a calculator, a configuration file.
The declarations. The dimensions and their base units:
length (m), mass (kg), time
(s), current (A), temperature (K),
amount (mol), luminosity (cd) and
information (b, bits, kept in a long). The SI
prefixes from q to Q, and the binary ones from Ki to
Yi. About 270 units and their spellings: time (min,
h, d, yr), length (in, ft, mi,
nmi, au, ly, pc), area, volume (l,
gal, cup), mass (g, t, lb,
oz), force, pressure (N, Pa, bar,
atm, psi), energy and power (J, W, Wh,
cal, eV), electricity, information (B),
radiation (Bq, Gy, Sv), angles (deg,
rev, rpm, which are plain numbers: rad is 1), ratios
(%, ppm) and the constants c, gn and
planck, which are units: (number-in v c) is a speed as a
fraction of light’s. A program that wants other units declares them; a
program that wants other bases declares dimensions of its own, and does
not import this module.
At run time. A dimension is a product of base dimensions with
rational exponents. A unit is an atom with a dimension and an exact
factor to the coherent unit of that dimension, or an alias for a unit
expression. A Measurement is a double in the coherent unit and its
dimension.
Grammar. Tightest first: a|b divides two numbers; ^
(or **) raises to a rational exponent, as in m^2,
Hz^(-1/2) and s^-1; juxtaposition multiplies; * and
/ go left to right; + and - add measurements. So
kg m/s^2 is kg·m/s² and m/s kg is m/(s·kg). A name ending in
digits is a power, m2, unless the whole name is a unit.
pi is the number. sqrt(...) and cbrt(...) take roots
of measurements.
Names. A name is looked up as written, then as a name with a
trailing power, then as a prefix on a unit, the longest prefix first:
min is a minute, MiB is 2^20 bytes. Plurals are aliases in
the table, not guessed.
The standard table. The SI base dimensions and information
(b), the SI and binary prefixes, and about 200 units. There is no
degC or degF: absolute temperatures are Celsius and
Fahrenheit, and differences are K or degR.
Errors. Functions that read text return
(Result string ...). Arithmetic on measurements of different
dimensions, and the temperature and decibel functions on the wrong
dimension, raise ArgumentException.
See also: convert-query, string->measurement, resolve-unit, standard-units
Reference
atomatom-dimsatom-factoratom-namecelsius->kelvinconformable-unitsconformable?convert-querydBmdBm->powerdBSPLdBSPL->pressuredBVdBV->voltagedBWdBW->powerdef-dimensiondef-preferreddef-prefixdef-unitdims->stringfactorfactor*factor->doublefactor-exptfactor-one?factor-pifactor-rationalfactor/fahrenheit->kelvinkelvin->celsiuskelvin->fahrenheitmeasurementmeasurement*measurement+measurement-measurement->stringmeasurement->string/mixedmeasurement-dimsmeasurement-exptmeasurement-inmeasurement-scalemeasurement-sqrtmeasurement-valuemeasurement/resolve-unitresolved-atomsresolved-coeffresolved-dimsresolved-factorresolved-termstring->measurementunit-table-names
Types
Atom
record ↑ Types
A named unit with its dimension and its exact factor to the coherent unit of that dimension.
Resolved
record ↑ Types
A resolved unit expression: a coefficient times atoms to rational powers.
resolve-unit returns one. The term maps atom names to their
exponents, and the atoms map holds every atom the term names, so a
Resolved needs no table to be converted. 3 km/h is the
coefficient 3 and the term km·h⁻¹.
PrefixUse
union ↑ Types
Which prefixes printing may put on a preferred unit: NoPrefix, SmallPrefixes (below 1 only) or AllPrefixes.
Measurement
record ↑ Types
A value in the coherent unit of its dimension, and the dimension.
value- The value in the coherent unit.
dims- Base dimension names to nonzero exponents.
Functions
factor
function ↑ Functions
(: factor (-> Rational int Factor))
(factor r k)
A factor.
r- The rational part.
k- The power of pi.
- returns
- r × pi^k.
factor-rational
function ↑ Functions
(: factor-rational (-> Factor Rational))
(factor-rational f)
The rational part of a factor.
f- The factor.
- returns
- r in r × pi^k.
factor-pi
function ↑ Functions
(: factor-pi (-> Factor int))
(factor-pi f)
The power of pi in a factor.
f- The factor.
- returns
- k in r × pi^k.
factor-one?
function ↑ Functions
(: factor-one? (-> Factor bool))
(factor-one? f)
Whether a factor is 1.
f- The factor.
- returns
- #t for 1 × pi^0.
factor*
function ↑ Functions
(: factor* (-> Factor Factor Factor))
(factor* a b)
The product of two factors.
a- The first factor.
b- The second factor.
- returns
- a × b.
factor/
function ↑ Functions
(: factor/ (-> Factor Factor Factor))
(factor/ a b)
The quotient of two factors.
a- The dividend.
b- The divisor. Raises DivideByZeroException when its rational part is zero.
- returns
- a / b.
factor-expt
function ↑ Functions
(: factor-expt (-> Factor Rational (Option Factor)))
(factor-expt f q)
A factor to a rational power, when the result is exact.
f- The factor.
q- The exponent.
- returns
- (Some f^q), or None when f^q is irrational, or f is zero and q negative.
(factor-expt (factor (rational 100 1) 0) (rational 1 2)) ; (Some 10)
(factor-expt (factor (rational 1000 1) 0) (rational 1 2)) ; None
factor->double
function ↑ Functions
(: factor->double (-> Factor double))
(factor->double f)
A factor as a double.
f- The factor.
- returns
- The nearest double to the rational part, times pi^k.
atom
function ↑ Functions
(: atom (-> string (OrderedMap string Rational) Factor Atom))
(atom name dims f)
An atom.
name- The unit's name.
dims- Its dimension: base dimension names to exponents.
f- Its factor to the coherent unit of dims.
- returns
- The atom.
atom-name
function ↑ Functions
(: atom-name (-> Atom string))
(atom-name a)
The name of an atom.
a- The atom.
- returns
- The name.
atom-dims
function ↑ Functions
(: atom-dims (-> Atom (OrderedMap string Rational)))
(atom-dims a)
The dimension of an atom.
a- The atom.
- returns
- Base dimension names to nonzero exponents.
atom-factor
function ↑ Functions
(: atom-factor (-> Atom Factor))
(atom-factor a)
The factor of an atom.
a- The atom.
- returns
- Its factor to the coherent unit of its dimension.
resolved-coeff
function ↑ Functions
(: resolved-coeff (-> Resolved Factor))
(resolved-coeff r)
The coefficient of a resolved expression.
r- The resolved expression.
- returns
- The number the expression multiplies its atoms by.
resolved-term
function ↑ Functions
(: resolved-term (-> Resolved (OrderedMap string Rational)))
(resolved-term r)
The atoms of a resolved expression and their exponents.
r- The resolved expression.
- returns
- Atom names to nonzero rational exponents.
resolved-atoms
function ↑ Functions
(: resolved-atoms (-> Resolved (OrderedMap string Atom)))
(resolved-atoms r)
The atoms a resolved expression names.
r- The resolved expression.
- returns
- Atom names to atoms, one for each name in the term.
resolved-dims
function ↑ Functions
(: resolved-dims (-> Resolved (OrderedMap string Rational)))
(resolved-dims r)
The dimension of a resolved expression.
r- The resolved expression.
- returns
- Base dimension names to nonzero exponents.
resolved-factor
function ↑ Functions
(: resolved-factor (-> Resolved (Result string Factor)))
(resolved-factor r)
The exact factor from a resolved expression to the coherent unit of its dimension.
r- The resolved expression.
- returns
- (Ok factor), or (Err message) when the factor is irrational.
The factor of km/h is 5/18. The factor of km^(1/2) is
√1000, and the result is (Err "the factor of km^(1/2) is
irrational").
def-dimension
function ↑ Functions
(: def-dimension (-> UnitTable string string (Result string UnitTable)))
(def-dimension t dim unit)
Adds a base dimension and its coherent unit.
t- The table.
dim- The dimension's name, as in "length".
unit- The unit's name, as in "m".
- returns
- The new table, or why the names cannot be added.
(def-dimension empty-unit-table "money" "EUR")
def-unit
function ↑ Functions
(: def-unit (-> UnitTable string string (Result string UnitTable)))
(def-unit t name definition)
Adds a unit defined by a unit expression.
t- The table.
name- The unit's name.
definition- A unit expression over the table, as in "12 in".
- returns
- The new table, or why the unit cannot be added.
A definition with coefficient 1 makes an alias: N for
kg m/s^2 is the same unit as its definition. Any other makes an
atom of its own: ft for 12 in. The definition’s factor must
be exact. A name that is already defined is an error.
def-prefix
function ↑ Functions
(: def-prefix (-> UnitTable string string (Result string UnitTable)))
(def-prefix t name value)
Adds a prefix.
t- The table.
name- The prefix, as in "k".
value- Its value as a number, as in "1000", "1e-3" or "1|1024".
- returns
- The new table, or why the prefix cannot be added.
def-preferred
function ↑ Functions
(: def-preferred (-> UnitTable string PrefixUse (Result string UnitTable)))
(def-preferred t unit use)
Sets the unit printing uses for that unit’s dimension.
t- The table.
unit- A unit expression, usually one name.
use- Which prefixes printing may put on it.
- returns
- The new table, or why the unit does not resolve.
unit-table-names
function ↑ Functions
(: unit-table-names (-> UnitTable (List string)))
(unit-table-names t)
The unit names of a table.
t- The table.
- returns
- Every name defined in the table, prefixed and powered forms not included.
resolve-unit
function ↑ Functions
(: resolve-unit (-> UnitTable string (Result string Resolved)))
(resolve-unit t text)
Resolves a unit expression exactly against a table.
t- The table.
text- The expression, as in "km/h" or "1|60 deg".
- returns
- The resolved expression, or what is wrong with the text.
+, -, sqrt and cbrt are not unit
expressions. A power whose coefficient would be irrational, as in
2^(1/2), is an error; an atom to a rational power is not.
Unknown names come with the nearest name in the table when one is close:
unknown unit 'meeter'. Did you mean 'meter'?.
conformable-units
function ↑ Functions
(: conformable-units (-> UnitTable string (Result string (List string))))
(conformable-units t text)
The names in a table with the same dimension as an expression: GNU’s ?.
t- The table.
text- A unit expression.
- returns
- The names, or what is wrong with the text.
measurement
function ↑ Functions
(: measurement (-> double (OrderedMap string Rational) Measurement))
(measurement v d)
A measurement.
v- The value in the coherent unit.
d- The dimension: base dimension names to nonzero exponents.
- returns
- The measurement.
measurement-value
function ↑ Functions
(: measurement-value (-> Measurement double))
(measurement-value m)
The value of a measurement.
m- The measurement.
- returns
- The value in the coherent unit of its dimension.
measurement-dims
function ↑ Functions
(: measurement-dims (-> Measurement (OrderedMap string Rational)))
(measurement-dims m)
The dimension of a measurement.
m- The measurement.
- returns
- Base dimension names to nonzero exponents.
string->measurement
function ↑ Functions
(: string->measurement (-> string (#:table UnitTable) (Result string Measurement)))
(string->measurement text #:table standard-units)
Evaluates an expression with units.
text- The expression, as in "6000 m + 50 ft".
#:table- The table. The standard table by default.
- returns
- The measurement, or what is wrong with the text.
measurement+
function ↑ Functions
(: measurement+ (-> Measurement Measurement Measurement))
(measurement+ a b)
The sum of two measurements.
a- The first.
b- The second. Raises ArgumentException when its dimension is not a's.
- returns
- a + b.
measurement-
function ↑ Functions
(: measurement- (-> Measurement Measurement Measurement))
(measurement- a b)
The difference of two measurements.
a- The first.
b- The second. Raises ArgumentException when its dimension is not a's.
- returns
- a - b.
measurement*
function ↑ Functions
(: measurement* (-> Measurement Measurement Measurement))
(measurement* a b)
The product of two measurements.
a- The first.
b- The second.
- returns
- a × b, with the dimensions multiplied.
measurement/
function ↑ Functions
(: measurement/ (-> Measurement Measurement Measurement))
(measurement/ a b)
The quotient of two measurements.
a- The dividend.
b- The divisor.
- returns
- a / b, with the dimensions divided.
measurement-scale
function ↑ Functions
(: measurement-scale (-> double Measurement Measurement))
(measurement-scale k m)
A measurement times a number.
k- The number.
m- The measurement.
- returns
- k × m, of m's dimension.
measurement-expt
function ↑ Functions
(: measurement-expt (-> Measurement Rational Measurement))
(measurement-expt m q)
A measurement to a rational power.
m- The measurement.
q- The exponent.
- returns
- m^q, with the dimension's exponents times q.
measurement-sqrt
function ↑ Functions
(: measurement-sqrt (-> Measurement Measurement))
(measurement-sqrt m)
The square root of a measurement.
m- The measurement.
- returns
- m^(1/2).
conformable?
function ↑ Functions
(: conformable? (-> Measurement Measurement bool))
(conformable? a b)
Whether two measurements have the same dimension.
a- The first.
b- The second.
- returns
- #t when a and b can be added.
measurement-in
function ↑ Functions
(: measurement-in (-> Measurement string (#:table UnitTable) (Result string double)))
(measurement-in m target #:table standard-units)
A measurement as a number of a unit.
m- The measurement.
target- A unit expression, as in "ft" or "12 mi/h".
#:table- The table. The standard table by default.
- returns
- m divided by target, or an error when their dimensions differ.
(match (string->measurement "1 mi")
((Ok m) (measurement-in m "km")) ; (Ok 1.609344)
((Err e) (Err e)))
measurement->string
function ↑ Functions
(: measurement->string (-> Measurement (#:table UnitTable) string))
(measurement->string m #:table standard-units)
A measurement as text, in a unit chosen for its dimension.
m- The measurement.
#:table- The table. The standard table by default.
- returns
- The value with 7 significant digits, a space and a unit.
The unit is the dimension’s preferred unit with a prefix by magnitude,
as in 3.6 MJ and 5 ms, or else the coherent unit written
with the base units, as in 27.77778 m/s. A dimensionless
measurement is the number alone.
measurement->string/mixed
function ↑ Functions
(: measurement->string/mixed (-> Measurement (List string) (#:table UnitTable) (Result string string)))
(measurement->string/mixed m units #:table standard-units)
A measurement as a sum of units: “5 h 25 min”.
m- The measurement.
units- Unit expressions, largest first. Each but the last takes a whole number.
#:table- The table. The standard table by default.
- returns
- The text, or an error when a unit's dimension is not m's.
convert-query
function ↑ Functions
(: convert-query (-> string (#:table UnitTable) (Result string string)))
(convert-query query #:table standard-units)
Evaluates a query as Umits takes it.
query- An expression, optionally followed by in and one or more units separated by commas.
#:table- The table. The standard table by default.
- returns
- The result as text, or what is wrong with the query.
Commas on the left add: 6 ft, 2 in in m. Several units on the
right give mixed output: 1.8796 m in ft,in. A single unit of
another dimension divides, and the quotient is printed as
measurement->string prints: 65 mi in 12 mi/h is
19500 s. Without in, the result is printed as
measurement->string prints.
(convert-query "12 h in s") ; (Ok "43200 s")
(convert-query "65 mi/(12 mi/h) in h,min") ; (Ok "5 h 25 min")
(convert-query "1 m + 1 s") ; (Err "cannot add length and time")
dims->string
function ↑ Functions
(: dims->string (-> (OrderedMap string Rational) string))
(dims->string d)
A dimension as text.
d- Base dimension names to exponents.
- returns
- "length/time", "mass/(length time^2)", or "dimensionless".
celsius->kelvin
function ↑ Functions
(: celsius->kelvin (-> Celsius Measurement))
(celsius->kelvin c)
A Celsius temperature in kelvin.
c- The temperature.
- returns
- A measurement of temperature: 20 °C is 293.15 K.
kelvin->celsius
function ↑ Functions
(: kelvin->celsius (-> Measurement Celsius))
(kelvin->celsius k)
A temperature in Celsius.
k- A measurement of temperature. Raises ArgumentException for any other dimension.
- returns
- The Celsius temperature.
fahrenheit->kelvin
function ↑ Functions
(: fahrenheit->kelvin (-> Fahrenheit Measurement))
(fahrenheit->kelvin f)
A Fahrenheit temperature in kelvin.
f- The temperature.
- returns
- A measurement of temperature: 32 °F is 273.15 K.
kelvin->fahrenheit
function ↑ Functions
(: kelvin->fahrenheit (-> Measurement Fahrenheit))
(kelvin->fahrenheit k)
A temperature in Fahrenheit.
k- A measurement of temperature. Raises ArgumentException for any other dimension.
- returns
- The Fahrenheit temperature.
dBW
function ↑ Functions
(: dBW (-> Measurement double))
(dBW p)
A power in decibels relative to 1 W.
p- A measurement of power. Raises ArgumentException for any other dimension.
- returns
- 10 log10(p / 1 W).
dBm
function ↑ Functions
(: dBm (-> Measurement double))
(dBm p)
A power in decibels relative to 1 mW.
p- A measurement of power. Raises ArgumentException for any other dimension.
- returns
- 10 log10(p / 1 mW).
dBV
function ↑ Functions
(: dBV (-> Measurement double))
(dBV v)
A voltage in decibels relative to 1 V.
v- A measurement of voltage. Raises ArgumentException for any other dimension.
- returns
- 20 log10(v / 1 V).
dBSPL
function ↑ Functions
(: dBSPL (-> Measurement double))
(dBSPL p)
A sound pressure in decibels relative to 20 µPa.
p- A measurement of pressure. Raises ArgumentException for any other dimension.
- returns
- 20 log10(p / 20 µPa).
dBW->power
function ↑ Functions
(: dBW->power (-> double Measurement))
(dBW->power x)
The power a dBW level is.
x- The level.
- returns
- 1 W × 10^(x/10).
dBm->power
function ↑ Functions
(: dBm->power (-> double Measurement))
(dBm->power x)
The power a dBm level is.
x- The level.
- returns
- 1 mW × 10^(x/10).
dBV->voltage
function ↑ Functions
(: dBV->voltage (-> double Measurement))
(dBV->voltage x)
The voltage a dBV level is.
x- The level.
- returns
- 1 V × 10^(x/20).
dBSPL->pressure
function ↑ Functions
(: dBSPL->pressure (-> double Measurement))
(dBSPL->pressure x)
The sound pressure a dBSPL level is.
x- The level.
- returns
- 20 µPa × 10^(x/20).
Values
standard-units
value ↑ Values
(: standard-units UnitTable)
The standard table: SI, binary prefixes, and the common units.