Crate semver

Semantic version parsing and comparison.

Semantic versioning (see http://semver.org/) is a set of rules for assigning version numbers.

SemVer overview

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards-compatible manner, and
3. PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Any references to ‘the spec’ in this documentation refer to version 2.0 of the SemVer spec.

SemVer and the Rust ecosystem

Rust itself follows the SemVer specification, as does its standard libraries. The two are not tied together.

Cargo, Rust’s package manager, uses SemVer to determine which versions of packages you need installed.

Versions

At its simplest, the semver crate allows you to construct Version objects using the parse method:

use semver::Version;

assert!(Version::parse("1.2.3") == Ok(Version {
   major: 1,
   minor: 2,
   patch: 3,
   pre: vec!(),
   build: vec!(),
}));

If you have multiple Versions, you can use the usual comparison operators to compare them:

use semver::Version;

assert!(Version::parse("1.2.3-alpha") != Version::parse("1.2.3-beta"));
assert!(Version::parse("1.2.3-alpha2") >  Version::parse("1.2.0"));

If you explicitly need to modify a Version, SemVer also allows you to increment the major, minor, and patch numbers in accordance with the spec.

Please note that in order to do this, you must use a mutable Version:

use semver::Version;

let mut bugfix_release = Version::parse("1.0.0").unwrap();
bugfix_release.increment_patch();

assert_eq!(Ok(bugfix_release), Version::parse("1.0.1"));

When incrementing the minor version number, the patch number resets to zero (in accordance with section 7 of the spec)

use semver::Version;

let mut feature_release = Version::parse("1.4.6").unwrap();
feature_release.increment_minor();

assert_eq!(Ok(feature_release), Version::parse("1.5.0"));

Similarly, when incrementing the major version number, the patch and minor numbers reset to zero (in accordance with section 8 of the spec)

use semver::Version;

let mut chrome_release = Version::parse("41.5.5377").unwrap();
chrome_release.increment_major();

assert_eq!(Ok(chrome_release), Version::parse("42.0.0"));

Requirements

The semver crate also provides the ability to compare requirements, which are more complex comparisons.

For example, creating a requirement that only matches versions greater than or equal to 1.0.0:

use semver::Version;
use semver::VersionReq;

let r = VersionReq::parse(">= 1.0.0").unwrap();
let v = Version::parse("1.0.0").unwrap();

assert!(r.to_string() == ">= 1.0.0".to_string());
assert!(r.matches(&v))

It also allows parsing of ~x.y.z and ^x.y.z requirements as defined at https://www.npmjs.org/doc/misc/semver.html

Tilde requirements specify a minimal version with some updates:

~1.2.3 := >=1.2.3 <1.3.0
~1.2   := >=1.2.0 <1.3.0
~1     := >=1.0.0 <2.0.0

Caret requirements allow SemVer compatible updates to a specified verion, 0.x and 0.x+1 are not considered compatible, but 1.x and 1.x+1 are.

0.0.x is not considered compatible with any other version. Missing minor and patch versions are desugared to 0 but allow flexibility for that value.

^1.2.3 := >=1.2.3 <2.0.0
^0.2.3 := >=0.2.3 <0.3.0
^0.0.3 := >=0.0.3 <0.0.4
^0.0   := >=0.0.0 <0.1.0
^0     := >=0.0.0 <1.0.0

Wildcard requirements allows parsing of version requirements of the formats *, x.* and x.y.*.

*     := >=0.0.0
1.*   := >=1.0.0 <2.0.0
1.2.* := >=1.2.0 <1.3.0

Re-exports

pub use version::Identifier::Numeric;

pub use version::Identifier::AlphaNumeric;

Structs

Version

Represents a version number conforming to the semantic versioning scheme.

VersionReq

A VersionReq is a struct containing a list of predicates that can apply to ranges of version numbers. Matching operations can then be done with the VersionReq against a particular version to see if it satisfies some or all of the constraints.

Enums

Identifier

An identifier in the pre-release or build metadata.

ReqParseError

A ReqParseError is returned from methods which parse a string into a VersionReq. Each enumeration is one of the possible errors that can occur.

SemVerError

An error type for this crate