Skip to main content

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}