Crate version_compare

A Rust library to easily compare version numbers in any format, and test them against various comparison operators.

Comparing version numbers is hard. Especially when version numbers get really complex, or when their formatting differs.

This library helps you to easily compare any kind of version number with minimal code. Two version numbers can be compared to each other, to get a relevant comparison operator (<, ==, >), or version numbers can be tested against any given comparison operator.

Along with version comparison, the library also features other useful tools.
For example: version numbers can be parsed to inspect a version number by it’s bare numeric or text based parts.

Inspired by PHPs version_compare().

Formats

A list of version number examples that are parsed successfully:

• 1
• 3.10.4.1
• 1.2.alpha
• 1.2.dev.4
• (empty)
• . -32 . 1 (undefined formats)
• MyApp 3.2.0 / build 0932 (complex formats, not fully functional yet)
• Many more and support for custom formats to come…

Semver

Version number formats like semver try to make version numbers consistent and manageable, there are too many projects however that don’t follow such format.

version-compare makes working with them easy and supports semver formats out of the box with zero configuration.

Features

• Compare two version numbers, get: <, == or >.
• Compare two version numbers against a comparison operator
• Parse complex and undefined version number formats.
• Static, standalone methods to easily compare version strings

The following features will be added in a later version:

• Version manifest, to specify detailed version number constraints.
• Version ranges, and tests against them.
• Support for operators in version strings, npm-style, and tests against them.
• Batch comparisons.

Examples

example.rs:

use version_compare::{Cmp, Version};

fn main() {
    // Define some version numbers
    let a = "1.2";
    let b = "1.5.1";

    // The following comparison operators are used:
    // - Cmp::Eq -> Equal
    // - Cmp::Ne -> Not equal
    // - Cmp::Lt -> Less than
    // - Cmp::Le -> Less than or equal
    // - Cmp::Ge -> Greater than or equal
    // - Cmp::Gt -> Greater than

    // Easily compare version strings
    assert_eq!(version_compare::compare(a, b).unwrap(), Cmp::Lt);
    assert_eq!(version_compare::compare_to(a, b, Cmp::Le).unwrap(), true);
    assert_eq!(version_compare::compare_to(a, b, Cmp::Gt).unwrap(), false);

    // Version string parsing
    let a = Version::from(a).unwrap();
    let b = Version::from(b).unwrap();

    // Directly compare parsed versions
    assert_eq!(a < b, true);
    assert_eq!(a <= b, true);
    assert_eq!(a > b, false);
    assert_eq!(a != b, true);
    assert_eq!(a.compare(&b), Cmp::Lt);
    assert_eq!(b.compare(&a), Cmp::Gt);
    assert_eq!(a.compare_to(&b, Cmp::Lt), true);

    // Match
    match a.compare(b) {
        Cmp::Lt => println!("Version a is less than b"),
        Cmp::Eq => println!("Version a is equal to b"),
        Cmp::Gt => println!("Version a is greater than b"),
        _ => unreachable!(),
    }
}

Check out the examples directory for more.

View complete README

Structs

Manifest

Version manifest (configuration).

Version

Version struct, wrapping a string, providing useful comparison functions.

Enums

Cmp

Comparison operators enum.

Part

Version string part enum.

Functions

compare

Compare two version number strings to each other.

compare_to

Compare two version number strings to each other and test against the given comparison operator.