Struct dia_semver::Semver

pub struct Semver { /* fields omitted */ }

Semver.

Concepts

Strict parser

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

Tolerant parser

• Ignores leading/trailing white 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 expose internal fields (where the user can make 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. 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().

Implementations

impl Semver

pub const MAX_INPUT_STR_LEN: u16

Max input string length allowed to be parsed

pub const fn new(major: u64, minor: u64, patch: u64) -> 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>. If you need pre-release and/or build metadata, you can use parse().

pub fn parse<S>(s: S) -> Result<Self> where
    S: AsRef<str>, 

Parses input string to make a new semver

• Minor and patch version numbers are required.
• Leading/trailing white 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 white 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<S>(s: S) -> Result<Self> where
    S: AsRef<OsStr>, 

Parses an &OsStr

This function uses strict parser.

pub fn from_os_str<S>(s: S) -> Result<Self> where
    S: AsRef<OsStr>, 

Parses an &OsStr

This function uses tolerant parser.

pub fn parse_c_str<S>(s: S) -> Result<Self> where
    S: AsRef<CStr>, 

Parses a &CStr

This function uses strict parser.

pub fn from_c_str<S>(s: S) -> Result<Self> where
    S: AsRef<CStr>, 

Parses a &CStr

This function uses tolerant parser.

pub fn major(&self) -> u64

Major

pub fn minor(&self) -> u64

Minor

pub fn patch(&self) -> u64

Patch

pub fn build_metadata(&self) -> Option<&str>

Build metadata

pub fn pre_release(&self) -> Option<&str>

Pre-release

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(&self, other: &Self) -> 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) -> Option<Self>

Makes new semver with major version incremented by 1

Notes

• Pre-release and build metadata will be dropped.
• checked_add() will be used. So if overflow happens, None is returned.

Examples

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

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

pub fn new_minor(&self) -> Option<Self>

Makes new semver with minor version incremented by 1

Notes

• Pre-release and build metadata will be dropped.
• checked_add() will be used. So if overflow happens, None is returned.

Examples

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

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

pub fn new_patch(&self) -> Option<Self>

Makes new semver with patch version incremented by 1

Notes

• Pre-release and build metadata will be dropped.
• checked_add() will be used. So if overflow happens, None is returned.

Examples

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

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

pub fn new_pre_release<S>(
    &self,
    pre_release: S,
    keep_build_metadata: bool
) -> Result<Self> where
    S: AsRef<str>, 

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.

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 drop_pre_release(&self) -> Self

Drops pre-release

Examples

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

assert_eq!(
    Semver::from_str("1.2.3-alpha")?.drop_pre_release(),
    Semver::new(1, 2, 3),
);
assert_eq!(
    Semver::from_str("1.2.3-some+rigel")?.drop_pre_release().to_string(),
    Semver::from_str("1.2.3+rigel")?.to_string(),
);

pub fn new_build_metadata<S>(
    &self,
    build_metadata: S,
    keep_pre_release: bool
) -> Result<Self> where
    S: AsRef<str>, 

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.

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"
);

pub fn drop_build_metadata(&self) -> Self

Drops build metadata

Examples

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

assert_eq!(
    Semver::from_str("1.2.3+bsd")?.drop_build_metadata().to_string(),
    Semver::new(1, 2, 3).to_string(),
);
assert_eq!(
    Semver::from_str("1.2.3-beta+artix")?.drop_build_metadata().to_string(),
    Semver::from_str("1.2.3-beta")?.to_string(),
);

Trait Implementations

impl Clone for Semver

fn clone(&self) -> Semver

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Semver

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

Formats the value using the given formatter.

impl Default for Semver

fn default() -> Semver

Returns the “default value” for a type.

impl Display for Semver

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

Formats the value using the given formatter.

impl Eq for Semver

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 white spaces are ignored.

For strict parser, see parse().

impl Hash for Semver

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

Feeds this value into the given Hasher.

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

Feeds a slice of this type into the given Hasher.

impl Ord for Semver

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

This method returns an Ordering between self and other.

#[must_use]pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<Semver> for Semver

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

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

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialOrd<Semver> for Semver

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

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

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

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

#[must_use]pub fn le(&self, other: &Rhs) -> bool

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

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

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

#[must_use]pub 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 StructuralEq for Semver