version_number/version/
full.rs

1use crate::parsers::modular;
2use crate::{BaseVersion, FullVersionParser, ParserError};
3use std::fmt;
4
5/// A three-component `MAJOR.MINOR.PATCH` version.
6///
7/// This version number is a subset of [`semver`]. In particular, it consists of the `MAJOR`.
8/// `MINOR` and `PATCH` components, and leaves out the additional labels for pre-release and build
9/// metadata.
10///
11/// If you require a version number which also discards the `PATCH` number,
12/// please see the [`BaseVersion`] variant.
13///
14/// For a [`semver`] compliant parser, you should use the `semver` [`crate`] instead.
15///
16/// # Converting to a semver::Version
17///
18/// This version type may be converted to a [`semver::Version`] using the [`From`] trait, assuming
19/// the `semver` feature is enabled.
20///
21///
22/// [`semver`]: https://semver.org/spec/v2.0.0.html
23/// [`BaseVersion`]: crate::BaseVersion
24/// [`crate`]: https://crates.io/crates/semver
25/// [`semver::Version`]: https://docs.rs/semver/1/semver/struct.Version.html
26/// [`From`]: https://doc.rust-lang.org/std/convert/trait.From.html
27#[derive(Copy, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
28pub struct FullVersion {
29    /// A `major` version is incremented when backwards incompatible changes are made to a public
30    /// API.
31    ///
32    /// When this number equals `0`, the version is considered an *unstable initial development
33    /// version*.
34    pub major: u64,
35    /// The `minor` version is incremented when backwards compatibles changes are made to a public
36    /// API.
37    ///
38    /// When the version number is considered an *unstable initial development version*, it may also
39    /// be incremented for backwards incompatible changes.
40    pub minor: u64,
41    /// The `patch` version is incremented when backwards compatibles bug fixes are made.
42    pub patch: u64,
43}
44
45impl FullVersion {
46    /// Instantiate a three component, version number with `MAJOR`, `MINOR` and `PATCH` components.
47    ///
48    /// See [`FullVersion`] for more.
49    ///
50    /// [`FullVersion`]: crate::FullVersion
51    pub fn new(major: u64, minor: u64, patch: u64) -> Self {
52        Self {
53            major,
54            minor,
55            patch,
56        }
57    }
58
59    /// Parse a three component, `major.minor.patch` version number from a given input.
60    ///
61    /// Returns a [`ParserError`] if it fails to parse.
62    pub fn parse(input: &str) -> Result<Self, ParserError> {
63        modular::ModularParser.parse_full(input)
64    }
65
66    /// Convert this full version to a base version.
67    ///
68    /// This conversion is lossy because the `patch` value is lost upon conversion.
69    pub fn to_base_version_lossy(self) -> BaseVersion {
70        BaseVersion {
71            major: self.major,
72            minor: self.minor,
73        }
74    }
75
76    /// Map a [`FullVersion`] to `U`.
77    ///
78    /// # Example
79    ///
80    /// ```
81    /// use version_number::FullVersion;
82    ///
83    /// // 🧑‍🔬
84    /// fn invert_version(v: FullVersion) -> FullVersion {
85    ///     FullVersion::new(v.patch, v.minor, v.major)
86    /// }
87    ///
88    /// let example = FullVersion::new(1, 2, 3);
89    ///
90    /// assert_eq!(example.map(invert_version), FullVersion::new(3, 2, 1));
91    /// ```
92    pub fn map<U, F>(self, fun: F) -> U
93    where
94        F: FnOnce(Self) -> U,
95    {
96        fun(self)
97    }
98}
99
100#[cfg(feature = "semver")]
101impl From<FullVersion> for semver::Version {
102    /// Convert the given [`FullVersion`] to a [`semver::Version`].
103    ///
104    /// Requires the `semver` feature to be enabled.
105    ///
106    /// # Example
107    ///
108    /// ```
109    /// # use version_number::FullVersion;
110    ///
111    /// let version = FullVersion::new(1, 2, 3);
112    /// let converted: semver::Version = version.into();
113    ///
114    /// assert_eq!(converted, semver::Version::new(1, 2, 3));
115    /// ```
116    ///
117    /// [`FullVersion`]: crate::FullVersion
118    /// [`semver::Version`]: https://docs.rs/semver/1/semver/struct.Version.html
119    fn from(version: FullVersion) -> Self {
120        semver::Version::new(version.major, version.minor, version.patch)
121    }
122}
123
124impl From<(u64, u64, u64)> for FullVersion {
125    fn from(tuple: (u64, u64, u64)) -> Self {
126        FullVersion {
127            major: tuple.0,
128            minor: tuple.1,
129            patch: tuple.2,
130        }
131    }
132}
133
134impl fmt::Display for FullVersion {
135    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
136        f.write_fmt(format_args!("{}.{}.{}", self.major, self.minor, self.patch))
137    }
138}
139
140#[cfg(test)]
141mod tests {
142    use crate::{BaseVersion, FullVersion};
143
144    #[test]
145    fn from_tuple() {
146        let major = 0;
147        let minor = 1;
148        let patch = 2;
149
150        assert_eq!(
151            FullVersion {
152                major,
153                minor,
154                patch
155            },
156            FullVersion::from((major, minor, patch))
157        );
158    }
159
160    #[yare::parameterized(
161        zeros = { FullVersion { major: 0, minor: 0, patch: 0 }, "0.0.0" },
162        non_zero = { FullVersion { major: 1, minor: 2, patch: 3 }, "1.2.3" },
163    )]
164    fn display(base_version: FullVersion, expected: &str) {
165        let displayed = format!("{}", base_version);
166
167        assert_eq!(&displayed, expected);
168    }
169
170    #[test]
171    fn to_base_version_lossy() {
172        let full = FullVersion {
173            major: 1,
174            minor: 2,
175            patch: 3,
176        };
177        let converted = full.to_base_version_lossy();
178
179        assert_eq!(BaseVersion { major: 1, minor: 2 }, converted)
180    }
181
182    #[test]
183    fn map() {
184        let version = BaseVersion::new(1, 2);
185        let mapped = version.map(|v| ("Everything is awesome", v.major, v.minor));
186
187        assert_eq!(mapped.1, 1);
188        assert_eq!(mapped.2, 2);
189    }
190}
191
192#[cfg(test)]
193mod ord_tests {
194    use crate::FullVersion;
195    use std::cmp::Ordering;
196
197    #[yare::parameterized(
198        zero = { FullVersion { major: 0, minor: 0, patch: 0 }, FullVersion { major: 0, minor: 0, patch: 0 } },
199        ones = { FullVersion { major: 1, minor: 1, patch: 1 }, FullVersion { major: 1, minor: 1, patch: 1 } },
200    )]
201    fn equals(lhs: FullVersion, rhs: FullVersion) {
202        assert_eq!(lhs.cmp(&rhs), Ordering::Equal);
203    }
204
205    #[yare::parameterized(
206        major_by_1 = { FullVersion { major: 0, minor: 0, patch: 0 }, FullVersion { major: 1, minor: 0, patch: 0 } },
207        minor_by_1 = { FullVersion { major: 0, minor: 0, patch: 0 }, FullVersion { major: 0, minor: 1, patch: 0 } },
208        patch_by_1 = { FullVersion { major: 0, minor: 0, patch: 0 }, FullVersion { major: 0, minor: 0, patch: 1 } },
209    )]
210    fn less(lhs: FullVersion, rhs: FullVersion) {
211        assert_eq!(lhs.cmp(&rhs), Ordering::Less);
212    }
213
214    #[yare::parameterized(
215        major_by_1 = { FullVersion { major: 1, minor: 0, patch: 0 }, FullVersion { major: 0, minor: 0, patch: 0 } },
216        minor_by_1 = { FullVersion { major: 0, minor: 1, patch: 0 }, FullVersion { major: 0, minor: 0, patch: 0 } },
217        patch_by_1 = { FullVersion { major: 0, minor: 0, patch: 1 }, FullVersion { major: 0, minor: 0, patch: 0 } },
218    )]
219    fn greater(lhs: FullVersion, rhs: FullVersion) {
220        assert_eq!(lhs.cmp(&rhs), Ordering::Greater);
221    }
222}
223
224#[cfg(test)]
225mod partial_ord_tests {
226    use crate::FullVersion;
227    use std::cmp::Ordering;
228
229    #[yare::parameterized(
230        zero = { FullVersion { major: 0, minor: 0, patch: 0 }, FullVersion { major: 0, minor: 0, patch: 0 } },
231        ones = { FullVersion { major: 1, minor: 1, patch: 1 }, FullVersion { major: 1, minor: 1, patch: 1 } },
232    )]
233    fn equals(lhs: FullVersion, rhs: FullVersion) {
234        assert_eq!(lhs.partial_cmp(&rhs), Some(Ordering::Equal));
235    }
236
237    #[yare::parameterized(
238        major_by_1 = { FullVersion { major: 0, minor: 0, patch: 0 }, FullVersion { major: 1, minor: 0, patch: 0 } },
239        minor_by_1 = { FullVersion { major: 0, minor: 0, patch: 0 }, FullVersion { major: 0, minor: 1, patch: 0 } },
240        patch_by_1 = { FullVersion { major: 0, minor: 0, patch: 0 }, FullVersion { major: 0, minor: 0, patch: 1 } },
241    )]
242    fn less(lhs: FullVersion, rhs: FullVersion) {
243        assert_eq!(lhs.partial_cmp(&rhs), Some(Ordering::Less));
244    }
245
246    #[yare::parameterized(
247        major_by_1 = { FullVersion { major: 1, minor: 0, patch: 0 }, FullVersion { major: 0, minor: 0, patch: 0 } },
248        minor_by_1 = { FullVersion { major: 0, minor: 1, patch: 0 }, FullVersion { major: 0, minor: 0, patch: 0 } },
249        patch_by_1 = { FullVersion { major: 0, minor: 0, patch: 1 }, FullVersion { major: 0, minor: 0, patch: 0 } },
250    )]
251    fn greater(lhs: FullVersion, rhs: FullVersion) {
252        assert_eq!(lhs.partial_cmp(&rhs), Some(Ordering::Greater));
253    }
254}
255
256#[cfg(test)]
257mod parse_full {
258    use crate::parsers::error::ExpectedError;
259    use crate::parsers::NumericError;
260    use crate::{FullVersion, ParserError};
261
262    #[test]
263    fn ok() {
264        let version = FullVersion::parse("1.2.3").unwrap();
265
266        assert_eq!(version, FullVersion::new(1, 2, 3));
267    }
268
269    #[test]
270    fn err_on_base_only() {
271        let result = FullVersion::parse("1.2");
272
273        assert!(matches!(
274            result.unwrap_err(),
275            ParserError::Expected(ExpectedError::Separator { .. })
276        ));
277    }
278
279    #[test]
280    fn err_on_not_finished() {
281        let result = FullVersion::parse("1.2.3.");
282
283        assert!(matches!(
284            result.unwrap_err(),
285            ParserError::Expected(ExpectedError::EndOfInput { .. })
286        ));
287    }
288
289    #[test]
290    fn err_on_starts_with_0() {
291        let result = FullVersion::parse("1.2.03");
292
293        assert!(matches!(
294            result.unwrap_err(),
295            ParserError::Numeric(NumericError::LeadingZero)
296        ));
297    }
298}
version_number/version/full.rs

version_number/version/
full.rs
