(std units)

Reference

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

Types

Functions

Values

Other

Types

Factor

record ↑ Types

An exact conversion factor: a rational times an integer power of pi.

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⁻¹.

UnitTable

record ↑ Types

Dimensions, units, prefixes and preferred units for printing.

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

factor-one

value ↑ Values

(: factor-one Factor)

The factor 1.

empty-unit-table

value ↑ Values

(: empty-unit-table UnitTable)

A table with nothing in it.

standard-units

value ↑ Values

(: standard-units UnitTable)

The standard table: SI, binary prefixes, and the common units.

Other

Celsius

newtype ↑ Other

An absolute temperature in degrees Celsius. A newtype over double.

Fahrenheit

newtype ↑ Other

An absolute temperature in degrees Fahrenheit. A newtype over double.