New upstream version 1.59.0+dfsg1

[rustc.git] / vendor / semver-0.11.0 / README.md

semver\r
======\r
\r
Semantic version parsing and comparison.\r
\r
![Build Status](https://github.com/steveklabnik/semver/workflows/CI/badge.svg)\r
\r
[Documentation](https://steveklabnik.github.io/semver)\r
\r
Semantic versioning (see https://semver.org/) is a set of rules for\r
assigning version numbers.\r
\r
## SemVer and the Rust ecosystem\r
\r
Rust itself follows the SemVer specification, as does its standard libraries. The two are\r
not tied together.\r
\r
[Cargo](https://crates.io), Rust's package manager, uses SemVer to determine which versions of\r
packages you need installed.\r
\r
## Installation\r
\r
To use `semver`, add this to your `[dependencies]` section:\r
\r
```toml\r
semver = "0.9.0"\r
```\r
\r
And this to your crate root:\r
\r
```rust\r
extern crate semver;\r
```\r
\r
## Versions\r
\r
At its simplest, the `semver` crate allows you to construct `Version` objects using the `parse`\r
method:\r
\r
```rust\r
use semver::Version;\r
\r
assert!(Version::parse("1.2.3") == Ok(Version {\r
   major: 1,\r
   minor: 2,\r
   patch: 3,\r
   pre: vec!(),\r
   build: vec!(),\r
}));\r
```\r
\r
If you have multiple `Version`s, you can use the usual comparison operators to compare them:\r
\r
```rust\r
use semver::Version;\r
\r
assert!(Version::parse("1.2.3-alpha")  != Version::parse("1.2.3-beta"));\r
assert!(Version::parse("1.2.3-alpha2") >  Version::parse("1.2.0"));\r
```\r
\r
## Requirements\r
\r
The `semver` crate also provides the ability to compare requirements, which are more complex\r
comparisons.\r
\r
For example, creating a requirement that only matches versions greater than or\r
equal to 1.0.0:\r
\r
```rust\r
use semver::Version;\r
use semver::VersionReq;\r
\r
let r = VersionReq::parse(">= 1.0.0").unwrap();\r
let v = Version::parse("1.0.0").unwrap();\r
\r
assert!(r.to_string() == ">= 1.0.0".to_string());\r
assert!(r.matches(&v))\r
```\r
\r
It also allows parsing of `~x.y.z` and `^x.y.z` requirements as defined at\r
https://www.npmjs.com/package/semver\r
\r
**Tilde requirements** specify a minimal version with some updates:\r
\r
```notrust\r
~1.2.3 := >=1.2.3 <1.3.0\r
~1.2   := >=1.2.0 <1.3.0\r
~1     := >=1.0.0 <2.0.0\r
```\r
\r
**Caret requirements** allow SemVer compatible updates to a specified version,\r
`0.x` and `0.x+1` are not considered compatible, but `1.x` and `1.x+1` are.\r
\r
`0.0.x` is not considered compatible with any other version.\r
Missing minor and patch versions are desugared to `0` but allow flexibility for that value.\r
\r
```notrust\r
^1.2.3 := >=1.2.3 <2.0.0\r
^0.2.3 := >=0.2.3 <0.3.0\r
^0.0.3 := >=0.0.3 <0.0.4\r
^0.0   := >=0.0.0 <0.1.0\r
^0     := >=0.0.0 <1.0.0\r
```\r