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-rcadmits1.0.0-rc.1, never1.0.0-beta;X.Y.Z-*and*-*opt in explicitly. - Build channels:
^1.0.0+winadmits1.4.2+win.x64only. - Contexts:
npm:react@18.2.0andnpm:react@^18scope 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.
Eqis 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
versionsthat satisfiesrange. - min_
satisfying - The lowest version in
versionsthat satisfiesrange. - parse
- Parse a version (optionally context-qualified, e.g.
npm:react@1.2.3). - rsort
- Sort versions descending by precedence.
- satisfies
- True if
versionsatisfiesrange. 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
Noneifversionis not a valid version. The context, if any, is not part of the normalized string. - valid_
range - The desugared range (primitive comparators), or
Noneif invalid. An unbounded range is"*".