Units & quantities

Unit expressions, conversions, R84 quantity arithmetic, strict phrase patterns, cooking densities and custom units.

Main branch reference after R89 · released versions may differ docs/SYNTAX_REFERENCE.md @ 1ebc752

Units turn Numlex into a dimension-aware calculator: 5 m is metres while 5m is five million, 1 km + 500 m is 1.5 km, and 10 km in 45 min is a pace. Everything here is strict — phrase tracks either own a line completely or the line never enters them.

This page documents quantity syntax, unit expressions and their exclusions, case sensitivity, SI prefixes, the R84 quantity-arithmetic table, every strict phrase pattern, the 21-row cooking-density table, and how custom units extend the catalog.

The space matters

A quantity is <number> <unit> — the space is mandatory:

5 m — five metres.
5m — five million (a scalar; see compact suffixes).
2 Gb — two gigabits; 2 Gbyte — two gigabytes.

A glued letter is not a unit.

Unit expressions

Units combine with *, · and /, and take powers with ^, ² or ³ (the base of a power is a letter, e.g. m², m³):

km/h      kg/m³      N·m      m/s²

Restrictions:

Composition is linear only: powers cannot build arbitrary new dimensions — compound forms are limited to ^2, ^3, and fractions or products of catalog atoms.
Temperatures, currencies and fuel units are special: they participate standalone only and never enter compound expressions (C°/h is an error).
Conversion to|in|as <unit>: the right side is the target unit, the left side is the quantity, and the dimension signatures must match — 10 km in m = 10,000 m, while 10 km in kg is an error.
Temperatures convert with affine formulas, not a scale factor: 100 C° to F° = 212 F°.
Fuel units are the L/100km / L/km family and their inverse (km-per-litre-style) forms.

Case sensitivity

Input aliases keep their case:

MB (megabytes) and Mb (megabits) are different units.
mb is neither — after case folding it is ambiguous, so it is deterministically an unknown unit.
A unit’s display label is also accepted as input: 10 meters = 10 m.

SI prefixes

The allowed prefix glyphs are p n µ m c d k K M G T P — from 10⁻¹² (pico) to 10¹⁵ (peta). Every catalog atom declares which prefixes it accepts (the app lists them in the SI prefixes column, and the Unit catalog reproduces that column). Note that µ is the Greek mu (U+00B5 or U+03BC), not a Latin u.

Generated — i.e. not separately listed — forms:

plural atom forms (meters = meter),
prefixed forms (km, mm, kWh …), built by the rule prefix from the atom’s list + atom.

Combinations that the catalog does not declare are not prefixes: the letter is simply struck out as an unknown word and the number returns without a unit — 3 Pm → 3, 100 um → 100.

Quantity arithmetic (R84)

Quantity lines use a strict language: quantities, plain numbers, named values, the operators + - * / ^ × ÷ of ( ), and the suffix to|in|as <unit>. A line is either entirely in this language — a shape hit, which makes errors visible — or the language does not claim it at all (it falls through to money, dates or prose).

Operation	Rule	Example
`+` `−`	same dimension; a “plain” side accepts the other side’s unit	`300 + 20 km` = 320 km; `1 km + 500 m` = 1.5 km
`×` `/`	dimension composition; currencies and temperatures are rejected	`90 km / 3 day` = 30 km/day
`^`	power (subject to the compound-form restrictions)	`10 m × 2 m` = 20 m²
Display	the result is shown in the coarser operand unit (larger base coefficient); on a tie, the left one	`1 km + 500 m` → km

Named quantities and tokens work naturally: declare distance = 10 km and later ask distance in m. Temperatures, currencies and fuel remain standalone — they never participate in compound expressions.

Strict phrase patterns (R84)

Pattern	Example	Meaning
`<qtyA> in <qtyB>`	`10 km in 45 min`	speed / pace / rate: A ÷ B → `0.2222 km/min`
	`45 min in 10 km`	pace → `4.5 min/km`
	`1 Gbit in 5 s`	transfer rate → `0.2 Gbit/s`
