updater
stableSemantic versioning (semver) utilities for parsing, comparing, bumping, sorting, and validating version strings. Supports the 'MAJOR.MINOR.PATCH' format with optional pre-release and build metadata.
use plugin updater::{parse_semver, compare_versions, is_newer, …} Functions (14)
- parse_semver Parse a version string into components
- compare_versions Compare two versions, returns -1, 0, or 1
- is_newer Check if candidate is newer than current
- bump_major Increment the major version component
- bump_minor Increment the minor version component
- bump_patch Increment the patch version component
- format_version Build a version string from major/minor/patch
- is_valid_semver Validate a version string
- satisfies_range Check version against a range constraint
- max_version Find the highest version in a list
- min_version Find the lowest version in a list
- sort_versions Sort a list of versions in ascending order
- versions_equal Check if two versions are equal
- version_diff Get the type of difference between two versions
Overview
updater is a dependency-free toolkit for working with semantic version strings
in the MAJOR.MINOR.PATCH format, with optional -prerelease and +build
metadata. There are no handles or stateful objects: every function takes plain
strings (or a list of strings) and returns plain values, so a version is just
text you can parse, compare, bump, and sort freely. A leading v is stripped
automatically, so "v1.2.3" and "1.2.3" are treated the same.
Comparisons and ranges look only at the numeric major.minor.patch triple;
pre-release and build metadata are ignored when ordering versions. Use this
plugin whenever you need update checks, release-tooling math (bumping a version,
finding the latest in a set), or validating and constraining versions against a
range such as ^1.0.0 or >=1.4.0.
Common patterns
Decide whether an available release is worth pulling, then bump accordingly:
use plugin updater::{is_newer, version_diff, bump_patch}
let current = "1.4.2"
let latest = "1.5.0"
if is_newer(current, latest) {
print("update available: {current} -> {latest} ({version_diff(current, latest)})")
}
print("next hotfix: {bump_patch(current)}")
Pick the newest release from a list and check it against a range constraint:
use plugin updater::{max_version, satisfies_range}
let releases = ["1.0.0", "2.1.0", "1.9.5"]
let latest = max_version(releases)
if satisfies_range(latest, "^2.0.0") {
print("{latest} is compatible with the 2.x line")
}
Validate untrusted input before parsing it into components:
use plugin updater::{is_valid_semver, parse_semver}
let input = "2.1.3-beta+build.1"
if is_valid_semver(input) {
let v = parse_semver(input)
print("major {v["major"]}, prerelease {v["prerelease"]}")
}
Parse a version string into components
Parses a semver string into a table with major, minor, patch, prerelease, and build fields. Leading v is stripped automatically.
use plugin updater::{parse_semver}
let v = parse_semver("2.1.3-beta+build.1")
print(v["major"])
print(v["prerelease"])
Compare two versions, returns -1, 0, or 1
Compares two version strings. Returns -1 if v1 < v2, 0 if equal, 1 if v1 > v2.
use plugin updater::{compare_versions}
let result = compare_versions("1.2.0", "1.3.0")
print(result)
Because it returns an ordering, it composes with simple branching to describe the relationship between two builds:
use plugin updater::{compare_versions}
let c = compare_versions("2.0.0", "1.9.9")
if c > 0 {
print("first is ahead")
} else if c < 0 {
print("first is behind")
} else {
print("same version")
}
Check if candidate is newer than current
Returns true if candidate is strictly newer than current. Useful for update checks.
use plugin updater::{is_newer}
if is_newer("1.4.0", "1.5.0") {
print("Update available")
}
Increment the major version component
Increments the major component and resets minor and patch to zero.
use plugin updater::{bump_major}
print(bump_major("1.9.4"))
Increment the minor version component
Increments the minor component and resets patch to zero.
use plugin updater::{bump_minor}
print(bump_minor("1.2.7"))
Increment the patch version component
Increments the patch component, leaving major and minor unchanged.
use plugin updater::{bump_patch}
print(bump_patch("2.3.0"))
Build a version string from major/minor/patch
Constructs a version string from three integer components.
use plugin updater::{format_version}
let ver = format_version(3, 0, 1)
print(ver)
Validate a version string
Returns true if the string is a valid semver version that can be parsed.
use plugin updater::{is_valid_semver}
print(is_valid_semver("1.2.3"))
print(is_valid_semver("not-a-version"))
Check version against a range constraint
Checks whether version satisfies a range expression. Supported operators: >=, <=, >, <, =, ^ (compatible), ~ (approximately), and * (any).
use plugin updater::{satisfies_range}
print(satisfies_range("1.5.0", ">=1.4.0"))
print(satisfies_range("2.0.0", "^1.0.0"))
print(satisfies_range("1.2.3", "~1.2.0"))
The caret (^) allows updates within the same major version, while the tilde
(~) pins to the same major and minor; * accepts anything:
use plugin updater::{satisfies_range}
print(satisfies_range("1.9.9", "^1.4.0"))
print(satisfies_range("1.3.0", "~1.2.0"))
print(satisfies_range("3.7.1", "*"))
Find the highest version in a list
Returns the highest version string from a list.
use plugin updater::{max_version}
let latest = max_version(["1.0.0", "2.1.0", "1.9.5"])
print(latest)
Find the lowest version in a list
Returns the lowest version string from a list.
use plugin updater::{min_version}
let oldest = min_version(["1.0.0", "2.1.0", "1.9.5"])
print(oldest)
Sort a list of versions in ascending order
Returns a new list of version strings sorted in ascending order.
use plugin updater::{sort_versions}
let sorted = sort_versions(["2.0.0", "1.0.0", "1.5.3"])
print(sorted[1])
The returned list is 1-indexed, so the first element is the lowest and the last is the highest — a quick way to read both ends of a release history:
use plugin updater::{sort_versions}
let history = ["1.2.0", "0.9.0", "2.4.1", "1.10.0"]
let sorted = sort_versions(history)
print("oldest: {sorted[1]}")
print("newest: {sorted[4]}")
Check if two versions are equal
Returns true if v1 and v2 have the same major, minor, and patch. Build metadata is ignored.
use plugin updater::{versions_equal}
print(versions_equal("1.2.3", "1.2.3+build.5"))
Get the type of difference between two versions
Returns the type of difference between two versions: "major", "minor", "patch", or "none".
use plugin updater::{version_diff}
print(version_diff("1.0.0", "2.0.0"))
print(version_diff("1.2.0", "1.3.0"))
print(version_diff("1.0.0", "1.0.0"))