openbim_ifc_capi/lib.rs
1//! Versioned C ABI for the IFC facade (ADR 0013, #38).
2//!
3//! Every export is prefixed `openbim_ifc_v0_1_` and follows the conventions
4//! of Axiolid's C ABI (its ADR 0040), so a native host can use both the same
5//! way:
6//!
7//! - Models are opaque non-zero `u64` handles, never Rust addresses. A stale
8//! or twice-destroyed handle is [`OpenbimIfcStatus::InvalidHandle`].
9//! - The caller owns every output buffer. Each such call writes the size it
10//! needs to `out_required` first; a null buffer with capacity 0 is the size
11//! query, and a short buffer is [`OpenbimIfcStatus::BufferTooSmall`]. No
12//! Rust allocation crosses the boundary, so there is no free function.
13//! - Every export runs inside `catch_unwind`; a panic becomes
14//! [`OpenbimIfcStatus::Panic`] and never unwinds into C.
15//! - C integers are validated as integers, never read as Rust enums.
16//!
17//! Attribute values cross as a *value tape*: a flat pre-order array of
18//! [`OpenbimIfcValueNode`] plus one byte buffer holding every string. See
19//! [`tape`] for the encoding, which carries the same kinds as the other
20//! bindings so `$`/`*`, `.U.`/`.F.` and typed wrappers stay distinct.
21//!
22//! Reading and writing caller-provided C buffers cannot be done without
23//! `unsafe`, so this crate's unsafe surface is its whole export set. It is
24//! not the only unsafe code in the workspace: the opt-in memory-mapped read
25//! (`ifc_step::StepReader::read_path_mapped`, wrapped by
26//! `openbim-ifc-binding-core` and `openbim-ifc-py`) is an `unsafe fn` too,
27//! because another process may change a mapped file. Here, each dereference
28//! sits in `buffer` or directly beside its null/length check, with a
29//! `SAFETY` comment.
30//!
31//! The conventions above mirror Axiolid's ADR 0040 on purpose. A divergence
32//! needs its reason recorded in the module docs or an ADR. ABI 0.1 symbols
33//! are frozen once released: a change adds `openbim_ifc_v0_2_` exports rather
34//! than altering a `v0_1_` one.
35
36#![deny(unsafe_op_in_unsafe_fn)]
37
38mod attributes;
39mod authoring;
40mod buffer;
41mod checks;
42mod copying;
43mod curves;
44mod domains;
45mod edits;
46mod errors;
47mod geometry;
48mod graph;
49mod header;
50mod history;
51mod ifczip;
52mod inverse;
53mod model;
54mod open;
55mod options;
56mod registry;
57mod relations;
58mod removal;
59mod selector;
60mod status;
61mod table;
62pub mod tape;
63mod units;
64mod xml;
65
66pub use attributes::*;
67pub use authoring::*;
68pub use checks::*;
69pub use copying::*;
70pub use curves::*;
71pub use domains::*;
72pub use edits::*;
73pub use errors::*;
74pub use geometry::*;
75pub use graph::*;
76pub use header::*;
77pub use history::*;
78pub use ifczip::*;
79pub use inverse::*;
80pub use model::*;
81pub use open::*;
82pub use options::*;
83pub use relations::*;
84pub use removal::*;
85pub use selector::*;
86pub use status::{OpenbimIfcStatus, OpenbimIfcVersion};
87pub use table::*;
88pub use tape::OpenbimIfcValueNode;
89pub use units::*;
90pub use xml::*;
91
92/// Opt-in allocator (feature `rusty_alloc`, off by default). It only covers
93/// this library's Rust allocations; the host's `malloc` is untouched, and
94/// no Rust allocation crosses the ABI, so the host never frees one. See
95/// #49 for the measurements.
96#[cfg(test)]
97mod authoring_tests;
98#[cfg(test)]
99mod capability_tests;
100#[cfg(test)]
101mod copying_tests;
102#[cfg(test)]
103mod domain_tests;
104#[cfg(test)]
105mod geometry_tests;
106#[cfg(test)]
107mod graph_tests;
108#[cfg(test)]
109mod history_tests;
110#[cfg(test)]
111mod inverse_tests;
112#[cfg(test)]
113mod plain_tests;
114#[cfg(test)]
115mod relations_tests;
116#[cfg(test)]
117mod removal_tests;
118#[cfg(test)]
119mod selector_tests;
120#[cfg(test)]
121mod table_tests;
122#[cfg(test)]
123mod units_tests;
124
125#[cfg(feature = "rusty_alloc")]
126#[global_allocator]
127static ALLOCATOR: rusty_alloc_api::RustyAlloc = rusty_alloc_api::RustyAlloc;