simple_equation_inversion 1.0.1

A Rust library for solving linear equations and invertible function chains.
Documentation
use alloc::format;
use alloc::rc::Rc;
use core::cell::RefCell;
use core::fmt;

use crate::element::element_kind::ElementKind;
use crate::error::Error;
use crate::unknown::Unknown;

/// Represents a mathematical expression element in an equation (constant, variable, or transformed expression).
#[derive(Clone)]
pub struct Element {
    pub kind: ElementKind,
    pub error: Result<(), Error>,
}

impl fmt::Debug for Element {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Element")
            .field("kind", &self.kind)
            .field("error", &self.error)
            .finish()
    }
}

impl fmt::Display for Element {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if let Err(err) = &self.error {
            return write!(f, "<Error: {err}>");
        }

        match &self.kind {
            ElementKind::Known(val) => write!(f, "{val}"),
            ElementKind::Variable {
                factor,
                unknown,
                offset,
            } => {
                if let Err(err) = unknown.get_status() {
                    return write!(f, "<Error: {err}>");
                }
                format_affine(f, *factor, "x", *offset)
            }
            ElementKind::Transformed {
                factor,
                transform,
                inner,
                offset,
            } => {
                let inner_str = format!("{inner}");
                let term = format!("{}({inner_str})", transform.name());
                format_affine(f, *factor, &term, *offset)
            }
        }
    }
}

pub(crate) fn format_affine(
    f: &mut fmt::Formatter<'_>,
    a: f64,
    var_str: &str,
    b: f64,
) -> fmt::Result {
    if a == 0.0 {
        write!(f, "{b}")
    } else if b == 0.0 {
        if a == 1.0 {
            write!(f, "{var_str}")
        } else if a == -1.0 {
            write!(f, "-{var_str}")
        } else {
            write!(f, "{a}{var_str}")
        }
    } else if b > 0.0 {
        if a == 1.0 {
            write!(f, "{var_str} + {b}")
        } else if a == -1.0 {
            write!(f, "-{var_str} + {b}")
        } else {
            write!(f, "{a}{var_str} + {b}")
        }
    } else {
        let neg_b = -b;
        if a == 1.0 {
            write!(f, "{var_str} - {neg_b}")
        } else if a == -1.0 {
            write!(f, "-{var_str} - {neg_b}")
        } else {
            write!(f, "{a}{var_str} - {neg_b}")
        }
    }
}

impl Element {
    /// Creates a new element containing an unknown variable backed by a shared cell.
    pub fn new_unknown(x: Rc<RefCell<f64>>) -> Self {
        Self {
            kind: ElementKind::Variable {
                factor: 1.0,
                unknown: Unknown::new_with_value(x),
                offset: 0.0,
            },
            error: Ok(()),
        }
    }

    /// Creates a new element from an existing [`Unknown`].
    pub fn from_unknown(unknown: Unknown) -> Self {
        Self {
            kind: ElementKind::Variable {
                factor: 1.0,
                unknown,
                offset: 0.0,
            },
            error: Ok(()),
        }
    }

    /// Creates a new element with a known constant value.
    pub fn new_known(known: f64) -> Self {
        Self {
            kind: ElementKind::Known(known),
            error: Ok(()),
        }
    }

    /// Creates a new element with a known value from any type convertible into `f64`.
    pub fn known<T>(value: T) -> Self
    where
        T: Into<f64>,
    {
        Self::new_known(value.into())
    }

    /// Creates a new anonymous unknown element.
    pub fn unknown() -> Self {
        Self::from_unknown(Unknown::new())
    }

    /// Returns `true` if this element contains an unknown variable.
    pub fn is_unknown(&self) -> bool {
        matches!(
            self.kind,
            ElementKind::Variable { .. } | ElementKind::Transformed { .. }
        )
    }

    /// Returns the resolved value of the unknown variable if available.
    pub fn get_unknown_value(&self) -> Result<f64, Error> {
        match &self.kind {
            ElementKind::Variable { unknown, .. } => {
                unknown.get_status().and(Ok(*unknown.unknown.borrow()))
            }
            ElementKind::Transformed { inner, .. } => inner.get_unknown_value(),
            ElementKind::Known(_) => Err(Error::NoUnknown),
        }
    }

    /// Returns the numerical constant value if this element is [`ElementKind::Known`].
    pub fn value(&self) -> Option<f64> {
        match &self.kind {
            ElementKind::Known(val) => Some(*val),
            _ => None,
        }
    }

    /// Returns the constant offset of this element.
    pub fn offset(&self) -> f64 {
        match &self.kind {
            ElementKind::Known(val) => *val,
            ElementKind::Variable { offset, .. } => *offset,
            ElementKind::Transformed { offset, .. } => *offset,
        }
    }

    /// Returns the error status of this element.
    pub fn error(&self) -> Result<(), Error> {
        self.error.clone()
    }

    /// Traverses and retrieves the underlying [`Unknown`] reference if present.
    pub fn unknown_ref(&self) -> Option<Unknown> {
        match &self.kind {
            ElementKind::Variable { unknown, .. } => Some(unknown.clone()),
            ElementKind::Transformed { inner, .. } => inner.unknown_ref(),
            ElementKind::Known(_) => None,
        }
    }
}

impl From<&Element> for Element {
    fn from(value: &Element) -> Self {
        value.clone()
    }
}

impl From<f64> for Element {
    fn from(value: f64) -> Self {
        Self::new_known(value)
    }
}

impl From<f32> for Element {
    fn from(value: f32) -> Self {
        Self::new_known(value as f64)
    }
}

impl From<i32> for Element {
    fn from(value: i32) -> Self {
        Self::new_known(value as f64)
    }
}

impl From<i64> for Element {
    fn from(value: i64) -> Self {
        Self::new_known(value as f64)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    #[allow(unused_imports)]
    use alloc::format;
    #[allow(unused_imports)]
    use alloc::string::ToString;

    #[test]
    fn test_element_constructors_and_accessors() {
        let k = Element::known(42.0);
        assert_eq!(k.value(), Some(42.0));
        assert!(!k.is_unknown());
        assert_eq!(k.get_unknown_value(), Err(Error::NoUnknown));

        let u = Element::unknown();
        assert!(u.is_unknown());
    }

    #[test]
    fn test_element_display() {
        let k = Element::known(15.5);
        assert_eq!(format!("{k}"), "15.5");

        let u = Element::unknown();
        assert_eq!(format!("{u}"), "x");
    }

    #[test]
    fn test_display_edge_cases() {
        let setup_rc = Rc::new(RefCell::new(0.0));
        let x = Element::new_unknown(setup_rc);

        // Zero factor => only offset
        let zero_factor = 0.0 * x.clone() + 7.5;
        assert_eq!(format!("{zero_factor}"), "7.5");

        // -1 factor with positive offset
        let neg_one_pos = -x.clone() + 3.0;
        assert_eq!(format!("{neg_one_pos}"), "-x + 3");

        // -1 factor with negative offset
        let neg_one_neg = -x.clone() - 4.0;
        assert_eq!(format!("{neg_one_neg}"), "-x - 4");

        // arbitrary factor with negative offset
        let arb_neg = 3.0 * x - 8.0;
        assert_eq!(format!("{arb_neg}"), "3x - 8");
    }
}