# `Url`

An `http://` or `https://` address with a host.

Use it for links you store or send. For a path on your own site, use [`UrlPath`](/docs/types/type-url-path.md). For just the scheme and host, use [`WebOrigin`](/docs/types/type-web-origin.md).

## Shape

One value, with no fields to fill in. As text it reads `https://example.com/orders`.

## Example

```jadpo
Url("https://example.com/orders")
```

`text.parse(raw, as: Url)` reads one from text that comes from outside. Text that isn't one at all fails `malformed`, such as `example.com` or `ftp://example.com`.

These operations give one: `web.resolve` and `web.with_query`.

## Good to know

- `example.com` alone and `ftp://` are refused, so add the scheme.
- `web.with_query` adds query parameters, and `web.resolve` turns a [`RelativeUrl`](/docs/types/type-relative-url.md) into one.
- `==` tells you whether two are the same. `<` and `list.sort_by` don't take it.

## In JSON

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

```json
"https://example.com/orders"
```

## Details

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

`Url` is in the group Web and network, 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: `https://example.com/orders`.

### How it is stored

It is stored in one column named for the field, of type `text`. `https://example.com/orders` is stored as `'https://example.com/orders'`.

### How it is shown to people

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

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `https://example.com/orders` | `https://example.com/orders` |

### Operations

- `web.resolve(base: Url, relative: RelativeUrl) -> Url`: `relative` resolved against `base` by RFC 3986 (section 5.2): its `.` and `..` segments followed, a path starting `/` taken from the host, a query or a fragment alone kept with the base's path. A `UrlPath` is a `RelativeUrl`, so it resolves too.
- `web.with_query(url: Url, entries: Map<Text, Text>) -> Url`: `url` with each of `entries` added to its query as `key=value`, in key order, each percent-encoded as `encoding.to_url_component` encodes it, after any query `url` has and before its fragment.

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>