# `Dimensions`

A box's length, width and height, none below 0. Shown in centimetres, or the unit `unit:` names: `30 × 20 × 10 cm`.

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

## Make one

Build one from its fields, `Dimensions { length: ...  width: ...  height: ... }`.

## Fields

| Field | Type |
|---|---|
| `length` | [`Length`](type-length.md) |
| `width` | [`Length`](type-length.md) |
| `height` | [`Length`](type-length.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 parts.

| JSON |
|---|
| `{"length":{"value":"0.3","unit":"metre"},"width":{"value":"0.2","unit":"metre"},"height":{"value":"0.1","unit":"metre"}}` |
| `{"length":{"value":"1.2","unit":"metre"},"width":{"value":"0.8","unit":"metre"},"height":{"value":"0.144","unit":"metre"}}` |
| `{"length":{"value":"0.3048","unit":"metre"},"width":{"value":"0.2286","unit":"metre"},"height":{"value":"0.1016","unit":"metre"}}` |

It is stored in 3 columns, each named for the field, `_` and its suffix. This is `{"length":{"value":"1.2","unit":"metre"},"width":{"value":"0.8","unit":"metre"},"height":{"value":"0.144","unit":"metre"}}`:

| Column | Type | Holds |
|---|---|---|
| `<field>_length` | `numeric(38, 6)` | `1.2` |
| `<field>_width` | `numeric(38, 6)` | `0.8` |
| `<field>_height` | `numeric(38, 6)` | `0.144` |

## Shown to people

`text.format(value, locale:)` shows it to people in their locale. A call may also give `unit:`.

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `{"length":{"value":"0.3","unit":"metre"},"width":{"value":"0.2","unit":"metre"},"height":{"value":"0.1","unit":"metre"}}` | `30 × 20 × 10 cm` |
| `{"length":{"value":"1.2","unit":"metre"},"width":{"value":"0.8","unit":"metre"},"height":{"value":"0.144","unit":"metre"}}` | `120 × 80 × 14.4 cm` |
| `{"length":{"value":"12","unit":"inch"},"width":{"value":"9","unit":"inch"},"height":{"value":"4","unit":"inch"}}` | `30.48 × 22.86 × 10.16 cm` |

## 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.