Skip to main content

openformula_kernel/
error.rs

1use alloc::string::{String, ToString};
2use core::fmt;
3
4/// Result returned by calculation-kernel operations.
5pub type CalcResult<T = crate::Value> = Result<T, CalcError>;
6
7/// Stable categories for calculation failures.
8#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
9pub enum CalcErrorKind {
10    /// An empty range intersection or equivalent null reference.
11    Null,
12    /// Division by zero or an equivalent zero denominator.
13    DivZero,
14    /// A value has the wrong type or shape.
15    Value,
16    /// A reference supplied by a host is invalid.
17    Ref,
18    /// A function or identifier is unknown.
19    Name,
20    /// A numeric domain, range, or finite-result requirement failed.
21    Num,
22    /// A requested value is unavailable.
23    NotAvailable,
24    /// A configured evaluation bound was exceeded.
25    Limit,
26    /// The host did not provide a required impure capability.
27    Unsupported,
28}
29
30impl CalcErrorKind {
31    /// Return the spreadsheet-style stable error code.
32    #[must_use]
33    pub const fn code(self) -> &'static str {
34        match self {
35            Self::Null => "#NULL!",
36            Self::DivZero => "#DIV/0!",
37            Self::Value => "#VALUE!",
38            Self::Ref => "#REF!",
39            Self::Name => "#NAME?",
40            Self::Num => "#NUM!",
41            Self::NotAvailable => "#N/A",
42            Self::Limit => "#LIMIT!",
43            Self::Unsupported => "#UNSUPPORTED!",
44        }
45    }
46}
47
48/// A typed calculation error without parser- or storage-specific location data.
49#[derive(Clone, Debug, PartialEq, Eq, Hash)]
50pub struct CalcError {
51    kind: CalcErrorKind,
52    message: String,
53}
54
55impl CalcError {
56    /// Construct an error in a stable category.
57    #[must_use]
58    pub fn new(kind: CalcErrorKind, message: impl Into<String>) -> Self {
59        Self {
60            kind,
61            message: message.into(),
62        }
63    }
64
65    /// Return the stable error category.
66    #[must_use]
67    pub const fn kind(&self) -> CalcErrorKind {
68        self.kind
69    }
70
71    /// Return the spreadsheet-style error code.
72    #[must_use]
73    pub const fn code(&self) -> &'static str {
74        self.kind.code()
75    }
76
77    /// Return the human-readable diagnostic detail.
78    #[must_use]
79    pub fn message(&self) -> &str {
80        &self.message
81    }
82
83    pub(crate) fn value(message: impl Into<String>) -> Self {
84        Self::new(CalcErrorKind::Value, message)
85    }
86
87    pub(crate) fn num(message: impl Into<String>) -> Self {
88        Self::new(CalcErrorKind::Num, message)
89    }
90
91    pub(crate) fn name(message: impl Into<String>) -> Self {
92        Self::new(CalcErrorKind::Name, message)
93    }
94}
95
96impl fmt::Display for CalcError {
97    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
98        write!(formatter, "{} {}", self.code(), self.message)
99    }
100}
101
102#[cfg(feature = "std")]
103impl std::error::Error for CalcError {}
104
105impl From<CalcErrorKind> for CalcError {
106    fn from(kind: CalcErrorKind) -> Self {
107        Self::new(kind, kind.code().to_string())
108    }
109}