Skip to main content

ifc_properties/convert/
named.rs

1//! The named conversion-based units: the standard designations IFC4 lists
2//! for `IfcConversionBasedUnit.Name`, with exact factors.
3//!
4//! IFC4 ADD2 TC1 `IfcConversionBasedUnit`, Table 673 "Standard unit names",
5//! names the units and describes each with a rounded factor ("'yard' |
6//! Length measure equal to 914 mm", "'mile' | ... 1609 m", "'pound' | ...
7//! 0.454 kg", "'square mile' | ... 2 588 881 square meters"). The names are
8//! the standard's; the factors here are the exact legal definitions instead,
9//! because a converter that used the table's rounding would move a mile by
10//! 344 mm:
11//!
12//! - inch, foot, yard, mile and the pound, and every unit built from them:
13//!   the international yard and pound (1959), yard = 0.9144 m and pound =
14//!   0.453 592 37 kg exactly; the inch is 25.4 mm and the foot 304.8 mm,
15//!   which the IFC table states exactly too.
16//! - gallon UK = 4.546 09 L (UK Weights and Measures Act 1985); gallon US =
17//!   231 cubic inches; pints and fluid ounces are 1/8 and 1/160 (UK) or
18//!   1/8 and 1/128 (US) of their gallon.
19//! - lbf = pound × standard gravity 9.806 65 m/s² (CGPM 1901); kip = 1000
20//!   lbf; psi = lbf per square inch.
21//! - btu: the table's 1055.056 J (the ISO 31-4 "International Table" value
22//!   rounded as the table rounds it), since several BTUs exist and the
23//!   table names this one.
24//! - degree = π/180 rad; minute, hour and day are 60, 3600 and 86 400 s.
25//!
26//! A factor whose decimal expansion terminates is kept as an integer
27//! mantissa and a power of ten, so that `foot` to `MILLI METRE` is
28//! `3048 / 10` and not `0.3048 * 1000` (#469). The degree, the psi, the ksi
29//! and the US survey foot do not terminate and are the nearest `f64`.
30//!
31//! The US survey foot (1200/3937 m, still found in older US state plane
32//! grids) is not in the IFC table; it is listed under the name `US survey
33//! foot` so that a file using it can be read, and is never chosen for a
34//! name the table defines.
35//!
36//! Temperature units with an offset (degree Fahrenheit, and degree Celsius
37//! as an `IfcConversionBasedUnitWithOffset`) are refused by name: where IFC4
38//! applies `ConversionOffset` is not settled (#110).
39
40/// One named conversion-based unit.
41#[derive(Debug, Clone, Copy, PartialEq)]
42#[non_exhaustive]
43pub struct NamedUnit {
44    /// The designation, as IFC4 Table 673 spells it (case-insensitive in a
45    /// file).
46    pub name: &'static str,
47    /// The `IfcUnitEnum` constant of the unit.
48    pub unit_type: &'static str,
49    /// SI dimensional exponents `[L, M, T, I, Θ, N, J]`.
50    pub dimensions: [i32; 7],
51    /// The factor into SI base units is `mantissa * 10^decimal_exponent`.
52    pub mantissa: f64,
53    /// See [`Self::mantissa`].
54    pub decimal_exponent: i32,
55}
56
57impl NamedUnit {
58    /// The factor into SI base units (metre, kilogram, second, radian ...).
59    #[must_use]
60    pub fn scale(&self) -> f64 {
61        super::shift(self.mantissa, self.decimal_exponent)
62    }
63}
64
65const L: [i32; 7] = [1, 0, 0, 0, 0, 0, 0];
66const A: [i32; 7] = [2, 0, 0, 0, 0, 0, 0];
67const V: [i32; 7] = [3, 0, 0, 0, 0, 0, 0];
68const M: [i32; 7] = [0, 1, 0, 0, 0, 0, 0];
69const T: [i32; 7] = [0, 0, 1, 0, 0, 0, 0];
70const ANGLE: [i32; 7] = [0; 7];
71const FORCE: [i32; 7] = [1, 1, -2, 0, 0, 0, 0];
72const PRESSURE: [i32; 7] = [-1, 1, -2, 0, 0, 0, 0];
73const ENERGY: [i32; 7] = [2, 1, -2, 0, 0, 0, 0];
74
75const fn unit(
76    name: &'static str,
77    unit_type: &'static str,
78    dimensions: [i32; 7],
79    mantissa: f64,
80    decimal_exponent: i32,
81) -> NamedUnit {
82    NamedUnit {
83        name,
84        unit_type,
85        dimensions,
86        mantissa,
87        decimal_exponent,
88    }
89}
90
91/// 1 lbf = 0.45359237 kg × 9.80665 m/s² = 4.4482216152605 N exactly.
92const LBF_MANTISSA: f64 = 44_482_216_152_605.0;
93/// 1 psi = 1 lbf / (0.0254 m)² = 4.4482216152605 / 0.00064516 Pa.
94const PSI: f64 = 4.448_221_615_260_5 / 0.000_645_16;
95
96/// IFC4 Table 673, in its order, with exact factors; then the US survey
97/// foot.
98pub(crate) const NAMED_UNITS: [NamedUnit; 33] = [
99    unit("inch", "LENGTHUNIT", L, 254.0, -4),
100    unit("foot", "LENGTHUNIT", L, 3048.0, -4),
101    unit("yard", "LENGTHUNIT", L, 9144.0, -4),
102    unit("mile", "LENGTHUNIT", L, 1_609_344.0, -3),
103    unit("square inch", "AREAUNIT", A, 64_516.0, -8),
104    unit("square foot", "AREAUNIT", A, 9_290_304.0, -8),
105    unit("square yard", "AREAUNIT", A, 83_612_736.0, -8),
106    unit("acre", "AREAUNIT", A, 40_468_564_224.0, -7),
107    unit("square mile", "AREAUNIT", A, 2_589_988_110_336.0, -6),
108    unit("cubic inch", "VOLUMEUNIT", V, 16_387_064.0, -12),
109    unit("cubic foot", "VOLUMEUNIT", V, 28_316_846_592.0, -12),
110    unit("cubic yard", "VOLUMEUNIT", V, 764_554_857_984.0, -12),
111    unit("litre", "VOLUMEUNIT", V, 1.0, -3),
112    unit("fluid ounce UK", "VOLUMEUNIT", V, 284_130_625.0, -13),
113    unit("fluid ounce US", "VOLUMEUNIT", V, 295_735_295_625.0, -16),
114    unit("pint UK", "VOLUMEUNIT", V, 56_826_125.0, -11),
115    unit("pint US", "VOLUMEUNIT", V, 473_176_473.0, -12),
116    unit("gallon UK", "VOLUMEUNIT", V, 454_609.0, -8),
117    unit("gallon US", "VOLUMEUNIT", V, 3_785_411_784.0, -12),
118    unit(
119        "degree",
120        "PLANEANGLEUNIT",
121        ANGLE,
122        std::f64::consts::PI / 180.0,
123        0,
124    ),
125    unit("ounce", "MASSUNIT", M, 28_349_523_125.0, -12),
126    unit("pound", "MASSUNIT", M, 45_359_237.0, -8),
127    unit("ton UK", "MASSUNIT", M, 10_160_469_088.0, -7),
128    unit("ton US", "MASSUNIT", M, 90_718_474.0, -5),
129    unit("lbf", "FORCEUNIT", FORCE, LBF_MANTISSA, -13),
130    unit("kip", "FORCEUNIT", FORCE, LBF_MANTISSA, -10),
131    unit("psi", "PRESSUREUNIT", PRESSURE, PSI, 0),
132    unit("ksi", "PRESSUREUNIT", PRESSURE, PSI, 3),
133    unit("minute", "TIMEUNIT", T, 60.0, 0),
134    unit("hour", "TIMEUNIT", T, 3600.0, 0),
135    unit("day", "TIMEUNIT", T, 86_400.0, 0),
136    unit("btu", "ENERGYUNIT", ENERGY, 1_055_056.0, -3),
137    unit("US survey foot", "LENGTHUNIT", L, 1200.0 / 3937.0, 0),
138];
139
140/// Names of conversion-based temperature units that carry an offset,
141/// refused by name until #110 settles where `ConversionOffset` applies. The
142/// SI `DEGREE_CELSIUS` is not among them: its offset is the SI definition.
143pub(crate) const OFFSET_UNIT_NAMES: [&str; 2] = ["fahrenheit", "degree fahrenheit"];
144
145/// The named unit of this designation, ignoring ASCII case and treating
146/// `_` as a space.
147pub(crate) fn named_unit(name: &str) -> Option<&'static NamedUnit> {
148    let wanted = normalise(name);
149    NAMED_UNITS
150        .iter()
151        .find(|unit| normalise(unit.name) == wanted)
152}
153
154pub(crate) fn normalise(name: &str) -> String {
155    name.trim()
156        .chars()
157        .map(|c| {
158            if c == '_' {
159                ' '
160            } else {
161                c.to_ascii_lowercase()
162            }
163        })
164        .collect::<String>()
165        .split_whitespace()
166        .collect::<Vec<_>>()
167        .join(" ")
168}
169
170/// Every named conversion-based unit this crate converts, in IFC4 Table 673
171/// order followed by the US survey foot.
172#[must_use]
173pub fn named_units() -> &'static [NamedUnit] {
174    &NAMED_UNITS
175}
176
177#[cfg(test)]
178mod tests {
179    use super::*;
180
181    #[test]
182    fn terminating_factors_are_the_legal_definitions() {
183        let scale = |name| named_unit(name).expect(name).scale();
184        assert_eq!(scale("inch"), 0.0254);
185        assert_eq!(scale("foot"), 0.3048);
186        assert_eq!(scale("yard"), 0.9144);
187        assert_eq!(scale("mile"), 1609.344);
188        assert_eq!(scale("pound"), 0.453_592_37);
189        // 231 cubic inches.
190        let gallon = 231.0 * 16_387_064.0;
191        assert_eq!(gallon, 3_785_411_784.0);
192        // The pint and fluid ounce are fractions of their gallon.
193        assert_eq!(454_609.0 * 1e5 / 8.0, 5_682_612_500.0);
194        assert_eq!(56_826_125.0 / 20.0 * 100.0, 284_130_625.0);
195        assert_eq!(3_785_411_784.0 / 8.0, 473_176_473.0);
196        assert!((3_785_411_784.0 / 128.0 * 1e4 - 295_735_295_625.0_f64).abs() < 1e-3);
197        // lbf = pound × g0.
198        assert_eq!(45_359_237.0 * 980_665.0, LBF_MANTISSA);
199        // Areas and volumes are the powers of their length.
200        assert_eq!(254.0 * 254.0, 64_516.0);
201        assert_eq!(3048.0 * 3048.0, 9_290_304.0);
202        assert_eq!(9144.0 * 9144.0, 83_612_736.0);
203        assert_eq!(1_609_344.0 * 1_609_344.0, 2_589_988_110_336.0);
204        assert_eq!(254.0 * 254.0 * 254.0, 16_387_064.0);
205        assert_eq!(3048.0 * 3048.0 * 3048.0, 28_316_846_592.0);
206        assert_eq!(9144.0 * 9144.0 * 9144.0, 764_554_857_984.0);
207        // An acre is 4840 square yards.
208        assert_eq!(4840.0 * 83_612_736.0, 404_685_642_240.0);
209    }
210
211    #[test]
212    fn names_match_ignoring_case_and_underscores() {
213        assert_eq!(named_unit("FOOT").unwrap().name, "foot");
214        assert_eq!(named_unit("Square_Foot").unwrap().name, "square foot");
215        assert_eq!(named_unit("  gallon   us ").unwrap().name, "gallon US");
216        assert!(named_unit("furlong").is_none());
217    }
218}