# `PhoneNumber`

A phone number with its country code, written `+447400123456`.

Use it for any number you might call or text. It is stored in one international form, so two people typing the same number differently can't create two records. For the digits dialled after it, use [`PhoneExtension`](/docs/types/type-phone-extension.md). For a country's code on its own, use [`CallingCode`](/docs/types/type-calling-code.md). It is personal data with no `personal:` on the field: it counts as `PersonalData.contact`.

## Shape

One value, held as text in one set form, with no parts: `+33612345678`.

## Example

```jadpo
PhoneNumber("+447400123456")
```

`PhoneNumber(raw)` checks the text, and text that isn't one breaks the `format` rule.

`text.parse(raw, as: PhoneNumber)` reads one from text that comes from outside. Text that isn't one at all fails `malformed`, such as `07400123456`, `+44 7400 123456` or `447400123456`.

## Good to know

- It refuses a number written the local way, such as `07400123456`, because that doesn't say which country it is in. Ask for the country as well and put the `+44` on yourself.
- `text.format` shows the number the way its own country writes it, which for this one is `07400 123456`.
- `==` tells you whether two are the same. `<` and `list.sort_by` don't take it.
- A field that holds one counts as personal data (`contact`), so you don't mark it yourself.

## In JSON

A string, in a request, a response or `json.write`:

```json
"+447400123456"
"+12015550123"
"+33612345678"
```

## Details

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

`PhoneNumber` is in the group People and contact, and has been in Jadpo since 0.1.0.

### Text form

`text.from` writes one standard text form, the same form `text.parse` reads back: `+447400123456`, `+12015550123` and `+33612345678`.

### How it is stored

It is stored in one column named for the field, of type `text`. `+12015550123` is stored as `'+12015550123'`.

### How it is shown to people

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

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `+447400123456` | `07400 123456` |
| `+12015550123` | `+1 201-555-0123` |
| `+33612345678` | `+33 6 12 34 56 78` |

### Operations

It also takes `text.parse`, `text.from`, `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>