Skip to main content

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}