Skip to main content

codec_cbor/general/
float.rs

1// SPDX-FileCopyrightText: 2026 ReallyMe Technologies Limited
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5use half::f16;
6use zeroize::{Zeroize, ZeroizeOnDrop};
7
8use super::error::{error, CborError, ErrorReason};
9use super::profile::FloatPolicy;
10
11/// IEEE 754 representation width.
12#[derive(Clone, Copy, Debug, Eq, PartialEq)]
13#[non_exhaustive]
14pub enum FloatWidth {
15    /// Binary16.
16    Binary16,
17    /// Binary32.
18    Binary32,
19    /// Binary64.
20    Binary64,
21}
22
23/// Owned floating-point bits, zeroized on drop without content-printing traits.
24///
25/// NaN payloads and signs are retained. Shortening a NaN preserves its
26/// significand by right-side zero extension, rather than canonicalizing it.
27pub struct Float {
28    bits: FloatBits,
29}
30
31enum FloatBits {
32    Binary16(u16),
33    Binary32(u32),
34    Binary64(u64),
35}
36
37impl Float {
38    /// Preserve all binary16 bits.
39    #[must_use]
40    pub const fn binary16(bits: u16) -> Self {
41        Self {
42            bits: FloatBits::Binary16(bits),
43        }
44    }
45    /// Preserve all binary32 bits.
46    #[must_use]
47    pub const fn binary32(bits: u32) -> Self {
48        Self {
49            bits: FloatBits::Binary32(bits),
50        }
51    }
52    /// Preserve all binary64 bits.
53    #[must_use]
54    pub const fn binary64(bits: u64) -> Self {
55        Self {
56            bits: FloatBits::Binary64(bits),
57        }
58    }
59    /// Preserve a Rust binary64 value's bits.
60    #[must_use]
61    pub fn from_f64(value: f64) -> Self {
62        Self::binary64(value.to_bits())
63    }
64    /// Inspect representation width.
65    #[must_use]
66    pub const fn width(&self) -> FloatWidth {
67        match self.bits {
68            FloatBits::Binary16(_) => FloatWidth::Binary16,
69            FloatBits::Binary32(_) => FloatWidth::Binary32,
70            FloatBits::Binary64(_) => FloatWidth::Binary64,
71        }
72    }
73    /// Explicitly extract the original bits; callers own any resulting copy.
74    #[must_use]
75    pub fn bits(&self) -> u64 {
76        match self.bits {
77            FloatBits::Binary16(value) => u64::from(value),
78            FloatBits::Binary32(value) => u64::from(value),
79            FloatBits::Binary64(value) => value,
80        }
81    }
82
83    fn layout(&self) -> (u32, u64, u32) {
84        match self.width() {
85            FloatWidth::Binary16 => (10, 0x1f, 15),
86            FloatWidth::Binary32 => (23, 0xff, 31),
87            FloatWidth::Binary64 => (52, 0x7ff, 63),
88        }
89    }
90
91    fn fraction(&self) -> u64 {
92        let (fraction_bits, _, _) = self.layout();
93        self.bits() & ((1_u64 << fraction_bits) - 1)
94    }
95
96    /// Inspect whether the represented value is a NaN.
97    #[must_use]
98    pub fn is_nan(&self) -> bool {
99        !self.is_finite() && self.fraction() != 0
100    }
101    /// Inspect whether the represented value is finite.
102    #[must_use]
103    pub fn is_finite(&self) -> bool {
104        let (fraction_bits, exponent_mask, _) = self.layout();
105        (self.bits() >> fraction_bits) & exponent_mask != exponent_mask
106    }
107
108    /// Convert without losing a NaN's sign or significand.
109    #[must_use]
110    pub fn to_f64(&self) -> f64 {
111        if self.is_nan() {
112            let (fraction_bits, _, sign_bit) = self.layout();
113            let sign = (self.bits() >> sign_bit) << 63;
114            return f64::from_bits(
115                sign | 0x7ff0_0000_0000_0000 | (self.fraction() << (52 - fraction_bits)),
116            );
117        }
118        match self.bits {
119            // The portable conversion avoids host FP16 assembly and gives
120            // native, interpreted, and WASM lanes the same bit-level path.
121            FloatBits::Binary16(value) => f16::from_bits(value).to_f64_const(),
122            FloatBits::Binary32(value) => f64::from(f32::from_bits(value)),
123            FloatBits::Binary64(value) => f64::from_bits(value),
124        }
125    }
126
127    pub(super) fn check(&self, policy: FloatPolicy) -> Result<(), CborError> {
128        match policy {
129            FloatPolicy::Reject => Err(error(ErrorReason::FloatNotAllowed)),
130            FloatPolicy::FiniteOnly if !self.is_finite() => Err(error(ErrorReason::NonFiniteFloat)),
131            _ => Ok(()),
132        }
133    }
134
135    pub(super) fn shortest(&self) -> FloatWidth {
136        if self.is_nan() {
137            let (fraction_bits, _, _) = self.layout();
138            let normalized = self.fraction() << (64 - fraction_bits);
139            if normalized & ((1_u64 << 54) - 1) == 0 {
140                return FloatWidth::Binary16;
141            }
142            if normalized & ((1_u64 << 41) - 1) == 0 {
143                return FloatWidth::Binary32;
144            }
145            return FloatWidth::Binary64;
146        }
147        let value = self.to_f64();
148        if f16::from_f64_const(value).to_f64_const().to_bits() == value.to_bits() {
149            return FloatWidth::Binary16;
150        }
151        // This narrowing is intentional; the round trip proves exactness and
152        // includes the sign of zero. It is never used for lengths or offsets.
153        if f64::from(value as f32).to_bits() == value.to_bits() {
154            return FloatWidth::Binary32;
155        }
156        FloatWidth::Binary64
157    }
158
159    pub(super) fn at_width(&self, width: FloatWidth) -> Result<u64, CborError> {
160        if width == self.width() {
161            return Ok(self.bits());
162        }
163        if self.is_nan() {
164            let (source_bits, _, sign_bit) = self.layout();
165            let (target_bits, exponent, target_sign) = match width {
166                FloatWidth::Binary16 => (10, 0x1f_u64, 15),
167                FloatWidth::Binary32 => (23, 0xff, 31),
168                FloatWidth::Binary64 => (52, 0x7ff, 63),
169            };
170            let normalized = self.fraction() << (64 - source_bits);
171            let fraction = normalized >> (64 - target_bits);
172            if fraction == 0 || fraction << (64 - target_bits) != normalized {
173                return Err(error(ErrorReason::NonPreferredFloat));
174            }
175            return Ok(((self.bits() >> sign_bit) << target_sign)
176                | (exponent << target_bits)
177                | fraction);
178        }
179        let value = self.to_f64();
180        match width {
181            FloatWidth::Binary16 => Ok(u64::from(f16::from_f64_const(value).to_bits())),
182            FloatWidth::Binary32 => Ok(u64::from((value as f32).to_bits())),
183            FloatWidth::Binary64 => Ok(value.to_bits()),
184        }
185    }
186
187    pub(super) fn equivalent(&self, other: &Self) -> bool {
188        if self.is_nan() || other.is_nan() {
189            if !self.is_nan() || !other.is_nan() {
190                return false;
191            }
192            let (left, _, _) = self.layout();
193            let (right, _, _) = other.layout();
194            return self.fraction() << (64 - left) == other.fraction() << (64 - right);
195        }
196        self.to_f64() == other.to_f64()
197    }
198
199    /// Total-order key whose equality is exactly [`Self::equivalent`].
200    ///
201    /// NaNs key by their right-zero-extended significand, ignoring sign and
202    /// width. Other values key by their exactly widened binary64 bits, with
203    /// both zeros sharing one key because `-0.0 == 0.0`.
204    pub(super) fn equivalence_key(&self) -> (u8, u64) {
205        if self.is_nan() {
206            let (fraction_bits, _, _) = self.layout();
207            return (1, self.fraction() << (64 - fraction_bits));
208        }
209        let value = self.to_f64();
210        if value == 0.0 {
211            (0, 0)
212        } else {
213            (0, value.to_bits())
214        }
215    }
216}
217
218impl Zeroize for Float {
219    fn zeroize(&mut self) {
220        match &mut self.bits {
221            FloatBits::Binary16(value) => value.zeroize(),
222            FloatBits::Binary32(value) => value.zeroize(),
223            FloatBits::Binary64(value) => value.zeroize(),
224        }
225    }
226}
227impl Drop for Float {
228    fn drop(&mut self) {
229        self.zeroize();
230    }
231}
232impl ZeroizeOnDrop for Float {}