# `UnitQuantity`

How much of something an order line or a stock count holds: a count of items, or an amount by mass, volume, length or area, never below 0. Shown `3`, `2.5 kg`.

[Commerce and logistics](types.md#commerce-and-logistics); not ordered; since Jadpo 0.1.0.

## Make one

Pick one of its variants and give its fields, `UnitQuantity.each { count: ... }`.

## Variants

| Variant | Fields |
|---|---|
| `each` | `count`: `Int` |
| `mass` | `amount`: [`Mass`](type-mass.md) |
| `volume` | `amount`: [`Volume`](type-volume.md) |
| `length` | `amount`: [`Length`](type-length.md) |
| `area` | `amount`: [`Area`](type-area.md) |

## Text, JSON and storage

It has no single text form, so `text.from` and `text.parse` don't take it. JSON sends an object of its variant's name, as `tag`, and the variant's fields.

| JSON |
|---|
| `{"tag":"each","count":3}` |
| `{"tag":"each","count":1200}` |
| `{"tag":"mass","amount":{"value":"2.5","unit":"kg"}}` |
| `{"tag":"volume","amount":{"value":"0.0015","unit":"cubic_metre"}}` |
| `{"tag":"length","amount":{"value":"12","unit":"metre"}}` |
| `{"tag":"area","amount":{"value":"20","unit":"sqm"}}` |

It is stored in 3 columns, each named for the field, `_` and its suffix. This is `{"tag":"volume","amount":{"value":"0.0015","unit":"cubic_metre"}}`:

| Column | Type | Holds |
|---|---|---|
| `<field>_kind` | `text` | `'volume'` |
| `<field>_count` | `bigint` | `NULL::bigint` |
| `<field>_amount` | `numeric(38, 9)` | `0.0015` |

## Shown to people

`text.format(value, locale:)` shows it to people in their locale.

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `{"tag":"each","count":3}` | `3` |
| `{"tag":"each","count":1200}` | `1,200` |
| `{"tag":"mass","amount":{"value":"2.5","unit":"kg"}}` | `2.5 kg` |
| `{"tag":"volume","amount":{"value":"0.0015","unit":"cubic_metre"}}` | `0.0015 m³` |
| `{"tag":"length","amount":{"value":"12","unit":"metre"}}` | `12 m` |
| `{"tag":"area","amount":{"value":"20","unit":"sqm"}}` | `20 m²` |

## Operations

It has the contract's own operations: `text.format`, `json.read`, `json.write` and `==`. It isn't ordered, so `<` and sorting don't take it. [Every standard type meets one contract](../topics/every-standard-type-meets-one-contract.md) says how they work.