Skip to main content

r_metadata/
version.rs

1//! R package versions.
2
3use crate::Span;
4use std::{
5    cmp::Ordering,
6    hash::{Hash, Hasher},
7    str::FromStr,
8};
9
10/// A numeric R package version that retains its original spelling.
11///
12/// At least two ASCII decimal components are required. Dots and hyphens are
13/// equivalent separators. Equality, ordering and hashing ignore spelling,
14/// leading zeroes and trailing zero components.
15#[derive(Debug, Clone)]
16pub struct Version {
17    original: Box<str>,
18    components: Box<[u32]>,
19}
20
21impl Version {
22    /// Returns the exact parsed spelling.
23    pub fn as_str(&self) -> &str {
24        &self.original
25    }
26    /// Returns numeric components.
27    pub fn components(&self) -> &[u32] {
28        &self.components
29    }
30    /// Returns the first component.
31    pub fn major(&self) -> u32 {
32        self.components[0]
33    }
34    /// Returns the second component.
35    pub fn minor(&self) -> u32 {
36        self.components[1]
37    }
38
39    fn significant(&self) -> &[u32] {
40        let len = self
41            .components
42            .iter()
43            .rposition(|&x| x != 0)
44            .map_or(0, |i| i + 1);
45        &self.components[..len]
46    }
47}
48
49impl PartialEq for Version {
50    fn eq(&self, other: &Self) -> bool {
51        self.cmp(other).is_eq()
52    }
53}
54impl Eq for Version {}
55impl Hash for Version {
56    fn hash<H: Hasher>(&self, state: &mut H) {
57        self.significant().hash(state);
58    }
59}
60impl PartialOrd for Version {
61    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
62        Some(self.cmp(other))
63    }
64}
65impl Ord for Version {
66    fn cmp(&self, other: &Self) -> Ordering {
67        (0..self.components.len().max(other.components.len()))
68            .map(|i| {
69                self.components
70                    .get(i)
71                    .copied()
72                    .unwrap_or(0)
73                    .cmp(&other.components.get(i).copied().unwrap_or(0))
74            })
75            .find(|order| !order.is_eq())
76            .unwrap_or(Ordering::Equal)
77    }
78}
79impl AsRef<str> for Version {
80    fn as_ref(&self) -> &str {
81        self.as_str()
82    }
83}
84impl std::fmt::Display for Version {
85    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
86        f.write_str(self.as_str())
87    }
88}
89
90impl FromStr for Version {
91    type Err = VersionParseError;
92    fn from_str(input: &str) -> Result<Self, Self::Err> {
93        let mut values = Vec::new();
94        let mut start = 0;
95        for (offset, byte) in input.bytes().enumerate() {
96            match byte {
97                b'0'..=b'9' => {}
98                b'.' | b'-' => {
99                    if offset == start {
100                        return Err(VersionParseError::EmptyComponent {
101                            index: values.len(),
102                            span: Span::new(offset, offset),
103                        });
104                    }
105                    values.push(component(input, values.len(), start, offset)?);
106                    start = offset + 1;
107                }
108                _ => {
109                    let end = offset + input[offset..].chars().next().map_or(1, char::len_utf8);
110                    return Err(VersionParseError::InvalidComponent {
111                        index: values.len(),
112                        span: Span::new(offset, end),
113                    });
114                }
115            }
116        }
117        if start == input.len() {
118            return Err(VersionParseError::EmptyComponent {
119                index: values.len(),
120                span: Span::new(start, start),
121            });
122        }
123        values.push(component(input, values.len(), start, input.len())?);
124        if values.len() < 2 {
125            return Err(VersionParseError::TooFewComponents);
126        }
127        Ok(Self {
128            original: input.into(),
129            components: values.into_boxed_slice(),
130        })
131    }
132}
133
134fn component(
135    input: &str,
136    index: usize,
137    start: usize,
138    end: usize,
139) -> Result<u32, VersionParseError> {
140    input[start..end]
141        .parse()
142        .map_err(|_| VersionParseError::ComponentOverflow {
143            index,
144            span: Span::new(start, end),
145        })
146}
147
148/// Error parsing a numeric R package version.
149#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
150pub enum VersionParseError {
151    /// Fewer than two components were supplied.
152    #[error("version must contain at least two components")]
153    TooFewComponents,
154    /// A component is empty.
155    #[error("version component {index} is empty")]
156    EmptyComponent {
157        /// Zero-based component index.
158        index: usize,
159        /// Offending relative byte span.
160        span: Span,
161    },
162    /// A component contains a non-ASCII digit.
163    #[error("version component {index} is not an ASCII integer")]
164    InvalidComponent {
165        /// Zero-based component index.
166        index: usize,
167        /// Offending relative byte span.
168        span: Span,
169    },
170    /// A component exceeds `u32`.
171    #[error("version component {index} is too large")]
172    ComponentOverflow {
173        /// Zero-based component index.
174        index: usize,
175        /// Offending relative byte span.
176        span: Span,
177    },
178}
179
180impl VersionParseError {
181    /// Returns the offending relative byte span, when localized.
182    pub const fn span(&self) -> Option<Span> {
183        match self {
184            Self::TooFewComponents => None,
185            Self::EmptyComponent { span, .. }
186            | Self::InvalidComponent { span, .. }
187            | Self::ComponentOverflow { span, .. } => Some(*span),
188        }
189    }
190    /// Alias for [`Self::span`].
191    pub const fn range(&self) -> Option<Span> {
192        self.span()
193    }
194}