ifc_schema/version.rs
1//! Which IFC schema version a file declares.
2//!
3//! The token comes from the `FILE_SCHEMA` entry in a STEP header. Real files
4//! carry variants (`IFC4X3_ADD2` as well as `IFC4X3`), so matching is explicit
5//! rather than a prefix test: `IFC4X1` and `IFC4X2` are their own releases,
6//! never a prefix match onto IFC4. Each release's accepted tokens are its
7//! `SCHEMA` name as declared in its normative EXPRESS file (`SCHEMA IFC4X1;`,
8//! `SCHEMA IFC4X2;`), which is what ISO 10303-21 writes into `FILE_SCHEMA`.
9//!
10//! # Known releases without a published schema
11//!
12//! `IFC4X3_TC1` (IFC 4.3.0.1) and `IFC4X3_ADD1` (IFC 4.3.1.0) are real
13//! identifiers: buildingSMART's IFC4.x-development generator wrote them as
14//! the `SCHEMA` name of the ISO build before `IFC4X3_ADD2` (4.3.2.0).
15//! buildingSMART publishes no EXPRESS file for either, and their content
16//! differs from ADD2 (TC1 predates `IfcGeographicCRS`, `IfcWellKnownText`
17//! and others), so neither can have tables of its own nor be read as
18//! ADD2 by assumption. [`SchemaVersion::from_header_token`] does not
19//! recognise them; [`UnpublishedRelease::from_header_token`] names them, so
20//! a caller can refuse them precisely rather than as an unknown token
21//! (#467). A caller that chooses to read such a file as IFC4X3 ADD2 does
22//! so explicitly, by passing [`UnpublishedRelease::superseded_by`]'s tables
23//! itself, and owns that choice.
24
25/// Which IFC schema version a table describes.
26///
27/// `#[non_exhaustive]`: a release added later is a new variant, and a
28/// consumer's `match` must say what it does with a release it has not
29/// proven -- refuse it, never alias it to a neighbour.
30#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
31#[non_exhaustive]
32pub enum SchemaVersion {
33 /// IFC2x3 TC1 — 653 entities. Still the most common in the wild.
34 Ifc2x3,
35 /// IFC4 ADD2 TC1 — 776 entities. The ISO-standard release.
36 Ifc4,
37 /// IFC4x1 FINAL — 801 entities. Adds alignment (`IfcAlignment` and its
38 /// curves) to IFC4.
39 Ifc4x1,
40 /// IFC4x2 FINAL — 816 entities. Adds bridges (`IfcBridge`, `IfcFacility`)
41 /// to IFC4x1.
42 Ifc4x2,
43 /// IFC4x3 ADD2 — 876 entities. Adds alignment and civil infrastructure.
44 Ifc4x3,
45}
46
47impl SchemaVersion {
48 /// Every version this crate knows, oldest first.
49 ///
50 /// Which of them have bundled tables in a given build is a separate
51 /// question; see `for_version`.
52 pub const ALL: [Self; 5] = [
53 Self::Ifc2x3,
54 Self::Ifc4,
55 Self::Ifc4x1,
56 Self::Ifc4x2,
57 Self::Ifc4x3,
58 ];
59
60 /// Exact published release identifier for the bundled structural table.
61 #[must_use]
62 pub const fn release_id(self) -> &'static str {
63 match self {
64 Self::Ifc2x3 => "IFC2X3_TC1",
65 Self::Ifc4 => "IFC4_ADD2_TC1",
66 Self::Ifc4x1 => "IFC4X1_FINAL",
67 Self::Ifc4x2 => "IFC4X2_FINAL",
68 Self::Ifc4x3 => "IFC4X3_ADD2",
69 }
70 }
71
72 /// Entity count asserted when the bundled artifact is generated.
73 #[must_use]
74 pub const fn expected_entity_count(self) -> usize {
75 match self {
76 Self::Ifc2x3 => 653,
77 Self::Ifc4 => 776,
78 Self::Ifc4x1 => 801,
79 Self::Ifc4x2 => 816,
80 Self::Ifc4x3 => 876,
81 }
82 }
83
84 /// Defined-type count asserted when the bundled artifact is generated.
85 #[must_use]
86 pub const fn expected_type_count(self) -> usize {
87 match self {
88 Self::Ifc2x3 => 327,
89 Self::Ifc4 => 397,
90 Self::Ifc4x1 => 400,
91 Self::Ifc4x2 => 407,
92 Self::Ifc4x3 => 436,
93 }
94 }
95
96 /// Header tokens accepted for this release, excluding case-only variants.
97 #[must_use]
98 pub const fn header_tokens(self) -> &'static [&'static str] {
99 match self {
100 Self::Ifc2x3 => &["IFC2X3"],
101 Self::Ifc4 => &["IFC4"],
102 Self::Ifc4x1 => &["IFC4X1"],
103 Self::Ifc4x2 => &["IFC4X2"],
104 Self::Ifc4x3 => &["IFC4X3", "IFC4X3_ADD2"],
105 }
106 }
107
108 /// The `ifc-schema` cargo feature that bundles this release's table.
109 #[must_use]
110 pub const fn feature_name(self) -> &'static str {
111 match self {
112 Self::Ifc2x3 => "ifc2x3",
113 Self::Ifc4 => "ifc4",
114 Self::Ifc4x1 => "ifc4x1",
115 Self::Ifc4x2 => "ifc4x2",
116 Self::Ifc4x3 => "ifc4x3",
117 }
118 }
119
120 /// Whether this build bundles this release's table, i.e. whether
121 /// `for_version(self)` succeeds.
122 #[must_use]
123 pub const fn is_bundled(self) -> bool {
124 match self {
125 Self::Ifc2x3 => cfg!(feature = "ifc2x3"),
126 Self::Ifc4 => cfg!(feature = "ifc4"),
127 Self::Ifc4x1 => cfg!(feature = "ifc4x1"),
128 Self::Ifc4x2 => cfg!(feature = "ifc4x2"),
129 Self::Ifc4x3 => cfg!(feature = "ifc4x3"),
130 }
131 }
132
133 /// Parse the token found in a STEP file's `FILE_SCHEMA` header entry.
134 pub fn from_header_token(token: &str) -> Option<Self> {
135 match token.trim().to_ascii_uppercase().as_str() {
136 "IFC2X3" => Some(Self::Ifc2x3),
137 "IFC4" => Some(Self::Ifc4),
138 "IFC4X1" => Some(Self::Ifc4x1),
139 "IFC4X2" => Some(Self::Ifc4x2),
140 "IFC4X3" | "IFC4X3_ADD2" => Some(Self::Ifc4x3),
141 _ => None,
142 }
143 }
144}
145
146/// An IFC release whose identifier is known but whose normative EXPRESS
147/// schema buildingSMART does not publish (#467).
148///
149/// No tables exist for it, and it is never aliased to a neighbouring
150/// release: [`SchemaVersion::from_header_token`] returns `None` for its
151/// identifier. This type lets a caller say *which* release a file
152/// declares when refusing it.
153///
154/// Source of each identifier and version number: the `SCHEMA_NAME` and
155/// documentation header of buildingSMART/IFC4.x-development's generator,
156/// `IFC4X3_TC1` "IFC 4.3.0.1" (commits `3629c4ec3e` and `623808efce`,
157/// 2022-08) and `IFC4X3_ADD1` "IFC 4.3.1.0" (commit `29f283e98f`,
158/// 2022-09), both superseded by `IFC4X3_ADD2` "IFC 4.3.2.0" (commit
159/// `524daac53c`, 2023-09), the only IFC 4.3 release buildingSMART lists
160/// and publishes as EXPRESS.
161#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
162#[non_exhaustive]
163pub enum UnpublishedRelease {
164 /// `IFC4X3_TC1`, IFC 4.3.0.1.
165 Ifc4x3Tc1,
166 /// `IFC4X3_ADD1`, IFC 4.3.1.0.
167 Ifc4x3Add1,
168}
169
170impl UnpublishedRelease {
171 /// Every unpublished release this crate names, oldest first.
172 pub const ALL: [Self; 2] = [Self::Ifc4x3Tc1, Self::Ifc4x3Add1];
173
174 /// The `SCHEMA` identifier the release's files declare in `FILE_SCHEMA`.
175 #[must_use]
176 pub const fn identifier(self) -> &'static str {
177 match self {
178 Self::Ifc4x3Tc1 => "IFC4X3_TC1",
179 Self::Ifc4x3Add1 => "IFC4X3_ADD1",
180 }
181 }
182
183 /// The four-part IFC version number of the release.
184 #[must_use]
185 pub const fn version_number(self) -> &'static str {
186 match self {
187 Self::Ifc4x3Tc1 => "4.3.0.1",
188 Self::Ifc4x3Add1 => "4.3.1.0",
189 }
190 }
191
192 /// The published release that superseded it. Not a claim that the two
193 /// schemas are identical: they are not proven to be.
194 #[must_use]
195 pub const fn superseded_by(self) -> SchemaVersion {
196 match self {
197 Self::Ifc4x3Tc1 | Self::Ifc4x3Add1 => SchemaVersion::Ifc4x3,
198 }
199 }
200
201 /// The unpublished release a `FILE_SCHEMA` token names, if any. Case
202 /// and surrounding whitespace are ignored, as for
203 /// [`SchemaVersion::from_header_token`].
204 pub fn from_header_token(token: &str) -> Option<Self> {
205 let token = token.trim();
206 Self::ALL
207 .into_iter()
208 .find(|release| release.identifier().eq_ignore_ascii_case(token))
209 }
210}
211
212#[cfg(test)]
213mod tests {
214 use super::*;
215
216 #[test]
217 fn recognizes_the_schema_tokens_our_fixtures_carry() {
218 assert_eq!(
219 SchemaVersion::from_header_token("IFC4"),
220 Some(SchemaVersion::Ifc4)
221 );
222 assert_eq!(
223 SchemaVersion::from_header_token("ifc2x3"),
224 Some(SchemaVersion::Ifc2x3)
225 );
226 assert_eq!(SchemaVersion::from_header_token("STEP"), None);
227 }
228
229 /// IFC4X3_TC1 and IFC4X3_ADD1 are named, never mapped onto the
230 /// bundled IFC4X3 ADD2 tables (#467).
231 #[test]
232 fn unpublished_ifc4x3_releases_are_named_not_aliased() {
233 for (token, release, number) in [
234 ("IFC4X3_TC1", UnpublishedRelease::Ifc4x3Tc1, "4.3.0.1"),
235 (" ifc4x3_add1 ", UnpublishedRelease::Ifc4x3Add1, "4.3.1.0"),
236 ] {
237 assert_eq!(SchemaVersion::from_header_token(token), None, "{token}");
238 assert_eq!(UnpublishedRelease::from_header_token(token), Some(release));
239 assert_eq!(release.version_number(), number);
240 assert_eq!(release.superseded_by(), SchemaVersion::Ifc4x3);
241 }
242 for version in SchemaVersion::ALL {
243 for token in version.header_tokens() {
244 assert_eq!(UnpublishedRelease::from_header_token(token), None);
245 }
246 }
247 for token in ["IFC4X3", "IFC4X3_ADD2", "IFC4X3_RC4", "IFC4X3_TC"] {
248 assert_eq!(UnpublishedRelease::from_header_token(token), None);
249 }
250 }
251
252 /// Every declared header token maps back to its own version, and the
253 /// release identifiers are distinct: IFC4X1 and IFC4X2 are neither IFC4
254 /// nor IFC4X3.
255 #[test]
256 fn header_tokens_and_release_ids_round_trip_for_every_version() {
257 for version in SchemaVersion::ALL {
258 for token in version.header_tokens() {
259 assert_eq!(SchemaVersion::from_header_token(token), Some(version));
260 assert_eq!(
261 SchemaVersion::from_header_token(&token.to_ascii_lowercase()),
262 Some(version)
263 );
264 }
265 }
266 assert_eq!(
267 SchemaVersion::from_header_token("IFC4X1"),
268 Some(SchemaVersion::Ifc4x1)
269 );
270 assert_eq!(
271 SchemaVersion::from_header_token(" ifc4x2 "),
272 Some(SchemaVersion::Ifc4x2)
273 );
274 assert_eq!(SchemaVersion::Ifc4x1.release_id(), "IFC4X1_FINAL");
275 assert_eq!(SchemaVersion::Ifc4x2.release_id(), "IFC4X2_FINAL");
276 let ids: std::collections::BTreeSet<_> =
277 SchemaVersion::ALL.iter().map(|v| v.release_id()).collect();
278 assert_eq!(ids.len(), SchemaVersion::ALL.len());
279 }
280}