# `VersionRange`

A range of versions: `^1.2.3`, `>=1.0.0 <2.0.0`.

Use it for what a dependency allows, in npm's grammar. For one version, use [`SemanticVersion`](/docs/types/type-semantic-version.md).

## Shape

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

## Example

```jadpo
VersionRange("^1.2.3")
```

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

`text.parse(raw, as: VersionRange)` reads one from text that comes from outside. Text that isn't one at all fails `malformed`, such as `^v1.2.3`, `=1.2.3` or `>= 1.0.0`.

## Good to know

- `==` 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
"^1.2.3"
"~1.2"
">=1.0.0 <2.0.0"
```

## Details

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

`VersionRange` is in the group Software, 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: `^1.2.3`, `~1.2` and `>=1.0.0 <2.0.0`.

### How it is stored

It is stored in one column named for the field, of type `text`. `1.2.x \|\| >=2.5.0-beta.1` is stored as `'1.2.x \|\| >=2.5.0-beta.1'`.

### How it is shown to people

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

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `^1.2.3` | `^1.2.3` |
| `~1.2` | `~1.2` |
| `>=1.0.0 <2.0.0` | `>=1.0.0 <2.0.0` |
| `1.2.x \|\| >=2.5.0-beta.1` | `1.2.x \|\| >=2.5.0-beta.1` |
| `1.0.0 - 1.4.2` | `1.0.0 - 1.4.2` |
| `*` | `*` |
| `2.0.0` | `2.0.0` |

### Operations

- `semver.satisfies(version: SemanticVersion, range: VersionRange) -> Bool`: Whether `version` is inside `range`, as node-semver reads the range: in one of its sets joined by `||`, meeting each comparison of it. A pre-release is inside only where a comparison of that set names a pre-release of the same major, minor and patch, so `^1.2.3` never takes `2.0.0-beta.1`.

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>