Skip to main content

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}