bare_types/sys/

os_version.rs

//! Operating system version type for system information.
//!
//! This module provides a type-safe abstraction for operating system versions,
//! ensuring valid version number parsing and comparison.
//!
//! # Version Format
//!
//! OS versions follow semantic versioning principles:
//!
//! - **Major**: Major version number (e.g., 14 for macOS Sonoma)
//! - **Minor**: Minor version number (e.g., 6 for macOS 14.6)
//! - **Patch**: Patch/build number (e.g., 1 for 14.6.1)
//!
//! # Examples
//!
//! ```rust
//! use bare_types::sys::OsVersion;
//!
//! // Parse from string
//! let version: OsVersion = "14.6.1".parse()?;
//!
//! // Access components
//! assert_eq!(version.major(), 14);
//! assert_eq!(version.minor(), 6);
//! assert_eq!(version.patch(), Some(1));
//!
//! // Compare versions
//! assert!(version >= OsVersion::new(14, 0, None));
//!
//! // Short version (no patch)
//! let version: OsVersion = "14.6".parse()?;
//! assert_eq!(version.patch(), None);
//! # Ok::<(), bare_types::sys::OsVersionError>(())
//! ```

use core::fmt;
use core::str::FromStr;

#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};

#[cfg(feature = "arbitrary")]
use arbitrary::Arbitrary;

/// Error type for OS version parsing.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum OsVersionError {
    /// Empty version string
    ///
    /// The provided string is empty. Version strings must contain at least
    /// major and a minor version number (e.g., "14.6").
    Empty,
    /// Invalid major version number
    ///
    /// The major version component could not be parsed as a valid u16 number.
    /// Version numbers must be non-negative integers.
    InvalidMajor,
    /// Invalid minor version number
    ///
    /// The minor version component could not be parsed as a valid u16 number.
    /// Version numbers must be non-negative integers.
    InvalidMinor,
    /// Invalid patch version number
    ///
    /// The patch version component could not be parsed as a valid u16 number.
    /// Version numbers must be non-negative integers.
    InvalidPatch,
    /// Too many version components (max 3)
    ///
    /// Version strings can have at most 3 components: major.minor.patch.
    /// More than 3 components (e.g., "1.2.3.4") are not supported.
    TooManyComponents,
    /// Negative version number
    ///
    /// Version numbers cannot be negative. This error may occur if parsing
    /// negative integers in version components.
    NegativeVersion,
}

impl fmt::Display for OsVersionError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Empty => write!(f, "version string is empty"),
            Self::InvalidMajor => write!(f, "invalid major version number"),
            Self::InvalidMinor => write!(f, "invalid minor version number"),
            Self::InvalidPatch => write!(f, "invalid patch version number"),
            Self::TooManyComponents => write!(f, "version has too many components (max 3)"),
            Self::NegativeVersion => write!(f, "version numbers cannot be negative"),
        }
    }
}

#[cfg(feature = "std")]
impl std::error::Error for OsVersionError {}

/// Operating system version.
///
/// This type provides type-safe OS version numbers with up to three components:
/// major, minor, and optional patch version.
///
/// # Invariants
///
/// - Major and minor versions are always present (u16)
/// - Patch version is optional (Some(u16) or None)
/// - All version numbers are non-negative
///
/// # Examples
///
/// ```rust
/// use bare_types::sys::OsVersion;
///
/// // Create from components
/// let version = OsVersion::new(14, 6, Some(1));
///
/// // Parse from string
/// let version: OsVersion = "14.6.1".parse()?;
/// assert_eq!(version.major(), 14);
///
/// // Two-component version
/// let version: OsVersion = "22.04".parse()?;
/// assert_eq!(version.patch(), None);
/// # Ok::<(), bare_types::sys::OsVersionError>(())
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "arbitrary", derive(Arbitrary))]
pub struct OsVersion {
    /// The major version number
    major: u16,
    /// The minor version number
    minor: u16,
    /// The optional patch version number
    patch: Option<u16>,
}

