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

@ -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.
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}
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.