17 Numbers with Units
A number in firmware is almost always a measurement of something: a delay in milliseconds, a supply in volts, a speed in revolutions per minute. In most languages the unit lives only in a comment or in the programmer’s head, and mixing two of them up is a classic bug: a delay of 500 meant as milliseconds and read as microseconds, or millivolts added to volts. In Zeno a number can carry its unit, and the unit is checked.
17.1 Writing a quantity
A number followed by a unit is a quantity:
let wait = 500 ms
let supply = 3.3 V
let speed = 1200 rpm
print(wait, supply, speed)500 ms 3.3 V 1200 rpm
The units come from a fixed list:
| Measures | Units |
|---|---|
| time | ns us ms s min h |
| frequency | Hz kHz MHz |
| voltage | uV mV V kV |
| current | uA mA A |
| resistance | ohm kohm Mohm |
| power | mW W kW |
| energy | J Wh kWh |
| temperature | degC, and K
apart from it |
| length | mm cm m km |
| mass | mg g kg |
| angle | deg, and rad
apart from it |
| rotation | rpm |
A word that is not on the list is refused, with some that are:
let wait = 5 secerror: `sec` is not a unit Zeno knows. Some that it does: s, ms, us, Hz, V, mV, A, mA, W, degC
--> main.zeno:1:12
|
1 | let wait = 5 sec
| ^
1 error found. Nothing was run.
If any word after a number were a unit, a typing slip would quietly make a new one, and the bug that units are there to stop would be back. (Decision 1.15.)
17.2 What a quantity can do
Quantities of the same unit add, subtract and compare as numbers do. A quantity times or divided by a plain number keeps its unit, and one quantity divided by another of the same kind is a plain number, how many times the one goes into the other:
let wait = 500 ms
print(wait + 250 ms, wait * 2, wait / 4, wait > 100 ms)
print(wait / 1 ms, 3.3 V / 1 mV)750 ms 1000 ms 125 ms true
500.0 3300.0
Dividing by one of a unit, as in wait / 1 ms, is how a
program takes the unit off and keeps the bare number, saying which unit
the number is in.
Quantities of different kinds never meet. Volts do not add to seconds, and a bare number does not add to either:
let total = 1 s + 3 Verror: `+` does not work between a quantity in s and a quantity in V
--> main.zeno:1:13
|
1 | let total = 1 s + 3 V
| ^
1 error found. Nothing was run.
let supply = 3.3 V
print(supply + 2)error: `+` does not work between a quantity in V and int
--> main.zeno:2:7
|
2 | print(supply + 2)
| ^
1 error found. Nothing was run.
17.3 Units of one kind work together
Units that measure the same thing combine, and the answer is in the finer of the two:
print(1 s + 500 ms, 1 s == 1000 ms, 1 h / 1 min, 1 kWh == 3600000 J)1500 ms true 60.0 true
Going from seconds to milliseconds multiplies by a whole number, which loses nothing. Going the other way divides, and a millisecond is not exactly a number of seconds in binary. So the direction that is always exact is the one taken without being asked. (Decision 1.15.)
Changing unit
A quantity is given in another unit of its kind with a dot and the unit’s name. It reads as "delay, in seconds":
let delay = 1500 ms
print(delay.s, (3 s).ms, (3300 mV).V)1.5 s 3000 ms 3.3 V
17.4 A unit is a type
The name of a unit is also a type. A parameter of type
ms takes a quantity in milliseconds, and nothing else:
function pause(length: ms) {
print("pausing for", length)
}
pause(250 ms)
pause((2 s).ms)pausing for 250 ms
pausing for 2000 ms
function pause(length: ms) {
print("pausing for", length)
}
pause(2 s)
pause(250)error: `length` of `pause` should be a quantity in ms, but this is a quantity in s. Convert it with `.ms`
--> main.zeno:4:7
|
4 | pause(2 s)
| ^
error: `length` of `pause` should be a quantity in ms, but this is int
--> main.zeno:5:7
|
5 | pause(250)
| ^
2 errors found. Nothing was run.
Passing 2 s where ms is wanted is refused,
and the message says to write .ms.
Converting by itself at a call was tried on paper and turned down.
zeno run would show 2 s where a compiled
program, which knows that the parameter is ms, would show
2000 ms: one program, two outputs. Writing .ms
means the same in both. (Decision 1.15.)
17.5 Time
The time module works in quantities. sleep
takes a time with its unit, and now() gives the time in
ms since a fixed moment:
from time import sleep, now
let start = now()
sleep(20 ms)
let took = now() - start
print(took >= 20 ms)true
sleep(500) is refused. Whether a bare 500 is seconds or
milliseconds is the question every delay function in every C library
answers differently, and here the program text answers it.
now() counts from a moment the program cannot know, such
as the moment a board was switched on, so only the difference of two
readings means anything.
17.6 What does not convert
Degrees Celsius and kelvin differ by an offset, not by a scale, so adding one to the other means nothing, and Zeno refuses it:
print(20 degC + 1 K)error: `+` does not work between a quantity in degC and a quantity in K
--> main.zeno:1:7
|
1 | print(20 degC + 1 K)
| ^
1 error found. Nothing was run.
Degrees and radians of angle have no exact factor between them, so
they too never meet by themselves. A program changes one to the other
when it asks, with .rad and .deg:
let half_turn = 180.0 deg
print(half_turn.rad, (half_turn.rad).deg)3.141592653589793 rad 180 deg
The angle functions of the math module take and give
angles with their units (Mathematics).
17.7 Showing a quantity
A quantity is shown with its unit after a space. A format applies to the number, and the unit stays:
let supply = 3.3 V
let angle = 30.456 deg
print(f"[{supply:8.2f}] [{angle:.1f}]")[ 3.30 V] [30.5 deg]
The width counts the unit too, so a column of quantities lines up on the right, as numbers do.
17.8 What units leave out
In version 0.1 there are no derived units: V * A is not
W, and quantities of two kinds cannot be multiplied. A
program that needs power works it out from the bare numbers and puts the
unit back:
let volts = 12.0 V
let amps = 2.0 A
let power = (volts / 1 V) * (amps / 1 A) * 1 W
print(power)24 W
There are no units of a program’s own either, and sum,
min and max take plain numbers. Both are on
the list in Appendix G.
A number followed by a unit from Zeno’s list is a quantity.
Quantities of one kind combine, in the finer unit, and never mix with
another kind or with bare numbers. .ms and its like change
unit; dividing by 1 ms gives the bare number. A unit’s name
is a type. sleep and now work in quantities. A
format applies to the number, and the unit is always shown.
Write
function blink_period(rate: Hz) -> ms. What is the bare number you have to work with, and where does the unit go back?Add
250 usto1 msand print the answer. Then print it in microseconds and in seconds.Try
sleep(3 V)and read the message.Write a voltage divider: given a supply and two resistances in
kohm, give the output voltage as a quantity inV.