Struct nextver::Version

pub struct Version<'vs, S: Scheme> { /* private fields */ }

A Version object represents a specific point in a project’s development, comprised of values and literal text. It’s structure is defined by a Format. Versions can be displayed (to_string()), incremented (next()), and compared (partial_cmp()).

Version objects are created with the Scheme::new_version or Format::new_version methods.

(In)Equality

Version objects only implement a partial ordering. This is because the ordering only makes sense when they have the same format. Therefore, comparisons between versions with different formats will always return false.

Examples

use nextver::prelude::*;

let version = Sem::new_version("<MAJOR>.<MINOR>.<PATCH>", "1.2.3")?;

Or, use a previously created Format object:

use nextver::prelude::*;

let format = Sem::new_format("<MAJOR>.<MINOR>.<PATCH>")?;
let version = format.new_version("1.2.3")?;

Implementations

impl<'vs> Version<'vs, Sem>

pub fn next(&self, level: SemLevel) -> Result<Self, NextError>

Returns a new version where the value of specifier given by level is incremented, and all lesser semantic values are reset to zero. This is similar to how an odometer works.

Example

use nextver::prelude::*;;

let cur = Sem::new_version("<MAJOR>.<MINOR>.<PATCH>", "1.2.3")?;
let next = cur.next(SemLevel::Major)?;
assert_eq!("2.0.0", &next.to_string());
assert!(cur < next);

let next_next = next.next(SemLevel::Patch)?;
assert_eq!("2.0.1", &next_next.to_string());
assert!(next < next_next);

Errors

Returns a Result::Err of…

• NextError::SemLevelNotInFormat if the specifier of level is not in format.

impl<'vs> Version<'vs, Cal>

pub fn next(&self, date: Date) -> Result<Self, NextError>

Returns a new version where the values of all date specifiers is advanced to those in date.

If date is before the date in this version, an error is returned. (See Self::next_unchecked to skip this check.)

Example

use nextver::prelude::*;;

let date = Date::utc_now();  // assume today is 2024-02-23

let cur = Cal::new_version("<YYYY>.<MM>", "2024.1")?;
let next = cur.next(date)?;
assert_eq!("2024.2", &next.to_string());
assert!(cur < next);

Errors

Returns a Result::Err of…

• NextError::NoCalendarChange if the date does not change the calendar values.
• NextError::NewDateIsBefore if date is before the date in this version.
• NextError::NegativeYearValue if the year value would be negative. (Year specifiers have lower bounds. See the table for more information.)

pub fn next_unchecked(&self, date: Date) -> Result<Self, NextError>

Same as next, but without checking if date is after the date in this version.

Errors

Same as next, but without NextError::NewDateIsBefore.

impl<'vs> Version<'vs, CalSem>

pub fn next(&self, date: Date, level: CalSemLevel) -> Result<Self, NextError>

Returns a new version where the following are done in order:

1. The values of all calendar specifiers are changed to those in date.
2. A check is performed to see if the date has advanced. Then, one of the following is performed:
   • (date-is-different) Iff the date has advanced, all semantic values are reset to zero.
   • (date-is-same) Otherwise, the value of semantic specifier given by level is incremented, and all lesser semantic values are reset to zero. This is similar to how an odometer works.

If date is before the date in this version, an error is returned. (See next_unchecked to skip this check.)

Example

In the date-is-different case:

use nextver::prelude::*;;

let date = Date::utc_now();  // assume today is 2024-02-23

let cur = CalSem::new_version("<YYYY>.<MM>.<PATCH>", "2024.1.123")?;
let next = cur.next(date, CalSemLevel::Patch)?;
assert_eq!("2024.2.0", &next.to_string());
assert!(cur < next);

In the date-is-same case:

use nextver::prelude::*;;

let date = Date::utc_now();  // assume today is 2024-02-23

let cur = CalSem::new_version("<YYYY>.<MM>.<PATCH>", "2024.2.123")?;
let next = cur.next(date, CalSemLevel::Patch)?;
assert_eq!("2024.2.124", &next.to_string());
assert!(cur < next);

Errors

Returns a Result::Err of…

• NextError::NoCalendarChange if the date does not change the calendar values.
• NextError::NewDateIsBefore if date is before the date in this version.
• NextError::NegativeYearValue if the year value would be negative. (Year specifiers have lower bounds. See the table for more information.)
• NextError::SemLevelNotInFormat if the specifier of level is not in format.

pub fn next_unchecked( &self, date: Date, level: CalSemLevel ) -> Result<Self, NextError>

Same as next, but without checking if date is after the date in this version.

Errors

Same as next, but without NextError::NewDateIsBefore.

Trait Implementations

impl<'vs, S: Clone + Scheme> Clone for Version<'vs, S>

fn clone(&self) -> Version<'vs, S>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'vs, S: Debug + Scheme> Debug for Version<'vs, S>

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

Formats the value using the given formatter.

impl<'vs, S: Scheme> Display for Version<'vs, S>

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

Returns the rendered version string

impl<'vs, S: PartialEq + Scheme> PartialEq for Version<'vs, S>

fn eq(&self, other: &Version<'vs, S>) -> 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<'vs, S: Scheme> PartialOrd for Version<'vs, S>

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

Compares two versions. This is only a partial ordering it is only meaningful to compare two versions when they come from the same format.

Returns None when either of the following are true:

• The number of tokens in the versions are different. Tokens are either literal text or specifier values.
• For two given tokens, they are not of the same type. E.g., one is a literal, one is a value.
• For two given literal tokens, the text is not the same.
• For two given value tokens, they are not of the same specifier type. E.g., one is a <YYYY> value, one is a <YY> value.

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<'vs, S: Eq + Scheme> Eq for Version<'vs, S>

impl<'vs, S: Scheme> StructuralPartialEq for Version<'vs, S>