Skip to main content

openformula_kernel/
registry.rs

1use alloc::collections::BTreeMap;
2use alloc::format;
3use alloc::string::{String, ToString};
4use alloc::vec::Vec;
5use core::cmp::Ordering;
6
7use crate::number::normalize_zero;
8use crate::{Argument, CalcError, CalcErrorKind, CalcResult, EvalContext, Number, Value};
9
10/// Controls host-selected implicit conversions.
11#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
12pub enum CoercionPolicy {
13    /// OpenFormula conversions with locale-neutral text parsing.
14    #[default]
15    OpenFormula,
16    /// Accept only exact logical and numeric types; aggregates still ignore
17    /// empty values.
18    Strict,
19}
20
21/// Whether a registered function is standard or explicitly namespaced.
22#[derive(Clone, Debug, PartialEq, Eq)]
23pub enum FunctionNamespace {
24    /// An OpenFormula-derived standard function.
25    Standard,
26    /// A host extension namespace such as `KITU`.
27    Extension(String),
28}
29
30/// Compatibility information attached to every registry entry.
31#[derive(Clone, Debug, PartialEq, Eq)]
32pub struct FunctionMetadata {
33    name: String,
34    namespace: FunctionNamespace,
35    openformula_reference: Option<&'static str>,
36    notes: &'static str,
37}
38
39impl FunctionMetadata {
40    /// Return the case-normalized callable name.
41    #[must_use]
42    pub fn name(&self) -> &str {
43        &self.name
44    }
45
46    /// Return the standard or extension namespace.
47    #[must_use]
48    pub const fn namespace(&self) -> &FunctionNamespace {
49        &self.namespace
50    }
51
52    /// Return the normative OpenFormula 1.4 section, when applicable.
53    #[must_use]
54    pub const fn openformula_reference(&self) -> Option<&'static str> {
55        self.openformula_reference
56    }
57
58    /// Return concise compatibility notes.
59    #[must_use]
60    pub const fn notes(&self) -> &'static str {
61        self.notes
62    }
63}
64
65/// Function pointer accepted by the registry for standard and extension calls.
66pub type FunctionHandler = fn(&[Argument], &mut dyn EvalContext, CoercionPolicy) -> CalcResult;
67
68#[derive(Clone)]
69struct RegisteredFunction {
70    metadata: FunctionMetadata,
71    handler: FunctionHandler,
72}
73
74/// Case-insensitive registry with separate standard and extension namespaces.
75#[derive(Clone)]
76pub struct FunctionRegistry {
77    functions: BTreeMap<String, RegisteredFunction>,
78    coercion: CoercionPolicy,
79}
80
81impl FunctionRegistry {
82    /// Construct a registry containing the supported standard function subset.
83    #[must_use]
84    pub fn standard() -> Self {
85        Self::standard_with_policy(CoercionPolicy::OpenFormula)
86    }
87
88    /// Construct the standard registry with an explicit host coercion policy.
89    #[must_use]
90    pub fn standard_with_policy(coercion: CoercionPolicy) -> Self {
91        let mut registry = Self {
92            functions: BTreeMap::new(),
93            coercion,
94        };
95        registry.register_standard(
96            "SUM",
97            "6.16.61",
98            "NumberSequenceList semantics; scalar text conversion is locale-neutral",
99            sum,
100        );
101        registry.register_standard(
102            "MIN",
103            "6.18.48",
104            "returns zero when no numeric value is present",
105            min,
106        );
107        registry.register_standard(
108            "MAX",
109            "6.18.45",
110            "returns zero when no numeric value is present",
111            max,
112        );
113        registry.register_standard(
114            "AVERAGE",
115            "6.18.3",
116            "returns #DIV/0! when no numeric value is present",
117            average,
118        );
119        registry.register_standard(
120            "IF",
121            "6.15.4",
122            "use evaluate_lazy to guarantee unselected-branch short circuiting",
123            if_prepared,
124        );
125        registry.register_standard("ABS", "6.16.2", "integer overflow returns #NUM!", abs);
126        registry.register_standard(
127            "ROUND",
128            "6.17.5",
129            "Digits is intentionally bounded to -15..=15",
130            round,
131        );
132        registry.register_standard(
133            "FLOOR",
134            "6.17.3",
135            "two-ULP correction applies only at exact-multiple boundaries",
136            floor,
137        );
138        registry.register_standard(
139            "CEILING",
140            "6.17.1",
141            "two-ULP correction applies only at exact-multiple boundaries",
142            ceiling,
143        );
144        registry.register_standard(
145            "POWER",
146            "6.16.46",
147            "0^0 is 1; negative fractional powers return #NUM!",
148            power,
149        );
150        registry
151    }
152
153    /// Return the active coercion policy.
154    #[must_use]
155    pub const fn coercion_policy(&self) -> CoercionPolicy {
156        self.coercion
157    }
158
159    /// Register an explicitly namespaced extension function.
160    ///
161    /// Namespace and local name are ASCII identifiers and are normalized to
162    /// uppercase. Standard names cannot be replaced by this API.
163    pub fn register_extension(
164        &mut self,
165        namespace: &str,
166        name: &str,
167        notes: &'static str,
168        handler: FunctionHandler,
169    ) -> CalcResult<()> {
170        if !valid_identifier(namespace) || !valid_identifier(name) {
171            return Err(CalcError::name(
172                "extension namespace and name must be ASCII identifiers",
173            ));
174        }
175        let namespace = namespace.to_ascii_uppercase();
176        if namespace == "OF" || namespace == "OPENFORMULA" || namespace == "STANDARD" {
177            return Err(CalcError::name("extension namespace is reserved"));
178        }
179        let full_name = format!("{namespace}.{}", name.to_ascii_uppercase());
180        if self.functions.contains_key(&full_name) {
181            return Err(CalcError::name(format!(
182                "function `{full_name}` is already registered"
183            )));
184        }
185        let metadata = FunctionMetadata {
186            name: full_name.clone(),
187            namespace: FunctionNamespace::Extension(namespace),
188            openformula_reference: None,
189            notes,
190        };
191        self.functions
192            .insert(full_name, RegisteredFunction { metadata, handler });
193        Ok(())
194    }
195
196    /// Return metadata for a registered function.
197    #[must_use]
198    pub fn metadata(&self, name: &str) -> Option<&FunctionMetadata> {
199        self.functions
200            .get(&name.to_ascii_uppercase())
201            .map(|function| &function.metadata)
202    }
203
204    /// Iterate over all compatibility metadata in stable name order.
205    pub fn all_metadata(&self) -> impl Iterator<Item = &FunctionMetadata> {
206        self.functions.values().map(|function| &function.metadata)
207    }
208
209    /// Evaluate already-prepared arguments.
210    ///
211    /// For `IF`, this method selects only the requested prepared branch, but a
212    /// caller that needs to avoid evaluating branch expressions must use
213    /// [`Self::evaluate_lazy`].
214    pub fn evaluate(
215        &self,
216        name: &str,
217        arguments: &[Argument],
218        context: &mut dyn EvalContext,
219    ) -> CalcResult {
220        let normalized = name.to_ascii_uppercase();
221        let function = self.functions.get(&normalized).ok_or_else(|| {
222            CalcError::new(CalcErrorKind::Name, format!("unknown function `{name}`"))
223        })?;
224        if normalized == "IF" {
225            return if_prepared(arguments, context, self.coercion);
226        }
227        propagate_leftmost_error(arguments)?;
228        (function.handler)(arguments, context, self.coercion)
229    }
230
231    /// Evaluate arguments on demand, preserving OpenFormula `IF` short circuiting.
232    pub fn evaluate_lazy<F>(
233        &self,
234        name: &str,
235        argument_count: usize,
236        mut evaluate_argument: F,
237        context: &mut dyn EvalContext,
238    ) -> CalcResult
239    where
240        F: FnMut(usize) -> CalcResult<Argument>,
241    {
242        let normalized = name.to_ascii_uppercase();
243        if !self.functions.contains_key(&normalized) {
244            return Err(CalcError::new(
245                CalcErrorKind::Name,
246                format!("unknown function `{name}`"),
247            ));
248        }
249        if normalized == "IF" {
250            if !(1..=3).contains(&argument_count) {
251                return Err(CalcError::value("IF expects one to three arguments"));
252            }
253            let condition = evaluate_argument(0)?;
254            let condition =
255                coerce_logical(required_scalar(&condition, "IF condition")?, self.coercion)?;
256            if argument_count == 1 {
257                return Ok(Value::Boolean(condition));
258            }
259            let selected = if condition { 1 } else { 2 };
260            if selected >= argument_count {
261                return Ok(Value::Boolean(false));
262            }
263            let value = evaluate_argument(selected)?;
264            return selected_if_value(value);
265        }
266        let mut arguments = Vec::with_capacity(argument_count);
267        for index in 0..argument_count {
268            arguments.push(evaluate_argument(index)?);
269        }
270        self.evaluate(&normalized, &arguments, context)
271    }
272
273    fn register_standard(
274        &mut self,
275        name: &'static str,
276        reference: &'static str,
277        notes: &'static str,
278        handler: FunctionHandler,
279    ) {
280        let metadata = FunctionMetadata {
281            name: name.to_string(),
282            namespace: FunctionNamespace::Standard,
283            openformula_reference: Some(reference),
284            notes,
285        };
286        self.functions
287            .insert(name.to_string(), RegisteredFunction { metadata, handler });
288    }
289}
290
291/// Convert a scalar to a number under the selected host policy.
292pub fn coerce_number(value: &Value, policy: CoercionPolicy) -> CalcResult<Number> {
293    match value {
294        Value::Number(value) => Ok(*value),
295        Value::Error(error) => Err(error.clone()),
296        Value::Boolean(value) if policy == CoercionPolicy::OpenFormula => {
297            Ok(Number::from_i64(i64::from(*value)))
298        }
299        Value::Empty if policy == CoercionPolicy::OpenFormula => Ok(Number::from_i64(0)),
300        Value::Text(value) if policy == CoercionPolicy::OpenFormula => value
301            .trim()
302            .parse::<f64>()
303            .map_err(|_| CalcError::value("text cannot be converted to a number"))
304            .and_then(Number::try_from_f64),
305        Value::Boolean(_) | Value::Empty | Value::Text(_) => {
306            Err(CalcError::value("expected a number"))
307        }
308    }
309}
310
311/// Convert a scalar to a logical under the selected host policy.
312pub fn coerce_logical(value: &Value, policy: CoercionPolicy) -> CalcResult<bool> {
313    match value {
314        Value::Boolean(value) => Ok(*value),
315        Value::Error(error) => Err(error.clone()),
316        Value::Number(value) if policy == CoercionPolicy::OpenFormula => Ok(!value.is_zero()),
317        Value::Empty if policy == CoercionPolicy::OpenFormula => Ok(false),
318        Value::Text(value) if policy == CoercionPolicy::OpenFormula => {
319            if value.eq_ignore_ascii_case("TRUE") {
320                Ok(true)
321            } else if value.eq_ignore_ascii_case("FALSE") {
322                Ok(false)
323            } else {
324                Err(CalcError::value("text cannot be converted to a logical"))
325            }
326        }
327        Value::Number(_) | Value::Empty | Value::Text(_) => {
328            Err(CalcError::value("expected a logical"))
329        }
330    }
331}
332
333pub(crate) fn required_scalar<'a>(argument: &'a Argument, label: &str) -> CalcResult<&'a Value> {
334    match argument {
335        Argument::Scalar(value) => Ok(value),
336        Argument::Range(_) => Err(CalcError::value(format!("{label} must be a scalar"))),
337        Argument::Missing => Err(CalcError::value(format!("{label} is required"))),
338    }
339}
340
341fn valid_identifier(value: &str) -> bool {
342    let mut characters = value.chars();
343    matches!(characters.next(), Some(first) if first.is_ascii_alphabetic() || first == '_')
344        && characters.all(|character| character.is_ascii_alphanumeric() || character == '_')
345}
346
347fn propagate_leftmost_error(arguments: &[Argument]) -> CalcResult<()> {
348    for argument in arguments {
349        match argument {
350            Argument::Scalar(Value::Error(error)) => return Err(error.clone()),
351            Argument::Range(values) => {
352                if let Some(Value::Error(error)) =
353                    values.iter().find(|value| matches!(value, Value::Error(_)))
354                {
355                    return Err(error.clone());
356                }
357            }
358            Argument::Scalar(_) | Argument::Missing => {}
359        }
360    }
361    Ok(())
362}
363
364fn require_count(
365    name: &str,
366    arguments: &[Argument],
367    minimum: usize,
368    maximum: usize,
369) -> CalcResult<()> {
370    if (minimum..=maximum).contains(&arguments.len()) {
371        Ok(())
372    } else if minimum == maximum {
373        Err(CalcError::value(format!(
374            "{name} expects {minimum} arguments"
375        )))
376    } else {
377        Err(CalcError::value(format!(
378            "{name} expects {minimum} to {maximum} arguments"
379        )))
380    }
381}
382
383fn selected_if_value(argument: Argument) -> CalcResult {
384    match argument {
385        Argument::Scalar(Value::Error(error)) => Err(error),
386        Argument::Scalar(value) => Ok(value),
387        Argument::Missing => Ok(Value::from(0_i64)),
388        Argument::Range(_) => Err(CalcError::value("IF branch must be a scalar")),
389    }
390}
391
392fn if_prepared(
393    arguments: &[Argument],
394    _context: &mut dyn EvalContext,
395    policy: CoercionPolicy,
396) -> CalcResult {
397    require_count("IF", arguments, 1, 3)?;
398    let condition = coerce_logical(required_scalar(&arguments[0], "IF condition")?, policy)?;
399    if arguments.len() == 1 {
400        return Ok(Value::Boolean(condition));
401    }
402    let selected = if condition { 1 } else { 2 };
403    if selected >= arguments.len() {
404        return Ok(Value::Boolean(false));
405    }
406    selected_if_value(arguments[selected].clone())
407}
408
409fn collect_numbers(arguments: &[Argument], policy: CoercionPolicy) -> CalcResult<Vec<Number>> {
410    let mut numbers = Vec::new();
411    for argument in arguments {
412        match argument {
413            Argument::Missing => return Err(CalcError::value("missing aggregate argument")),
414            Argument::Scalar(value) => match value {
415                Value::Number(number) => numbers.push(*number),
416                Value::Empty => {}
417                Value::Error(error) => return Err(error.clone()),
418                Value::Boolean(_) | Value::Text(_) => {
419                    numbers.push(coerce_number(value, policy)?);
420                }
421            },
422            Argument::Range(values) => {
423                for value in values {
424                    match value {
425                        Value::Number(number) => numbers.push(*number),
426                        Value::Empty => {}
427                        Value::Error(error) => return Err(error.clone()),
428                        Value::Boolean(_) | Value::Text(_)
429                            if policy == CoercionPolicy::OpenFormula => {}
430                        Value::Boolean(_) | Value::Text(_) => {
431                            return Err(CalcError::value(
432                                "range contains a non-numeric value under strict coercion",
433                            ));
434                        }
435                    }
436                }
437            }
438        }
439    }
440    Ok(numbers)
441}
442
443fn strict_requires_argument(
444    name: &str,
445    arguments: &[Argument],
446    policy: CoercionPolicy,
447) -> CalcResult<()> {
448    if policy == CoercionPolicy::Strict && arguments.is_empty() {
449        Err(CalcError::value(format!(
450            "{name} requires at least one argument under strict coercion"
451        )))
452    } else {
453        Ok(())
454    }
455}
456
457fn sum(
458    arguments: &[Argument],
459    _context: &mut dyn EvalContext,
460    policy: CoercionPolicy,
461) -> CalcResult {
462    strict_requires_argument("SUM", arguments, policy)?;
463    let numbers = collect_numbers(arguments, policy)?;
464    if numbers.is_empty() {
465        return Ok(Value::from(0_i64));
466    }
467    let all_integer = numbers.iter().all(|number| number.as_i64().is_some());
468    if all_integer {
469        let mut total = Number::from_i64(0);
470        for number in numbers {
471            total = total.checked_add(number)?;
472        }
473        return Ok(Value::Number(total));
474    }
475    let mut total = 0.0;
476    let mut compensation = 0.0;
477    for number in numbers {
478        let value = number.as_f64();
479        let adjusted = value - compensation;
480        let next = total + adjusted;
481        compensation = (next - total) - adjusted;
482        total = next;
483        if !total.is_finite() {
484            return Err(CalcError::num("SUM overflow"));
485        }
486    }
487    Ok(Value::Number(Number::try_from_f64(total)?))
488}
489
490fn min(
491    arguments: &[Argument],
492    _context: &mut dyn EvalContext,
493    policy: CoercionPolicy,
494) -> CalcResult {
495    strict_requires_argument("MIN", arguments, policy)?;
496    let numbers = collect_numbers(arguments, policy)?;
497    let value = numbers
498        .into_iter()
499        .min_by(|left, right| left.partial_cmp(right).unwrap_or(Ordering::Equal))
500        .unwrap_or_else(|| Number::from_i64(0));
501    Ok(Value::Number(value))
502}
503
504fn max(
505    arguments: &[Argument],
506    _context: &mut dyn EvalContext,
507    policy: CoercionPolicy,
508) -> CalcResult {
509    strict_requires_argument("MAX", arguments, policy)?;
510    let numbers = collect_numbers(arguments, policy)?;
511    let value = numbers
512        .into_iter()
513        .max_by(|left, right| left.partial_cmp(right).unwrap_or(Ordering::Equal))
514        .unwrap_or_else(|| Number::from_i64(0));
515    Ok(Value::Number(value))
516}
517
518fn average(
519    arguments: &[Argument],
520    _context: &mut dyn EvalContext,
521    policy: CoercionPolicy,
522) -> CalcResult {
523    strict_requires_argument("AVERAGE", arguments, policy)?;
524    let numbers = collect_numbers(arguments, policy)?;
525    if numbers.is_empty() {
526        return Err(CalcError::new(
527            CalcErrorKind::DivZero,
528            "AVERAGE has no numeric values",
529        ));
530    }
531    let mut total = 0.0;
532    let mut compensation = 0.0;
533    for number in &numbers {
534        let adjusted = number.as_f64() - compensation;
535        let next = total + adjusted;
536        compensation = (next - total) - adjusted;
537        total = next;
538    }
539    let value = total / numbers.len() as f64;
540    Ok(Value::Number(Number::try_from_f64(value)?))
541}
542
543fn abs(
544    arguments: &[Argument],
545    _context: &mut dyn EvalContext,
546    policy: CoercionPolicy,
547) -> CalcResult {
548    require_count("ABS", arguments, 1, 1)?;
549    let value = coerce_number(required_scalar(&arguments[0], "ABS value")?, policy)?;
550    Ok(Value::Number(value.checked_abs()?))
551}
552
553fn round(
554    arguments: &[Argument],
555    _context: &mut dyn EvalContext,
556    policy: CoercionPolicy,
557) -> CalcResult {
558    require_count("ROUND", arguments, 1, 2)?;
559    let value = coerce_number(required_scalar(&arguments[0], "ROUND value")?, policy)?;
560    let digits = if arguments.len() == 2 {
561        let digits = coerce_number(required_scalar(&arguments[1], "ROUND digits")?, policy)?;
562        let digits = digits
563            .as_i64_exact()
564            .ok_or_else(|| CalcError::value("ROUND digits must be an integer"))?;
565        if !(-15..=15).contains(&digits) {
566            return Err(CalcError::new(
567                CalcErrorKind::Limit,
568                "ROUND digits must be in -15..=15",
569            ));
570        }
571        digits as i32
572    } else {
573        0
574    };
575    let factor = libm::pow(10.0, f64::from(digits.unsigned_abs()));
576    let rounded = if digits >= 0 {
577        stable_round_half_away(value.as_f64() * factor) / factor
578    } else {
579        stable_round_half_away(value.as_f64() / factor) * factor
580    };
581    Ok(Value::Number(Number::try_from_f64(rounded)?))
582}
583
584fn floor(
585    arguments: &[Argument],
586    _context: &mut dyn EvalContext,
587    policy: CoercionPolicy,
588) -> CalcResult {
589    round_to_multiple("FLOOR", arguments, policy, Direction::Floor)
590}
591
592fn ceiling(
593    arguments: &[Argument],
594    _context: &mut dyn EvalContext,
595    policy: CoercionPolicy,
596) -> CalcResult {
597    round_to_multiple("CEILING", arguments, policy, Direction::Ceiling)
598}
599
600#[derive(Clone, Copy)]
601enum Direction {
602    Floor,
603    Ceiling,
604}
605
606fn round_to_multiple(
607    name: &str,
608    arguments: &[Argument],
609    policy: CoercionPolicy,
610    direction: Direction,
611) -> CalcResult {
612    require_count(name, arguments, 1, 3)?;
613    let number = coerce_number(required_scalar(&arguments[0], "rounding value")?, policy)?;
614    let raw_number = number.as_f64();
615    let significance = if arguments.len() >= 2 {
616        match &arguments[1] {
617            Argument::Missing => {
618                if raw_number < 0.0 {
619                    -1.0
620                } else {
621                    1.0
622                }
623            }
624            argument => coerce_number(required_scalar(argument, "significance")?, policy)?.as_f64(),
625        }
626    } else if raw_number < 0.0 {
627        -1.0
628    } else {
629        1.0
630    };
631    let mode = if arguments.len() == 3 {
632        match &arguments[2] {
633            Argument::Missing => false,
634            argument => !coerce_number(required_scalar(argument, "mode")?, policy)?.is_zero(),
635        }
636    } else {
637        false
638    };
639    if raw_number == 0.0 || significance == 0.0 {
640        return Ok(Value::Number(Number::try_from_f64(0.0)?));
641    }
642    if raw_number.is_sign_negative() != significance.is_sign_negative() {
643        return Err(CalcError::num(format!(
644            "{name} value and significance must have the same sign"
645        )));
646    }
647    let unit = libm::fabs(significance);
648    let (quotient, sign) = if mode {
649        (
650            libm::fabs(raw_number) / unit,
651            if raw_number < 0.0 { -1.0 } else { 1.0 },
652        )
653    } else {
654        (raw_number / unit, 1.0)
655    };
656    if !quotient.is_finite() {
657        return Err(CalcError::num(format!("{name} quotient overflow")));
658    }
659    let nearest = libm::round(quotient);
660    if libm::fabs(quotient - nearest) <= two_ulp_tolerance(quotient) {
661        return Ok(Value::Number(Number::try_from_f64(raw_number)?));
662    }
663    let multiple = match (direction, mode) {
664        (Direction::Ceiling, _) => libm::ceil(quotient),
665        (Direction::Floor, _) => libm::floor(quotient),
666    };
667    let result = normalize_zero(multiple * unit * sign);
668    Ok(Value::Number(Number::try_from_f64(result)?))
669}
670
671fn power(
672    arguments: &[Argument],
673    _context: &mut dyn EvalContext,
674    policy: CoercionPolicy,
675) -> CalcResult {
676    require_count("POWER", arguments, 2, 2)?;
677    let base = coerce_number(required_scalar(&arguments[0], "POWER base")?, policy)?;
678    let exponent = coerce_number(required_scalar(&arguments[1], "POWER exponent")?, policy)?;
679    let base = base.as_f64();
680    let exponent = exponent.as_f64();
681    if base == 0.0 && exponent < 0.0 {
682        return Err(CalcError::new(
683            CalcErrorKind::DivZero,
684            "POWER cannot raise zero to a negative exponent",
685        ));
686    }
687    if base == 0.0 && exponent == 0.0 {
688        return Ok(Value::from(1_i64));
689    }
690    if base < 0.0 && libm::trunc(exponent) != exponent {
691        return Err(CalcError::num(
692            "POWER with a negative base requires an integer exponent",
693        ));
694    }
695    Ok(Value::Number(Number::try_from_f64(libm::pow(
696        base, exponent,
697    ))?))
698}
699
700fn stable_round_half_away(value: f64) -> f64 {
701    let truncated = libm::trunc(value);
702    let fraction = value - truncated;
703    if libm::fabs(libm::fabs(fraction) - 0.5) <= two_ulp_tolerance(value) {
704        truncated + if value < 0.0 { -1.0 } else { 1.0 }
705    } else {
706        libm::round(value)
707    }
708}
709
710fn two_ulp_tolerance(value: f64) -> f64 {
711    let next = next_up(value);
712    2.0 * libm::fabs(next - value)
713}
714
715fn next_up(value: f64) -> f64 {
716    if value == f64::INFINITY {
717        return value;
718    }
719    if value == -0.0 {
720        return f64::from_bits(1);
721    }
722    let bits = value.to_bits();
723    if value >= 0.0 {
724        f64::from_bits(bits + 1)
725    } else {
726        f64::from_bits(bits - 1)
727    }
728}