impl OsVersion {
    /// Creates a new OS version from components.
    ///
    /// # Arguments
    ///
    /// * `major` - The major version number
    /// * `minor` - The minor version number
    /// * `patch` - The optional patch version number
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::OsVersion;
    ///
    /// // Three-component version
    /// let version = OsVersion::new(14, 6, Some(1));
    /// assert_eq!(version.major(), 14);
    /// assert_eq!(version.minor(), 6);
    /// assert_eq!(version.patch(), Some(1));
    ///
    /// // Two-component version
    /// let version = OsVersion::new(22, 4, None);
    /// assert_eq!(version.patch(), None);
    /// ```
    #[must_use]
    pub const fn new(major: u16, minor: u16, patch: Option<u16>) -> Self {
        Self {
            major,
            minor,
            patch,
        }
    }

    /// Returns the major version number.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::OsVersion;
    ///
    /// let version = OsVersion::new(14, 6, Some(1));
    /// assert_eq!(version.major(), 14);
    /// ```
    #[must_use]
    #[inline]
    pub const fn major(&self) -> u16 {
        self.major
    }

    /// Returns the minor version number.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::OsVersion;
    ///
    /// let version = OsVersion::new(14, 6, Some(1));
    /// assert_eq!(version.minor(), 6);
    /// ```
    #[must_use]
    #[inline]
    pub const fn minor(&self) -> u16 {
        self.minor
    }

    /// Returns the optional patch version number.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::OsVersion;
    ///
    /// let version = OsVersion::new(14, 6, Some(1));
    /// assert_eq!(version.patch(), Some(1));
    ///
    /// let version = OsVersion::new(22, 4, None);
    /// assert_eq!(version.patch(), None);
    /// ```
    #[must_use]
    #[inline]
    pub const fn patch(&self) -> Option<u16> {
        self.patch
    }

    /// Returns `true` if this is a major version (x.0.x or x.0).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::OsVersion;
    ///
    /// assert!(OsVersion::new(14, 0, Some(0)).is_major_release());
    /// assert!(OsVersion::new(14, 0, None).is_major_release());
    /// assert!(!OsVersion::new(14, 6, Some(0)).is_major_release());
    /// ```
    #[must_use]
    pub const fn is_major_release(&self) -> bool {
        self.minor == 0
            && match self.patch {
                Some(p) => p == 0,
                None => true,
            }
    }

    /// Returns `true` if this is an initial release (x.0.0 or x.0).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::OsVersion;
    ///
    /// assert!(OsVersion::new(14, 0, Some(0)).is_initial_release());
    /// assert!(!OsVersion::new(14, 6, Some(0)).is_initial_release());
    /// ```
    #[must_use]
    pub const fn is_initial_release(&self) -> bool {
        self.minor == 0
            && match self.patch {
                Some(p) => p == 0,
                None => true,
            }
    }

    /// Returns a tuple of (major, minor, patch) for comparison.
    ///
    /// For versions without a patch, 0 is used as the patch number for comparison.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::OsVersion;
    ///
    /// let version = OsVersion::new(14, 6, Some(1));
    /// assert_eq!(version.as_tuple(), (14, 6, 1));
    ///
    /// let version = OsVersion::new(22, 4, None);
    /// assert_eq!(version.as_tuple(), (22, 4, 0));
    /// ```
    #[must_use]
    pub const fn as_tuple(&self) -> (u16, u16, u16) {
        (
            self.major,
            self.minor,
            match self.patch {
                Some(p) => p,
                None => 0,
            },
        )
    }

    /// Returns a new version with only major and minor components.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::OsVersion;
    ///
    /// let version = OsVersion::new(14, 6, Some(1));
    /// let short = version.to_short();
    /// assert_eq!(short.patch(), None);
    /// assert_eq!(short.major(), 14);
    /// assert_eq!(short.minor(), 6);
    /// ```
    #[must_use]
    pub const fn to_short(&self) -> Self {
        Self::new(self.major, self.minor, None)
    }

