l_system_fractals/

num_validity.rs

// src/num_validity.rs
//
// This file is part of l-system-fractals
//
// Copyright 2024 Christopher Phan
//
// See README.md in repository root directory for copyright/license info
//
// SPDX-License-Identifier: MIT OR Apache-2.0

//! Functions to screen out NaN and ±∞, as well as test for near equality.
use std::collections::HashMap;
use std::hash;
use std::iter::zip;
use std::num::FpCategory;

use crate::errors::LSystemError;

/// A type of which two objects can be "almost equal" (i.e., have a distance less than ε).
///
/// # Examples
///
/// ```
/// use std::collections::HashMap;
///
/// use l_system_fractals::num_validity::AlmostEq;
///
/// // Defined as (self - other).abs() < epsilon for f64 numbers
///
/// let a: f64 = 25.0;
/// let b: f64 = 24.99999;
/// assert!(a.almost_eq(&b, 0.0001));
/// assert!(!a.almost_eq(&b, 0.00000001));
///
/// assert_ne!((1.57_f64).sin(), 1.0); // off by about 3.17e-07
///
/// assert!((1.57_f64).sin().almost_eq(&1.0, 1e-06));
/// assert!(!(1.57_f64).sin().almost_eq(&1.0, 1e-09));
///
/// // Defined for HashMap<K, V> when V implements AlmostEq
///
/// let hm_1: HashMap<String, f64> = HashMap::from([
///     ("alpha".into(), 10.001),
///     ("beta".into(), -5.25001),
/// ]);
///
/// let hm_2: HashMap<String, f64> = HashMap::from([
///     ("alpha".into(), 9.999),
///     ("beta".into(), -5.25002)
/// ]);
///
/// let hm_3: HashMap<String, f64> = HashMap::from([
///     ("alpha".into(), 10.001)
/// ]);
///
/// let hm_4: HashMap<String, f64> = HashMap::from([
///     ("alpha".into(), 10.001),
///     ("beta".into(), -5.25001),
///     ("gamma".into(), 3.0),
/// ]);
///
/// assert!(hm_1.almost_eq(&hm_2, 0.01));
/// assert!(!hm_1.almost_eq(&hm_2, 0.001)); // "alpha" values too far apart
/// assert!(!hm_1.almost_eq(&hm_3, 0.01)); // hm_3 does not have key "beta"
/// assert!(!hm_1.almost_eq(&hm_4, 0.01)); // hm_1 does not have key "gamma"
///
/// // Defined for Vec<T> when T implements AlmostEq
///
/// let v_1: Vec<f64> = vec![3.0, 2.0, -5.0];
/// let v_2: Vec<f64> = vec![3.0, 2.0, -4.999];
///
/// assert!(v_1.almost_eq(&v_2, 0.002));
/// assert!(!v_1.almost_eq(&v_2, 0.0005));
/// ```
///
/// ```
/// use std::f64::consts::PI;
///
/// use l_system_fractals::num_validity::AlmostEq;
///
/// #[derive(Clone, Copy, Debug)]
/// struct Angle(f64);
///
/// impl Angle {
///     fn reduce(&self) -> Self {
///         Self(self.0.rem_euclid(2.0 * PI))
///     }
///
///     fn abs_diff(&self, other: &Self) -> Self {
///         let diff = (self.0 - other.0).abs().rem_euclid(2.0 * PI);
///         Self(diff.min(2.0 * PI - diff))
///     }
///
///     fn flip(&self) -> Self {
///         Self(self.0 + PI).reduce()
///     }
/// }
///
/// impl PartialEq for Angle {
///     fn eq(&self, other: &Self) -> bool {
///         self.reduce() == other.reduce()
///     }
/// }
///
/// impl AlmostEq for Angle {
///     fn almost_eq(&self, other: &Self, epsilon: f64) -> bool {
///         self.abs_diff(&other).0 < epsilon
///     }
/// }
///
/// let a = Angle(PI/4.0);
/// let b = Angle(9.0 * PI/4.0);
/// let c = Angle(PI * 0.249);
///
/// assert!(a.almost_eq(&b, 0.00001));
/// assert!(a.almost_eq(&c, 0.01));
/// assert!(!a.almost_eq(&c, 0.00001));
///
/// #[derive(Clone, Copy, Debug)]
/// struct PolarCoordinates {
///     angle: Angle,
///     radius: f64
/// }
///
/// impl PolarCoordinates {
///     fn reduce(&self) -> Self {
///         let neg_radius: bool = self.radius < 0.0;
///         let radius: f64 = if neg_radius { - self.radius } else { self.radius };
///         let angle: Angle = if neg_radius { self.angle.flip() } else {self.angle.reduce()};
///         Self { angle, radius }
///     }
/// }
///
/// impl PartialEq for PolarCoordinates {
///     fn eq(&self, other: &Self) -> bool {
///         self.radius == 0.0 && other.radius == 0.0 || {
///             let s_red = self.reduce();
///             let o_red = other.reduce();
///             s_red.radius == o_red.radius && s_red.angle == o_red.angle
///         }
///     }
/// }
///
/// impl AlmostEq for PolarCoordinates {
///     fn almost_eq(&self, other: &Self, epsilon: f64) -> bool {
///         self.radius.abs() < epsilon && other.radius.abs() < epsilon || {
///             let s_red = self.reduce();
///             let o_red = other.reduce();
///             s_red.radius.almost_eq(&o_red.radius, epsilon)
///                 && s_red.angle.almost_eq(&o_red.angle, epsilon)
///         }
///     }
/// }
///
/// let p1 = PolarCoordinates { angle: Angle(0.25 * PI), radius: 10.0 };
/// let p2 = PolarCoordinates { angle: Angle(2.24999 * PI), radius: 9.99999};
///
/// assert!(p1.almost_eq(&p2, 0.001));
/// assert!(!p1.almost_eq(&p2, 0.000000000000001));
///
/// let p3 = PolarCoordinates { angle: Angle(1.25 * PI), radius: 0.0005 };
/// let p4 = PolarCoordinates { angle: Angle(0.75 * PI), radius: 0.0005 };
/// assert!(p3.almost_eq(&p4, 0.001));
/// assert!(!p3.almost_eq(&p4, 0.00001));
/// ```
pub trait AlmostEq {
    /// Returns `true` if the distance between objects is less than `epsilon`.
    fn almost_eq(&self, other: &Self, epsilon: f64) -> bool;
}

