README.md
1[![Build status on Travis CI][travis-master-badge]][travis-link]
2[![Built status on AppVeyor][appveyor-master-badge]][appveyor-master-link]
3[![Crate version][crate-version-badge]][crate-link]
4[![Documentation][docs-badge]][docs]
5[![Download statistics][crate-download-badge]][crate-link]
6[![Coverage status][coverage-badge]][coverage-link]
7[![Dependencies][dependency-badge]][crate-link]
8[![License][crate-license-badge]][crate-link]
9
10[crate-version-badge]: https://img.shields.io/crates/v/version-compare.svg
11[crate-download-badge]: https://img.shields.io/crates/d/version-compare.svg
12[crate-license-badge]: https://img.shields.io/crates/l/version-compare.svg
13[crate-link]: https://crates.io/crates/version-compare
14[coverage-badge]: https://coveralls.io/repos/github/timvisee/version-compare/badge.svg?branch=master
15[coverage-link]: https://coveralls.io/github/timvisee/version-compare?branch=master
16[dependency-badge]: https://img.shields.io/badge/dependencies-none!-green.svg
17[docs]: https://docs.rs/version-compare
18[docs-badge]: https://docs.rs/version-compare/badge.svg
19
20# Rust library: version-compare
21> A Rust library to easily compare version numbers in any format, and test them against various comparison operators.
22
23Comparing version numbers is hard. Especially when version numbers get really complex,
24or when their formatting differs.
25
26This library helps you to easily compare any kind of version number with minimal code.
27Two version numbers can be compared to each other, to get a relevant comparison operator (`<`, `==`, `>`),
28or version numbers can be tested against any given comparison operator.
29
30Along with version comparison, the library also features other useful tools.
31For example: version numbers can be parsed to inspect a version number by it's bare numeric or text based parts.
32
33Inspired by PHPs [version_compare()](http://php.net/manual/en/function.version-compare.php).
34
35**Note:** This library is still a work in progress.
36See the list below for a list of currently available and future features.
37
38### Version formats
39A list of version number examples that are parsed successfully:
40
41- `1`
42- `3.10.4.1`
43- `1.2.alpha`
44- `1.2.dev.4`
45- ` ` _(empty)_
46- ` . -32 . 1` _(undefined formats)_
47- `MyApp 3.2.0 / build 0932` _(complex formats, not fully functional yet)_
48- _Many more and support for custom formats to come..._
49
50### Semver
51Version number formats like [_semver_](http://semver.org/) try to make version numbers consistent and manageable,
52there are too many projects however that don't follow such format.
53
54Version-compare makes working with them easy and supports semver formats out of the box with zero configuration.
55
56## Features
57* Compare two version numbers, get: `<`, `==` or `>`.
58* Compare two version numbers against any comparison operator, get: `true` or `false`.
59* Parse complex and undefined version number formats.
60* Static, single-statement methods available.
61
62The following features will be added in a later version:
63
64* Support for text parts in version strings.
65* Version manifest, to specify detailed version number constraints.
66* Version ranges, and tests against them.
67* Support for operators in version strings, [npm-style](https://docs.npmjs.com/misc/semver), and tests against them.
68* Batch comparisons.
69
70## Example
71This library is very easy to use. Here's a basic usage example:
72
73Cargo.toml:
74```toml
75[dependencies]
76version-compare = "0.0.10"
77```
78
79[example.rs:](examples/example.rs)
80```rust
81extern crate version_compare;
82
83use version_compare::{CompOp, Version, VersionCompare};
84
85fn main() {
86 // Define some version numbers
87 let a = "1.2";
88 let b = "1.5.1";
89
90 // The following comparison operators are used:
91 // - CompOp::Eq -> Equal
92 // - CompOp::Ne -> Not equal
93 // - CompOp::Lt -> Less than
94 // - CompOp::Le -> Less than or equal
95 // - CompOp::Ge -> Greater than or equal
96 // - CompOp::Gt -> Greater than
97
98 // Easily compare version strings
99 assert_eq!(VersionCompare::compare(&a, &b).unwrap(), CompOp::Lt);
100 assert_eq!(VersionCompare::compare_to(&a, &b, &CompOp::Le).unwrap(), true);
101 assert_eq!(VersionCompare::compare_to(&a, &b, &CompOp::Gt).unwrap(), false);
102
103 // Version string parsing
104 let a_ver = Version::from(a).unwrap();
105 let b_ver = Version::from(b).unwrap();
106
107 // Directly compare parsed versions
108 assert_eq!(a_ver < b_ver, true);
109 assert_eq!(a_ver <= b_ver, true);
110 assert_eq!(a_ver > b_ver, false);
111 assert_eq!(a_ver != b_ver, true);
112 assert_eq!(a_ver.compare(&b_ver), CompOp::Lt);
113 assert_eq!(b_ver.compare(&a_ver), CompOp::Gt);
114 assert_eq!(a_ver.compare_to(&b_ver, &CompOp::Lt), true);
115
116 // Match
117 match a_ver.compare(&b_ver) {
118 CompOp::Lt => println!("Version a is less than b"),
119 CompOp::Eq => println!("Version a is equal to b"),
120 CompOp::Gt => println!("Version a is greater than b"),
121 _ => unreachable!()
122 }
123}
124```
125
126Check out the [examples](examples) directory for more complete examples.
127
128## Builds
129This library is automatically build and tested for each commit using CI services.
130
131| Service | Platforms | Branch | Build Status | |
132| --------: | :----------- | :---------- | :------------------------------------------------------------: | :---------------------------------- |
133| Travis CI | Linux, macOS | master | [![Build status][travis-master-badge]][travis-link] | [View Status][travis-link] |
134| Travis CI | Linux, macOS | last commit | [![Build status][travis-last-badge]][travis-link] | [View Status][travis-link] |
135| AppVeyor | Windows | master | [![Build status][appveyor-master-badge]][appveyor-master-link] | [View Status][appveyor-master-link] |
136| AppVeyor | Windows | last commit | [![Build status][appveyor-last-badge]][appveyor-last-link] | [View Status][appveyor-last-link] |
137
138[travis-master-badge]: https://travis-ci.org/timvisee/version-compare.svg?branch=master
139[travis-last-badge]: https://travis-ci.org/timvisee/version-compare.svg
140[travis-link]: https://travis-ci.org/timvisee/version-compare
141[appveyor-master-badge]: https://ci.appveyor.com/api/projects/status/nikhmuoonooo05a6/branch/master?svg=true
142[appveyor-last-badge]: https://ci.appveyor.com/api/projects/status/nikhmuoonooo05a6?svg=true
143[appveyor-master-link]: https://ci.appveyor.com/project/timvisee/version-compare/branch/master
144[appveyor-last-link]: https://ci.appveyor.com/project/timvisee/version-compare
145
146## License
147This project is released under the MIT license. Check out the [LICENSE](LICENSE) file for more information.
148