    /// Returns a new version with the patch component set.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::OsVersion;
    ///
    /// let version = OsVersion::new(14, 6, None);
    /// let patched = version.with_patch(1);
    /// assert_eq!(patched.patch(), Some(1));
    /// ```
    #[must_use]
    pub const fn with_patch(&self, patch: u16) -> Self {
        Self::new(self.major, self.minor, Some(patch))
    }

    /// Creates a version from major and minor only.
    ///
    /// This is a convenience method for two-component versions.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bare_types::sys::OsVersion;
    ///
    /// let version = OsVersion::new_short(22, 4);
    /// assert_eq!(version.major(), 22);
    /// assert_eq!(version.minor(), 4);
    /// assert_eq!(version.patch(), None);
    /// ```
    #[must_use]
    pub const fn new_short(major: u16, minor: u16) -> Self {
        Self::new(major, minor, None)
    }
}

impl FromStr for OsVersion {
    type Err = OsVersionError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        if s.is_empty() {
            return Err(OsVersionError::Empty);
        }

        let parts: Vec<&str> = s.split('.').collect();

        if parts.len() > 3 {
            return Err(OsVersionError::TooManyComponents);
        }

        if parts.len() < 2 {
            return Err(OsVersionError::InvalidMinor);
        }

        let major = parts[0]
            .parse::<u16>()
            .map_err(|_| OsVersionError::InvalidMajor)?;

        let minor = parts[1]
            .parse::<u16>()
            .map_err(|_| OsVersionError::InvalidMinor)?;

        let patch = if parts.len() > 2 {
            Some(
                parts[2]
                    .parse::<u16>()
                    .map_err(|_| OsVersionError::InvalidPatch)?,
            )
        } else {
            None
        };

        Ok(Self::new(major, minor, patch))
    }
}

impl TryFrom<&str> for OsVersion {
    type Error = OsVersionError;

    fn try_from(s: &str) -> Result<Self, Self::Error> {
        s.parse()
    }
}

