The Zeno Book Zeno 0.1 zeno-lang.org

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 sec
error: `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 V
error: `+` 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.

  1. Write function blink_period(rate: Hz) -> ms. What is the bare number you have to work with, and where does the unit go back?

  2. Add 250 us to 1 ms and print the answer. Then print it in microseconds and in seconds.

  3. Try sleep(3 V) and read the message.

  4. Write a voltage divider: given a supply and two resistances in kohm, give the output voltage as a quantity in V.