# `RichTextSpan`

A run of text in a block, never empty, with no control character but a tab or a line feed (a line break); its marks; and the address it links to, if any: `https:` with a host, or `mailto:`.

[Text formats](types.md#text-formats); not ordered; since Jadpo 0.1.0.

## Make one

Build one from its fields, `RichTextSpan { text: ...  marks: ... }`.

## Fields

| Field | Type |
|---|---|
| `text` | `Text` |
| `marks` | `List<`[`RichTextMark`](type-rich-text-mark.md)`>` |
| `link` | `Text?` |

## 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 |
|---|
| `{"text":"Soup","marks":[]}` |
| `{"text":"today's soup","marks":["strong","emphasis"]}` |
| `{"text":"our site","marks":[],"link":"https://example.com/soups?day=mon#leek"}` |
| `{"text":"write to us","marks":["underline"],"link":"mailto:soup@example.com"}` |

It is stored in 3 columns, each named for the field, `_` and its suffix. This is `{"text":"our site","marks":[],"link":"https://example.com/soups?day=mon#leek"}`:

| Column | Type | Holds |
|---|---|---|
| `<field>_text` | `text` | `'our site'` |
| `<field>_marks` | `text[]` | `'{}'::text[]` |
| `<field>_link` | `text` | `'https://example.com/soups?day=mon#leek'` |

## Shown to people

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

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `{"text":"Soup","marks":[]}` | `Soup` |
| `{"text":"today's soup","marks":["strong","emphasis"]}` | `today's soup` |
| `{"text":"our site","marks":[],"link":"https://example.com/soups?day=mon#leek"}` | `our site` |
| `{"text":"write to us","marks":["underline"],"link":"mailto:soup@example.com"}` | `write to us` |

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