honeycomb_core/cmap/dim2/sews/
mod.rs

1mod one;
2mod two;
3
4use crate::cmap::{CMap2, DartIdType, SewError};
5use crate::geometry::CoordsFloat;
6use crate::stm::{atomically_with_err, Transaction, TransactionClosureResult};
7
8/// # **Sew implementations**
9impl<T: CoordsFloat> CMap2<T> {
10    /// `I`-sew operator.
11    ///
12    /// # Description
13    ///
14    /// This operation corresponds to:
15    /// - coherently linking two darts via their *β* images,
16    /// - merging the attributes associated to their respective original `I`-cells.
17    ///
18    /// For a thorough explanation of this operation, its hypothesis & consequences, refer
19    /// to the [user guide][UG].
20    ///
21    /// [UG]: https://lihpc-computational-geometry.github.io/honeycomb/user-guide/definitions/sew.html
22    ///
23    /// # Arguments
24    ///
25    /// - `const I: u8` -- Sew dimension.
26    /// - `trans: &mut Transaction` -- Transaction associated to the operation.
27    /// - `ld: DartIdType` -- First dart ID.
28    /// - `rd: DartIdType` -- Second dart ID.
29    ///
30    /// # Errors
31    ///
32    /// This variant will abort the sew operation and raise an error if:
33    /// - the transaction cannot be completed,
34    /// - one (or more) attribute merge fails,
35    /// - for `I == 2`: orientation is inconsistent.
36    ///
37    /// The returned error can be used in conjunction with transaction control to avoid any
38    /// modifications in case of failure at attribute level. The user can then choose to retry or
39    /// abort as he wishes using `Transaction::with_control`.
40    ///
41    /// # Panics
42    ///
43    /// The method may panic if:
44    /// - `I >= 3` or `I == 0`,
45    /// - the two darts are not `I`-sewable.
46    pub fn sew<const I: u8>(
47        &self,
48        trans: &mut Transaction,
49        ld: DartIdType,
50        rd: DartIdType,
51    ) -> TransactionClosureResult<(), SewError> {
52        // these assertions + match on a const are optimized away
53        assert!(I < 3);
54        assert_ne!(I, 0);
55        match I {
56            1 => self.one_sew(trans, ld, rd),
57            2 => self.two_sew(trans, ld, rd),
58            _ => unreachable!(),
59        }
60    }
61
62    /// `I`-unsew operator.
63    ///
64    /// # Description
65    ///
66    /// This operation corresponds to:
67    /// - unlinking two darts by resetting their *β* images,
68    /// - splitting the attributes associated to the original `I`-cell.
69    ///
70    /// For a thorough explanation of this operation, its hypothesis & consequences, refer
71    /// to the [user guide][UG].
72    ///
73    /// [UG]: https://lihpc-computational-geometry.github.io/honeycomb/user-guide/definitions/sew.html
74    ///
75    /// # Arguments
76    ///
77    /// - `const I: u8` -- Unsew dimension.
78    /// - `trans: &mut Transaction` -- Transaction associated to the operation.
79    /// - `ld: DartIdType` -- First dart ID.
80    ///
81    /// The second dart ID is fetched using `I` and `ld`.
82    ///
83    /// # Errors
84    ///
85    /// This variant will abort the unsew operation and raise an error if:
86    /// - the transaction cannot be completed,
87    /// - one (or more) attribute split fails,
88    ///
89    /// The returned error can be used in conjunction with transaction control to avoid any
90    /// modifications in case of failure at attribute level. The user can then choose to retry or
91    /// abort as he wishes using `Transaction::with_control`.
92    ///
93    /// # Panics
94    ///
95    /// The method may panic if:
96    /// - `I >= 3` or `I == 0`,
97    /// - `ld` is already `I`-free.
98    pub fn unsew<const I: u8>(
99        &self,
100        trans: &mut Transaction,
101        ld: DartIdType,
102    ) -> TransactionClosureResult<(), SewError> {
103        // these assertions + match on a const are optimized away
104        assert!(I < 3);
105        assert_ne!(I, 0);
106        match I {
107            1 => self.one_unsew(trans, ld),
108            2 => self.two_unsew(trans, ld),
109            _ => unreachable!(),
110        }
111    }
112
113    #[allow(clippy::missing_errors_doc, clippy::missing_panics_doc)]
114    /// `I`-sew operator.
115    ///
116    /// This variant is equivalent to [`sew`][Self::sew], but internally uses a transaction that
117    /// will be retried until validated.
118    pub fn force_sew<const I: u8>(&self, ld: DartIdType, rd: DartIdType) -> Result<(), SewError> {
119        // these assertions + match on a const are optimized away
120        assert!(I < 3);
121        assert_ne!(I, 0);
122        match I {
123            1 => atomically_with_err(|trans| self.one_sew(trans, ld, rd)),
124            2 => atomically_with_err(|trans| self.two_sew(trans, ld, rd)),
125            _ => unreachable!(),
126        }
127    }
128
129    #[allow(clippy::missing_errors_doc, clippy::missing_panics_doc)]
130    /// `I`-unsew operator.
131    ///
132    /// This variant is equivalent to [`unsew`][Self::unsew], but internally uses a transaction that
133    /// will be retried until validated.
134    pub fn force_unsew<const I: u8>(&self, ld: DartIdType) -> Result<(), SewError> {
135        // these assertions + match on a const are optimized away
136        assert!(I < 3);
137        assert_ne!(I, 0);
138        match I {
139            1 => atomically_with_err(|trans| self.one_unsew(trans, ld)),
140            2 => atomically_with_err(|trans| self.two_unsew(trans, ld)),
141            _ => unreachable!(),
142        }
143    }
144}
honeycomb_core/cmap/dim2/sews/mod.rs

honeycomb_core/cmap/dim2/sews/
mod.rs
