module 0.3.1

Modular NixOS-style configuration crate.
Documentation 
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

use core::mem::replace;

use super::Merge;
use super::error::Error;

/// A memory location that allows repeated merging.
///
/// This type acts like an "accumulator" for merging. It allows merging many
/// values and defering merge errors for later.
///
/// [`MergeCell`] deliberately does not implement [`Merge`]. It is not intended
/// to be merged with other values, rather it expects to have values merged
/// into it.
///
/// # Example
///
/// ```rust
/// # use module::merge::{Merge, MergeCell};
/// let mut cell = MergeCell::empty();
///
/// cell.merge(vec![1, 2]);
/// cell.merge(vec![]);
/// cell.merge(vec![0, 4, 8]);
///
/// let merged = cell.try_finish().unwrap().unwrap();
/// assert_eq!(merged, &[1, 2, 0, 4, 8]);
/// ```
#[derive(Debug)]
pub struct MergeCell<T> {
    value: Option<T>,
    result: Result<(), Error>,
}

impl<T> Default for MergeCell<T> {
    fn default() -> Self {
        Self::empty()
    }
}

impl<T> MergeCell<T> {
    /// Create a new empty [`MergeCell`].
    pub fn empty() -> Self {
        Self {
            value: None,
            result: Ok(()),
        }
    }

    /// Create a new [`MergeCell`] that is initialized with `value`.
    pub fn new(value: T) -> Self {
        Self {
            value: Some(value),
            result: Ok(()),
        }
    }

    /// Check whether the cell is empty.
    ///
    /// The cell is empty if and only if it was created with [`empty()`] and no
    /// values have been [`merge()`]d.
    ///
    /// [`empty()`]: MergeCell::empty
    /// [`merge()`]: MergeCell::merge
    pub fn is_empty(&self) -> bool {
        self.value.is_none()
    }

    /// Check whether a previous [`merge()`] operation has failed.
    ///
    /// [`merge()`]: MergeCell::merge
    pub fn has_errored(&self) -> bool {
        self.result.is_err()
    }

    /// Destruct the [`MergeCell`] and get back the final merged value.
    ///
    /// Returns the result of all of the [`merge()`] operations on the cell.
    ///
    /// # Panics
    ///
    /// If the [`MergeCell`] is empty. For the non-panicking version of this
    /// method, see: [`try_finish()`].
    ///
    /// # Example
    ///
    /// ```rust
    /// # use module::merge::{Merge, MergeCell};
    /// let mut cell = MergeCell::empty();
    ///
    /// cell.merge(vec![1, 2]);
    /// cell.merge(vec![]);
    /// cell.merge(vec![0, 4, 8]);
    ///
    /// let merged = cell.finish().unwrap();
    /// assert_eq!(merged, &[1, 2, 0, 4, 8]);
    /// ```
    ///
    /// [`merge()`]: MergeCell::merge
    /// [`try_finish()`]: MergeCell::try_finish
    pub fn finish(self) -> Result<T, Error> {
        self.try_finish()
            .expect("tried to .finish() an empty MergeCell")
    }

    /// Destruct the [`MergeCell`] and get back the final merged value.
    ///
    /// This is the non-panicking version of [`finish()`].
    ///
    /// Returns [`None`] if the cell is empty. Otherwise, it is functionally the
    /// same as [`finish()`].
    ///
    /// # Example
    ///
    /// ```rust
    /// # use module::merge::{Merge, MergeCell};
    /// let mut cell = MergeCell::empty();
    ///
    /// cell.merge(vec![1, 2]);
    /// cell.merge(vec![]);
    /// cell.merge(vec![0, 4, 8]);
    ///
    /// let merged = cell.try_finish().unwrap().unwrap();
    /// assert_eq!(merged, &[1, 2, 0, 4, 8]);
    /// ```
    ///
    /// [`finish()`]: MergeCell::finish
    pub fn try_finish(self) -> Option<Result<T, Error>> {
        let value = self.value?;
        let r = self.result.map(|()| value);
        Some(r)
    }
}

impl<T> MergeCell<T>
where
    T: Merge,
{
    /// Merge `other` into the cell.
    ///
    /// This function will fill the cell if it is empty.
    pub fn merge(&mut self, other: T) {
        match self.value {
            Some(ref mut value) => {
                let r = replace(&mut self.result, Ok(()));
                self.result = r.and_then(|()| value.merge_ref(other));
            }

            None => self.value = Some(other),
        }
    }
}