ifc_step/index.rs
1//! Offset index: what is in a file, without decoding it.
2//!
3//! # Why this exists
4//!
5//! A type census, or picking 200 walls out of nine million records, needs
6//! to know where each record is and what type it has -- not what it says.
7//! [`Index::scan`] answers that from the borrowed source: it frames every
8//! record with `openbim_step::scan` and keeps its id, byte span and type,
9//! and nothing else. It does not copy the input and does not validate the
10//! inside of a record, which makes it the cheapest way to look into a file.
11//!
12//! For a model that decodes on access with every record validated up front,
13//! read with [`StepCodec`](crate::StepCodec): a strict read is lazy.
14//!
15//! # Trust
16//!
17//! Framing is `openbim_step::scan`: the header is parsed strictly,
18//! everything between records goes through the real lexer, and junk,
19//! missing section ends or a second file appended are errors rather than
20//! skipped. Decoding a record ([`Index::entity`]) runs the same parser and
21//! the same IFC conversion as a full read, on exactly the record's bytes.
22//! `tests/index_agreement.rs` checks both against the eager reader on every
23//! fixture in the repository.
24
25use std::collections::HashMap;
26
27use ifc_model::{Entity, EntityId, Model, Value};
28use openbim_step::{ParseOptions, Span};
29
30use crate::{parser, StepError};
31
32/// What is in a file, without what it says.
33///
34/// Borrows the source bytes and stores, per record, its id, span and an
35/// index into a table of distinct type names -- about 32 bytes per entity,
36/// two orders of magnitude less than a decoded [`Model`].
37///
38/// Use [`Index::entity`] to decode one record, or [`Index::materialize_closure`]
39/// to build a real [`Model`] from a chosen subset.
40pub struct Index<'a> {
41 source: &'a [u8],
42 header: ifc_model::header::Header,
43 ids: Vec<u64>,
44 spans: Vec<Span>,
45 type_ids: Vec<u32>,
46 type_names: Vec<String>,
47 /// Position of each id in the columns. Files list ids in increasing
48 /// order in practice, where a binary search over `ids` needs nothing
49 /// extra; this map exists only for a file that does not.
50 unordered: Option<HashMap<u64, usize>>,
51}
52
53impl<'a> Index<'a> {
54 /// Frames every record of `source`. Does not decode attributes.
55 ///
56 /// # Errors
57 ///
58 /// A header or framing defect: the wrong physical-file marker, a
59 /// malformed header, anything between records that is not a record, a
60 /// missing `ENDSEC`, content after the end marker, or an instance id or
61 /// type the IFC record model cannot hold (an id beyond `u64`, a complex
62 /// instance), or two records with one id ([`StepError::DuplicateId`]).
63 /// Defects inside a record surface when it is decoded.
64 pub fn scan(source: &'a [u8]) -> Result<Self, StepError> {
65 let scanned =
66 openbim_step::scan(source).map_err(|error| StepError::from_step(source, error))?;
67 let mut header = ifc_model::header::Header::default();
68 parser::apply_header(&mut header, scanned.header().standard());
69 let mut ids = Vec::new();
70 let mut spans = Vec::new();
71 let mut type_ids = Vec::new();
72 let mut type_names: Vec<String> = Vec::new();
73 let mut seen: HashMap<String, u32> = HashMap::new();
74 let mut held = ahash::AHashSet::new();
75 for record in scanned.records() {
76 let record = record.map_err(|error| StepError::from_step(source, error))?;
77 let id = record.id.as_str().parse::<u64>().map_err(|_| {
78 unrepresentable(
79 record.span,
80 "instance id exceeds the IFC record model range",
81 )
82 })?;
83 if !held.insert(id) {
84 return Err(StepError::DuplicateId {
85 id: EntityId(id),
86 offset: record.span.start,
87 });
88 }
89 let Some(name) = record.name else {
90 return Err(unrepresentable(
91 record.span,
92 "complex STEP instances are not representable in the IFC record model",
93 ));
94 };
95 let upper = name.to_ascii_uppercase();
96 let next = u32::try_from(type_names.len()).expect("fewer than 2^32 distinct types");
97 let type_id = *seen.entry(upper.clone()).or_insert(next);
98 if type_id == next {
99 type_names.push(upper);
100 }
101 ids.push(id);
102 spans.push(record.span);
103 type_ids.push(type_id);
104 }
105 let unordered = (!ids.windows(2).all(|pair| pair[0] < pair[1])).then(|| {
106 // Ids are unique (a repeat is refused above).
107 ids.iter()
108 .enumerate()
109 .map(|(position, id)| (*id, position))
110 .collect()
111 });
112 Ok(Self {
113 source,
114 header,
115 ids,
116 spans,
117 type_ids,
118 type_names,
119 unordered,
120 })
121 }
122
123 /// Number of records found.
124 #[must_use]
125 pub fn len(&self) -> usize {
126 self.ids.len()
127 }
128
129 /// Whether the file has no data records.
130 #[must_use]
131 pub fn is_empty(&self) -> bool {
132 self.ids.is_empty()
133 }
134
135 /// The file header, as a model read would report it.
136 #[must_use]
137 pub fn header(&self) -> &ifc_model::header::Header {
138 &self.header
139 }
140
141 /// Every id, in file order.
142 pub fn ids(&self) -> impl Iterator<Item = EntityId> + '_ {
143 self.ids.iter().copied().map(EntityId)
144 }
145
146 /// Upper-cased type name of `id`, without decoding it.
147 #[must_use]
148 pub fn type_of(&self, id: EntityId) -> Option<&str> {
149 let position = self.position(id)?;
150 Some(&self.type_names[self.type_ids[position] as usize])
151 }
152
153 /// How many records of each type. The census a viewer opens with.
154 #[must_use]
155 pub fn count_by_type(&self) -> std::collections::BTreeMap<&str, usize> {
156 let mut out = std::collections::BTreeMap::new();
157 for type_id in &self.type_ids {
158 *out.entry(self.type_names[*type_id as usize].as_str())
159 .or_insert(0) += 1;
160 }
161 out
162 }
163
164 /// Ids of every record whose type matches `name`, case-insensitively,
165 /// in file order.
166 #[must_use]
167 pub fn ids_of_type(&self, name: &str) -> Vec<EntityId> {
168 let upper = name.to_ascii_uppercase();
169 let Some(type_id) = self.type_names.iter().position(|n| *n == upper) else {
170 return Vec::new();
171 };
172 let type_id = u32::try_from(type_id).expect("fewer than 2^32 distinct types");
173 self.type_ids
174 .iter()
175 .enumerate()
176 .filter(|(_, t)| **t == type_id)
177 .map(|(position, _)| EntityId(self.ids[position]))
178 .collect()
179 }
180
181 fn position(&self, id: EntityId) -> Option<usize> {
182 match &self.unordered {
183 Some(map) => map.get(&id.0).copied(),
184 None => self.ids.binary_search(&id.0).ok(),
185 }
186 }
187
188 /// Decodes one record into an [`Entity`]: the same parser and IFC
189 /// conversion a full read uses, on exactly the record's bytes.
190 ///
191 /// # Errors
192 ///
193 /// When the record is malformed or holds a value the IFC record model
194 /// cannot represent -- exactly what would make a strict read fail.
195 pub fn entity(&self, id: EntityId) -> Result<Option<Entity>, StepError> {
196 let Some(position) = self.position(id) else {
197 return Ok(None);
198 };
199 let (record, _) =
200 parser::decode(self.source, self.spans[position], ParseOptions::strict())?;
201 Ok(Some(parser::convert(record)?.1))
202 }
203
204 /// Builds a [`Model`] from exactly `wanted`, and nothing else, with the
205 /// file's header. Ids the file does not contain are skipped.
206 ///
207 /// # Dangling references
208 ///
209 /// The result is a real `Model` but not a self-contained one: an entity
210 /// that referenced `#7` still says `Ref(7)` even when `#7` was not
211 /// requested. Traversal will not resolve it. Use
212 /// [`Index::materialize_closure`] unless you specifically want the raw
213 /// subset and will handle missing targets yourself.
214 ///
215 /// # Errors
216 ///
217 /// The first wanted record that does not decode; see [`Index::entity`].
218 pub fn materialize(&self, wanted: &[EntityId]) -> Result<Model, StepError> {
219 self.build(wanted.iter().copied())
220 }
221
222 /// Builds a [`Model`] containing `wanted` and everything they reach.
223 ///
224 /// Follows references transitively, so the result has no dangling `Ref`
225 /// except to ids the file itself does not define. This is the
226 /// constructor to reach for: it is what makes a subset independently
227 /// usable.
228 ///
229 /// # Errors
230 ///
231 /// The first reached record that does not decode; see [`Index::entity`].
232 pub fn materialize_closure(&self, wanted: &[EntityId]) -> Result<Model, StepError> {
233 let mut needed: std::collections::BTreeSet<u64> = wanted.iter().map(|i| i.0).collect();
234 let mut frontier: Vec<u64> = needed.iter().copied().collect();
235 while let Some(id) = frontier.pop() {
236 let Some(entity) = self.entity(EntityId(id))? else {
237 continue;
238 };
239 for value in &entity.attributes {
240 collect_refs(value, &mut needed, &mut frontier);
241 }
242 }
243 self.build(needed.into_iter().map(EntityId))
244 }
245
246 /// Decodes `wanted` into a model, in file order, with the file's header.
247 fn build(&self, wanted: impl Iterator<Item = EntityId>) -> Result<Model, StepError> {
248 let mut positions: Vec<usize> = wanted.filter_map(|id| self.position(id)).collect();
249 positions.sort_unstable();
250 positions.dedup();
251 let mut model = Model::new();
252 *model.header_mut() = self.header.clone();
253 for position in positions {
254 let (record, _) =
255 parser::decode(self.source, self.spans[position], ParseOptions::strict())?;
256 let (id, entity) = parser::convert(record)?;
257 model.insert(id, entity);
258 }
259 Ok(model)
260 }
261}
262
263fn unrepresentable(span: Span, detail: &str) -> StepError {
264 StepError::Syntax {
265 offset: span.start,
266 detail: detail.into(),
267 }
268}
269
270/// Adds every `Ref` reachable from `value` to the work set.
271fn collect_refs(
272 value: &Value,
273 needed: &mut std::collections::BTreeSet<u64>,
274 frontier: &mut Vec<u64>,
275) {
276 match value {
277 Value::Ref(id) => {
278 if needed.insert(id.0) {
279 frontier.push(id.0);
280 }
281 }
282 Value::List(items) => {
283 for v in items {
284 collect_refs(v, needed, frontier);
285 }
286 }
287 Value::Typed { value, .. } => collect_refs(value, needed, frontier),
288 _ => {}
289 }
290}