ifc_cost/currency.rs
1//! Currency and dimensional agreement for cost arithmetic.
2//!
3//! # Why this exists
4//!
5//! `IfcMonetaryUnit` states a currency as a plain string (`"EUR"`, `"GBP"`).
6//! Nothing in the schema stops a file carrying cost values in two currencies,
7//! and nothing marks which one a given `IfcCostValue` is in -- the currency
8//! lives on the project's `UnitsInContext`, not on the value.
9//!
10//! So summing two cost values is only meaningful when the file states exactly
11//! one monetary unit. When it states several, this crate reports the ambiguity
12//! instead of adding numbers that are not comparable. A silent sum across EUR
13//! and GBP is a wrong total that looks right, which is the worst failure mode
14//! a cost tool has.
15//!
16//! # Slots, verified against IFC4 EXPRESS
17//!
18//! ```text
19//! IfcMonetaryUnit 0 Currency (IfcLabel, not an enum in IFC4)
20//! IfcProject 8 UnitsInContext -> IfcUnitAssignment
21//! IfcUnitAssignment 0 Units SET of unit entities
22//! ```
23
24use ifc_model::{EntityId, Model, Value};
25
26/// Why a monetary total could not be trusted.
27#[derive(Debug, Clone, PartialEq, Eq)]
28#[non_exhaustive]
29pub enum CurrencyError {
30 /// The file states no monetary unit at all.
31 ///
32 /// Amounts are still readable; they simply have no stated currency, so a
33 /// total is a bare number rather than money.
34 Unstated,
35 /// The file states more than one currency.
36 ///
37 /// Every distinct currency found, sorted for determinism. Summing across
38 /// them requires an exchange rate this crate does not have and will not
39 /// invent.
40 Ambiguous {
41 /// The currencies found, sorted.
42 currencies: Vec<String>,
43 },
44}
45
46/// The single currency this file's costs are expressed in.
47///
48/// # Errors
49///
50/// [`CurrencyError::Unstated`] when no `IfcMonetaryUnit` exists, or
51/// [`CurrencyError::Ambiguous`] when the file states more than one.
52pub fn project_currency(model: &Model) -> Result<String, CurrencyError> {
53 let mut found: Vec<String> = Vec::new();
54 for (_, entity) in model.of_type("IFCMONETARYUNIT") {
55 // IFC4 relaxed Currency from IfcCurrencyEnum to IfcLabel, so it is a
56 // quoted string. Accept an enum token too: IFC2X3 files converted
57 // forward sometimes retain the older form.
58 let currency = match entity.attribute(0) {
59 Some(Value::Text(text)) => Some(text.to_string()),
60 Some(Value::Enum(token)) => Some(token.to_string()),
61 _ => None,
62 };
63 if let Some(currency) = currency {
64 if !found.contains(¤cy) {
65 found.push(currency);
66 }
67 }
68 }
69
70 match found.len() {
71 0 => Err(CurrencyError::Unstated),
72 1 => Ok(found.remove(0)),
73 _ => {
74 found.sort();
75 Err(CurrencyError::Ambiguous { currencies: found })
76 }
77 }
78}
79
80/// Every `IfcMonetaryUnit` in the file, in file order.
81#[must_use]
82pub fn monetary_units(model: &Model) -> Vec<EntityId> {
83 model.ids_of_type("IFCMONETARYUNIT").to_vec()
84}