impl AlmostEq for f64 {
    fn almost_eq(&self, other: &Self, epsilon: f64) -> bool {
        (self - other).abs() < epsilon
    }
}

impl<T> AlmostEq for Vec<T>
where
    T: AlmostEq,
{
    fn almost_eq(&self, other: &Self, epsilon: f64) -> bool {
        (self.len() == other.len())
            && zip(self.iter(), other.iter()).all(|(p, q)| p.almost_eq(q, epsilon))
    }
}

impl<K, V> AlmostEq for HashMap<K, V>
where
    V: AlmostEq,
    K: Eq + PartialEq + hash::Hash,
{
    fn almost_eq(&self, other: &Self, epsilon: f64) -> bool {
        for (key, val) in self.iter() {
            match other.get(key) {
                None => {
                    return false;
                }
                Some(val2) => {
                    if !val.almost_eq(val2, epsilon) {
                        return false;
                    }
                }
            }
        }
        other.keys().all(|k| self.contains_key(k))
    }
}

/// Returns `true` if value is neither NaN nor &pm;&infin;.
///
/// # Examples
///
/// ```
/// use std::num::FpCategory;
///
/// use l_system_fractals::num_validity::is_valid;
///
/// let n: f64 = 0.2024_f64.sin();
/// assert_eq!(n.classify(), FpCategory::Normal);
/// assert!(is_valid(n));
///
/// let z: f64 = 0.0;
/// assert_eq!(z.classify(), FpCategory::Zero);
/// assert!(is_valid(z));
///
/// let s: f64 = f64::MIN_POSITIVE / 2.0;
/// assert_eq!(s.classify(), FpCategory::Subnormal);
/// assert!(is_valid(s));
///
/// let i1: f64 = f64::INFINITY;
/// assert_eq!(i1.classify(), FpCategory::Infinite);
/// assert!(!is_valid(i1));
///
/// let i2: f64 = f64::NEG_INFINITY;
/// assert_eq!(i2.classify(), FpCategory::Infinite);
/// assert!(!is_valid(i2));
///
/// let na: f64 = f64::NAN;
/// assert_eq!(na.classify(), FpCategory::Nan);
/// assert!(!is_valid(na));
/// ```
pub fn is_valid(x: f64) -> bool {
    let cat: FpCategory = x.classify();
    (cat == FpCategory::Zero) || (cat == FpCategory::Subnormal) || (cat == FpCategory::Normal)
}

