<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from version.rs. Do not edit. -->


# version

<div class="pperl-badges"><span class="pperl-badge pperl-tier-std" title="Minimum feature tier: std. Available in all builds from \`--features native-std\` upward.">📦 std</span></div>

Turn a version string into an object you can compare, print, and introspect.

Perl has three spellings for a version, and mixing them in one program
is normal. `version` gives you a single object type that handles all
three so `$a <=> $b` always does the right thing.

- **Decimal** — a plain number like `1.023` or `"1.02_03"`. One integer
  part, then three-digit chunks after the dot. An underscore marks an
  alpha release.
- **Dotted-integer** — two or more integers separated by dots, e.g.
  `1.2.3`. No `v` prefix required, but three or more components are
  treated as dotted-integer regardless.
- **v-string** — an explicit `v` prefix, e.g. `v1.23.45`. This form is
  recommended for `$VERSION` declarations and is required to pass
  `is_strict`.

## Synopsis

```perl
use version 0.77;
our $VERSION = version->declare("v1.2.3");
my $v = version->parse("1.0203");
if ($v1 == $v2)  { ... }                # numeric equality
@sorted = sort { $a <=> $b } @versions; # ordering
```

`use version` imports `qv` into the caller’s package and installs an
overloaded `UNIVERSAL::VERSION` so `$module->VERSION` returns a
version object rather than a raw string.

## Operators

version objects are overloaded so you can use the normal Perl
comparison operators directly:

- `==`, `!=` — numeric equality
- `<`, `<=`, `>`, `>=`, `<=>` — numeric ordering
- `eq`, `ne`, `cmp` — same thing, stringwise spelling
- `""` — stringifies to original form (dotted) or decimal, whichever
  the object was created with
- `0+` — numifies to a decimal

The overload fallback is on, so any relational operator not listed
above works by auto-generation from `<=>`.

## Functions

### Construction

#### [`new`](version/new.md)

Build a version object from any recognisable version string.

#### [`declare`](version/declare.md)

Build a version object, forcing dotted-integer form regardless of input shape.

### Stringification

#### [`stringify`](version/stringify.md)

Render a version object as a string, using the form it was created in.

#### [`numify`](version/numify.md)

Render a version as a plain decimal number, with three digits per sub-component.

#### [`normal`](version/normal.md)

Render a version in canonical dotted-integer form with a leading `v`.

### Comparison

#### [`vcmp`](version/vcmp.md)

Compare two versions, returning `-1`, `0`, or `1` like `<=>`.

#### [`bool`](version/bool.md)

Give a version object its boolean truth value — true unless every component is zero.

#### [`nomethod`](version/nomethod.md)

Catch-all handler for overloaded operators with no dedicated method.

### Introspection

#### [`is_qv`](version/is_qv.md)

Tell whether a version object is in dotted-integer form.

#### [`is_alpha`](version/is_alpha.md)

Tell whether a version marks an alpha / developer release.

#### [`is_lax`](version/is_lax.md)

Test whether a string is acceptable to `parse` / `new` as a version.

#### [`is_strict`](version/is_strict.md)

Test whether a string is a strict version suitable for CPAN indexing.