Skip to main content

ifc_model/mutation/
record.rs

1//! Recording: capture the exact inverse of a run of model writes.
2//!
3//! While a recording is open, every primitive write (`insert`, `push`,
4//! `set_attribute`, `set_attributes`, `truncate_attributes`, `retype`, `remove`,
5//! `header_mut`,
6//! `reserve_ids_through`) keeps the step that undoes it. Ending the recording
7//! yields an [`Inverse`].
8//!
9//! Recordings nest. The inner recording's inverse is returned to its caller
10//! and its steps also join the enclosing recording, so the outer inverse
11//! undoes everything the inner one did and more.
12//!
13//! Outside a recording nothing is captured and a write pays one emptiness
14//! check.
15
16use crate::model::Model;
17use crate::mutation::inverse::Inverse;
18use crate::mutation::step::Step;
19
20/// The writes of one open recording.
21#[derive(Debug, Clone)]
22pub(crate) struct Segment {
23    /// Undoing steps in the order the writes happened.
24    pub(crate) steps: Vec<Step>,
25    /// `max_id` when the recording began.
26    pub(crate) max_id: u64,
27    /// The revision when the recording began.
28    pub(crate) revision: u64,
29}
30
31/// The open recordings of a model. A clone is not recording: its writes are
32/// not the original's to capture.
33#[derive(Debug, Default)]
34pub(crate) struct Recording(pub(crate) Vec<Segment>);
35
36impl Clone for Recording {
37    fn clone(&self) -> Self {
38        Self::default()
39    }
40}
41
42impl Model {
43    /// Start capturing the inverse of every write that follows.
44    ///
45    /// Nestable: each call needs its own [`Model::end_recording`].
46    pub fn begin_recording(&mut self) {
47        let segment = Segment {
48            steps: Vec::new(),
49            max_id: self.max_id(),
50            revision: self.revision(),
51        };
52        self.recording_mut().push(segment);
53    }
54
55    /// Stop the innermost recording and return the inverse of its writes,
56    /// or `None` when no recording is open.
57    ///
58    /// The inner steps are also kept by the enclosing recording, if any.
59    pub fn end_recording(&mut self) -> Option<Inverse> {
60        let segment = self.recording_mut().pop()?;
61        if let Some(outer) = self.recording_mut().last_mut() {
62            outer.steps.extend(segment.steps.iter().cloned());
63        }
64        let mut steps = segment.steps;
65        steps.reverse();
66        Some(Inverse::new(
67            steps,
68            segment.max_id,
69            segment.revision,
70            self.revision(),
71        ))
72    }
73
74    /// How many recordings are open.
75    pub(crate) fn recording_depth(&self) -> usize {
76        self.recording_len()
77    }
78
79    /// Ends recordings opened inside a change that did not end them, down to
80    /// `depth`, keeping their steps in the one below.
81    pub(crate) fn unwind_recording(&mut self, depth: usize) {
82        while self.recording_len() > depth {
83            let segment = self.recording_mut().pop().expect("depth checked");
84            if let Some(outer) = self.recording_mut().last_mut() {
85                outer.steps.extend(segment.steps);
86            }
87        }
88    }
89
90    /// Whether a recording is open.
91    pub fn is_recording(&self) -> bool {
92        !self.recording_is_empty()
93    }
94}