# `DosageInstruction`

How to take a medicine (FHIR's `Dosage`): a dose, a route, at least once in a period above nothing, and whether only when needed. Shown `500 mg, Oral use, 2 times per 1 day`.

[Health](types.md#health); not ordered; since Jadpo 0.1.0.

## Make one

Build one from its fields, `DosageInstruction { dose: ...  route: ...  times: ... }`.

## Fields

| Field | Type |
|---|---|
| `dose` | [`Dose`](type-dose.md) |
| `route` | [`RouteOfAdministration`](type-route-of-administration.md) |
| `times` | `Int` |
| `per` | [`Duration`](type-duration.md) |
| `as_needed` | `Bool` |

## 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 |
|---|
| `{"dose":{"tag":"mass","amount":{"value":"0.0005","unit":"kg"}},"route":"oral","times":2,"per":"PT24H","as_needed":false}` |
| `{"dose":{"tag":"volume","amount":{"value":"0.00001","unit":"cubic_metre"}},"route":"oral","times":1,"per":"PT6H","as_needed":true}` |
| `{"dose":{"tag":"mass","amount":{"value":"0.00004","unit":"kg"}},"route":"subcutaneous","times":1,"per":"PT168H","as_needed":false}` |

It is stored in 6 columns, each named for the field, `_` and its suffix. This is `{"dose":{"tag":"volume","amount":{"value":"0.00001","unit":"cubic_metre"}},"route":"oral","times":1,"per":"PT6H","as_needed":true}`:

| Column | Type | Holds |
|---|---|---|
| `<field>_dose_kind` | `text` | `'volume'` |
| `<field>_dose_amount` | `numeric(38, 9)` | `0.00001` |
| `<field>_route` | `text` | `'oral'` |
| `<field>_times` | `integer` | `1` |
| `<field>_per` | `bigint` | `21600000` |
| `<field>_as_needed` | `boolean` | `TRUE` |

## Shown to people

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

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `{"dose":{"tag":"mass","amount":{"value":"500","unit":"mg"}},"route":"oral","times":2,"per":"PT24H","as_needed":false}` | `500 mg, Oral use, 2 times per 1 day` |
| `{"dose":{"tag":"volume","amount":{"value":"10","unit":"ml"}},"route":"oral","times":1,"per":"PT6H","as_needed":true}` | `10 ml, Oral use, 1 time per 6 hours, when needed` |
| `{"dose":{"tag":"mass","amount":{"value":"40","unit":"mg"}},"route":"subcutaneous","times":1,"per":"PT168H","as_needed":false}` | `40 mg, Subcutaneous use, 1 time per 7 days` |

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