Skip to main content

Crate semantic_versions

Crate semantic_versions 

Source
Expand description

§semantic-versions

The Rust reference implementation of Semantic Versions: parse, validate, compare and range-match versions.

It follows the specification at https://semver.xyz/spec/ and its published BNF grammars, and passes the same shared conformance suite as the JavaScript reference parser (semantic-versions on npm). Where it differs from Semantic Versioning 2.0.0 and from node-semver:

  • Builds participate in precedence: 1.0.0 < 1.0.0+build.1.
  • Pre-release channels: ^1.0.0-rc admits 1.0.0-rc.1, never 1.0.0-beta; X.Y.Z-* and *-* opt in explicitly.
  • Build channels: ^1.0.0+win admits 1.4.2+win.x64 only.
  • Contexts: npm:react@18.2.0 and npm:react@^18 scope a version or range to an identity.
use semantic_versions::{satisfies, valid_range, Version, Range};

let v: Version = "1.2.3-beta.4+build.7".parse().unwrap();
assert_eq!(v.major, 1);
assert!(Version::parse("1.0.0").unwrap() < Version::parse("1.0.0+build.1").unwrap());

assert!(satisfies("1.4.0", "^1.2.3"));
assert!(satisfies("1.0.0-rc.1", "^1.0.0-rc"));
assert!(!satisfies("1.0.0-beta", "^1.0.0-rc"));
assert!(satisfies("1.4.2+win.x64", "^1.0.0+win"));
assert_eq!(valid_range("~>1.2").as_deref(), Some(">=1.2.0 <1.3.0-0"));

let r = Range::parse("npm:react@^18").unwrap();
assert!(r.test(&"npm:react@18.2.0".parse().unwrap()));
assert!(!r.test(&"18.2.0".parse().unwrap()));

Structs§

Comparator
A primitive comparator: an operator and a version, or “any” (matches every version). A build on the comparator’s version is a build channel: a prefix filter on the candidate’s build, orthogonal to the numeric bound. A pre-release on it declares a pre-release channel for its tuple.
Identifiers
Dot-separated identifiers (a pre-release or a build), stored as written. Empty when the version has none. Short lists (up to 22 bytes, which covers rc.1, beta.4, next.12, …) are stored inline without allocating; identifiers are produced on demand.
Range
A parsed range: one or more comparator sets joined by ||, optionally scoped to a context (npm:react@^18).
Version
A parsed Semantic Version, optionally scoped to a context (npm:react@18.2.0).

Enums§

Error
Why a version or range failed to parse.
Identifier
One pre-release or build identifier, borrowed from its version.
Op
A comparator operator. Eq is written without an operator (1.2.3).

Constants§

MAX_LENGTH
Maximum length of a version or range string, matching the JavaScript reference.
MAX_SAFE_INTEGER
Largest numeric identifier accepted (JavaScript’s Number.MAX_SAFE_INTEGER), so both reference implementations accept exactly the same inputs.

Functions§

compare
Compare two versions by precedence. Errors if either is invalid.
max_satisfying
The highest version in versions that satisfies range.
min_satisfying
The lowest version in versions that satisfies range.
parse
Parse a version (optionally context-qualified, e.g. npm:react@1.2.3).
rsort
Sort versions descending by precedence.
satisfies
True if version satisfies range. Invalid input never satisfies.
sort
Sort versions ascending by precedence.
split_reference
Split an optional context off a reference: npm:react@1.2.3 → (Some("npm:react"), "1.2.3"). The context ends at the last @ of the first whitespace-delimited token; a leading @ (a scoped npm name) is part of the context, and an @ at position 0 means there is no context.
valid
The normalized version string, or None if version is not a valid version. The context, if any, is not part of the normalized string.
valid_range
The desugared range (primitive comparators), or None if invalid. An unbounded range is "*".