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#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
12pub enum CoercionPolicy {
13 #[default]
15 OpenFormula,
16 Strict,
19}
20
21#[derive(Clone, Debug, PartialEq, Eq)]
23pub enum FunctionNamespace {
24 Standard,
26 Extension(String),
28}
29
30#[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 #[must_use]
42 pub fn name(&self) -> &str {
43 &self.name
44 }
45
46 #[must_use]
48 pub const fn namespace(&self) -> &FunctionNamespace {
49 &self.namespace
50 }
51
52 #[must_use]
54 pub const fn openformula_reference(&self) -> Option<&'static str> {
55 self.openformula_reference
56 }
57
58 #[must_use]
60 pub const fn notes(&self) -> &'static str {
61 self.notes
62 }
63}
64
65pub type FunctionHandler = fn(&[Argument], &mut dyn EvalContext, CoercionPolicy) -> CalcResult;
67
68#[derive(Clone)]
69struct RegisteredFunction {
70 metadata: FunctionMetadata,
71 handler: FunctionHandler,
72}
73
74#[derive(Clone)]
76pub struct FunctionRegistry {
77 functions: BTreeMap<String, RegisteredFunction>,
78 coercion: CoercionPolicy,
79}
80
81impl FunctionRegistry {
82 #[must_use]
84 pub fn standard() -> Self {
85 Self::standard_with_policy(CoercionPolicy::OpenFormula)
86 }
87
88 #[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 #[must_use]
155 pub const fn coercion_policy(&self) -> CoercionPolicy {
156 self.coercion
157 }
158
159 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 #[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 pub fn all_metadata(&self) -> impl Iterator<Item = &FunctionMetadata> {
206 self.functions.values().map(|function| &function.metadata)
207 }
208
209 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 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
291pub 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
311pub 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}