Unit arithmetic

Package: UOM_PACKAGE. Registered by createEngine(); for a slimmer engine, register it explicitly (see choosing packages).

A unit is the thing a number is measured in: metres, kilograms, hours. Solve lets you write a quantity the way you would say it, and add or subtract two quantities even when they are written in different units of the same kind.

Units are case-sensitive and are never remapped, which is deliberate. m is metres and M is the millions suffix, and guessing between them would produce confidently wrong answers.

Most units have more than one spelling, and all of them work: lb, lbs and pounds are the same unit, as are m, metre and metres. What you will not get is a guess, so a spelling that is not a unit stays an error rather than being resolved to the nearest thing that looks similar. The error does name the nearest real spellings, though, so a typo is one glance from fixed:

20 kilomters in miles // ERROR: Undefined variable: kilomters. Did you mean kilometers?
5 km in mies // ERROR: "mies" is not a unit. Did you mean miles?

The same goes for a mistyped function or variable name, which is checked against the functions the engine knows and the names defined earlier in the note. When two or three names are equally close, all of them are listed.

A plain number is given a unit the same way a quantity is converted, with in: 5 in km is five kilometres. The word after in has to be a unit, a currency or the name of a converter, so a number is never labelled with a word that is none of those. A converter’s name reads as the converter, as it does after as, so 2024 in roman is the Roman numeral.

5 in km // 5.00 km
5 in EUR // €5.00
5 in widgets // ERROR: "widgets" is not a unit.
2024 in roman // MMXXIV

Every spelling the engine accepts is listed on the unit reference page, which is generated by running each one through a real engine rather than by transcribing a table.

The left operand decides the result unit.

100cm + 2m // 300.00 cm
1 km + 500 m // 1.50 km

Multiplying and dividing

Adding needs two quantities of the same kind. Multiplying and dividing combine kinds instead: a length times a length is an area, and a price per kilogram times a number of kilograms is an amount of money. Those rules, and the products that have no unit at all, are on their own page, multiplying and dividing units.

5 m * 3 m // 15.00 m²
3 kg * $5/kg // $15.00

A power on a unit is the unit’s own, so 5 m^2 is five square metres. Only a length has a square or a cube with a unit, so a power written on any other unit is refused rather than answered with the bare number. Acceleration in metres per second squared, m/s^2, is a unit in its own right, and so is m/s², the way the engine writes it back; see derived units.

9.81 m/s² // 9.81 m/s²
10 kg * 9.81 m/s² // 98.10 N

5 kg^2 // ERROR: "kg^2" is not a unit: a power on a unit makes an area or a volume, so it applies only to a length the unit table spells squared or cubed, such as m^2 or ft^3.

A unit after a power of ten

Scientific notation puts the unit after the power: 1.5 * 10^3 kg is 1,500 kilograms. The unit belongs to the whole power, not to the exponent, so 10^3 m is a thousand metres and 10^-3 m a millimetre. A power’s exponent is a count and never has a unit, so one written with a unit inside brackets is refused.

10^3 m in km // 1.00 km
1.5 * 10^3 kg // 1,500.00 kg
10^-3 m in mm // 1.00 mm

Two units side by side

A quantity takes one unit. A second unit written straight after the first, as in 5 kg m, names nothing the engine knows (kilogram-metres is not in its table), so it is refused rather than relabelling the five kilograms as five metres. To change a quantity’s unit, convert it with in. Compound units such as km/h and m/s^2 are written with a slash and read as one unit.

5 kg m // ERROR: A quantity in kg cannot take a second unit, m: two units side by side are not a unit. To convert, write "in m".
2^(3 m) // ERROR: An exponent cannot carry a unit (m): a power counts multiplications. For a quantity in scientific notation, write the unit after the power, as in "10^3 m".