`<qty> at <money> per <unit>`	`2.5 kg at €3 per kg`	price: qty/unit × price → `€7.50`
`per <unit>` (inside the algebra)	`90 km per 3 day`	30 km/day (a mixed-stage operator)
PPI (both directions)	`10 in in px at 96 ppi`	960 px; `960 px at 96 ppi to in` = 10 in (1 in = 0.0254 m exactly)
Cooking densities	`200 g of flour to ml`	mass → volume through the `CookingDensities` table (≈)
	`1 cup of honey to g`	volume → mass (≈)
	`1 L of oil as kg`	opposite-kind targets work with `in` / `as` / `to`

Every phrase track owns the line it matches: an error is visible, never a “word-strip fallback”.

Cooking densities (21 entries, version `r84-1`)

Approximate packing densities that reproduce standard US baking-cup tables. The values are pinned by the version string — a future recalibration is a visible change, never quiet drift. Input is lowercase and ignores spaces and hyphens (brown sugar = brown-sugar = brownsugar).

Input name	Label	kg/m³	Note
water	water	1000	1 cup ≈ 237 g
flour	all-purpose flour	528.3	1 cup ≈ 125 g (spooned, leveled)
sugar	granulated sugar	845.4	1 cup ≈ 200 g
brownsugar	brown sugar (packed)	930.3	1 cup ≈ 220 g
icingsugar	powdered sugar	507.2	1 cup ≈ 120 g
salt	table salt	1153.9	1 cup ≈ 273 g
butter	butter	959.4	1 cup ≈ 227 g
honey	honey	1437.1	1 cup ≈ 340 g
milk	whole milk	1031.3	1 cup ≈ 244 g
oil	vegetable oil	921.4	1 cup ≈ 218 g
rice	white rice (dry)	782.0	1 cup ≈ 185 g uncooked
cornstarch	cornstarch	541.0	1 cup ≈ 128 g
oats	rolled oats (dry)	338.2	1 cup ≈ 80 g
cocoa	cocoa powder (sifted)	359.3	1 cup ≈ 85 g
chocolate	chocolate chips	718.5	1 cup ≈ 170 g
peanutbutter	peanut butter	1090.5	1 cup ≈ 258 g
creamcheese	cream cheese	976.4	1 cup ≈ 231 g
yogurt	plain yogurt	1035.6	1 cup ≈ 245 g
applesauce	applesauce	1031.3	1 cup ≈ 244 g
cornmeal	cornmeal	613.1	1 cup ≈ 145 g
yeast	dry yeast	450	1 cup ≈ 107 g (very light)

Custom units

Custom units are defined in Settings → Units and extend the catalog beyond the 237 built-in entries:

Name: 1–6 ASCII words, ≤ 40 characters, the first word starting with a letter; must be unique (a collision with the catalog or another custom unit is rejected).
Definition: either <number> <existing unit expression> (for example 2.54 cm) or the literal new unit, which declares a new independent atom.
Dependencies resolve in declaration order and outside it; a cycle is an error. The global limit is 100 custom units.
Custom units are app-global (application settings) and are not saved in a .nlx sheet.
The plural of the name is accepted automatically, like catalog atoms.

The full grammar and the constants system live in Custom units & constants.

Verified examples

10 km to m                → 10 000 m
300 + 20 km               → 320 km
90 km / 3 day             → 30 km/day
10 km in 45 min           → 0.2222 km/min
45 min in 10 km           → 4.5 min/km
1 Gbit in 5 s             → 0.2 Gbit/s
2.5 kg at €3 per kg       → €7.50
90 km per 3 day           → 30 km/day
10 in in px at 96 ppi     → 960 px
200 g of flour to ml      → 378.6 ml (≈)
1 cup of honey to g       → 340 g (≈)

Unit catalog — all 237 non-currency units with aliases, prefixes and dimensions.
Custom units & constants — the settings side of units.
Live data & geography — distances computed on the Earth’s surface.