Struct dia_semver::Semver

pub struct Semver {
    pub major: u128,
    pub minor: u128,
    pub patch: u128,
    pub pre_release: Option<String>,
    pub build_metadata: Option<String>,
    // some fields omitted
}

Semver.

Concepts

Strict parser

• Does not allow leading/trailing while spaces.
• All 3 version numbers are required: major, minor, patch.

Tolerant parser

• Ignores leading/trailing while spaces.
• Minor and patch version numbers are optional.

This mode is added by the crate author, it's not described in official specification.

Usage

A semver instance should always be valid. For this reason, it does not support making new instance directly. Instead, it provides helper functions:

• ::new() makes new instance from raw input version numbers.
• ::parse() and ::parse_*() use strict parser, while ::from_*() are more tolerant.

Since Rust encourages the use of immutable variables, a semver instance should not be changed. Once made, there are no functions which help you change its fields. So let mut is discouraged. However there are useful functions to help you make new semver from an existing one: new_major(), new_minor(), new_patch()...

Others might also come in handy: is_stable(), is_early().

Full specification

https://semver.org/spec/v2.0.0.html

Fields

major: u128

Major.

minor: u128

Minor.

patch: u128

Patch.

pre_release: Option<String>

Pre-release.

This does not contain the leading character -. However calling Semver.to_string() will always have that character displayed.

build_metadata: Option<String>

Build metadata.

This does not contain the leading character +. However calling Semver.to_string() will always have that character displayed.

Methods

impl Semver

pub fn new(major: u128, minor: u128, patch: u128) -> Semver

Makes new semver from raw input version numbers.

This function does not support pre-release and build metadata -- which are required to be parsed. For convenience, it returns a direct instance, not a Result<Semver, ParseSemverError>. If you need pre-release and/or build metadata, you can use ::parse().

pub fn parse<T: AsRef<str>>(s: T) -> Result<Semver, ParseSemverError>

Parses input string to make a new semver.

• Minor and patch version numbers are required.
• Leading/trailing while spaces are not allowed.

For convenience, you can use ::from_str() implemented from FromStr trait. It uses tolerant parser, in which:

• Minor and patch version numbers are optional.
• Leading/trailing while spaces are ignored.

Examples

use std::str::FromStr;
use dia_semver::Semver;

assert_eq!(Semver::parse("1.2.3").unwrap().to_string(), "1.2.3");
assert_eq!(Semver::from_str("\t     1-a.b.c     \r\n").unwrap().to_string(), "1.0.0-a.b.c");

pub fn parse_os_str<T: AsRef<OsStr>>(s: T) -> Result<Semver, ParseSemverError>

Parses an &OsStr.

This function uses strict parser.

pub fn from_os_str<T: AsRef<OsStr>>(s: T) -> Result<Semver, ParseSemverError>

Parses an &OsStr.

This function uses tolerant parser.

pub fn parse_c_str<T: AsRef<CStr>>(s: T) -> Result<Semver, ParseSemverError>

Parses a &CStr.

This function uses strict parser.

pub fn from_c_str<T: AsRef<CStr>>(s: T) -> Result<Semver, ParseSemverError>

Parses a &CStr.

This function uses tolerant parser.

pub fn is_stable(&self) -> bool

Checks to see if the semver is stable.

A semver is stable if:

• It's not a pre-release.
• Its major version is larger than zero.

pub fn is_early(&self) -> bool

Checks to see if the semver is in early development state, in which major version is zero.

pub fn parse_pre_release(&self) -> Option<PreRelease>

Parses pre-release to see if it starts with some common phrases.

Notes:

• Case is ignored.
• If it returns None, it means the semver doesn't have a pre-release.

Examples

use std::str::FromStr;
use dia_semver::{Semver, PreRelease};

match Semver::from_str("1.2.3-hola").unwrap().parse_pre_release() {
    Some(PreRelease::Alpha) => println!("Alpha"),
    Some(PreRelease::Beta) => println!("Beta"),
    Some(PreRelease::RC) => println!("RC"),
    Some(PreRelease::Other) => println!("Other"),
    None => println!("Not available"),
};

