Struct dia_semver::Semver

pub struct Semver { /* private fields */ }

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

This struct 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.

For protection against flood attack, max length of the string (to be parsed) is one of:

• 255 bytes (on 8-bit machines)
• 2048 bytes (on larger machines)

Since Rust encourages the use of immutable variables, a semver instance should not be changed. Indeed, there are no mutable functions. 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 fn new(major: u64, minor: u64, patch: u64) -> Self

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().

If you only have a single major version number, there’s a simpler call:

use dia_semver::Semver;

assert_eq!(Semver::new(2, 0, 0), Semver::from(2_u8));

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 implementation of FromStr trait. It uses tolerant parser, where:

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

Examples

use core::str::FromStr;
use dia_semver::Semver;

assert_eq!(Semver::parse("1.2.3")?.to_string(), "1.2.3");
assert_eq!(
    Semver::from_str("\t     1-a.b.c     \r\n")?.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 pre_release(&self) -> Option<&str>

Pre-release

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

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

Build metadata

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

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 core::str::FromStr;
use dia_semver::{Semver, PreRelease};

match Semver::from_str("1.2.3-hola")?.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 core::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")?) == false);
assert!(Semver::new(0, 0, 1).compatible_with(&Semver::from_str("0.0.1+abc")?));

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 core::str::FromStr;
use dia_semver::Semver;

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

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

Makes new semver with major version incremented by 1

Notes

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

Examples

use core::str::FromStr;
use dia_semver::Semver;

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

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 core::str::FromStr;
use dia_semver::Semver;

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

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

Makes new semver with minor version incremented by 1

Notes

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

Examples

use core::str::FromStr;
use dia_semver::Semver;

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

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 core::str::FromStr;
use dia_semver::Semver;

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

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

Makes new semver with patch version incremented by 1

Notes

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

Examples

use core::str::FromStr;
use dia_semver::Semver;

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

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 core::str::FromStr;
use dia_semver::Semver;

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

pub fn drop_pre_release(&self) -> Self

Drops pre-release

Examples

use {
    core::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 core::str::FromStr;
use dia_semver::Semver;

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

pub fn drop_build_metadata(&self) -> Self

Drops build metadata

Examples

use {
    core::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(),
);

pub fn to_short_format(&self) -> String

Makes this version in short format

Short format means the last version number(s) will be left out, if they’re zeros.

Examples

use core::str::FromStr;
use dia_semver::Semver;

for (sample, expected) in &[
    ("1.0.0-alpha+bsd", "1-alpha+bsd"),
    ("1.1.0", "1.1"),
    ("2.0.1-beta", "2.0.1-beta"),
] {
    assert_eq!(Semver::from_str(sample)?.to_short_format(), *expected);
}

Trait Implementations

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 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 From<&Semver> for Range

fn from(semver: &Semver) -> Self

Converts to this type from the input type.

impl From<Semver> for Range

fn from(semver: Semver) -> Self

Converts to this type from the input type.

impl<T> From<T> for Semverwhere
    T: Into<u64>,

fn from(value: T) -> Self

Converts to this type from the input type.

impl FromStr for Semver

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().

type Err = Error

The associated error which can be returned from parsing.

impl Hash for Semver

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

Feeds this value into the given Hasher.

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

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.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere
    Self: Sized + PartialOrd<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 ==.

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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.

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 RangeBounds<Semver> for Range

fn start_bound(&self) -> Bound<&Semver>

Start index bound.

fn end_bound(&self) -> Bound<&Semver>

End index bound.

fn contains<U>(&self, item: &U) -> boolwhere
    T: PartialOrd<U>,
    U: PartialOrd<T> + ?Sized,

Returns true if item is contained in the range.

impl Eq for Semver

impl StructuralEq for Semver