impl fmt::Display for OsVersion {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if let Some(patch) = self.patch {
            write!(f, "{}.{}.{}", self.major, self.minor, patch)
        } else {
            write!(f, "{}.{}", self.major, self.minor)
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_new() {
        let version = OsVersion::new(14, 6, Some(1));
        assert_eq!(version.major(), 14);
        assert_eq!(version.minor(), 6);
        assert_eq!(version.patch(), Some(1));

        let version = OsVersion::new(22, 4, None);
        assert_eq!(version.major(), 22);
        assert_eq!(version.minor(), 4);
        assert_eq!(version.patch(), None);
    }

    #[test]
    fn test_new_short() {
        let version = OsVersion::new_short(22, 4);
        assert_eq!(version.major(), 22);
        assert_eq!(version.minor(), 4);
        assert_eq!(version.patch(), None);
    }

    #[test]
    fn test_is_major_release() {
        assert!(OsVersion::new(14, 0, Some(0)).is_major_release());
        assert!(OsVersion::new(14, 0, None).is_major_release());
        assert!(!OsVersion::new(14, 6, Some(0)).is_major_release());
        assert!(!OsVersion::new(14, 6, None).is_major_release());
    }

    #[test]
    fn test_is_initial_release() {
        assert!(OsVersion::new(14, 0, Some(0)).is_initial_release());
        assert!(!OsVersion::new(14, 6, Some(0)).is_initial_release());
        assert!(OsVersion::new(14, 0, None).is_initial_release());
    }

    #[test]
    fn test_as_tuple() {
        let version = OsVersion::new(14, 6, Some(1));
        assert_eq!(version.as_tuple(), (14, 6, 1));

        let version = OsVersion::new(22, 4, None);
        assert_eq!(version.as_tuple(), (22, 4, 0));
    }

    #[test]
    fn test_to_short() {
        let version = OsVersion::new(14, 6, Some(1));
        let short = version.to_short();
        assert_eq!(short.patch(), None);
        assert_eq!(short.major(), 14);
        assert_eq!(short.minor(), 6);
    }

    #[test]
    fn test_with_patch() {
        let version = OsVersion::new(14, 6, None);
        let patched = version.with_patch(1);
        assert_eq!(patched.patch(), Some(1));
        assert_eq!(patched.major(), 14);
        assert_eq!(patched.minor(), 6);
    }

    #[test]
    fn test_from_str_three_components() {
        let version: OsVersion = "14.6.1".parse().unwrap();
        assert_eq!(version.major(), 14);
        assert_eq!(version.minor(), 6);
        assert_eq!(version.patch(), Some(1));
    }

    #[test]
    fn test_from_str_two_components() {
        let version: OsVersion = "22.04".parse().unwrap();
        assert_eq!(version.major(), 22);
        assert_eq!(version.minor(), 4);
        assert_eq!(version.patch(), None);
    }

    #[test]
    fn test_from_str_zero_padded() {
        let version: OsVersion = "10.0.19041".parse().unwrap();
        assert_eq!(version.major(), 10);
        assert_eq!(version.minor(), 0);
        assert_eq!(version.patch(), Some(19041));
    }

    #[test]
    fn test_from_str_errors() {
        // Empty
        assert!(matches!(
            "".parse::<OsVersion>(),
            Err(OsVersionError::Empty)
        ));

        // Too many components
        assert!(matches!(
            "1.2.3.4".parse::<OsVersion>(),
            Err(OsVersionError::TooManyComponents)
        ));

        // Only one component
        assert!(matches!(
            "14".parse::<OsVersion>(),
            Err(OsVersionError::InvalidMinor)
        ));

        // Invalid numbers
        assert!("abc.def".parse::<OsVersion>().is_err());
        assert!("14.abc".parse::<OsVersion>().is_err());
        assert!("14.6.abc".parse::<OsVersion>().is_err());
    }

    #[test]
    fn test_display() {
        let version = OsVersion::new(14, 6, Some(1));
        assert_eq!(format!("{}", version), "14.6.1");

        let version = OsVersion::new(22, 4, None);
        assert_eq!(format!("{}", version), "22.4");
    }

    #[test]
    fn test_equality() {
        let v1 = OsVersion::new(14, 6, Some(1));
        let v2 = OsVersion::new(14, 6, Some(1));
        let v3 = OsVersion::new(14, 6, None);

        assert_eq!(v1, v2);
        assert_ne!(v1, v3);
    }

    #[test]
    fn test_ordering() {
        let v1 = OsVersion::new(14, 6, Some(1));
        let v2 = OsVersion::new(14, 6, Some(2));
        let v3 = OsVersion::new(14, 7, None);
        let v4 = OsVersion::new(15, 0, None);

        assert!(v1 < v2);
        assert!(v2 < v3);
        assert!(v3 < v4);

        // Version with patch > version without patch at same major.minor
        let with_patch = OsVersion::new(14, 6, Some(0));
        let without_patch = OsVersion::new(14, 6, None);
        assert!(without_patch < with_patch);
    }

    #[test]
    fn test_copy() {
        let version = OsVersion::new(14, 6, Some(1));
        let version2 = version;
        assert_eq!(version, version2);
    }

    #[test]
    fn test_clone() {
        let version = OsVersion::new(14, 6, Some(1));
        let version2 = version.clone();
        assert_eq!(version, version2);
    }

    #[test]
    fn test_common_versions() {
        // Ubuntu LTS versions
        let ubuntu_2204: OsVersion = "22.04".parse().unwrap();
        assert_eq!(ubuntu_2204.major(), 22);
        assert_eq!(ubuntu_2204.minor(), 4);

        let ubuntu_2404: OsVersion = "24.04".parse().unwrap();
        assert_eq!(ubuntu_2404.major(), 24);

        // macOS versions
        let macos_sonoma: OsVersion = "14.6.1".parse().unwrap();
        assert_eq!(macos_sonoma.major(), 14);
        assert_eq!(macos_sonoma.minor(), 6);
        assert_eq!(macos_sonoma.patch(), Some(1));

        // Windows versions
        let win11: OsVersion = "10.0.22000".parse().unwrap();
        assert_eq!(win11.major(), 10);
        assert_eq!(win11.minor(), 0);
        assert_eq!(win11.patch(), Some(22000));
    }
}