Skip to main content

embedded_maths/embedded-maths-functions/
abs.rs

1// SPDX-License-Identifier: GPL-2.0-or-later
2//! Absolute value of `f32` for `no_std`, without `libm`.
3//!
4//! L'opération se réduit à effacer le bit de signe (bit 31) : une seule
5//! instruction `AND` sur Cortex-M, RISC-V (ESP32-C3) et RP2350, sans
6//! branchement et sans FPU requise.
7//!
8//! # Comportement
9//!
10//! | Entrée      | Sortie                                  |
11//! |-------------|-----------------------------------------|
12//! | `-0.0`      | `+0.0`                                  |
13//! | `±∞`        | `+∞`                                    |
14//! | `NaN`       | `NaN` (payload conservé, signe effacé)  |
15//! | subnormaux  | magnitude inchangée, signe effacé       |
16
17const SIGN_BIT: u32 = 1 << 31;
18const MAGNITUDE_MASK: u32 = !SIGN_BIT;
19
20/// Retourne `|x|`.
21///
22/// Utilisable dans un contexte `const` (Rust ≥ 1.83).
23#[inline(always)]
24pub const fn abs(x: f32) -> f32 {
25    f32::from_bits(x.to_bits() & MAGNITUDE_MASK)
26}
27
28/// Remplace chaque élément de `values` par sa valeur absolue.
29#[inline]
30pub fn abs_in_place(values: &mut [f32]) {
31    for v in values {
32        *v = abs(*v);
33    }
34}
35
36/// Écrit `|src[i]|` dans `dst[i]`.
37///
38/// # Panics
39///
40/// Panique si `src.len() != dst.len()`.
41#[inline]
42pub fn abs_into(src: &[f32], dst: &mut [f32]) {
43    assert_eq!(src.len(), dst.len(), "abs_into: longueurs différentes");
44    for (d, s) in dst.iter_mut().zip(src) {
45        *d = abs(*s);
46    }
47}
48
49#[cfg(test)]
50mod tests {
51    use super::*;
52
53    /// Référence indépendante du masquage de bits (comparaisons flottantes).
54    fn reference(x: f32) -> f32 {
55        if x < 0.0 {
56            -x
57        } else if x == 0.0 {
58            0.0 // couvre -0.0 → +0.0
59        } else {
60            x
61        }
62    }
63
64    fn check(bits: u32) {
65        let x = f32::from_bits(bits);
66        let got = abs(x);
67        if x.is_nan() {
68            assert!(got.is_nan(), "bits = {bits:#010x}");
69            assert_eq!(got.to_bits(), bits & MAGNITUDE_MASK, "bits = {bits:#010x}");
70        } else {
71            assert_eq!(got.to_bits(), reference(x).to_bits(), "bits = {bits:#010x}");
72        }
73        assert_eq!(
74            got.to_bits() & SIGN_BIT,
75            0,
76            "signe non effacé, bits = {bits:#010x}"
77        );
78    }
79
80    #[test]
81    fn valeurs_usuelles() {
82        assert_eq!(abs(1.0), 1.0);
83        assert_eq!(abs(-1.0), 1.0);
84        assert_eq!(abs(0.0), 0.0);
85        assert_eq!(abs(-123.456), 123.456);
86        assert_eq!(abs(7.25), 7.25);
87    }
88
89    #[test]
90    fn zero_signe() {
91        assert_eq!(abs(-0.0).to_bits(), 0.0f32.to_bits());
92        assert_eq!(abs(0.0).to_bits(), 0.0f32.to_bits());
93    }
94
95    #[test]
96    fn infinis() {
97        assert_eq!(abs(f32::INFINITY).to_bits(), f32::INFINITY.to_bits());
98        assert_eq!(abs(f32::NEG_INFINITY).to_bits(), f32::INFINITY.to_bits());
99    }
100
101    #[test]
102    fn nan_reste_nan() {
103        assert!(abs(f32::NAN).is_nan());
104        // NaN négatif avec payload personnalisé
105        let bits = SIGN_BIT | 0x7FC0_1234;
106        let r = abs(f32::from_bits(bits));
107        assert!(r.is_nan());
108        assert_eq!(r.to_bits(), 0x7FC0_1234);
109    }
110
111    #[test]
112    fn nan_signalant() {
113        // sNaN : exposant plein, bit de quiet à 0, payload non nul
114        let bits = SIGN_BIT | 0x7F80_0001;
115        let r = abs(f32::from_bits(bits));
116        assert_eq!(r.to_bits(), 0x7F80_0001);
117    }
118
119    #[test]
120    fn extremes_et_subnormaux() {
121        for &x in &[
122            f32::MAX,
123            f32::MIN,
124            f32::MIN_POSITIVE,
125            -f32::MIN_POSITIVE,
126            f32::from_bits(1),            // plus petit subnormal
127            f32::from_bits(SIGN_BIT | 1), // idem, négatif
128            f32::from_bits(0x007F_FFFF),  // plus grand subnormal
129            f32::from_bits(SIGN_BIT | 0x007F_FFFF),
130        ] {
131            assert_eq!(abs(x).to_bits(), reference(x).to_bits(), "x = {x:e}");
132        }
133    }
134
135    #[test]
136    fn idempotence() {
137        for &x in &[-3.5f32, -0.0, 0.0, 7.25, f32::NEG_INFINITY, f32::MIN] {
138            let a = abs(x);
139            assert_eq!(abs(a).to_bits(), a.to_bits());
140        }
141    }
142
143    #[test]
144    fn symetrie() {
145        for &x in &[1.5f32, 1e-30, 1e30, f32::MAX, f32::MIN_POSITIVE] {
146            assert_eq!(abs(x).to_bits(), abs(-x).to_bits());
147        }
148    }
149
150    #[test]
151    fn contexte_const() {
152        const A: f32 = abs(-2.0);
153        const B: f32 = abs(f32::NEG_INFINITY);
154        assert_eq!(A, 2.0);
155        assert_eq!(B, f32::INFINITY);
156    }
157
158    #[test]
159    fn tranches() {
160        let mut v = [-1.0f32, 2.0, -0.0, f32::NEG_INFINITY, -5.5];
161        abs_in_place(&mut v);
162        assert_eq!(v[0], 1.0);
163        assert_eq!(v[1], 2.0);
164        assert_eq!(v[2].to_bits(), 0.0f32.to_bits());
165        assert_eq!(v[3], f32::INFINITY);
166        assert_eq!(v[4], 5.5);
167
168        let src = [-3.0f32, 4.0, -0.5];
169        let mut dst = [0.0f32; 3];
170        abs_into(&src, &mut dst);
171        assert_eq!(dst, [3.0, 4.0, 0.5]);
172    }
173
174    #[test]
175    fn tranche_vide() {
176        abs_in_place(&mut []);
177        abs_into(&[], &mut []);
178    }
179
180    #[test]
181    #[should_panic(expected = "longueurs différentes")]
182    fn abs_into_longueurs_differentes() {
183        abs_into(&[1.0, 2.0], &mut [0.0]);
184    }
185
186    #[test]
187    fn balayage_espace_des_bits() {
188        // Pas premier avec le modulo 2^32 : visite ~1M motifs répartis
189        // sur tous les exposants, subnormaux, infinis et NaN.
190        let mut bits: u32 = 0;
191        loop {
192            check(bits);
193            match bits.checked_add(4099) {
194                Some(next) => bits = next,
195                None => break,
196            }
197        }
198    }
199
200    /// Exhaustif sur les 2^32 motifs. Lent : `cargo test --release -- --ignored`.
201    #[test]
202    #[ignore]
203    fn exhaustif() {
204        let mut bits: u32 = 0;
205        loop {
206            check(bits);
207            if bits == u32::MAX {
208                break;
209            }
210            bits += 1;
211        }
212    }
213}