// SPDX-FileCopyrightText: Peter Pentchev // SPDX-License-Identifier: BSD-2-Clause //! Parse version strings and compare them. //! //! The [`Version`] struct may be used to break a version string down //! into its separate components and then compare it to another one, //! e.g. to decide whether a certain feature is really supported. //! //! ```rust //! use std::cmp; //! # use std::error::Error; //! //! use feature_check::version::Version; //! //! # fn main() -> Result<(), Box> { //! let v1: Version = "2.1".parse()?; //! let v2: Version = "2.2.b2".parse()?; //! println!("{v1} {res:?} {v2}", res = v1.cmp(&v2)); //! println!("equal? {res}", res = v1 == v2); //! println!("smaller: {res}", res = cmp::min(&v1, &v2)); //! println!("larger: {res}", res = cmp::max(&v1, &v2)); //! println!("v1: {v1}"); //! for comp in &v1 { //! println!( //! "- {num}/{rest}", //! num = match comp.num { //! Some(value) => value.to_string(), //! None => "(none)".to_string(), //! }, //! rest = comp.rest, //! ); //! } //! println!("v2: {v2}"); //! for comp in v2.into_iter() { //! println!( //! "- {num}/{rest}", //! num = match comp.num { //! Some(value) => value.to_string(), //! None => "(none)".to_string(), //! }, //! rest = comp.rest, //! ); //! } //! # Ok(()) //! # } //! ``` use std::cmp::Ordering; use std::error::Error; use std::fmt::{Display, Formatter, Result as FmtResult}; use std::slice::Iter; use std::str::FromStr; use std::vec::IntoIter as VecIntoIter; use anyhow::Error as AnyError; use serde_derive::{Deserialize, Serialize}; use crate::expr::parser; /// An error that occurred while parsing a version string. #[derive(Debug)] #[non_exhaustive] pub enum ParseError { /// A parser failed. ParseFailure(String, AnyError), /// A parser left some bytes out. ParseLeftovers(String, usize), } impl Display for ParseError { #[inline] fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult { match *self { Self::ParseFailure(ref value, _) => { write!(f, "Could not parse '{value}' as a version string") } Self::ParseLeftovers(ref value, ref count) => write!( f, "Could not parse '{value}' as a version string: {count} bytes left over" ), } } } impl Error for ParseError { #[inline] fn source(&self) -> Option<&(dyn Error + 'static)> { match *self { Self::ParseFailure(_, ref err) => Some(err.as_ref()), Self::ParseLeftovers(_, _) => None, } } } /// A single version component, e.g. "3" or "b2". #[derive(Debug, Clone, Eq, PartialEq)] #[non_exhaustive] #[expect( clippy::module_name_repetitions, reason = "sensible name for the struct" )] pub struct VersionComponent { /// The numeric portion of the version component. pub num: Option, /// The freeform portion of the version component. pub rest: String, } /// Compare two already-extracted version components. fn compare_single(left: &VersionComponent, right: &VersionComponent) -> Ordering { left.num.map_or_else( || { if right.num.is_some() { Ordering::Less } else { left.rest.cmp(&right.rest) } }, |ver_left| { right.num.map_or(Ordering::Greater, |ver_right| { let res = ver_left.cmp(&ver_right); if res == Ordering::Equal { left.rest.cmp(&right.rest) } else { res } }) }, ) } /// Compare two lists of already-extracted version components. fn compare_components(left: &[VersionComponent], right: &[VersionComponent]) -> Ordering { left.split_first().map_or_else( || { right.first().map_or(Ordering::Equal, |ver_right| { if ver_right.num.is_some() { Ordering::Less } else { Ordering::Greater } }) }, |(comp_left, rest_left)| { right.split_first().map_or_else( || { if comp_left.num.is_some() { Ordering::Greater } else { Ordering::Less } }, |(comp_right, rest_right)| { let res = compare_single(comp_left, comp_right); if res == Ordering::Equal { compare_components(rest_left, rest_right) } else { res } }, ) }, ) } /// A version string, both in full and broken down into components. #[derive(Debug, Clone, Deserialize, Serialize)] #[serde(transparent)] pub struct Version { /// The full version string. value: String, /// The components of the version string. #[serde(skip)] components: Vec, } impl Version { /// Create a version object with the specified attributes. #[inline] #[must_use] pub const fn new(value: String, components: Vec) -> Self { Self { value, components } } /// Return an iterator over the version components. #[inline] pub fn iter(&self) -> Iter<'_, VersionComponent> { self.components.iter() } } impl FromStr for Version { type Err = ParseError; #[inline] fn from_str(value: &str) -> Result { parser::parse_version(value) } } impl AsRef for Version { #[inline] fn as_ref(&self) -> &str { &self.value } } impl Display for Version { #[inline] fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult { write!(f, "{}", self.as_ref()) } } impl PartialEq for Version { #[inline] fn eq(&self, other: &Self) -> bool { self.cmp(other) == Ordering::Equal } } impl Eq for Version {} impl PartialOrd for Version { #[inline] fn partial_cmp(&self, other: &Self) -> Option { Some(self.cmp(other)) } } impl Ord for Version { #[inline] fn cmp(&self, other: &Self) -> Ordering { compare_components(&self.components, &other.components) } } impl IntoIterator for Version { type Item = VersionComponent; type IntoIter = VecIntoIter; #[inline] fn into_iter(self) -> Self::IntoIter { self.components.into_iter() } } impl<'data> IntoIterator for &'data Version { type Item = &'data VersionComponent; type IntoIter = Iter<'data, VersionComponent>; #[inline] fn into_iter(self) -> Self::IntoIter { self.components.iter() } } #[cfg(test)] mod tests { #![expect(clippy::panic_in_result_fn, reason = "this is a test suite")] use std::error::Error; #[test] fn num_only() -> Result<(), Box> { let expected: [super::VersionComponent; 1] = [super::VersionComponent { num: Some(616), rest: String::new(), }]; let ver: super::Version = "616".parse()?; let components = ver.into_iter().collect::>(); assert_eq!(&expected[..], &*components); Ok(()) } #[test] fn rest_only() -> Result<(), Box> { let expected: [super::VersionComponent; 1] = [super::VersionComponent { num: None, rest: "whee".to_owned(), }]; let ver: super::Version = "whee".parse()?; let components = ver.into_iter().collect::>(); assert_eq!(&expected[..], &*components); Ok(()) } #[test] fn both() -> Result<(), Box> { let expected: [super::VersionComponent; 1] = [super::VersionComponent { num: Some(29), rest: "palms".to_owned(), }]; let ver: super::Version = "29palms".parse()?; let components = ver.into_iter().collect::>(); assert_eq!(&expected[..], &*components); Ok(()) } #[test] fn three() -> Result<(), Box> { let expected: [super::VersionComponent; 3] = [ super::VersionComponent { num: Some(1), rest: String::new(), }, super::VersionComponent { num: Some(5), rest: "a".to_owned(), }, super::VersionComponent { num: None, rest: "beta3".to_owned(), }, ]; // let ver = super::Version::from_str("1.5a2.beta3")?; let ver: super::Version = "1.5a.beta3".parse()?; let components = ver.into_iter().collect::>(); assert_eq!(&expected[..], &*components); Ok(()) } }