1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171

//! A crate containing many types of linked lists.
//! 
//! Each different list is enabled with a cargo feature.

#![no_std]
#![warn(missing_docs)]
#![deny(unsafe_code)]

extern crate alloc;
use core::fmt;

/// A struct describing the version of a module in this crate.
///
/// List-containing modules in this crate have their own version, separate from the full crate version.
/// A module on a `0.x.y` version is subject to ANY change during a crate *minor* release,
/// including removal of it entirely.
///
/// This system also exists so that you can use a breaking *crate-level* update,
/// while knowing that you will not have to change any of your code,
/// because the update only broke a specific list that you are not using.
///
/// Essentially, when using this crate, you should always use an exact version specifier `=x.y.z`,
/// and only update when you have checked the new ListVersion of the list(s) you are using.
/// The ListVersion of all of the lists is next to the module name in the README, and in `module::VERSION`.
///
/// See the [SemVer specification](https://semver.org) for details on the meaning of
/// "major", "minor", and "patch".
#[derive(Clone, Copy)]
pub struct ListVersion {
    /// The major version of a module.
    ///
    /// When this is 0, all items in the module are considered "experimental",
    /// and may be removed at any crate minor release.
    /// Otherwise, the biggest change to *any* module will cause that level of crate update.
    pub major: u16,
    /// The minor version of a module.
    pub minor: u16,
    /// The patch version of a module.
    pub patch: u16,
}

impl ListVersion {
    /// Gets the effective major version.
    /// By SemVer spec, in `0.x.y` version, minor should be considered the "major" version.
    #[inline]
    fn get_maj(self) -> u16 {
        if self.experimental() { self.minor }
        else { self.major }
    }

    /// Gets the effective minor version.
    /// By SemVer spec, in `0.x.y` versions, patch should be considered the "minor" version.
    #[inline]
    fn get_min(self) -> u16 {
        if self.experimental() { self.patch }
        else { self.minor }
    }

    /// Returns whether this list is considered "experimental" or not.
    ///
    /// An experimental list can have breaking changes in non-breaking crate releases.
    #[inline]
    pub fn experimental(self) -> bool {
        self.major == 0
    }

    /// Returns whether `self` could be used when `other` was the specified version.
    /// 
    /// # Examples
    /// 
    /// ```
    /// use linked_lists::ListVersion;
    /// 
    /// let version = ListVersion {
    ///     major: 1,
    ///     minor: 2,
    ///     patch: 3,
    /// };
    /// 
    /// let expected = linked_lists::ListVersion {
    ///     major: 1,
    ///     minor: 0,
    ///     patch: 0
    /// };
    /// 
    /// assert!(version.compatible(expected));
    /// ```
    pub fn compatible(self, other: ListVersion) -> bool {
        if self.get_maj() == other.get_maj() && self.get_min() > other.get_min() {
            true
        } else {
            self.get_min() == other.get_min() && self.patch >= other.patch
        }
    }
}

macro_rules! version {
    ($major: literal, $minor: literal, $patch: literal) => {
        use crate::ListVersion;
        /// The `ListVersion` of this module. See [its documentation](ListVersion) for more information.
        pub const VERSION: ListVersion = ListVersion {
            major: $major,
            minor: $minor,
            patch: $patch
        };
    };
}

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

impl fmt::Debug for ListVersion {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        <Self as fmt::Display>::fmt(self, f)
    }
}

#[cfg(feature = "stack")]
pub mod stack;

#[macro_use]
#[cfg(any(feature = "persistent", feature = "persistent_arc"))]
mod persistent_common;

#[cfg(feature = "persistent")]
pub mod persistent;

#[cfg(feature = "persistent_arc")]
pub mod persistent_arc;

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

    #[test]
    fn compatibility() {
        let experimental = ListVersion {
            major: 0,
            minor: 1,
            patch: 4,
        };

        let less_experimental = ListVersion {
            major: 0,
            minor: 1,
            patch: 77,
        };

        assert!(less_experimental.compatible(experimental));

        let one = ListVersion {
            major: 1,
            minor: 3,
            patch: 4,
        };

        assert!(!one.compatible(experimental));

        let two = ListVersion {
            major: 2,
            minor: 0,
            patch: 0,
        };

        assert!(!one.compatible(two));
        assert!(!two.compatible(one));
    }
}