pub fn compatible_with<T: AsRef<Semver>>(&self, other: T) -> bool

Checks to see if this semver is compatible with one other.

Two semvers are compatible with each other if one of these conditions is true:

• They have same major version, which must be larger than 0.
• If both major versions are 0, they must have exactly these same components: major, minor, patch, pre-release.

Examples

use std::str::FromStr;
use dia_semver::Semver;

assert!(Semver::new(1, 0, 1).compatible_with(&Semver::new(1, 2, 3)));
assert!(Semver::new(1, 0, 1).compatible_with(&Semver::new(1, 99, 9)));
assert!(Semver::new(1, 0, 1).compatible_with(&Semver::new(2, 0, 0)) == false);
assert!(Semver::new(0, 0, 1).compatible_with(Semver::new(0, 2, 0)) == false);
assert!(Semver::new(0, 0, 1).compatible_with(Semver::from_str("0.0.1-abc").unwrap()) == false);
assert!(Semver::new(0, 0, 1).compatible_with(Semver::from_str("0.0.1+abc").unwrap()));

pub fn new_major(&self) -> Semver

Makes new semver with major version incremented by 1.

Pre-release and build metadata will be dropped.

Examples

use std::str::FromStr;
use dia_semver::Semver;

assert_eq!(Semver::from_str("1.2.3-abc+xyz").unwrap().new_major().to_string(), "2.0.0");

pub fn new_minor(&self) -> Semver

Makes new semver with minor version incremented by 1.

Pre-release and build metadata will be dropped.

Examples

use std::str::FromStr;
use dia_semver::Semver;

assert_eq!(Semver::from_str("1.2.3-abc+xyz").unwrap().new_minor().to_string(), "1.3.0");

pub fn new_patch(&self) -> Semver

Makes new semver with patch version incremented by 1.

Pre-release and build metadata will be dropped.

Examples

use std::str::FromStr;
use dia_semver::Semver;

assert_eq!(Semver::from_str("1.2.3-abc+xyz").unwrap().new_patch().to_string(), "1.2.4");

pub fn new_pre_release<T: AsRef<str>>(     &self,     pre_release: T,     keep_build_metadata: bool ) -> Result<Semver, ParseSemverError>

Makes new semver with same version numbers, but new pre-release and/or same build metadata.

pre_release should not include leading character -; it will be added automatically (details).

Examples

use std::str::FromStr;
use dia_semver::Semver;

assert_eq!(
    Semver::from_str("1.2.3-alpha.1+abc").unwrap()
        .new_pre_release("alpha.2", false).unwrap()
        .to_string(),
    "1.2.3-alpha.2"
);

pub fn new_build_metadata<T: AsRef<str>>(     &self,     build_metadata: T,     keep_pre_release: bool ) -> Result<Semver, ParseSemverError>

Makes new semver with same version numbers, but new build metadata and/or same pre-release.

build_metadata should not include leading character +; it will be added automatically (details).

Examples

use std::str::FromStr;
use dia_semver::Semver;

assert_eq!(
    Semver::from_str("1.2.3-alpha.1+abc").unwrap()
        .new_build_metadata("xyz", false).unwrap()
        .to_string(),
    "1.2.3+xyz"
);

Trait Implementations

impl Debug for Semver

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Clone for Semver

fn clone(&self) -> Semver

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Eq for Semver

impl PartialEq for Semver

fn eq(&self, other: &Semver) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Ord for Semver

fn cmp(&self, other: &Semver) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

impl PartialOrd for Semver

fn partial_cmp(&self, other: &Semver) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Hash for Semver

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where     H: Hasher,

Feeds a slice of this type into the given [Hasher].

impl FromStr for Semver

type Err = ParseSemverError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses input string via tolerant parser to make a new semver.

• Minor and patch version numbers are optional.
• Leading/trailing while spaces are ignored.

For strict parser, see ::parse().

impl Display for Semver

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.

impl AsRef<Semver> for Semver

fn as_ref(&self) -> &Self

Performs the conversion.