openbim_ifc_capi/attributes.rs
1//! Entity attributes by name (#326), resolved against the release the
2//! file's header declares.
3//!
4//! Names match ASCII case-insensitively and answers spell them as the
5//! schema does. The positional exports (`openbim_ifc_v0_1_entity_attribute`,
6//! `openbim_ifc_v0_1_entity_set_attribute`) are unchanged; these resolve a
7//! name to its slot first, in the shared core.
8//!
9//! `openbim_ifc_v0_1_entity_set_attribute_by_name_plain` (#342) reads its
10//! tape as plain host values and coerces them against the attribute's
11//! declared type; the shared core's `coerce` module states the rules.
12
13use openbim_ifc_binding_core::record::to_records;
14
15use crate::buffer::{bytes, slice, text};
16use crate::domains::{list_export, Out};
17use crate::model::{done, with_model, OpenbimIfcModel};
18use crate::status::{boundary, OpenbimIfcStatus};
19use crate::tape::{OpenbimIfcValueNode, Reader};
20
21/// Every explicit attribute of entity `id` in slot order, inherited first:
22/// a `LIST` of `AttributeInfo` records, their number in `out_count`.
23/// `AttributeInfo`: name (`TEXT`, the schema's spelling), index
24/// (`INTEGER`, the slot), type name (`TEXT`), optional (`BOOL`), aggregate
25/// (`BOOL`), derived (`BOOL`: written `*`, not writable), declared by
26/// (`TEXT`, the entity introducing it). `INVERSE` attributes hold no slot
27/// and are listed by `openbim_ifc_v0_1_entity_inverse_attribute_names`.
28///
29/// `MissingEntity`; `UnsupportedSchema` when the header names no bundled
30/// release or the release does not declare the entity's type.
31///
32/// # Safety
33/// `out_count` valid for one write; otherwise as for
34/// `openbim_ifc_v0_1_entity_attribute`.
35#[no_mangle]
36pub unsafe extern "C" fn openbim_ifc_v0_1_entity_attribute_names(
37 model: OpenbimIfcModel,
38 id: u64,
39 out_count: *mut usize,
40 nodes: *mut OpenbimIfcValueNode,
41 node_capacity: usize,
42 out_nodes_required: *mut usize,
43 strings: *mut u8,
44 string_capacity: usize,
45 out_strings_required: *mut usize,
46) -> OpenbimIfcStatus {
47 let out = Out {
48 nodes,
49 node_capacity,
50 out_nodes_required,
51 strings,
52 string_capacity,
53 out_strings_required,
54 };
55 // SAFETY: caller contract above.
56 unsafe {
57 list_export(model, out_count, out, |m| {
58 Ok(to_records(&m.attribute_names(id)?))
59 })
60 }
61}
62
63/// Attribute `name` (UTF-8, `name_len` bytes, any case, e.g. `Name`) of
64/// entity `id` as a value tape; `NULL` when the record stops before its
65/// slot.
66///
67/// An `INVERSE` name (`IsDefinedBy`, #462) reads the entities referencing
68/// `id` through the declared release's `FOR` clause: a `LIST` of `REF`s
69/// in ascending id order for a `SET` or `BAG` (`SET [0:1]` included: zero
70/// or one element), a `REF` or `NULL` for a single-valued inverse, which
71/// two referrers refuse with `InvalidModel`.
72///
73/// `MissingEntity`, `UnknownAttribute`, `UnsupportedSchema` as for
74/// [`openbim_ifc_v0_1_entity_attribute_names`].
75///
76/// # Safety
77/// `name` valid for `name_len` reads; otherwise as for
78/// `openbim_ifc_v0_1_entity_attribute`.
79#[no_mangle]
80pub unsafe extern "C" fn openbim_ifc_v0_1_entity_attribute_by_name(
81 model: OpenbimIfcModel,
82 id: u64,
83 name: *const u8,
84 name_len: usize,
85 nodes: *mut OpenbimIfcValueNode,
86 node_capacity: usize,
87 out_nodes_required: *mut usize,
88 strings: *mut u8,
89 string_capacity: usize,
90 out_strings_required: *mut usize,
91) -> OpenbimIfcStatus {
92 let out = Out {
93 nodes,
94 node_capacity,
95 out_nodes_required,
96 strings,
97 string_capacity,
98 out_strings_required,
99 };
100 boundary(|| {
101 // SAFETY: caller contract above.
102 let name = match unsafe { text(name, name_len) } {
103 Ok(name) => name,
104 Err(status) => return status,
105 };
106 with_model(model, |m| {
107 let value = m.attribute_by_name(id, name)?;
108 // SAFETY: caller contract above.
109 unsafe { out.write(&value) }
110 })
111 })
112}
113
114/// Set attribute `name` (UTF-8, any case) of entity `id` from a one-value
115/// tape. Every check runs before the write, so a refusal changes nothing.
116///
117/// `DerivedAttribute` for a slot the entity's type derives (written `*`);
118/// `InverseAttribute` for an `INVERSE` name, which holds no slot; otherwise as for [`openbim_ifc_v0_1_entity_attribute_by_name`] and
119/// `openbim_ifc_v0_1_entity_set_attribute`.
120///
121/// # Safety
122/// `name` valid for `name_len` reads; the tape as for
123/// `openbim_ifc_v0_1_entity_set_attribute`.
124#[no_mangle]
125pub unsafe extern "C" fn openbim_ifc_v0_1_entity_set_attribute_by_name(
126 model: OpenbimIfcModel,
127 id: u64,
128 name: *const u8,
129 name_len: usize,
130 nodes: *const OpenbimIfcValueNode,
131 node_count: usize,
132 strings: *const u8,
133 string_len: usize,
134) -> OpenbimIfcStatus {
135 boundary(|| {
136 // SAFETY: caller contract above.
137 let inputs = unsafe {
138 (
139 text(name, name_len),
140 slice(nodes, node_count),
141 bytes(strings, string_len),
142 )
143 };
144 let (name, nodes, strings) = match inputs {
145 (Ok(a), Ok(b), Ok(c)) => (a, b, c),
146 (Err(status), ..) | (_, Err(status), _) | (.., Err(status)) => return status,
147 };
148 with_model(model, |m| {
149 let value = Reader::new(nodes, strings).single()?;
150 m.set_attribute_by_name(id, name, value)?;
151 done(OpenbimIfcStatus::Ok)
152 })
153 })
154}
155
156/// Set attribute `name` (UTF-8, any case) of entity `id` from a one-value
157/// tape of plain values, coerced against the attribute's declared type in
158/// the declared release (#342); returns as
159/// [`openbim_ifc_v0_1_entity_set_attribute_by_name`] does.
160///
161/// `TEXT` is a string, `INTEGER` an integer, `REAL` a float, `BOOL` a
162/// boolean, `REF` an entity handle, `LIST` a sequence of plain values,
163/// `NULL` unset. A string becomes a label (bare) or the enumeration item it
164/// names; an integer an `INTEGER` or `REAL` as declared; a reference is
165/// checked to exist and fit; in a SELECT, the one member that takes the
166/// value is written as a typed parameter. An `EXACT` node's child, and
167/// `DERIVED`, `UNKNOWN`, `BINARY`, `ENUM` and `TYPED` nodes, are written as
168/// given.
169///
170/// `TypeMismatch` for a value that does not fit, `AmbiguousValue` for one
171/// several SELECT members take, `MissingReference` for a reference to a
172/// missing entity, `Unsupported` for a declared type the tables do not
173/// resolve; otherwise as for
174/// [`openbim_ifc_v0_1_entity_set_attribute_by_name`]. A refusal changes
175/// nothing.
176///
177/// # Safety
178/// As for [`openbim_ifc_v0_1_entity_set_attribute_by_name`].
179#[no_mangle]
180pub unsafe extern "C" fn openbim_ifc_v0_1_entity_set_attribute_by_name_plain(
181 model: OpenbimIfcModel,
182 id: u64,
183 name: *const u8,
184 name_len: usize,
185 nodes: *const OpenbimIfcValueNode,
186 node_count: usize,
187 strings: *const u8,
188 string_len: usize,
189) -> OpenbimIfcStatus {
190 boundary(|| {
191 // SAFETY: caller contract above.
192 let inputs = unsafe {
193 (
194 text(name, name_len),
195 slice(nodes, node_count),
196 bytes(strings, string_len),
197 )
198 };
199 let (name, nodes, strings) = match inputs {
200 (Ok(a), Ok(b), Ok(c)) => (a, b, c),
201 (Err(status), ..) | (_, Err(status), _) | (.., Err(status)) => return status,
202 };
203 with_model(model, |m| {
204 let value = Reader::new(nodes, strings).plain_single()?;
205 m.set_attribute_by_name_plain(id, name, value)?;
206 done(OpenbimIfcStatus::Ok)
207 })
208 })
209}