openbim_ifc_capi/selector.rs
1//! Selectors and values by path (#464).
2//!
3//! A selector such as `IfcWall, Pset_WallCommon.IsExternal=TRUE` selects
4//! ids into the caller's buffer as `openbim_ifc_v0_1_model_ids` fills it;
5//! a value path such as `type.Name` reads one value as a tape and writes
6//! one from a tape of plain values. A query that does not parse, or names
7//! a class or attribute the declared release lacks, is `InvalidSelector`;
8//! `openbim_ifc_v0_1_last_error_span` then gives the byte range it refuses.
9
10use crate::buffer::{bytes, fill, put, slice, text};
11use crate::domains::Out;
12use crate::model::{done, with_model, OpenbimIfcModel};
13use crate::registry::{self, lock};
14use crate::status::{boundary, OpenbimIfcStatus};
15use crate::tape::{OpenbimIfcValueNode, Reader};
16
17/// The selector grammar's major version (#464); a selector written for one
18/// major version parses the same in every build of it.
19pub const OPENBIM_IFC_SELECTOR_GRAMMAR_MAJOR: u32 = 1;
20/// The selector grammar's minor version: it grows when the grammar accepts
21/// more.
22pub const OPENBIM_IFC_SELECTOR_GRAMMAR_MINOR: u32 = 0;
23
24/// The ids selector `query` (UTF-8, `query_len` bytes) selects, ascending,
25/// filling `buffer` as `openbim_ifc_v0_1_model_ids` does.
26///
27/// Class facets (subtypes included) add entities, `!` removes them;
28/// attribute, property and `type=`, `material=`, `classification=`,
29/// `location=` and `group=` facets filter; `,` chains facets and `+`
30/// unites lists. `InvalidSelector` (span through
31/// `openbim_ifc_v0_1_last_error_span`), `UnsupportedSchema`,
32/// `InvalidModel` for an ambiguous or malformed relationship or a
33/// duplicated `GlobalId` an instance facet names, `MissingReference`, and
34/// the property refusals of `openbim_ifc_v0_1_entity_property_sets`.
35///
36/// # Safety
37/// `query` valid for `query_len` reads; otherwise as for
38/// `openbim_ifc_v0_1_model_ids`.
39#[no_mangle]
40pub unsafe extern "C" fn openbim_ifc_v0_1_model_select(
41 model: OpenbimIfcModel,
42 query: *const u8,
43 query_len: usize,
44 buffer: *mut u64,
45 capacity: usize,
46 out_required: *mut usize,
47) -> OpenbimIfcStatus {
48 boundary(|| {
49 // SAFETY: caller contract above.
50 let query = match unsafe { text(query, query_len) } {
51 Ok(query) => query,
52 Err(status) => return status,
53 };
54 with_model(model, |m| {
55 let ids = m.select(query)?;
56 // SAFETY: caller contract above.
57 done(unsafe { fill(&ids, buffer, capacity, out_required) })
58 })
59 })
60}
61
62/// As [`openbim_ifc_v0_1_model_select`], selecting from the `base_count`
63/// ids at `base` alone; `MissingEntity` for one the model lacks.
64///
65/// # Safety
66/// `base` valid for `base_count` reads; otherwise as for
67/// [`openbim_ifc_v0_1_model_select`].
68#[no_mangle]
69pub unsafe extern "C" fn openbim_ifc_v0_1_model_select_from(
70 model: OpenbimIfcModel,
71 query: *const u8,
72 query_len: usize,
73 base: *const u64,
74 base_count: usize,
75 buffer: *mut u64,
76 capacity: usize,
77 out_required: *mut usize,
78) -> OpenbimIfcStatus {
79 boundary(|| {
80 // SAFETY: caller contract above.
81 let inputs = unsafe { (text(query, query_len), slice(base, base_count)) };
82 let (query, base) = match inputs {
83 (Ok(query), Ok(base)) => (query, base),
84 (Err(status), _) | (_, Err(status)) => return status,
85 };
86 with_model(model, |m| {
87 let ids = m.select_from(query, base)?;
88 // SAFETY: caller contract above.
89 done(unsafe { fill(&ids, buffer, capacity, out_required) })
90 })
91 })
92}
93
94/// The value `path` (UTF-8, e.g. `type.Name`, `Pset_WallCommon.FireRating`)
95/// reads from entity `id`, as a value tape: a scalar or reference as its
96/// node, several values as a `LIST`, a property set as a `LIST` of
97/// two-item `LIST`s, each the member's name (`TEXT`) and value.
98///
99/// `InvalidSelector` for a path that does not parse, `MissingEntity`, and
100/// as for [`openbim_ifc_v0_1_model_select`].
101///
102/// # Safety
103/// `path` valid for `path_len` reads; otherwise as for
104/// `openbim_ifc_v0_1_entity_attribute`.
105#[no_mangle]
106pub unsafe extern "C" fn openbim_ifc_v0_1_entity_get_value(
107 model: OpenbimIfcModel,
108 id: u64,
109 path: *const u8,
110 path_len: usize,
111 nodes: *mut OpenbimIfcValueNode,
112 node_capacity: usize,
113 out_nodes_required: *mut usize,
114 strings: *mut u8,
115 string_capacity: usize,
116 out_strings_required: *mut usize,
117) -> OpenbimIfcStatus {
118 let out = Out {
119 nodes,
120 node_capacity,
121 out_nodes_required,
122 strings,
123 string_capacity,
124 out_strings_required,
125 };
126 boundary(|| {
127 // SAFETY: caller contract above.
128 let path = match unsafe { text(path, path_len) } {
129 Ok(path) => path,
130 Err(status) => return status,
131 };
132 with_model(model, |m| {
133 let value = m.get_value(id, path)?.to_tagged();
134 // SAFETY: caller contract above.
135 unsafe { out.write(&value) }
136 })
137 })
138}
139
140/// Write a one-value tape of plain values at `path` (UTF-8) of entity
141/// `id`, as one transaction: an attribute (`Name`, `type.Name`) coerced
142/// as `openbim_ifc_v0_1_entity_set_attribute_by_name_plain` coerces it,
143/// or a property (`Pset_WallCommon.FireRating`) from a `TYPED` value, or a
144/// plain one when the property already states its type. A refusal
145/// changes nothing.
146///
147/// `InvalidValue` for a path that names no single value (a pattern,
148/// `count`, a prefix reaching no entity), `UnknownAttribute`,
149/// `DerivedAttribute`, `TypeMismatch` (also for a plain value no stated
150/// property types), `AmbiguousValue`, and the property edit's refusals.
151///
152/// # Safety
153/// `path` valid for `path_len` reads; the tape as for
154/// `openbim_ifc_v0_1_entity_set_attribute_by_name_plain`.
155#[no_mangle]
156pub unsafe extern "C" fn openbim_ifc_v0_1_entity_set_value(
157 model: OpenbimIfcModel,
158 id: u64,
159 path: *const u8,
160 path_len: usize,
161 nodes: *const OpenbimIfcValueNode,
162 node_count: usize,
163 strings: *const u8,
164 string_len: usize,
165) -> OpenbimIfcStatus {
166 boundary(|| {
167 // SAFETY: caller contract above.
168 let inputs = unsafe {
169 (
170 text(path, path_len),
171 slice(nodes, node_count),
172 bytes(strings, string_len),
173 )
174 };
175 let (path, nodes, strings) = match inputs {
176 (Ok(a), Ok(b), Ok(c)) => (a, b, c),
177 (Err(status), ..) | (_, Err(status), _) | (.., Err(status)) => return status,
178 };
179 with_model(model, |m| {
180 let value = Reader::new(nodes, strings).plain_single()?;
181 m.set_value(id, path, value)?;
182 done(OpenbimIfcStatus::Ok)
183 })
184 })
185}
186
187/// The byte range in the query the last error on `model` refuses, written
188/// to `out_start` and `out_end`; `NoValue` when the last call succeeded or
189/// its error names no span (only `InvalidSelector` does).
190///
191/// # Safety
192/// `out_start` and `out_end` valid for one write each.
193#[no_mangle]
194pub unsafe extern "C" fn openbim_ifc_v0_1_last_error_span(
195 model: OpenbimIfcModel,
196 out_start: *mut usize,
197 out_end: *mut usize,
198) -> OpenbimIfcStatus {
199 boundary(|| {
200 if out_start.is_null() || out_end.is_null() {
201 return OpenbimIfcStatus::NullPointer;
202 }
203 let Some(shared) = registry::get(model) else {
204 return OpenbimIfcStatus::InvalidHandle;
205 };
206 // Read without going through `with_model`, which would clear the
207 // error.
208 let entry = lock(&shared);
209 let Some((start, end)) = entry.last_error.as_ref().and_then(|error| error.span()) else {
210 return OpenbimIfcStatus::NoValue;
211 };
212 // SAFETY: checked non-null; caller contract above.
213 match unsafe { (put(out_start, start), put(out_end, end)) } {
214 (Ok(()), Ok(())) => OpenbimIfcStatus::Ok,
215 (Err(status), _) | (_, Err(status)) => status,
216 }
217 })
218}