Skip to main content

openbim_ifc_capi/
history.rs

1//! Undo and redo (#465).
2//!
3//! History is off until `openbim_ifc_v0_1_model_set_history_limit` gives it
4//! a bound; then each mutating export is one undo entry. `undo` and `redo`
5//! answer with a `HistoryChange` record tape: created (`LIST` of `REF`),
6//! removed (`LIST` of `REF`), modified (`LIST` of `REF`), header (`BOOL`).
7//!
8//! The buffer protocol never applies a step it cannot report: the call
9//! peeks first, and a size query or a short buffer answers `BufferTooSmall`
10//! with the sizes and leaves the model unchanged. The applied change has the
11//! peeked one's size.
12
13use openbim_ifc_binding_core::{BindingError, HistoryChange, IfcModel, ToRecord};
14
15use crate::buffer::put;
16use crate::domains::Out;
17use crate::model::{done, with_model, OpenbimIfcModel};
18use crate::status::{boundary, OpenbimIfcStatus};
19use crate::tape::{OpenbimIfcValueNode, Tape};
20
21/// How much history a model holds (`HistoryState`).
22#[repr(C)]
23#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
24pub struct OpenbimIfcHistoryState {
25    /// The bound on undo entries; 0 records nothing.
26    pub limit: usize,
27    /// Entries `openbim_ifc_v0_1_model_undo` can step back through.
28    pub undo: usize,
29    /// Entries `openbim_ifc_v0_1_model_redo` can step forward through.
30    pub redo: usize,
31}
32
33/// Bound the undo entries a model keeps. 0 turns history off and drops what
34/// is held; a lower limit drops the oldest entries. History is off (0) for a
35/// new model.
36#[no_mangle]
37pub extern "C" fn openbim_ifc_v0_1_model_set_history_limit(
38    model: OpenbimIfcModel,
39    limit: usize,
40) -> OpenbimIfcStatus {
41    boundary(|| {
42        with_model(model, |m| {
43            m.set_history_limit(limit);
44            Ok(OpenbimIfcStatus::Ok)
45        })
46    })
47}
48
49/// Write the history bound and how many entries each direction holds.
50///
51/// # Safety
52/// `out_state` must be null or valid for one write.
53#[no_mangle]
54pub unsafe extern "C" fn openbim_ifc_v0_1_model_history(
55    model: OpenbimIfcModel,
56    out_state: *mut OpenbimIfcHistoryState,
57) -> OpenbimIfcStatus {
58    boundary(|| {
59        if out_state.is_null() {
60            return OpenbimIfcStatus::NullPointer;
61        }
62        with_model(model, |m| {
63            let state = m.history();
64            let state = OpenbimIfcHistoryState {
65                limit: state.limit,
66                undo: state.undo,
67                redo: state.redo,
68            };
69            // SAFETY: checked non-null; caller contract above.
70            done(match unsafe { put(out_state, state) } {
71                Ok(()) => OpenbimIfcStatus::Ok,
72                Err(status) => status,
73            })
74        })
75    })
76}
77
78/// Drop every undo and redo entry, keeping the limit.
79#[no_mangle]
80pub extern "C" fn openbim_ifc_v0_1_model_clear_history(model: OpenbimIfcModel) -> OpenbimIfcStatus {
81    boundary(|| {
82        with_model(model, |m| {
83            m.clear_history();
84            Ok(OpenbimIfcStatus::Ok)
85        })
86    })
87}
88
89/// Peek with `peek`; then write the change, applying it with `apply` first
90/// only when it fits.
91///
92/// # Safety
93/// The buffers as for `Out`.
94unsafe fn step_export(
95    model: OpenbimIfcModel,
96    out: &Out,
97    peek: impl Fn(&IfcModel) -> Result<HistoryChange, BindingError>,
98    apply: impl Fn(&mut IfcModel) -> Result<HistoryChange, BindingError>,
99) -> OpenbimIfcStatus {
100    boundary(|| {
101        with_model(model, |m| {
102            if let Err(status) = out.check() {
103                return done(status);
104            }
105            let planned = peek(m)?;
106            let tape = Tape::encode(&planned.to_record().to_tagged());
107            let fits =
108                tape.nodes.len() <= out.node_capacity && tape.strings.len() <= out.string_capacity;
109            let change = if fits { apply(m)? } else { planned };
110            // SAFETY: caller contract.
111            unsafe { out.write(&change.to_record().to_tagged()) }
112        })
113    })
114}
115
116/// Restore the model to the state before the last recorded change: entities
117/// under their ids and at their file positions, the header included. The
118/// answer is a `HistoryChange` tape: created, removed and modified (`LIST`s
119/// of `REF`) and header (`BOOL`). A size query or a short buffer peeks the
120/// step and answers `BufferTooSmall` without applying it.
121///
122/// `HistoryEmpty` with nothing to undo (history off, or the stack empty);
123/// `HistoryStale` when the model changed outside the history.
124///
125/// # Safety
126/// As for `openbim_ifc_v0_1_entity_attribute`.
127#[no_mangle]
128pub unsafe extern "C" fn openbim_ifc_v0_1_model_undo(
129    model: OpenbimIfcModel,
130    nodes: *mut OpenbimIfcValueNode,
131    node_capacity: usize,
132    out_nodes_required: *mut usize,
133    strings: *mut u8,
134    string_capacity: usize,
135    out_strings_required: *mut usize,
136) -> OpenbimIfcStatus {
137    let out = Out {
138        nodes,
139        node_capacity,
140        out_nodes_required,
141        strings,
142        string_capacity,
143        out_strings_required,
144    };
145    // SAFETY: caller contract above.
146    unsafe { step_export(model, &out, IfcModel::peek_undo, IfcModel::undo) }
147}
148
149/// Reverse the last undo. The answer and the buffer protocol are those of
150/// `openbim_ifc_v0_1_model_undo`; `HistoryEmpty` with nothing to redo.
151///
152/// # Safety
153/// As for `openbim_ifc_v0_1_entity_attribute`.
154#[no_mangle]
155pub unsafe extern "C" fn openbim_ifc_v0_1_model_redo(
156    model: OpenbimIfcModel,
157    nodes: *mut OpenbimIfcValueNode,
158    node_capacity: usize,
159    out_nodes_required: *mut usize,
160    strings: *mut u8,
161    string_capacity: usize,
162    out_strings_required: *mut usize,
163) -> OpenbimIfcStatus {
164    let out = Out {
165        nodes,
166        node_capacity,
167        out_nodes_required,
168        strings,
169        string_capacity,
170        out_strings_required,
171    };
172    // SAFETY: caller contract above.
173    unsafe { step_export(model, &out, IfcModel::peek_redo, IfcModel::redo) }
174}