Document units of measure and rational numbers

This commit is contained in:
Linus Björnstam 2026-11-03 15:18:28 +01:00
parent 2334da2516
commit d16bf477a1
4 changed files with 139 additions and 2 deletions

View file

@ -2484,9 +2484,20 @@ The numeric types are the .NET ones:
| @code{int} | about ±2.1 billion | @code{double} | 64-bit floating point |
| @code{bigint} | any integer | @code{float} | 32-bit floating point |
| @code{int128} | −2^127 … 2^127−1 | @code{decimal} | 28 digits, exact decimals |
| @code{uint128} | 0 … 2^128−1 | | |
| @code{uint128} | 0 … 2^128−1 | @code{rational} | exact fractions |
}
All but one are the .NET ones. @code{rational} is bjolang's own, an exact fraction over @code{bigint}, and a number like the others: @code{+ - * /} and the comparisons work on it, and a literal at it is exact, so @code{0.1} is one tenth and not the double nearest to it. It prints as @code{1/3}. @code{(std rational)} has its operations by name, as @code{rational+} and @code{rational->double}.
@codeblock[#:lang "bjolang"]|{
(: third rational)
(def third (/ 1 3))
(* third 0.3) ;; 1/10, exactly
(= (* third 3) 1) ;; #t
(cast double third) ;; 0.3333333333333333
}|
A @code{char} is not a number: it can be compared and converted, but not added.
@subsubsection{Writing numbers}
@ -2642,7 +2653,7 @@ If a function only compares values, use @code{(where (Ord %a))} instead. It work
@codeblock[#:lang "bjolang"]|{
(import (std maths))
(sqrt 9) ;; 3.0: the int 9 widens to a double at the call
(sqrt 9) ;; 3.0: the 9 is a double, since sqrt takes one
(pow 2.0 10.0) ;; 1024.0
(floor -2.5) ;; -3.0
(truncate -2.5) ;; -2.0
@ -2655,3 +2666,118 @@ If a function only compares values, use @code{(where (Ord %a))} instead. It work
The logarithms are @code{loge} (natural), @code{log2}, @code{log10} and @code{(log-base x b)}. The name @code{log} is taken by the logging function of the prelude.
@subsection{Units of measure}
A number can carry a dimension in its type. A @code{(double m/s)} is a speed, a @code{(double m)} is a length, and the compiler refuses to add the two. The checking is all at compile time: a @code{(double m/s)} is a plain @code{double} at run time, and a conversion between units is a constant the compiler works out.
@subsubsection{Quantities}
A quantity is written in angle brackets, a number and then a unit:
@codeblock[#:lang "bjolang"]|{
(import (std units))
(def g <9.80665 m/s^2>) ;; a (double m/s^2)
(def limit <120 km/h>) ;; a (double m/s): 33.33…
(def width <3 ft>) ;; a (double m): 0.9144
}|
Each dimension has a base unit, and a quantity is kept in it: a length in metres, a time in seconds, a speed in metres per second. @code{<120 km/h>} is converted to metres per second when the program is compiled, and is one constant in the code that comes out. So every length is the same type, whatever unit it was written in, and @code{(+ <1 m> <1 ft>)} is 1.3048 metres.
The unit is written as GNU @code{units} writes one: @code{kg m/s^2} is kilograms times metres per second squared, a space or a @code{*} multiplies, @code{/} divides, and @code{^} raises, with a negative or a fractional power as @code{s^-2} or @code{Hz^(-1/2)}. Everything after @code{/} up to the next @code{/} or @code{*} is below the line, so @code{m/s kg} is m/(s·kg). Prefixes go on any unit: @code{km}, @code{mg}, @code{GHz}, @code{KiB}. The number is read exactly, and may be a fraction: @code{<1|3 h>} is twenty minutes, and @code{<1e-3 km>} is a metre. A @code{<} with a digit right after it starts a quantity, so @code{(< 1 2)} is still a comparison, but @code{(<1 2)} is not.
@subsubsection{Types}
A type with a unit is a number type and a unit: @code{(double m/s)}, @code{(long cent)}, @code{(double kg m^2/s^2)}. A type names base units, so a field of a record is @code{(double m)} even when the numbers in it are thought of as kilometres. A unit that is only a name for base units can be written too: @code{(double N)} is @code{(double kg m/s^2)}. One that has a factor cannot, because a @code{(double km)} would be a number in metres with a lie on it:
@codeblock[#:lang "text"]|{
Type Error at trip.bjo:4:10: 'km' is 1000 m, and a type names base units only:
write (double m), and (number-in x km) where a number in km is needed.
}|
@code{<m/s>} is the unit with the number type its dimension keeps it in, which is @code{double} for SI. Records, unions, signatures and @code{let} take these types as they take any other:
@codeblock[#:lang "bjolang"]|{
(type (: Leg (Record (: distance (double m))
(: climb (double m))
(: speed (double m/s)))))
(def leg (Leg (distance <38 km>) (climb <800 ft>) (speed <15 mph>)))
(: hours (-> Leg (double s)))
(defun (hours l) (/ (.distance l) (.speed l))) ;; m / (m/s) is s
}|
@subsubsection{Arithmetic}
@code{+}, @code{-} and the comparisons take two numbers of the same unit, and @code{*} and @code{/} multiply and divide the units, so @code{(* <2 m> <3 m>)} is a @code{(double m^2)}. @code{sqrt} takes the root of the unit too: the square root of an area is a length. A number with no unit scales: @code{(* 2 g)} is still an acceleration.
@codeblock[#:lang "bjolang"]|{
(+ (.distance leg) (.climb leg)) ;; a length: 38243.84 m
(+ (.distance leg) (.speed leg)) ;; a type error: a length and a speed
(* <2 m> <3 m>) ;; 6 m^2
(sqrt (* <2 m> <8 m>)) ;; 4 m
}|
A plain number has no unit, so it cannot be compared with a length. The error says what to write instead. Zero is the exception: it is a number of every unit, so @code{(> (.climb leg) 0)} works.
@codeblock[#:lang "text"]|{
Type Error at trip.bjo:9:22: '1' is a plain number, and it is being used where a
(double m) is wanted. Write <1 m>, or a unit of the same dimension.
}|
A function that works at any unit says so with a unit variable, written as a type variable is:
@codeblock[#:lang "bjolang"]|{
(: larger (-> (double %u) (double %u) (double %u)))
(defun (larger a b) (if (> a b) a b))
(larger <1 km> <900 m>) ;; 1000 m: lengths are kept in metres
(larger <3 s> <2 s>) ;; 3 s
(: rms (-> (double %u) (double %u) (double %u)))
(defun (rms a b) (sqrt (/ (+ (sqr a) (sqr b)) 2.0))) ;; sqr: %u to %u^2
}|
@code{(num %c %u)} is a number of any type at any unit, for a function that is generic in both. A function that is generic over @code{Num} does not take a number with a unit, because @code{Num} allows multiplication and its type promises that the unit stays: @code{(sqr x)} on metres is square metres. @code{abs}, @code{min}, @code{max}, @code{clamp}, @code{sign}, @code{zero?}, @code{sqr} and @code{positive?} take any unit. @code{summing} does not yet.
@subsubsection{Getting the number out}
@code{(number-in x unit)} is the number @code{x} is in a unit, as a plain number: what a quantity is when it is printed, written to a file or given to .NET. The unit must have @code{x}'s dimension. The other way, a plain number gets a unit by multiplication:
@codeblock[#:lang "bjolang"]|{
(number-in (hours leg) h) ;; 1.574: the leg takes an hour and a half
(number-in (.distance leg) km) ;; 38.0
(number-in <45 deg> rad) ;; 0.785…
(* 2.5 <1 km>) ;; a length: 2500 m
(number-in (.distance leg) s) ;; a type error: a length, not a time
}|
@code{number-in} is one multiplication by a constant, and none when the unit is the base. @code{cast} also takes the unit off, but it does not convert: it is right only for a number already in the base unit.
@subsubsection{Dimensions and units of your own}
Nothing about SI is built into the compiler. @code{(std units)} is a module of declarations, and a program can make its own the same way, with or without it:
@codeblock[#:lang "bjolang"]|{
(def/dimension money #:base cent #:carrier long)
(def/unit EUR <100 cent>)
(def/prefix k 1000)
(: price (long cent))
(def price <12.50 EUR>) ;; 1250L
(number-in price EUR) ;; a compile error: it would divide a long by 100
}|
@read-list{
- @code{(def/dimension name #:base unit)} declares a dimension and its base unit. @code{#:carrier} says which number type its quantities are when nothing else says: @code{double} when it is left out. A type can always say otherwise, as @code{(double cent)} does.
- @code{(def/unit name quantity)} declares a unit as an amount of units already declared: @code{(def/unit mi <5280 ft>)}, @code{(def/unit N <1 kg m/s^2>)}. A unit with no dimension is a plain number: @code{(def/unit % <1|100>)}.
- @code{(def/prefix name number)} declares a prefix that goes on every unit.
}
Units belong to the module that declares them and to the modules that import it. Two modules that each declare an @code{m} have two different units, as two types called @code{Point} are two types.
A literal at an integer type has to come out whole: @code{<0.001 EUR>} at a @code{(long cent)} is a compile error, and so is @code{number-in} to a coarser unit, which would divide. At @code{rational} every conversion is exact, so a program that must not round declares its dimensions with @code{#:carrier rational}: there, @code{<1 km/h>} is exactly 5/18 metres per second, and back in kilometres per hour it is exactly 1.
The module reference for @link["modules/std/units.html"]{@code{(std units)}} lists the units it declares, and has a library for units at run time, for a unit that is read as text.