# Units

> Reference for the unit registry and the @recipe-book/core functions that look up units, convert quantities and temperatures, and find temperatures, durations, and quantities in step text.

Source: https://recipe-book.siraj.page/reference/core/units/

Use these exports from `@recipe-book/core` to look up units, convert quantities between units and measurement systems, convert temperatures, and find temperatures, durations, and quantities in step text. For a walkthrough, see [Convert units](https://recipe-book.siraj.page/guides/convert-units.md). In a React app, replace `@recipe-book/core` with `@recipe-book/react/core` in this page's imports.

## `convert`

```ts
function convert<A extends Amount, To extends UnitId>(
  quantity: Quantity & { amount: A },
  to: To,
): { amount: SameAmount<A>; unit: To }
```

Converts a quantity to another unit of the same dimension: mass to mass, or volume to volume.

| Name       | Type                                                                                            | Default  | Description                                                                                         |
| ---------- | ----------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `quantity` | [`Quantity`](https://recipe-book.siraj.page/reference/core/units.md#quantity)` & { amount: A }` | Required | The quantity to convert. It needs a `unit`; a quantity without one is a bare count.                 |
| `to`       | `To`                                                                                            | Required | The unit to convert to. It must measure the same dimension as `quantity.unit`, or be the same unit. |

Returns a new quantity in the `to` unit. Nothing is rounded, so the amount can be off in its last digit: 5 tbsp is 14.999999999999998 tsp. To show it, pass it to [`formatQuantity`](https://recipe-book.siraj.page/reference/core/formatting.md#formatquantity), which writes 15 tsp.

```ts
import { convert } from '@recipe-book/core'

convert({ amount: 1.25, unit: 'cup' }, 'ml') // { amount: 295.735295625, unit: 'ml' }
convert({ amount: { min: 2, max: 3 }, unit: 'tbsp' }, 'tsp') // { amount: { min: 6, max: 9 }, unit: 'tsp' }
```

Throws a [`RecipeBookError`](https://recipe-book.siraj.page/reference/core/errors.md#recipebookerror) with one of these codes:

- [`incompatible_units`](https://recipe-book.siraj.page/errors/incompatible_units.md) when the units measure different dimensions, such as cups to grams; when either unit is a count unit such as `clove` and the units differ; or when the quantity has no unit
- [`unknown_unit`](https://recipe-book.siraj.page/errors/unknown_unit.md) when `to` or `quantity.unit` isn't a unit ID, such as `'cups'`
- [`invalid_argument`](https://recipe-book.siraj.page/errors/invalid_argument.md) when `quantity` isn't a quantity object, when the amount isn't a finite number greater than 0 or a range of them, when a range's `min` is greater than its `max`, when `quantity` has a `max`, as a [`Servings`](https://recipe-book.siraj.page/reference/core/types.md#servings) or [`Yield`](https://recipe-book.siraj.page/reference/core/types.md#yield) has, or when the result overflows to `Infinity`, or when the result underflows to 0, which only an amount above about 1e300 or below about 1e-300 can do

An error thrown by a getter or proxy in the input passes through.

A cup's weight depends on the ingredient, so `convert` can't turn cups into grams. Give the ingredient its weight as an [equivalent](https://recipe-book.siraj.page/guides/author-recipes.md#add-equivalents) instead, as [Convert cups to grams](https://recipe-book.siraj.page/guides/convert-units.md#convert-cups-to-grams) shows.

When units come from data, check them with [`canConvert`](https://recipe-book.siraj.page/reference/core/units.md#canconvert) first.

## `canConvert`

```ts
function canConvert(from: UnitId | undefined, to: UnitId | undefined): boolean
```

Checks whether [`convert`](https://recipe-book.siraj.page/reference/core/units.md#convert) can convert between two units.

| Name   | Type                                                                                     | Default  | Description                                                                                                                                                    |
| ------ | ---------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from` | [`UnitId`](https://recipe-book.siraj.page/reference/core/units.md#unitid) \| `undefined` | Required | The unit to convert from. Pass `undefined` for a bare count.                                                                                                   |
| `to`   | [`UnitId`](https://recipe-book.siraj.page/reference/core/units.md#unitid) \| `undefined` | Required | The unit to convert to. `undefined`, as [`findUnit`](https://recipe-book.siraj.page/reference/core/units.md#findunit) returns for unknown text, gives `false`. |

Returns `true` when both are the same unit, or both are mass units, or both are volume units. Returns `false` otherwise, including for a bare count or a string that isn't a unit ID.

```ts
import { canConvert } from '@recipe-book/core'

canConvert('cup', 'ml') // true
canConvert('cup', 'g') // false
canConvert(undefined, 'g') // false
```

Never throws, so it's safe on data you don't control. It checks units only: `convert` can still throw [`invalid_argument`](https://recipe-book.siraj.page/errors/invalid_argument.md) for the amount.

[Convert units](https://recipe-book.siraj.page/guides/convert-units.md#check-units-from-data) uses it to check units from users or a CMS before converting them.

## `toSystem`

```ts
function toSystem<A extends Amount>(
  quantity: Quantity & { amount: A },
  system: System,
  options?: ToSystemOptions,
): { amount: SameAmount<A>; unit?: UnitId | undefined }
```

Expresses a quantity in a measurement system, choosing the unit from that system.

| Name       | Type                                                                                            | Default  | Description                                          |
| ---------- | ----------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------- |
| `quantity` | [`Quantity`](https://recipe-book.siraj.page/reference/core/units.md#quantity)` & { amount: A }` | Required | The quantity to express.                             |
| `system`   | [`System`](https://recipe-book.siraj.page/reference/core/units.md#system)                       | Required | The measurement system to use: `'metric'` or `'us'`. |
| `options`  | [`ToSystemOptions`](https://recipe-book.siraj.page/reference/core/units.md#tosystemoptions)     | `{}`     | Whether to keep the converted amount exact.          |

Returns the same quantity object when its unit is already native to `system`, when it's a count unit, or when it has no unit. tsp and tbsp are native to both systems. Otherwise, returns a new quantity in a unit from the system's ladder:

| System | Dimension | Ladder, largest unit first                            |
| ------ | --------- | ----------------------------------------------------- |
| metric | mass      | `kg` from 999.5 g, then `g`                           |
| metric | volume    | `l` from 999.5 mL, then `ml`                          |
| US     | mass      | `lb` from 15.9375 oz, then `oz`                       |
| US     | volume    | `cup` from ¼ cup, then `tbsp` from 1 tbsp, then `tsp` |

For mass and metric volume, `toSystem` picks the largest unit whose threshold the quantity meets. kg, L, and lb start where the smaller unit would format the quantity as 1 of them: 999.5 g formats as 1000 g, so it's 1 kg, while 998 g stays 998 g, and 15.9375 oz formats as 16 oz, so it's 1 lb. Metric amounts and US weights aren't rounded, so they can be off in their last digit, as with [`convert`](https://recipe-book.siraj.page/reference/core/units.md#convert). To show one, pass it to [`formatQuantity`](https://recipe-book.siraj.page/reference/core/formatting.md#formatquantity), which writes the 354.88235475 mL below as 355 mL.

US volume lands on a cup or spoon measure, except a quantity or range end too small to land on ⅛ tsp, which stays exact, and a range whose ends convert to different amounts but would land on the same measure, which keeps those amounts. It takes the measure from the first of these sets of measuring cups or spoons that fits:

1. Cups, on a multiple of ¼ or ⅓ cup less than 5% from the quantity.
2. From 1 cup, cups on the nearest multiple of ⅛ or ⅓ cup, at most 1/16 cup (1 tbsp) off. In a range, an end below 1 cup lands as it would in set 1.
3. From 1 tbsp, tbsp on a multiple of ½ tbsp less than 5% from the quantity.
4. tsp, on ⅛ tsp or a multiple of ¼ tsp less than 5% from the quantity.
5. tsp, on the nearest multiple of ⅛ tsp, at most 1/16 tsp off.

So 150 mL, 10.1442… tbsp, is 10 tbsp: ⅔ cup is 5.2% off, and ⅝ cup isn't a measure below 1 cup. The smallest measure of each set is its threshold, and a quantity slightly below one lands on it when it's less than 5% off: 14.2 mL (0.96 tbsp) is 1 tbsp, but 14.05 mL (0.95 tbsp) is 2 ¾ tsp. A quantity halfway between two measures lands on the larger, as [`formatQuantity`](https://recipe-book.siraj.page/reference/core/formatting.md#formatquantity) rounds it, so 3/16 tsp is ¼ tsp and 1 1/16 cups is 1 ⅛ cups. For a range, each end lands on its own measure, and both must fit the same set, so a range never mixes units. An end below 1 cup that fits set 1 also fits set 2, so 180–270 mL is ¾–1 ⅛ cups. A range whose ends convert to different amounts but would land on the same measure keeps those amounts, so 14.8–15 mL is 1.0009–1.0144 tbsp, which `formatQuantity` writes as 1 tbsp. [`resolveRecipe`](https://recipe-book.siraj.page/reference/core/resolving.md#resolverecipe) lands the cups and spoons it scales or converts the same way. Between two scales more than 1e-9 from 1, a scaled quantity that isn't a range never goes down as the scale grows. Either end of a range can go down: by less than 2/21 (about 9.5%) when the range moves to another measure set, and by less than 5%, 1/16 cup or 1/16 tsp when its ends start or stop landing on one measure. Units off the ladders, such as `fl-oz`, `quart`, and `dl`, are never chosen.

```ts
import { toSystem } from '@recipe-book/core'

toSystem({ amount: 1.5, unit: 'cup' }, 'metric') // { amount: 354.88235475, unit: 'ml' }
toSystem({ amount: 150, unit: 'ml' }, 'us') // { amount: 10, unit: 'tbsp' }
toSystem({ amount: 3, unit: 'tbsp' }, 'metric') // { amount: 3, unit: 'tbsp' }
toSystem({ amount: 150, unit: 'ml' }, 'us', { exact: true }) // { amount: 10.1442068105529, unit: 'tbsp' }
```

With `exact: true`, US volume takes the same unit but keeps its exact amount, as [`resolveRecipe`](https://recipe-book.siraj.page/reference/core/resolving.md#resolverecipe)'s `exact` does, so 150 mL is 10.1442… tbsp, which `formatQuantity` writes as 10 ⅛ tbsp. Any other `exact`, or `options` that isn't an object, rounds as above.

Throws a [`RecipeBookError`](https://recipe-book.siraj.page/reference/core/errors.md#recipebookerror) with one of these codes:

- [`invalid_argument`](https://recipe-book.siraj.page/errors/invalid_argument.md) when `system` isn't `'metric'` or `'us'`, when `quantity` isn't a quantity object, when the amount isn't a finite number greater than 0 or a range of them, when a range's `min` is greater than its `max`, when `quantity` has a `max`, as a [`Servings`](https://recipe-book.siraj.page/reference/core/types.md#servings) or [`Yield`](https://recipe-book.siraj.page/reference/core/types.md#yield) has, or when the result or the measure it lands on overflows to `Infinity`, or when the result underflows to 0, which only an amount above about 1e300 or below about 1e-300 can do
- [`unknown_unit`](https://recipe-book.siraj.page/errors/unknown_unit.md) when `quantity.unit` isn't a unit ID

An error thrown by a getter or proxy in the input passes through.

[Convert units](https://recipe-book.siraj.page/guides/convert-units.md#convert-to-metric-or-us-units) uses it to switch a reader between systems.

## `findUnit`

```ts
function findUnit<Alias extends UnitAlias>(text: Alias): UnitIdOf<Alias>
function findUnit<Alias extends UnitAlias>(text: `${Alias}.`): UnitIdOf<Alias>
function findUnit(text: string): UnitId | undefined
```

Finds the unit that author text names, such as `'cups'` or `'T'`, and returns its ID.

| Name   | Type     | Default  | Description                                                                                                                                                                                             |
| ------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text` | `string` | Required | The text to look up. Surrounding whitespace is ignored, inner whitespace is collapsed, a period that ends a word is dropped, and case is ignored except for `'T'` (tbsp), `'t'` (tsp), and `'c'` (cup). |

Returns the unit ID, or `undefined` when the text names no unit in the [registry](https://recipe-book.siraj.page/reference/core/units.md#units). When you pass a string literal that is a [`UnitAlias`](https://recipe-book.siraj.page/reference/core/units.md#unitalias), with or without a period after it, the return type is that unit's ID: `findUnit('tablespoons')` and `findUnit('tbsp.')` have the type `'tbsp'`.

```ts
import { findUnit } from '@recipe-book/core'

findUnit('Tablespoons') // 'tbsp'
findUnit('T') // 'tbsp'
findUnit('t') // 'tsp'
findUnit('fl  oz') // 'fl-oz'
findUnit('fl. oz.') // 'fl-oz'
findUnit('c.') // 'cup'
findUnit('C') // undefined
findUnit('knob') // undefined
```

Never throws. It returns `undefined` for values that aren't strings. Uppercase `C` isn't a unit, because it usually means Celsius.

It takes no options, so `'cups'` is always `cup`. To read cups or tablespoons in text as `cup-metric` or `tbsp-au`, pass [`units`](https://recipe-book.siraj.page/reference/core/parsing.md#parsequantityoptions) to a parser such as [`parseRecipe`](https://recipe-book.siraj.page/reference/core/parsing.md#parserecipe).

[Convert units](https://recipe-book.siraj.page/guides/convert-units.md#check-units-from-data) uses it to read units from users or a CMS.

## `getUnit`

```ts
function getUnit<Id extends UnitId>(
  id: Id,
): UnitDefinition & { readonly id: Id }
```

Returns the registry entry for a unit ID.

| Name | Type | Default  | Description                                                                                                                                     |
| ---- | ---- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `Id` | Required | The unit ID, such as `'cup'`. Use [`findUnit`](https://recipe-book.siraj.page/reference/core/units.md#findunit) to turn author text into an ID. |

Returns the frozen [`UnitDefinition`](https://recipe-book.siraj.page/reference/core/units.md#unitdefinition) for the unit, the same object as `units[id]`.

```ts
import { getUnit } from '@recipe-book/core'

getUnit('cup').toBase // 236.5882365
getUnit('tbsp').systems // ['metric', 'us']
```

Throws a [`RecipeBookError`](https://recipe-book.siraj.page/reference/core/errors.md#recipebookerror) with the code [`unknown_unit`](https://recipe-book.siraj.page/errors/unknown_unit.md) when `id` isn't a unit ID. When you pass an alias such as `'cups'`, the message names the ID to use.

## `units`

```ts
const units: { readonly [Id in UnitId]: UnitDefinition & { readonly id: Id } }
```

The unit registry: every supported unit for quantities, keyed by unit ID. Temperatures aren't in it: [`convertTemperature`](https://recipe-book.siraj.page/reference/core/units.md#converttemperature) converts between `'C'` and `'F'`. The registry and every entry in it are frozen.

```ts
import { units } from '@recipe-book/core'

units.cup.toBase // 236.5882365
Object.values(units).filter((unit) => unit.dimension === 'mass').length // 5
```

The supported units for quantities by dimension, with their sizes in grams or milliliters (`toBase`):

| Dimension   | ID           | Systems       | Size (`toBase`)   |
| ----------- | ------------ | ------------- | ----------------- |
| Mass (g)    | `mg`         | metric        | 0.001 g           |
| Mass (g)    | `g`          | metric        | 1 g               |
| Mass (g)    | `kg`         | metric        | 1000 g            |
| Mass (g)    | `oz`         | US            | 28.349523125 g    |
| Mass (g)    | `lb`         | US            | 453.59237 g       |
| Volume (mL) | `ml`         | metric        | 1 mL              |
| Volume (mL) | `cl`         | metric        | 10 mL             |
| Volume (mL) | `dl`         | metric        | 100 mL            |
| Volume (mL) | `l`          | metric        | 1000 mL           |
| Volume (mL) | `tsp`        | metric and US | 4.92892159375 mL  |
| Volume (mL) | `tbsp`       | metric and US | 14.78676478125 mL |
| Volume (mL) | `tbsp-au`    | metric        | 20 mL             |
| Volume (mL) | `fl-oz`      | US            | 29.5735295625 mL  |
| Volume (mL) | `cup`        | US            | 236.5882365 mL    |
| Volume (mL) | `cup-metric` | metric        | 250 mL            |
| Volume (mL) | `pint`       | US            | 473.176473 mL     |
| Volume (mL) | `quart`      | US            | 946.352946 mL     |
| Volume (mL) | `gallon`     | US            | 3785.411784 mL    |
| Count       | `pinch`      | metric and US | None              |
| Count       | `dash`       | metric and US | None              |
| Count       | `clove`      | metric and US | None              |
| Count       | `slice`      | metric and US | None              |
| Count       | `piece`      | metric and US | None              |
| Count       | `can`        | metric and US | None              |
| Count       | `package`    | metric and US | None              |
| Count       | `stick`      | metric and US | None              |
| Count       | `sprig`      | metric and US | None              |
| Count       | `bunch`      | metric and US | None              |
| Count       | `head`       | metric and US | None              |
| Count       | `bag`        | metric and US | None              |
| Count       | `handful`    | metric and US | None              |
| Count       | `jar`        | metric and US | None              |
| Count       | `stalk`      | metric and US | None              |

The sizes are exact, and all but `cup-metric` and `tbsp-au` are from NIST Handbook 44: 1 lb is 453.59237 g, and 1 tsp is 1/768 of a US gallon of 3785.411784 mL. So cups, pints, quarts, gallons, and fluid ounces are US sizes: `cup` is about 237 mL, not a 250 mL metric cup, and a pint is about 473 mL, not a 568 mL UK pint. For a recipe written with metric cups, use `cup-metric`, described below. For UK pints, give those quantities in milliliters.

Besides a unit's ID, [`findUnit`](https://recipe-book.siraj.page/reference/core/units.md#findunit) accepts its aliases:

- `mg`: `milligram`, `milligrams`, `milligramme`, `milligrammes`
- `g`: `gm`, `gms`, `gr`, `grs`, `gram`, `grams`, `gramme`, `grammes`
- `kg`: `kgs`, `kilo`, `kilos`, `kilogram`, `kilograms`, `kilogramme`, `kilogrammes`
- `oz`: `ozs`, `ounce`, `ounces`
- `lb`: `lbs`, `pound`, `pounds`
- `ml`: `mL`, `krm`, `milliliter`, `milliliters`, `millilitre`, `millilitres`
- `cl`: `cL`, `centiliter`, `centiliters`, `centilitre`, `centilitres`
- `dl`: `dL`, `deciliter`, `deciliters`, `decilitre`, `decilitres`
- `l`: `L`, `lt`, `lts`, `ltr`, `ltrs`, `liter`, `liters`, `litre`, `litres`
- `tsp`: `t`, `tsps`, `tl`, `tsk`, `ts`, `teaspoon`, `teaspoons`
- `tbsp`: `T`, `tb`, `tbs`, `tbsps`, `el`, `msk`, `spsk`, `ss`, `tablespoon`, `tablespoons`
- `fl-oz`: `fl oz`, `fluid ounce`, `fluid ounces`
- `cup`: `cups`, `c`
- `pint`: `pt`, `pts`, `pints`
- `quart`: `qt`, `qts`, `quarts`
- `gallon`: `gal`, `gals`, `gallons`
- `pinch`: `pinches`, `nypa`, `prise`, `prisen`
- `dash`: `dashes`
- `clove`: `cloves`
- `slice`: `slices`
- `piece`: `pieces`, `pc`, `pcs`, `unit`, `units`, `pièce`, `pièces`, `stk`, `stück`
- `can`: `cans`
- `package`: `packages`, `pkg`, `pkgs`
- `stick`: `sticks`
- `sprig`: `sprigs`
- `bunch`: `bunches`, `bund`
- `head`: `heads`
- `bag`: `bags`
- `handful`: `handfuls`
- `jar`: `jars`
- `stalk`: `stalks`

`el` and `tl` are the tablespoon and teaspoon as German recipes write them, `EL` and `TL`, and Dutch ones, `el` and `tl`. `tsk` is the teaspoon as Swedish and Danish recipes write it, and the tablespoon is `msk` in Swedish recipes and `spsk` in Danish ones.

`ss` and `ts` are the tablespoon and teaspoon as Norwegian recipes write them, and `krm`, the Swedish kryddmått, is a milliliter. `stk`, as Norwegian and Danish recipes write it, and the German `Stück` are a piece, the Swedish `nypa` and the German `Prise` and `Prisen` are a pinch, and the German `Bund` is a bunch. The Swedish `st` isn't read as a piece, since it would read the St. in `'3 St. Germain liqueur'`.

`cup-metric` is the 250 mL cup of Australia, New Zealand, Canada, and South Africa, and `tbsp-au` the 20 mL Australian tablespoon. They have no aliases besides their IDs, so text such as `'2 cups'` names them only through the parsers' [`units`](https://recipe-book.siraj.page/reference/core/parsing.md#parsequantityoptions) option, which reads every cup or tablespoon as one of them. They show the labels cup and tbsp, and round to fractions like US units.

> **Caution**
>
> `oz` is an ounce of mass. Fluid ounces are `fl-oz`, which [`findUnit`](https://recipe-book.siraj.page/reference/core/units.md#findunit) finds from `fl oz` or `fluid ounces`. `gr` and `grs` are grams: grains, also written `gr`, aren't a supported unit.

## `convertTemperature`

```ts
function convertTemperature(
  temperature: Temperature,
  to: TemperatureUnit,
): Temperature
```

Converts a temperature between Celsius and Fahrenheit.

| Name          | Type                                                                                        | Default  | Description                             |
| ------------- | ------------------------------------------------------------------------------------------- | -------- | --------------------------------------- |
| `temperature` | [`Temperature`](https://recipe-book.siraj.page/reference/core/units.md#temperature)         | Required | The temperature to convert.             |
| `to`          | [`TemperatureUnit`](https://recipe-book.siraj.page/reference/core/units.md#temperatureunit) | Required | The unit to convert to: `'C'` or `'F'`. |

Returns a new temperature in the `to` unit. Nothing is rounded, so the value can be off in its last digits: −18 °C is −0.3999999999999986 °F.

```ts
import { convertTemperature } from '@recipe-book/core'

convertTemperature({ value: 180, unit: 'C' }, 'F') // { value: 356, unit: 'F' }
convertTemperature({ value: 350, unit: 'F' }, 'C') // { value: 176.66666666666666, unit: 'C' }
```

Throws a [`RecipeBookError`](https://recipe-book.siraj.page/reference/core/errors.md#recipebookerror) with the code [`invalid_argument`](https://recipe-book.siraj.page/errors/invalid_argument.md) when the value isn't a finite number, when either unit isn't `'C'` or `'F'`, or when a value beyond about ±2e307 °C is converted to °F or one beyond about ±3.6e307 °F is converted to °C, where the arithmetic overflows to `Infinity` or `-Infinity` even when the result itself would be finite. An error thrown by a getter or proxy in the input passes through.

[Convert units](https://recipe-book.siraj.page/guides/convert-units.md#convert-temperatures) shows it, and [Display quantities](https://recipe-book.siraj.page/guides/display-quantities.md#format-oven-temperatures) rounds its result to an oven temperature a recipe would print, such as 180 °C.

## `segmentStepText`

```ts
function segmentStepText(
  text: string,
  options?: SegmentStepTextOptions,
): StepSegment[]
```

Splits step text into plain text and the temperatures and durations written in it.

| Name      | Type                                                                                                      | Default  | Description                                                                                                                                                                                            |
| --------- | --------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `text`    | `string`                                                                                                  | Required | The step text, such as a [`Step`](https://recipe-book.siraj.page/reference/core/types.md#step)'s `text`.                                                                                               |
| `options` | [`SegmentStepTextOptions`](https://recipe-book.siraj.page/reference/core/units.md#segmentsteptextoptions) | None     | Set `assumeTemperatureUnit` to read temperatures written with a degree sign or "degree" or "degrees" but no unit, as in `Bake at 350°.`, or `inferTemperatureUnit` to read those of 275 or more as °F. |

Returns the [segments](https://recipe-book.siraj.page/reference/core/units.md#stepsegment) in order. Joining every segment's `text` gives back `text` exactly.

A temperature is a number followed by a unit, a degree sign and a unit, or "degree" or "degrees" and a unit: `350°F`, `180 °C`, `180C`, `200℃`, `350 degrees F`, or `350 degrees Fahrenheit`. A minus sign, written `-`, `−`, or `–`, makes it negative at the start of the text, after a space or an opening parenthesis, or right after `~`, `/`, `−`, `⸺`, `﹣`, `－`, or a dash other than `-`, as in `Freeze at -18°C.` and `Freeze at -18°C–-20°C.`, which has two readings. `--` is a typed dash, so `Preheat the oven--350°F.` reads 350 °F. A `-` or `–` right after a number with no unit of its own, or with only a degree sign, as in `350 -375°F` and `350° -375°F`, is a dash that joins a range's ends instead, and so is a `−` between two digits, as in `350−375°F`. These rules decide the rest:

- A setting that the author already wrote more than one way is one segment, so it never gets a second conversion: `400 degrees F (200 degrees C)`, `200C/180C fan forced`, and `190C/170C fan/gas 5`. A gas mark stays in the segment's `text` and isn't read.
- A temperature written after a gas mark and a slash or "or", as in `gas 6/200C` and `gas mark 6 or 200C`, is still read. The `200C` is its own `temperature` segment, and the gas mark stays in the text segment before it.
- Readings pair only when a space, a slash, a comma, "or", a dash, or parentheses join them, so `350°F 180°C` is one segment and `350°F and 180°C` is two. A parenthesis may start with a hedge such as "about", "approx.", "around", "ca.", "i.e.", "or", or `~`, as in `350°F (about 180°C)`.
- Two readings for the same kind of oven pair only when they're in different units and within 10 °C (18 °F) of each other, so they state one setting. So `350°F or 375°F`, `160°C, 180°C`, and `350°F or 200°C` are separate segments.
- A conventional setting and a fan setting pair whichever comes first, so `190°C (375°F) or 170°C fan (340°F)` is one segment, as `170°C fan (340°F) or 190°C (375°F)` is. Otherwise, when a parenthesis restates a reading after the first, that reading starts its own segment. `190°C or 160°C fan (350°F)` is two segments, because 350 °F is a conventional setting, as below. So is `190°C (375°F) or 170°C (340°F) Fan`, whose second setting isn't marked until after its parenthesis.
- A fan or convection marker before or after a reading sets its `fan`: `170C fan`, `180C fan forced`, `fan-forced 180C`, `325°F (convection)`, and `Umluft 180 °C`. A marker after a closing parenthesis, as in `170°C (340°F) Fan`, sets it on every reading in the segment. Otherwise, a marker with other words between it and the reading, as in `325°F for convection`, isn't read, so that reading has `fan: false`, unless it restates a fan reading in parentheses, as below.
- An unmarked reading in parentheses that restates a fan reading is for a fan oven too, so both readings in `170°C fan (340°F)` have `fan`. In `160°C fan (350°F)`, 350 °F is 177 °C, so it's a conventional setting and keeps `fan: false`.
- A number with only a degree sign or "degree" or "degrees", as in `Bake at 350°.` or `Bake in a 350-degree oven.`, stays text unless you set `assumeTemperatureUnit`, and so does a reading paired with it, as in `Bake at 350° (175°C).` With `inferTemperatureUnit` instead, one of 275 or more is °F, since 275 °C is hotter than most home ovens go, so `Preheat the oven to 425 degrees.` reads 425 °F and `Warm the plates at 200°.` stays text. Even with either option, it counts only after a word such as "at", "to", or "bake", before "oven", or when it pairs with another reading, as in `Oven: 200° (180°C fan).` and `180°C fan (200°)`. So `rotate the pan 180 degrees` stays text. It pairs with a reading before or after it across a space, a comma, a slash, "or", or a dash, or in parentheses, wherever the same text with the unit written out would pair them, so with `'F'`, `Bake at 350°/175°C.` is one segment, as `Bake at 350°F/175°C.` is. With `inferTemperatureUnit`, it pairs only with a reading after it, so `Bake at 400° (200°C).` is one segment, but the `400°` in `Bake at 200°C (400°).` stays text. When it doesn't pair, a slash, "or", a dash, "to", "and", `&`, or `~` followed by a number makes it the first end of a range, which stays text with its other end, as in `Bake at 350°–375°F.` A number followed by a time word isn't the other end, so the `350°` in `Bake at 350° – 25 minutes.` is a temperature.
- A range with its unit only on the second end, such as `350–375°F`, `350 to 375 degrees F`, or `350 or 375°F`, stays text when a dash, a slash, `&`, `~`, "to", "and", or "or" joins its ends. A range with its unit only on the first end, such as `350°F–375`, `175°C to 190`, or `-18°C to -20`, stays text when a dash, `~`, or "to" joins them. The second end needs a minus sign, or has to be larger than a first end that isn't below zero without restating it in °F. With a degree sign, it can't have a fan marker or a parenthesis of its own, as in `170°C fan – 190° (375°F)`. Without one, the end of the text, `.`, `!`, `?`, `)`, "for", "until", "till", "oven", or a `,` or `;` that no other number follows has to follow it. So `200°C – 400°` reads 200 °C, and `27°C – 60% humidity`, `180°C – 250 g flour`, `4 °C – 72 Stunden`, and `18°C – 30, 60, or 90 days` read 27 °C, 180 °C, 4 °C, and 18 °C. Otherwise only the end with the unit is a temperature, as with another word, such as "through" or "till", between the ends, or with "or" in `350°F or 375`. A conversion then rewrites that end alone, so `showStep` below turns `350°F through 375` into `177 °C through 375`. A range with a unit on each end, such as `350°F to 375°F`, is two segments. A range written in both units, as in `350°F to 375°F (175°C to 190°C)`, is four segments, so a converted step shows the range twice.
- A change in temperature, as in `lower the heat by 25°F` or `by about another 20°F`, stays text.
- A unit written as one letter needs a whole number of at least two digits, as in `180C` or `350 F`, so `Step 12C` reads as 12 °C and `37.5C` stays text. A lowercase `f` needs three digits, so `90F` is a temperature and `90 f` isn't. A lowercase `c`, or a `C` after a space, could mean cups, so it needs three digits and a word such as "at" or "to" before it, "oven" after it, or another reading that it pairs with. `2C`, `12 C bowl`, and `add 100 c sugar` stay text, while `heat to 180 c`, `a 180 C oven`, `a 180 C fan oven`, `Oven: 180 C (350 F)`, and `350 F/180 C` are temperatures.

A segment's `oven` is `true` when the step says it's an oven setting rather than the food's, the oil's, or another appliance's temperature. That's when a reading in the segment has `fan` or the segment has a gas mark; when "oven" comes right after it, as in `a 200°C oven`; when "oven", "preheat", "bake", or "roast" comes before it in its sentence with no word such as "internal", "thermometer", "until", "oil", "air fryer", or "grill" and no new clause between them; or, with no such word before it in its sentence, when one of those oven words comes after it with no new clause between them, as in `At 180°C, bake for 20 minutes.` So `Roast until it registers 165°F.` and `Preheat your air fryer to 200°C.` aren't oven settings. A new clause starts at a comma or "and", with or without "then" after it, before "heat", "warm", "bring", or "cool" and an object other than "to", "at", or "it". So in `Preheat the oven to 220°C and heat the milk to 70°C.` and `Heat the milk to 70°C, then heat the oven to 220°C.` only `220°C` is an oven setting, but in `Put a rack in the oven and heat to 350°F.` `350°F` is one. A Dutch oven is a pot, so `Bake in a Dutch oven at 450°F.` is an oven setting and `Heat the oil in a Dutch oven to 350°F.` isn't. A dash, or one to three spaces or line breaks, can join the parts of "preheat" and "Dutch oven", as in `Pre heat to 350°F.` and `Heat a Dutch-oven to 350°F.`, but a dash with spaces around it can't, as in `Pre - heat to 350°F.` A sentence ends at `.`, `!`, `?`, or `;` before a space, or at a line break. Only English words are read, besides the fan markers above. The words that rule a reading out were chosen by reading the steps in recipe-scrapers' test data, and are scored on those same steps: there, 416 of the 418 segments that are English oven settings are marked, and 1 of the 417 marked isn't one. Expect more misses and false hits on other text.

```ts
import { segmentStepText } from '@recipe-book/core'

segmentStepText('Bake at 350°F.').map((segment) => segment.text) // ['Bake at ', '350°F', '.']
segmentStepText('Heat oven to 200C/180C fan forced.')[1] // { type: 'temperature', text: '200C/180C fan forced', temperature: { value: 200, unit: 'C' }, fan: false, oven: true, alternatives: [{ temperature: { value: 180, unit: 'C' }, fan: true }] }
segmentStepText('Bake at 350 degrees.').length // 1
segmentStepText('Bake at 350 degrees.', { assumeTemperatureUnit: 'F' })[1] // { type: 'temperature', text: '350 degrees', temperature: { value: 350, unit: 'F' }, fan: false, oven: true, alternatives: [] }
segmentStepText('Preheat the oven to 425 degrees.', { inferTemperatureUnit: true })[1] // { type: 'temperature', text: '425 degrees', temperature: { value: 425, unit: 'F' }, fan: false, oven: true, alternatives: [] }
segmentStepText('Bake at 350°F until a thermometer reads 165°F.').flatMap((segment) => (segment.type === 'temperature' ? [segment.oven] : [])) // [true, false]
```

A duration is a number or a range, then a time word: `20 minutes`, `1.5 hours`, `25–30 min`, or `10 to 12 secs`. After hours, it can go on to minutes, as in `1 hr 30 min`. Its `minutes` never scale, since twice the batch doesn't take twice as long, and [`formatDuration`](https://recipe-book.siraj.page/reference/core/formatting.md#formatduration) formats them. These rules decide the rest:

- The time words are "second", "sec", "minute", "min", "hour", and "hr", with or without an "s", in any case. A period after one stays outside the segment, as in `10 min.`
- A dash, a tilde, "to", "or", or "and" joins a range's ends, which share the time word, as in `10 to 12 min`, `10~12 min`, `25 or 30 minutes`, and `between 25 and 30 minutes`. A range with equal ends, such as `10-10 minutes`, is one value. A reversed range, such as `30-25 minutes`, stays text, and so does a duration of 0.
- Seconds are fractions of a minute, so `30 seconds` is 0.5 minutes, and hours are 60 minutes, so `1.5 hours` is 90 and `.5 hours` is 30.
- Before a minute or hour word, "a", "an", or "one" is 1, so `about a minute` is 1 and `an hour and 15 minutes` is 75. It doesn't start a range, so `Part one – 20 minutes` is 20 minutes. Before "second", it stays text, since there it usually means another, as in `a second bowl`. It stays text, too, at the end of a longer word, as in `Jamaican hour`, and after "half" or "quarter", as in `half an hour` and `three quarters of an hour`.
- Fractions, as in `1 ½ minutes`, `2 1/2 hours`, and `½–1 hour`, decimal commas, as in `1,5 hours`, other number words, as in "two minutes", hyphenated forms, as in `a 5-minute rest`, and single letters, as in `1 h`, stay text. A range that starts with a fraction, such as `1½–2 hours`, stays text whole. A comma, colon, or slash right before a number keeps its duration text too, as in `200°C/20 minutes`.
- Hours, then minutes, with only spaces or "and" between them, are one duration: `1 hour 30 minutes` and `1 hr 30 min` are 90, and `1 hour and 15 minutes` is 75. In a range, the minutes count for both ends, so `1–2 hours 30 minutes` is 90 to 150. Other pairs are two durations with text between them, as in `1 hour, 30 minutes` and `5 minutes and 1 hour`. A word before a number, as in "about 10 minutes", stays in the text before it.
- Temperatures are read first, and a dash between a temperature and a duration doesn't join them, so `200°C – 20 minutes` is a temperature, the text between them, and a duration.
- A number after "gas", "mark", or "step" doesn't start a range, so `gas 4 – 20 minutes` and `Step 2 – 20 minutes` are each 20 minutes. Nor does a gas mark range's high end, as in `gas 4–5 – 20 minutes`, `gas 4 - 5 – 20 minutes`, and `gas 4 to 5 – 20 minutes`. A high end is a mark above the low end, up to 9, so `gas 4 – 10 – 12 minutes` is 10 to 12. After a joiner with spaces before it, the joiner after the high end needs them too, so `gas 5 – 8–10 minutes` is 8 to 10.

```ts
import { segmentStepText } from '@recipe-book/core'

segmentStepText('Simmer for 25–30 minutes.')[1] // { type: 'duration', text: '25–30 minutes', minutes: 25, max: 30 }
segmentStepText('Whisk for 30 seconds.')[1] // { type: 'duration', text: '30 seconds', minutes: 0.5 }
segmentStepText('Roast for 1 hour and 15 minutes.')[1] // { type: 'duration', text: '1 hour and 15 minutes', minutes: 75 }
segmentStepText('Chill for about an hour.')[1] // { type: 'duration', text: 'an hour', minutes: 60 }
segmentStepText('Cook 30-25 minutes.').length // 1
```

To show a step in the reader's unit, show each kind of oven in a segment once. For the conventional setting and for the fan setting, take the reading of that kind that's already in the reader's unit, or else convert the first reading of that kind with [`convertTemperature`](https://recipe-book.siraj.page/reference/core/units.md#converttemperature). Then format that reading with [`formatTemperature`](https://recipe-book.siraj.page/reference/core/formatting.md#formattemperature): keep its value if it's already in the reader's unit. If you converted it, round it to oven steps when the segment's `oven` is `true`, and to whole degrees otherwise. This function does that:

```ts {26-31,41-45}
import {
  convertTemperature,
  formatTemperature,
  segmentStepText,
  type TemperatureUnit,
} from '@recipe-book/core'

function showStep(text: string, unit: TemperatureUnit): string {
  return segmentStepText(text)
    .map((segment) => {
      if (segment.type !== 'temperature') {
        return segment.text
      }
      const readings = [segment, ...segment.alternatives]
      return [false, true]
        .flatMap((fan) => {
          const kind = readings.filter((reading) => reading.fan === fan)
          const reading =
            kind.find(({ temperature }) => temperature.unit === unit) ?? kind[0]
          if (!reading) {
            return []
          }
          const shown = formatTemperature(
            convertTemperature(reading.temperature, unit),
            {
              rounding:
                reading.temperature.unit === unit
                  ? 'none'
                  : segment.oven
                    ? 'oven'
                    : 'kitchen',
            },
          )
          return [fan ? `${shown} fan` : shown]
        })
        .join(' / ')
    })
    .join('')
}

showStep('Preheat oven to 190°C (375°F) or 170°C fan (340°F).', 'F') // 'Preheat oven to 375 °F / 340 °F fan.'
showStep('Heat oven to 190C/170C fan/gas 5.', 'F') // 'Heat oven to 375 °F / 350 °F fan.'
showStep('Cook sous vide at 56.5°C.', 'C') // 'Cook sous vide at 56.5 °C.'
showStep('Cook sous vide at 56.5°C.', 'F') // 'Cook sous vide at 134 °F.'
showStep('Bake at 350°F until a thermometer reads 165°F.', 'C') // 'Bake at 180 °C until a thermometer reads 74 °C.'
```

In the first step, both settings are already written in Fahrenheit, so a US reader sees the values the author wrote. They're one segment, so a slash joins them in place of the author's "or". In the second, both are only in Celsius, so `showStep` converts them, rounds them to oven steps because they're oven settings, and leaves out the gas mark. In React, [`<Recipe.StepText>`](https://recipe-book.siraj.page/reference/react/steps.md#steptext) shows a step this way, in [`<Recipe.Root>`](https://recipe-book.siraj.page/reference/react/root.md)'s measurement system, and its [`inferTemperatureUnit`](https://recipe-book.siraj.page/reference/react/steps.md#temperatures-without-a-scale) prop passes that option. Its text differs from `showStep`'s in one way: a word joiner (U+2060) follows a dash or tilde between a duration's ends when a number comes right after it, as in `25–30 minutes` or `25~30 minutes`, so the line doesn't break there.

In the third step, a metric reader sees the 56.5 °C the author wrote. `showStep` uses `formatTemperature`'s oven rounding only for an oven setting, because a step can also give a food temperature: with oven rounding, a safe internal temperature of 165 °F would show as 70 °C rather than 74 °C. Sous vide isn't an oven setting, so the fourth step converts to whole degrees. In the fifth, the oven setting rounds to 180 °C and the thermometer's reading to 74 °C.

Throws a [`RecipeBookError`](https://recipe-book.siraj.page/reference/core/errors.md#recipebookerror) with the code [`invalid_argument`](https://recipe-book.siraj.page/errors/invalid_argument.md) when `text` isn't a string, or `assumeTemperatureUnit` isn't `'C'` or `'F'`. An error thrown by a getter or proxy in the options passes through.

## `segmentStepQuantities`

```ts
function segmentStepQuantities(text: string): StepQuantitySegment[]
```

Finds the mass and volume quantities in step text, and splits the text around them so a page can show them in another measurement system.

| Name   | Type     | Default  | Description                                                                                                                                                                                                                                |
| ------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `text` | `string` | Required | The step text, such as a [`Step`](https://recipe-book.siraj.page/reference/core/types.md#step)'s `text`, or the `text` of a text segment from [`segmentStepText`](https://recipe-book.siraj.page/reference/core/units.md#segmentsteptext). |

Returns the [segments](https://recipe-book.siraj.page/reference/core/units.md#stepquantitysegment) in order. Joining every segment's `text` gives back `text` exactly. It only finds quantities, and never converts or scales them.

A quantity is a whole number, a decimal with a point, a fraction, a mixed number, or a range, then a mass or volume unit that [`findUnit`](https://recipe-book.siraj.page/reference/core/units.md#findunit) reads, after up to three spaces or none: `200 g`, `180g`, `1 ½ cups`, `2¼ cups`, `1/2 cup`, `1.5 tbsp`, `2-3 tablespoons`, `1 to 2 cups`, or `8 fl oz`. These rules decide the rest:

- A quantity that the author already wrote another way is one segment, so it doesn't get a second conversion: `200 g (7 oz)`, `2 cups (about 480 ml)`, `1 cup (240 ml, 8 fl oz)`, `1 cup / 240 ml`, and `4 Tbsp or 60 ml`. A segment holds five quantities at most, as in `1 cup / 8 fl oz / 240 ml / 8 oz / 225 g`, or six when the last two share a parenthesis, as in `1 cup / 16 tbsp / 8 fl oz / 8 oz (240 ml, 225 g)`. The next quantity starts a new segment, so it can be converted again, unless a slash comes right before it with no space, which leaves it as text. The first quantity is the segment's `quantity`, and the others are its `alternatives`. A restatement in the other dimension or the other system always counts, so `8 oz (225 g)` and `2 tbsp (30 ml)` are one segment each. Teaspoons and tablespoons count as US here. One in the same system counts only within 15% of the first quantity, so `1 cup / 2 tbsp` is two segments. Quantities side by side, as in `1 lb 2 oz` and `1 cup 2 tbsp`, are a segment each and aren't added together, unlike [`parseIngredientLine`](https://recipe-book.siraj.page/reference/core/parsing.md#parseingredientline), which reads `1 lb 2 oz` as one 1.125 lb quantity.
- A period after an abbreviated unit is part of the segment when a lowercase word, a digit, or `(` follows it, as in `3 tbsp. sugar`. A period after `cup`, `cups`, `pint`, `kilo`, `gram`, or a unit word of five letters or more ends a sentence instead, so it stays outside, as in `8 cups.`
- Counts and count units, as in `2 eggs` and `1 bunch`, number words, as in `one tablespoon` and `a cup`, a size with a hyphen, as in `a 2-quart dish`, a decimal comma, as in `1,5 litres`, a number that starts with a point, as in `.5 cup`, an amount of 0, a reversed range, as in `3-2 cups`, and two numbers joined by "and" or "or", as in `1 and 1/2 cups` and `1 or 2 tablespoons`, stay text.
- A lone `c`, `t`, or `T` stays text, as in `Preheat to 180c.`, since it more often means Celsius than cups.
- A quantity in parentheses after a unit word stays text, since it restates a quantity that isn't read: `one tablespoon (15 ml)` and `a 7-quart (6 ½ liters) slow cooker`.
- When a parenthesis after a quantity starts with a restatement but doesn't close right after it or a second one, as in `600g (1lb 5oz)`, `1½ cups (300 g, 2 rice cooker cups)`, and `1 cup (240 ml, 8 fl oz, 16 tbsp)`, the quantity before it is a segment alone, and every quantity up to its `)` stays text, so none gets a second conversion. When it never closes, the rest of the text stays text.
- The size of a scoop or of a measuring cup or spoon stays text, as in `1/4 cup scoops` and `a 1/4 cup measuring cup`.
- An ounce is a weight unless it's written as `fl oz` or `fluid ounces`, so `1 ½ ounces vodka` reads as 1.5 `oz`, as it does in an ingredient line. Only English words are read, and a cup is the US cup.

```ts
import { segmentStepQuantities } from '@recipe-book/core'

segmentStepQuantities('Stir in 1 ½ cups milk.').map((segment) => segment.text) // ['Stir in ', '1 ½ cups', ' milk.']
segmentStepQuantities('Whisk in 200 g (7 oz) sugar.')[1] // { type: 'quantity', text: '200 g (7 oz)', quantity: { amount: 200, unit: 'g' }, alternatives: [{ amount: 7, unit: 'oz' }] }
segmentStepQuantities('Add 1 cup / 2 tbsp milk.').filter((segment) => segment.type === 'quantity').length // 2
segmentStepQuantities('Add 2 eggs and a pinch of salt.').length // 1
```

It doesn't read temperatures or durations. To find those too, run it on the text segments of `segmentStepText`:

```ts
import {
  type QuantitySegment,
  segmentStepQuantities,
  segmentStepText,
  type StepSegment,
} from '@recipe-book/core'

segmentStepText('Bake at 180 C with 200 g sugar for 20 minutes.')
  .flatMap<StepSegment | QuantitySegment>((segment) =>
    segment.type === 'text' ? segmentStepQuantities(segment.text) : segment,
  )
  .map((segment) => segment.type) // ['text', 'temperature', 'text', 'quantity', 'text', 'duration', 'text']
```

To show a step in the reader's measurement system, keep a segment as written when any of its quantities is already in that system. Otherwise convert its `quantity` with [`toSystem`](https://recipe-book.siraj.page/reference/core/units.md#tosystem) and format it with [`formatQuantity`](https://recipe-book.siraj.page/reference/core/formatting.md#formatquantity), as an ingredient list does. This function does that:

```ts
import {
  formatQuantity,
  segmentStepQuantities,
  type System,
  toSystem,
} from '@recipe-book/core'

function showAmounts(text: string, system: System): string {
  return segmentStepQuantities(text)
    .map((segment) => {
      if (segment.type === 'text') {
        return segment.text
      }
      const written = [segment.quantity, ...segment.alternatives].some(
        (quantity) => toSystem(quantity, system).unit === quantity.unit,
      )
      return written
        ? segment.text
        : formatQuantity(toSystem(segment.quantity, system))
    })
    .join('')
}

showAmounts('Stir in 1 ½ cups milk.', 'metric') // 'Stir in 355 mL milk.'
showAmounts('Whisk in 200 g (7 oz) sugar.', 'us') // 'Whisk in 200 g (7 oz) sugar.'
showAmounts('Add 2 tbsp oil.', 'metric') // 'Add 2 tbsp oil.'
```

Quantities in a step follow the measurement system only: scaling a recipe's servings changes its ingredient list, not its steps.

Throws a [`RecipeBookError`](https://recipe-book.siraj.page/reference/core/errors.md#recipebookerror) with the code [`invalid_argument`](https://recipe-book.siraj.page/errors/invalid_argument.md) when `text` isn't a string.

## Types

### `Quantity`

```ts
type Quantity = {
  amount: Amount
  unit?: UnitId | undefined
  max?: undefined
}
```

An amount and an optional unit ID. A [`Servings`](https://recipe-book.siraj.page/reference/core/types.md#servings) or [`Yield`](https://recipe-book.siraj.page/reference/core/types.md#yield) writes its range as `{ amount, max }`, so it isn't a quantity: the functions that take a quantity throw [`invalid_argument`](https://recipe-book.siraj.page/errors/invalid_argument.md) for it. Print those with [`formatServings`](https://recipe-book.siraj.page/reference/core/formatting.md#formatservings) and [`formatYield`](https://recipe-book.siraj.page/reference/core/formatting.md#formatyield).

| Name     | Type                                                                                     | Description                                                                              |
| -------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `amount` | [`Amount`](https://recipe-book.siraj.page/reference/core/units.md#amount)                | A number, or a range as `{ min, max }`.                                                  |
| `unit`   | [`UnitId`](https://recipe-book.siraj.page/reference/core/units.md#unitid) \| `undefined` | The unit's ID, such as `'cup'`. A quantity without a unit is a bare count, as in 2 eggs. |
| `max`    | `undefined`                                                                              | Always left out or `undefined`, because a quantity's range is its `amount`.              |

```ts
import type { Quantity } from '@recipe-book/core'

const flour: Quantity = { amount: 1.5, unit: 'cup' }
const oil: Quantity = { amount: { min: 2, max: 3 }, unit: 'tbsp' }
const eggs: Quantity = { amount: 2 }
```

[Display quantities](https://recipe-book.siraj.page/guides/display-quantities.md#mark-up-the-parts) uses it to type a React component's `quantity` prop.

### `Amount`

```ts
type Amount = number | Range
```

A finite number greater than 0, or a [`Range`](https://recipe-book.siraj.page/reference/core/units.md#range). Functions that take a quantity throw [`invalid_argument`](https://recipe-book.siraj.page/errors/invalid_argument.md) for any other amount.

### `Range`

```ts
type Range = { min: number; max: number }
```

An inclusive range, such as 2–3 tbsp. `convert`, `toSystem`, and [`scaleQuantity`](https://recipe-book.siraj.page/reference/core/resolving.md#scalequantity) can return equal ends for a range whose ends differ only in their last digit, and the functions that take a quantity accept them: [`formatQuantity`](https://recipe-book.siraj.page/reference/core/formatting.md#formatquantity) writes one number.

| Name  | Type     | Description                                                   |
| ----- | -------- | ------------------------------------------------------------- |
| `min` | `number` | The low end, a finite number greater than 0.                  |
| `max` | `number` | The high end, a finite number greater than or equal to `min`. |

### `SameAmount`

```ts
type SameAmount<A extends Amount> = A extends number ? number : Range
```

The amount that [`convert`](https://recipe-book.siraj.page/reference/core/units.md#convert), [`toSystem`](https://recipe-book.siraj.page/reference/core/units.md#tosystem), and [`scaleQuantity`](https://recipe-book.siraj.page/reference/core/resolving.md#scalequantity) return for an amount of type `A`: a number for a number, and a [`Range`](https://recipe-book.siraj.page/reference/core/units.md#range) for a range.

```ts
import { toSystem, type Amount, type Quantity, type SameAmount } from '@recipe-book/core'

function metricAmount<A extends Amount>(quantity: Quantity & { amount: A }): SameAmount<A> {
  return toSystem(quantity, 'metric').amount
}

metricAmount({ amount: { min: 1, max: 2 }, unit: 'cup' }) // { min: 236.5882365, max: 473.176473 }
```

### `UnitId`

```ts
type UnitId =
  | 'mg' | 'g' | 'kg' | 'oz' | 'lb'
  | 'ml' | 'cl' | 'dl' | 'l' | 'tsp' | 'tbsp' | 'tbsp-au' | 'fl-oz' | 'cup' | 'cup-metric' | 'pint' | 'quart' | 'gallon'
  | 'pinch' | 'dash' | 'clove' | 'slice' | 'piece' | 'can' | 'package' | 'stick' | 'sprig' | 'bunch' | 'head' | 'bag' | 'handful' | 'jar' | 'stalk'
```

The ID of a unit in the [registry](https://recipe-book.siraj.page/reference/core/units.md#units). Quantities always store IDs; use [`findUnit`](https://recipe-book.siraj.page/reference/core/units.md#findunit) to turn author text into one. The union may grow in minor releases, so a `Record<UnitId, …>` or an exhaustive `switch` of your own may need new entries after one.

### `UnitAlias`

Any unit ID or alias, exactly as the [registry](https://recipe-book.siraj.page/reference/core/units.md#units) lists it. `findUnit` also matches other cases (except `'T'`, `'t'`, and `'c'`) and a trailing period at runtime, such as `'Cups'` and `'tbsp.'`, but they aren't part of this type.

```ts
import type { UnitAlias } from '@recipe-book/core'

const aliases: UnitAlias[] = ['cups', 'T', 'litre', 'fl oz']
```

### `UnitIdOf`

`UnitIdOf<Alias extends UnitAlias>` is the ID of the unit an alias names. `UnitIdOf<'litres' | 'pound'>` is `'l' | 'lb'`.

```ts
import type { UnitIdOf } from '@recipe-book/core'

const tbsp: UnitIdOf<'tablespoons'> = 'tbsp'
```

### `UnitDefinition`

```ts
type UnitDefinition = {
  readonly id: UnitId
  readonly systems: readonly [System] | readonly ['metric', 'us']
  readonly aliases: readonly UnitAlias[]
  readonly labels: {
    readonly short: { readonly one: string; readonly other: string }
    readonly long: { readonly one: string; readonly other: string }
  }
} & (
  | { readonly dimension: 'mass' | 'volume'; readonly toBase: number }
  | { readonly dimension: 'count'; readonly toBase?: undefined }
)
```

One entry in the [registry](https://recipe-book.siraj.page/reference/core/units.md#units).

| Name        | Type                                                                                                                                    | Description                                                                                                                                                                                                                               |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | [`UnitId`](https://recipe-book.siraj.page/reference/core/units.md#unitid)                                                               | The unit's ID.                                                                                                                                                                                                                            |
| `dimension` | [`Dimension`](https://recipe-book.siraj.page/reference/core/units.md#dimension)                                                         | What the unit measures.                                                                                                                                                                                                                   |
| `systems`   | `readonly [System] \| readonly ['metric', 'us']`                                                                                        | The measurement systems where the unit is native: one, or both in that order.                                                                                                                                                             |
| `toBase`    | `number \| undefined`                                                                                                                   | The exact size in grams for mass units, or in milliliters for volume units. Count units don't have it, so it's a `number` once `dimension` is checked not to be `'count'`.                                                                |
| `aliases`   | readonly [`UnitAlias`](https://recipe-book.siraj.page/reference/core/units.md#unitalias)[]                                              | Every spelling `findUnit` accepts, starting with the ID, matched in any case except `'T'`, `'t'`, and `'c'`. See [`findUnit`](https://recipe-book.siraj.page/reference/core/units.md#findunit) for the whitespace and periods it ignores. |
| `labels`    | `{ readonly short: { readonly one: string; readonly other: string }; readonly long: { readonly one: string; readonly other: string } }` | English names for one and for many, such as `short: { one: 'tbsp', other: 'tbsp' }` and `long: { one: 'tablespoon', other: 'tablespoons' }`.                                                                                              |

### `Dimension`

```ts
type Dimension = 'mass' | 'volume' | 'count'
```

What a unit measures. Count units, such as `clove` or `pinch`, have no fixed size, so they convert only to themselves.

### `System`

```ts
type System = 'metric' | 'us'
```

A measurement system: `'metric'`, or `'us'` for US customary units.

### `ToSystemOptions`

```ts
type ToSystemOptions = {
  exact?: boolean | undefined
}
```

Options for [`toSystem`](https://recipe-book.siraj.page/reference/core/units.md#tosystem).

| Name    | Type                   | Description                                                                                                                                                                                            |
| ------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `exact` | `boolean \| undefined` | Pass `true` to keep the converted amount exact, so 150 mL in `'us'` is 10.1442… tbsp, which `formatQuantity` writes as 10 ⅛ tbsp, rather than 10 tbsp. The unit is still the one a cook measures with. |

### `Temperature`

```ts
type Temperature = { value: number; unit: TemperatureUnit }
```

An oven or food temperature. Temperatures aren't quantities, because converting them adds an offset: °F = °C × 9/5 + 32.

| Name    | Type                                                                                        | Description                                |
| ------- | ------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `value` | `number`                                                                                    | The number of degrees, such as `350`.      |
| `unit`  | [`TemperatureUnit`](https://recipe-book.siraj.page/reference/core/units.md#temperatureunit) | `'C'` for Celsius or `'F'` for Fahrenheit. |

### `TemperatureUnit`

```ts
type TemperatureUnit = 'C' | 'F'
```

Degrees Celsius or Fahrenheit.

### `StepSegment`

```ts
type StepSegment = TextSegment | TemperatureSegment | DurationSegment
```

A piece of step text that [`segmentStepText`](https://recipe-book.siraj.page/reference/core/units.md#segmentsteptext) returns. Check `type` before reading other fields. A minor release may add other kinds, so render a segment with an unknown `type` as its `text`.

### `TextSegment`

```ts
type TextSegment = { type: 'text'; text: string }
```

Step text with nothing recognized in it.

| Name   | Type     | Description                  |
| ------ | -------- | ---------------------------- |
| `type` | `'text'` | Always `'text'`.             |
| `text` | `string` | The text exactly as written. |

### `TemperatureSegment`

```ts
type TemperatureSegment = {
  type: 'temperature'
  text: string
  temperature: Temperature
  fan: boolean
  oven: boolean
  alternatives: TemperatureReading[]
}
```

A temperature in step text, or a setting that the author wrote more than one way. Code that builds one itself, such as a test fixture, has to set every property, including `oven`.

| Name           | Type                                                                                                | Description                                                                                                                                                                                                                             |
| -------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`         | `'temperature'`                                                                                     | Always `'temperature'`.                                                                                                                                                                                                                 |
| `text`         | `string`                                                                                            | The text exactly as written, such as `'350°F'` or `'190C/170C fan/gas 5'`, including any gas mark.                                                                                                                                      |
| `temperature`  | [`Temperature`](https://recipe-book.siraj.page/reference/core/units.md#temperature)                 | The first reading.                                                                                                                                                                                                                      |
| `fan`          | `boolean`                                                                                           | `true` when the text marks the first reading for a fan or convection oven, as in `'170C fan'`.                                                                                                                                          |
| `oven`         | `boolean`                                                                                           | `true` when the step says that it's an oven setting, as in `'Bake at 350°F'`, rather than a food temperature. [`segmentStepText`](https://recipe-book.siraj.page/reference/core/units.md#segmentsteptext) says how it tells them apart. |
| `alternatives` | [`TemperatureReading`](https://recipe-book.siraj.page/reference/core/units.md#temperaturereading)[] | The other readings, in the order written, such as the 200 °C in `'400 degrees F (200 degrees C)'`. Often empty.                                                                                                                         |

### `TemperatureReading`

```ts
type TemperatureReading = { temperature: Temperature; fan: boolean }
```

One reading in a [`TemperatureSegment`](https://recipe-book.siraj.page/reference/core/units.md#temperaturesegment)'s `alternatives`. A `TemperatureSegment` is a reading too, of its first temperature, so `[segment, ...segment.alternatives]` lists every reading in it, as `showStep` does.

| Name          | Type                                                                                | Description                                                                              |
| ------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `temperature` | [`Temperature`](https://recipe-book.siraj.page/reference/core/units.md#temperature) | The temperature read from the text, such as `{ value: 350, unit: 'F' }`.                 |
| `fan`         | `boolean`                                                                           | `true` when the text marks the reading for a fan or convection oven, as in `'170C fan'`. |

### `DurationSegment`

```ts
type DurationSegment = {
  type: 'duration'
  text: string
  minutes: number
  max?: number | undefined
}
```

A duration in step text, such as `'25–30 minutes'` or `'1 hour and 15 minutes'`. It never scales. To show it in another form, format `minutes`, and `max` when it's set, with [`formatDuration`](https://recipe-book.siraj.page/reference/core/formatting.md#formatduration).

| Name      | Type                  | Description                                                                                                 |
| --------- | --------------------- | ----------------------------------------------------------------------------------------------------------- |
| `type`    | `'duration'`          | Always `'duration'`.                                                                                        |
| `text`    | `string`              | The text exactly as written, such as `'25–30 minutes'` or `'1.5 hours'`.                                    |
| `minutes` | `number`              | The duration, or a range's low end, in minutes. Seconds are fractions, so `'30 seconds'` is `0.5`.          |
| `max`     | `number \| undefined` | A range's high end, in minutes, such as `30` for `'25–30 minutes'`. Always greater than `minutes` when set. |

### `SegmentStepTextOptions`

```ts
type SegmentStepTextOptions = {
  assumeTemperatureUnit?: TemperatureUnit | undefined
  inferTemperatureUnit?: boolean | undefined
}
```

Options for [`segmentStepText`](https://recipe-book.siraj.page/reference/core/units.md#segmentsteptext).

| Name                    | Type                                                                                                       | Description                                                                                                                                                                                                                                                                              |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `assumeTemperatureUnit` | [`TemperatureUnit`](https://recipe-book.siraj.page/reference/core/units.md#temperatureunit) \| `undefined` | The unit for a temperature written with a degree sign or "degree" or "degrees" but no unit, as in `Bake at 350 degrees.` When it's absent, such temperatures stay text unless `inferTemperatureUnit` reads them. A number with neither, as in `Preheat oven to 350.`, always stays text. |
| `inferTemperatureUnit`  | `boolean \| undefined`                                                                                     | Whether such a temperature is °F when it's 275 or more, as in `Preheat the oven to 425 degrees.` A lower one stays text, since it could be either. When it's absent or `false`, or `assumeTemperatureUnit` is set, it does nothing.                                                      |

### `StepQuantitySegment`

```ts
type StepQuantitySegment = TextSegment | QuantitySegment
```

A piece of step text that [`segmentStepQuantities`](https://recipe-book.siraj.page/reference/core/units.md#segmentstepquantities) returns. Check `type` before reading other fields.

### `QuantitySegment`

```ts
type QuantitySegment = {
  type: 'quantity'
  text: string
  quantity: Quantity
  alternatives: Quantity[]
}
```

A mass or volume quantity in step text, such as `'200 g'` or `'1 ½ cups'`. When the author already wrote it more than one way, as in `'200 g (7 oz)'` or `'1 cup / 240 ml'`, the run is one segment, up to the bounds that [`segmentStepQuantities`](https://recipe-book.siraj.page/reference/core/units.md#segmentstepquantities) describes.

| Name           | Type                                                                              | Description                                                                                          |
| -------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `type`         | `'quantity'`                                                                      | Always `'quantity'`.                                                                                 |
| `text`         | `string`                                                                          | The text exactly as written, such as `'200 g (7 oz)'`.                                               |
| `quantity`     | [`Quantity`](https://recipe-book.siraj.page/reference/core/units.md#quantity)     | The first quantity, such as `{ amount: 200, unit: 'g' }`. Always has a mass or volume unit.          |
| `alternatives` | [`Quantity`](https://recipe-book.siraj.page/reference/core/units.md#quantity)`[]` | The author's other ways of writing it, in order, such as `[{ amount: 7, unit: 'oz' }]`. Often empty. |
