README.md
1semver
2======
3
4Semantic version parsing and comparison.
5
6
7
8[Documentation](https://steveklabnik.github.io/semver)
9
10Semantic versioning (see https://semver.org/) is a set of rules for
11assigning version numbers.
12
13## SemVer and the Rust ecosystem
14
15Rust itself follows the SemVer specification, as does its standard libraries. The two are
16not tied together.
17
18[Cargo](https://crates.io), Rust's package manager, uses SemVer to determine which versions of
19packages you need installed.
20
21## Installation
22
23To use `semver`, add this to your `[dependencies]` section:
24
25```toml
26semver = "0.9.0"
27```
28
29And this to your crate root:
30
31```rust
32extern crate semver;
33```
34
35## Versions
36
37At its simplest, the `semver` crate allows you to construct `Version` objects using the `parse`
38method:
39
40```rust
41use semver::Version;
42
43assert!(Version::parse("1.2.3") == Ok(Version {
44 major: 1,
45 minor: 2,
46 patch: 3,
47 pre: vec!(),
48 build: vec!(),
49}));
50```
51
52If you have multiple `Version`s, you can use the usual comparison operators to compare them:
53
54```rust
55use semver::Version;
56
57assert!(Version::parse("1.2.3-alpha") != Version::parse("1.2.3-beta"));
58assert!(Version::parse("1.2.3-alpha2") > Version::parse("1.2.0"));
59```
60
61## Requirements
62
63The `semver` crate also provides the ability to compare requirements, which are more complex
64comparisons.
65
66For example, creating a requirement that only matches versions greater than or
67equal to 1.0.0:
68
69```rust
70use semver::Version;
71use semver::VersionReq;
72
73let r = VersionReq::parse(">= 1.0.0").unwrap();
74let v = Version::parse("1.0.0").unwrap();
75
76assert!(r.to_string() == ">= 1.0.0".to_string());
77assert!(r.matches(&v))
78```
79
80It also allows parsing of `~x.y.z` and `^x.y.z` requirements as defined at
81https://www.npmjs.com/package/semver
82
83**Tilde requirements** specify a minimal version with some updates:
84
85```notrust
86~1.2.3 := >=1.2.3 <1.3.0
87~1.2 := >=1.2.0 <1.3.0
88~1 := >=1.0.0 <2.0.0
89```
90
91**Caret requirements** allow SemVer compatible updates to a specified version,
92`0.x` and `0.x+1` are not considered compatible, but `1.x` and `1.x+1` are.
93
94`0.0.x` is not considered compatible with any other version.
95Missing minor and patch versions are desugared to `0` but allow flexibility for that value.
96
97```notrust
98^1.2.3 := >=1.2.3 <2.0.0
99^0.2.3 := >=0.2.3 <0.3.0
100^0.0.3 := >=0.0.3 <0.0.4
101^0.0 := >=0.0.0 <0.1.0
102^0 := >=0.0.0 <1.0.0
103```
104
){kind=link}