# `RichTextSpan`

A run of text in a block, with its marks and any link.

Use it when you build a [`RichTextBlock`](/docs/types/type-rich-text-block.md) in code.

## Shape

| Field | Type | Required? |
|---|---|---|
| `text` | `Text` | Yes |
| `marks` | `List<`[`RichTextMark`](/docs/types/type-rich-text-mark.md)`>` | Yes |
| `link` | `Text` | No |

Write every field when you build one, and give a field that isn't required as `none`.

## Example

```jadpo
RichTextSpan { text: "today's soup" marks: [RichTextMark.strong] link: none }
```

## Good to know

- It can't be empty. A link must be `https:` with a host, or `mailto:`.
- `==` tells you whether two are the same. `<` and `list.sort_by` don't take it, so sort by one of its parts instead.

## In JSON

An object of its parts, in a request, a response or `json.write`:

```json
{"text":"Soup","marks":[]}
{"text":"today's soup","marks":["strong","emphasis"]}
{"text":"our site","marks":[],"link":"https://example.com/soups?day=mon#leek"}
```

When you read one, a field that isn't required may be left out, or sent as `null`.

## Details

<details>
<summary>Text form, storage, how it is shown, and operations</summary>

`RichTextSpan` is in the group Text formats, and has been in Jadpo since 0.1.0.

### Text form

It has no single text form, so `text.from` and `text.parse` don't take it.

### How it is stored

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'` |

### How it is 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 also takes `text.format`, `json.read`, `json.write` and `==`. [How every standard type behaves](/docs/every-standard-type-meets-one-contract.md) says how they work.

</details>