/// Raises an error if the value is either NaN or &pm;&infin;.
///
/// The error raised is [`LSystemError::InvalidFloat`].
///
/// # Examples
///
/// ```
/// use std::num::FpCategory;
///
/// use l_system_fractals::num_validity::err_if_invalid;
///
/// let n: f64 = 0.2024_f64.sin();
/// assert_eq!(n.classify(), FpCategory::Normal);
/// assert!(err_if_invalid(n).is_ok());
///
/// let z: f64 = 0.0;
/// assert_eq!(z.classify(), FpCategory::Zero);
/// assert!(err_if_invalid(z).is_ok());
///
/// let s: f64 = f64::MIN_POSITIVE / 2.0;
/// assert_eq!(s.classify(), FpCategory::Subnormal);
/// assert!(err_if_invalid(s).is_ok());
///
/// let i1: f64 = f64::INFINITY;
/// assert_eq!(i1.classify(), FpCategory::Infinite);
/// assert!(err_if_invalid(i1).is_err());
///
/// let i2: f64 = f64::NEG_INFINITY;
/// assert_eq!(i2.classify(), FpCategory::Infinite);
/// assert!(err_if_invalid(i2).is_err());
///
/// let na: f64 = f64::NAN;
/// assert_eq!(na.classify(), FpCategory::Nan);
/// assert!(err_if_invalid(na).is_err());
/// ```
pub fn err_if_invalid(x: f64) -> Result<f64, LSystemError> {
    if is_valid(x) {
        Ok(x)
    } else {
        Err(LSystemError::InvalidFloat)
    }
}

/// Returns the maximum value of the slice ignoring any values that are
/// [NaN or infinite](is_valid()).
///
/// # Examples
///
/// ```
/// use l_system_fractals::num_validity::max;
///
/// assert_eq!(max(&[0.25, 0.0, f64::MIN_POSITIVE]).unwrap(), 0.25);
///
/// // f64::INFINITY ignored
/// assert_eq!(max(&[f64::INFINITY, 0.25, 0.0, f64::MIN_POSITIVE]).unwrap(), 0.25);
///
/// // no valid values
/// assert!(max(&[f64::INFINITY, f64::NAN]).is_none());
/// assert!(max(&[]).is_none());
/// ```
pub fn max(vals: &[f64]) -> Option<f64> {
    let mut current_max: Option<f64> = None;
    for k in vals {
        if is_valid(*k) {
            if current_max.is_none() {
                current_max = Some(*k);
            } else {
                current_max = Some(k.max(current_max.unwrap()));
            }
        }
    }
    current_max
}

/// Returns the minimum value of the slice ignoring any values that are
/// [NaN or infinite](is_valid()).
///
/// # Examples
///
/// ```
/// use l_system_fractals::num_validity::min;
///
/// assert_eq!(min(&[0.25, f64::MIN_POSITIVE, 100.0]).unwrap(), f64::MIN_POSITIVE);
///
/// // f64::NEG_INFINITY ignored
/// assert_eq!(
///     min(&[0.25, f64::MIN_POSITIVE, 100.0, f64::NEG_INFINITY]).unwrap(),
///     f64::MIN_POSITIVE
/// );
///
/// // no valid values
/// assert!(min(&[f64::INFINITY, f64::NAN]).is_none());
/// assert!(min(&[]).is_none());
/// ```
pub fn min(vals: &[f64]) -> Option<f64> {
    let mut current_min: Option<f64> = None;
    for k in vals {
        if is_valid(*k) {
            if current_min.is_none() {
                current_min = Some(*k);
            } else {
                current_min = Some(k.min(current_min.unwrap()));
            }
        }
    }
    current_min
}