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{int} | about ±2.1 billion | @code{double} | 64-bit floating point |
| @code{bigint} | any integer | @code{float} | 32-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{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. A @code{char} is not a number: it can be compared and converted, but not added.
@subsubsection{Writing numbers} @subsubsection{Writing numbers}
@ -2642,7 +2653,7 @@ If a function only compares values, use @code{(where (Ord %a))} instead. It work
@codeblock[#:lang "bjolang"]|{ @codeblock[#:lang "bjolang"]|{
(import (std maths)) (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 (pow 2.0 10.0) ;; 1024.0
(floor -2.5) ;; -3.0 (floor -2.5) ;; -3.0
(truncate -2.5) ;; -2.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. 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.

View file

@ -12,6 +12,11 @@ For more details, see @link["modules/std/prelude.html"]{@code{(std prelude)}}.
Numbers beyond the operators. Integer division has Racket's names: @code{quotient} and @code{remainder} are what @code{/} and @code{%} do, and @code{modulo} takes the sign of the divisor, so @code{(modulo -1 10)} is 9. There are @code{gcd}, @code{lcm}, an integer @code{expt} and an exact @code{integer-sqrt} at every integer type, the @code{exact-} roundings from a double to an int, and the rest of @code{System.Math} over doubles. The prelude has @code{abs}, @code{min}, @code{max} and @code{clamp} from here without an import. Numbers beyond the operators. Integer division has Racket's names: @code{quotient} and @code{remainder} are what @code{/} and @code{%} do, and @code{modulo} takes the sign of the divisor, so @code{(modulo -1 10)} is 9. There are @code{gcd}, @code{lcm}, an integer @code{expt} and an exact @code{integer-sqrt} at every integer type, the @code{exact-} roundings from a double to an int, and the rest of @code{System.Math} over doubles. The prelude has @code{abs}, @code{min}, @code{max} and @code{clamp} from here without an import.
For more details, see @link["modules/std/maths.html"]{@code{(std maths)}}. For more details, see @link["modules/std/maths.html"]{@code{(std maths)}}.
@subsection{std/units and std/rational}
Units of measure, and exact fractions. @code{(std units)} declares SI for the units in types and quantity literals that "Language basics" describes: the eight base dimensions, the SI and binary prefixes, and about 270 units from @code{in} and @code{mi} to @code{eV}, @code{Sv} and @code{rpm}. The constants @code{c}, @code{gn} and @code{planck} are units too, so @code{(number-in v c)} is a speed as a fraction of light's. It is also a library for units at run time, when a unit comes as text, as in a calculator: @code{(convert-query "6000 m + 50 ft in mi")} gives @code{(Ok "3.737697 mi")}, and a @code{Measurement} is a number with a dimension that is checked when the program runs. Absolute temperatures are the types @code{Celsius} and @code{Fahrenheit} rather than units, and the decibels are functions. @code{(std rational)} has the operations of the built-in @code{rational} by name, the roundings to a @code{bigint}, and conversions to and from text, rounded once to a @code{double} or a @code{decimal}.
For more details, see @link["modules/std/units.html"]{@code{(std units)}} and @link["modules/std/rational.html"]{@code{(std rational)}}.
@subsection{std/array and std/simd} @subsection{std/array and std/simd}
Two modules for numbers in bulk, with the CPU's vector instructions. @code{(std array)} has whole-array operations: @code{array-sum}, @code{array-dot}, @code{array-min}, @code{array-max}, @code{array-add!}, @code{array-scale!}, @code{array-count}, @code{array-index-of} and @code{array-fill!}. Each is one loop in the runtime, which works on as many elements per instruction as a vector register holds when the element is a primitive number, and one at a time for a type such as @code{bigint}. At @code{double}, a sum adds lane by lane, so its last bits can differ from a left fold. @code{(std simd)} has the vectors themselves, for the loops that the kernels do not cover. @code{(Simd128 %a)} and @code{(Simd256 %a)} are .NET's @code{Vector128<T>} and @code{Vector256<T>}, with a name per element type: @code{Float64x4} is four doubles, @code{UInt8x32} is 32 bytes. The operations are the methods of one trait, @code{Simd}, at both widths: @code{simd-add}, @code{simd-mul}, the comparisons @code{simd-lt} and the others, which give masks, @code{simd-select}, @code{simd-count-true}, @code{simd-sum} and more. A vector is made with @code{simd256-load}, @code{simd128-splat} or @code{simd256-zero}, and @code{simd256-whole} says where the elements after the last whole vector start. A 128-bit vector is fast on every x86-64 and ARM64 CPU. A 256-bit vector needs AVX2, and @code{simd256-accelerated?} says whether the CPU has it. The section on performance in "Writing programs" says when vectors pay. Two modules for numbers in bulk, with the CPU's vector instructions. @code{(std array)} has whole-array operations: @code{array-sum}, @code{array-dot}, @code{array-min}, @code{array-max}, @code{array-add!}, @code{array-scale!}, @code{array-count}, @code{array-index-of} and @code{array-fill!}. Each is one loop in the runtime, which works on as many elements per instruction as a vector register holds when the element is a primitive number, and one at a time for a type such as @code{bigint}. At @code{double}, a sum adds lane by lane, so its last bits can differ from a left fold. @code{(std simd)} has the vectors themselves, for the loops that the kernels do not cover. @code{(Simd128 %a)} and @code{(Simd256 %a)} are .NET's @code{Vector128<T>} and @code{Vector256<T>}, with a name per element type: @code{Float64x4} is four doubles, @code{UInt8x32} is 32 bytes. The operations are the methods of one trait, @code{Simd}, at both widths: @code{simd-add}, @code{simd-mul}, the comparisons @code{simd-lt} and the others, which give masks, @code{simd-select}, @code{simd-count-true}, @code{simd-sum} and more. A vector is made with @code{simd256-load}, @code{simd128-splat} or @code{simd256-zero}, and @code{simd256-whole} says where the elements after the last whole vector start. A 128-bit vector is fast on every x86-64 and ARM64 CPU. A 256-bit vector needs AVX2, and @code{simd256-accelerated?} says whether the CPU has it. The section on performance in "Writing programs" says when vectors pay.

3
modules/std/rational.sz Normal file
View file

@ -0,0 +1,3 @@
(meta (title "(std rational)"))
@generate-docs[#:module "std rational"]

3
modules/std/units.sz Normal file
View file

@ -0,0 +1,3 @@
(meta (title "(std units)"))
@generate-docs[#:module "std units"]