formualizer_eval/builtins/

engineering.rs

//! Engineering functions
//! Bitwise: BITAND, BITOR, BITXOR, BITLSHIFT, BITRSHIFT

use super::utils::{ARG_ANY_TWO, ARG_NUM_LENIENT_TWO, coerce_num};
use crate::args::ArgSchema;
use crate::function::Function;
use crate::traits::{ArgumentHandle, FunctionContext};
use formualizer_common::{ExcelError, LiteralValue};
use formualizer_macros::func_caps;

mod transcendental;

/// Helper to convert to integer for bitwise operations
/// Excel's bitwise functions only work with non-negative integers up to 2^48
fn to_bitwise_int(v: &LiteralValue) -> Result<i64, ExcelError> {
    let n = coerce_num(v)?;
    if n < 0.0 || n != n.trunc() || n >= 281474976710656.0 {
        // 2^48
        return Err(ExcelError::new_num());
    }
    Ok(n as i64)
}

/* ─────────────────────────── BITAND ──────────────────────────── */

/// Returns the bitwise AND of two non-negative integers.
///
/// Combines matching bits from both inputs and keeps only bits set in both numbers.
///
/// # Remarks
/// - Arguments are coerced to numbers and must be whole numbers in the range `[0, 2^48)`.
/// - Returns `#NUM!` for negative values, fractional values, or values outside the supported range.
/// - Propagates input errors.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Mask selected bits"
/// formula: "=BITAND(13,10)"
/// expected: 8
/// ```
///
/// ```yaml,sandbox
/// title: "Check least-significant bit"
/// formula: "=BITAND(7,1)"
/// expected: 1
/// ```
/// ```yaml,docs
/// related:
///   - BITOR
///   - BITXOR
///   - BITLSHIFT
/// faq:
///   - q: "When does `BITAND` return `#NUM!`?"
///     a: "Inputs must be whole numbers in `[0, 2^48)`; negatives, fractions, and out-of-range values return `#NUM!`."
/// ```
#[derive(Debug)]
pub struct BitAndFn;
/// [formualizer-docgen:schema:start]
/// Name: BITAND
/// Type: BitAndFn
/// Min args: 2
/// Max args: 2
/// Variadic: false
/// Signature: BITAND(arg1: number@scalar, arg2: number@scalar)
/// Arg schema: arg1{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}; arg2{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for BitAndFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "BITAND"
    }
    fn min_args(&self) -> usize {
        2
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_NUM_LENIENT_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let a = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match to_bitwise_int(&other) {
                Ok(n) => n,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };
        let b = match args[1].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match to_bitwise_int(&other) {
                Ok(n) => n,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
            (a & b) as f64,
        )))
    }
}

/* ─────────────────────────── BITOR ──────────────────────────── */

/// Returns the bitwise OR of two non-negative integers.
///
/// Combines matching bits from both inputs and keeps bits set in either number.
///
/// # Remarks
/// - Arguments are coerced to numbers and must be whole numbers in the range `[0, 2^48)`.
/// - Returns `#NUM!` for negative values, fractional values, or out-of-range values.
/// - Propagates input errors.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Merge bit flags"
/// formula: "=BITOR(13,10)"
/// expected: 15
/// ```
///
/// ```yaml,sandbox
/// title: "Set an additional bit"
/// formula: "=BITOR(8,1)"
/// expected: 9
/// ```
/// ```yaml,docs
/// related:
///   - BITAND
///   - BITXOR
///   - BITRSHIFT
/// faq:
///   - q: "Does `BITOR` accept decimal-looking values like `3.0`?"
///     a: "Yes if they coerce to whole integers; non-integer values still return `#NUM!`."
/// ```
#[derive(Debug)]
pub struct BitOrFn;
/// [formualizer-docgen:schema:start]
/// Name: BITOR
/// Type: BitOrFn
/// Min args: 2
/// Max args: 2
/// Variadic: false
/// Signature: BITOR(arg1: number@scalar, arg2: number@scalar)
/// Arg schema: arg1{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}; arg2{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for BitOrFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "BITOR"
    }
    fn min_args(&self) -> usize {
        2
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_NUM_LENIENT_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let a = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match to_bitwise_int(&other) {
                Ok(n) => n,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };
        let b = match args[1].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match to_bitwise_int(&other) {
                Ok(n) => n,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
            (a | b) as f64,
        )))
    }
}

/* ─────────────────────────── BITXOR ──────────────────────────── */

/// Returns the bitwise exclusive OR of two non-negative integers.
///
/// Keeps bits that differ between the two inputs.
///
/// # Remarks
/// - Arguments are coerced to numbers and must be whole numbers in the range `[0, 2^48)`.
/// - Returns `#NUM!` for negative values, fractional values, or out-of-range values.
/// - Propagates input errors.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Highlight differing bits"
/// formula: "=BITXOR(13,10)"
/// expected: 7
/// ```
///
/// ```yaml,sandbox
/// title: "XOR identical values"
/// formula: "=BITXOR(5,5)"
/// expected: 0
/// ```
/// ```yaml,docs
/// related:
///   - BITAND
///   - BITOR
///   - BITLSHIFT
/// faq:
///   - q: "Why does `BITXOR(x, x)` return `0`?"
///     a: "XOR keeps only differing bits; identical operands cancel every bit position."
/// ```
#[derive(Debug)]
pub struct BitXorFn;
/// [formualizer-docgen:schema:start]
/// Name: BITXOR
/// Type: BitXorFn
/// Min args: 2
/// Max args: 2
/// Variadic: false
/// Signature: BITXOR(arg1: number@scalar, arg2: number@scalar)
/// Arg schema: arg1{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}; arg2{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for BitXorFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "BITXOR"
    }
    fn min_args(&self) -> usize {
        2
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_NUM_LENIENT_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let a = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match to_bitwise_int(&other) {
                Ok(n) => n,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };
        let b = match args[1].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match to_bitwise_int(&other) {
                Ok(n) => n,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
            (a ^ b) as f64,
        )))
    }
}

/* ─────────────────────────── BITLSHIFT ──────────────────────────── */

/// Shifts a non-negative integer left or right by a given bit count.
///
/// Positive `shift_amount` shifts left; negative `shift_amount` shifts right.
///
/// # Remarks
/// - `number` must be a whole number in `[0, 2^48)`.
/// - Shift values are numerically coerced; large positive shifts can return `#NUM!`.
/// - Left-shift results must remain below `2^48`, or the function returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Shift left by two bits"
/// formula: "=BITLSHIFT(6,2)"
/// expected: 24
/// ```
///
/// ```yaml,sandbox
/// title: "Use negative shift to move right"
/// formula: "=BITLSHIFT(32,-3)"
/// expected: 4
/// ```
/// ```yaml,docs
/// related:
///   - BITRSHIFT
///   - BITAND
///   - BITOR
/// faq:
///   - q: "What does a negative `shift_amount` do in `BITLSHIFT`?"
///     a: "Negative shifts are interpreted as right shifts, while positive shifts move bits left."
/// ```
#[derive(Debug)]
pub struct BitLShiftFn;
/// [formualizer-docgen:schema:start]
/// Name: BITLSHIFT
/// Type: BitLShiftFn
/// Min args: 2
/// Max args: 2
/// Variadic: false
/// Signature: BITLSHIFT(arg1: number@scalar, arg2: number@scalar)
/// Arg schema: arg1{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}; arg2{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for BitLShiftFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "BITLSHIFT"
    }
    fn min_args(&self) -> usize {
        2
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_NUM_LENIENT_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let n = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match to_bitwise_int(&other) {
                Ok(n) => n,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };
        let shift = match args[1].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => coerce_num(&other)? as i32,
        };

        // Negative shift means right shift
        let result = if shift >= 0 {
            if shift >= 48 {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_num(),
                )));
            }
            let shifted = n << shift;
            // Check if result exceeds 48-bit limit
            if shifted >= 281474976710656 {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_num(),
                )));
            }
            shifted
        } else {
            let rshift = (-shift) as u32;
            if rshift >= 48 { 0 } else { n >> rshift }
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
            result as f64,
        )))
    }
}

/* ─────────────────────────── BITRSHIFT ──────────────────────────── */

/// Shifts a non-negative integer right or left by a given bit count.
///
/// Positive `shift_amount` shifts right; negative `shift_amount` shifts left.
///
/// # Remarks
/// - `number` must be a whole number in `[0, 2^48)`.
/// - Shift values are numerically coerced; large right shifts return `0`.
/// - Negative shifts that overflow the 48-bit limit return `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Shift right by three bits"
/// formula: "=BITRSHIFT(32,3)"
/// expected: 4
/// ```
///
/// ```yaml,sandbox
/// title: "Use negative shift to move left"
/// formula: "=BITRSHIFT(5,-1)"
/// expected: 10
/// ```
/// ```yaml,docs
/// related:
///   - BITLSHIFT
///   - BITAND
///   - BITXOR
/// faq:
///   - q: "Why can negative shifts in `BITRSHIFT` return `#NUM!`?"
///     a: "A negative shift means left-shift; if that left result exceeds the 48-bit limit, `#NUM!` is returned."
/// ```
#[derive(Debug)]
pub struct BitRShiftFn;
/// [formualizer-docgen:schema:start]
/// Name: BITRSHIFT
/// Type: BitRShiftFn
/// Min args: 2
/// Max args: 2
/// Variadic: false
/// Signature: BITRSHIFT(arg1: number@scalar, arg2: number@scalar)
/// Arg schema: arg1{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}; arg2{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for BitRShiftFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "BITRSHIFT"
    }
    fn min_args(&self) -> usize {
        2
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_NUM_LENIENT_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let n = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match to_bitwise_int(&other) {
                Ok(n) => n,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };
        let shift = match args[1].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => coerce_num(&other)? as i32,
        };

        // Negative shift means left shift
        let result = if shift >= 0 {
            if shift >= 48 { 0 } else { n >> shift }
        } else {
            let lshift = (-shift) as u32;
            if lshift >= 48 {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_num(),
                )));
            }
            let shifted = n << lshift;
            // Check if result exceeds 48-bit limit
            if shifted >= 281474976710656 {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_num(),
                )));
            }
            shifted
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
            result as f64,
        )))
    }
}

/* ─────────────────────────── Base Conversion Functions ──────────────────────────── */

use super::utils::ARG_ANY_ONE;

/// Helper to coerce value to text for base conversion
fn coerce_base_text(v: &LiteralValue) -> Result<String, ExcelError> {
    match v {
        LiteralValue::Text(s) => Ok(s.clone()),
        LiteralValue::Int(i) => Ok(i.to_string()),
        LiteralValue::Number(n) => Ok((*n as i64).to_string()),
        LiteralValue::Error(e) => Err(e.clone()),
        _ => Err(ExcelError::new_value()),
    }
}

/// Converts a binary text value to decimal.
///
/// Supports up to 10 binary digits, including two's-complement negative values.
///
/// # Remarks
/// - Input is coerced to text and must contain only `0` and `1`.
/// - 10-digit values starting with `1` are interpreted as signed two's-complement numbers.
/// - Returns `#NUM!` for invalid characters or inputs longer than 10 digits.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Convert an unsigned binary value"
/// formula: "=BIN2DEC(\"101010\")"
/// expected: 42
/// ```
///
/// ```yaml,sandbox
/// title: "Interpret signed 10-bit binary"
/// formula: "=BIN2DEC(\"1111111111\")"
/// expected: -1
/// ```
/// ```yaml,docs
/// related:
///   - DEC2BIN
///   - BIN2HEX
///   - BIN2OCT
/// faq:
///   - q: "How does `BIN2DEC` handle 10-bit values starting with `1`?"
///     a: "They are interpreted as signed two's-complement values, so `1111111111` becomes `-1`."
/// ```
#[derive(Debug)]
pub struct Bin2DecFn;
/// [formualizer-docgen:schema:start]
/// Name: BIN2DEC
/// Type: Bin2DecFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: BIN2DEC(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for Bin2DecFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "BIN2DEC"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let text = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_base_text(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        // Excel accepts 10-character binary (with sign bit)
        if text.len() > 10 || !text.chars().all(|c| c == '0' || c == '1') {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        // Handle two's complement for negative numbers (10 bits, first bit is sign)
        let result = if text.len() == 10 && text.starts_with('1') {
            // Negative number in two's complement
            let val = i64::from_str_radix(&text, 2).unwrap_or(0);
            val - 1024 // 2^10
        } else {
            i64::from_str_radix(&text, 2).unwrap_or(0)
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
            result as f64,
        )))
    }
}

/// Converts a decimal integer to binary text.
///
/// Optionally pads the result with leading zeros using `places`.
///
/// # Remarks
/// - `number` is coerced to an integer and must be in `[-512, 511]`.
/// - Negative values are returned as 10-bit two's-complement binary strings.
/// - `places` must be at least the output width and at most `10`, or `#NUM!` is returned.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Convert a positive integer"
/// formula: "=DEC2BIN(42)"
/// expected: "101010"
/// ```
///
/// ```yaml,sandbox
/// title: "Pad binary output"
/// formula: "=DEC2BIN(5,8)"
/// expected: "00000101"
/// ```
/// ```yaml,docs
/// related:
///   - BIN2DEC
///   - DEC2HEX
///   - DEC2OCT
/// faq:
///   - q: "What limits apply to `DEC2BIN`?"
///     a: "`number` must be in `[-512, 511]`, and optional `places` must be between output width and `10`, else `#NUM!`."
/// ```
#[derive(Debug)]
pub struct Dec2BinFn;
/// [formualizer-docgen:schema:start]
/// Name: DEC2BIN
/// Type: Dec2BinFn
/// Min args: 1
/// Max args: variadic
/// Variadic: true
/// Signature: DEC2BIN(arg1: number@scalar, arg2...: number@scalar)
/// Arg schema: arg1{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}; arg2{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for Dec2BinFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "DEC2BIN"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn variadic(&self) -> bool {
        true
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_NUM_LENIENT_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let n = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => coerce_num(&other)? as i64,
        };

        // Excel limits: -512 to 511
        if !(-512..=511).contains(&n) {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        let places = if args.len() > 1 {
            match args[1].value()?.into_literal() {
                LiteralValue::Error(e) => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
                }
                other => Some(coerce_num(&other)? as usize),
            }
        } else {
            None
        };

        let binary = if n >= 0 {
            format!("{:b}", n)
        } else {
            // Two's complement with 10 bits
            format!("{:010b}", (n + 1024) as u64)
        };

        let result = if let Some(p) = places {
            if p < binary.len() || p > 10 {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_num(),
                )));
            }
            format!("{:0>width$}", binary, width = p)
        } else {
            binary
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Converts a hexadecimal text value to decimal.
///
/// Supports up to 10 hex digits, including signed two's-complement values.
///
/// # Remarks
/// - Input is coerced to text and must contain only hexadecimal characters.
/// - 10-digit values beginning with `8`-`F` are interpreted as signed 40-bit numbers.
/// - Returns `#NUM!` for invalid characters or inputs longer than 10 digits.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Convert a positive hex value"
/// formula: "=HEX2DEC(\"FF\")"
/// expected: 255
/// ```
///
/// ```yaml,sandbox
/// title: "Interpret signed 40-bit hex"
/// formula: "=HEX2DEC(\"FFFFFFFFFF\")"
/// expected: -1
/// ```
/// ```yaml,docs
/// related:
///   - DEC2HEX
///   - HEX2BIN
///   - HEX2OCT
/// faq:
///   - q: "When is a 10-digit hex input treated as negative in `HEX2DEC`?"
///     a: "If the first digit is `8` through `F`, it is decoded as signed 40-bit two's-complement."
/// ```
#[derive(Debug)]
pub struct Hex2DecFn;
/// [formualizer-docgen:schema:start]
/// Name: HEX2DEC
/// Type: Hex2DecFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: HEX2DEC(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for Hex2DecFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "HEX2DEC"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let text = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_base_text(&other) {
                Ok(s) => s.to_uppercase(),
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        // Excel accepts 10-character hex
        if text.len() > 10 || !text.chars().all(|c| c.is_ascii_hexdigit()) {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        let result = if text.len() == 10 && text.starts_with(|c| c >= '8') {
            // Negative number in two's complement (40 bits)
            let val = i64::from_str_radix(&text, 16).unwrap_or(0);
            val - (1i64 << 40)
        } else {
            i64::from_str_radix(&text, 16).unwrap_or(0)
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
            result as f64,
        )))
    }
}

/// Converts a decimal integer to hexadecimal text.
///
/// Optionally pads the result with leading zeros using `places`.
///
/// # Remarks
/// - `number` is coerced to an integer and must be in `[-2^39, 2^39 - 1]`.
/// - Negative values are returned as 10-digit two's-complement hexadecimal strings.
/// - `places` must be at least the output width and at most `10`, or `#NUM!` is returned.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Convert decimal to hex"
/// formula: "=DEC2HEX(255)"
/// expected: "FF"
/// ```
///
/// ```yaml,sandbox
/// title: "Pad hexadecimal output"
/// formula: "=DEC2HEX(31,4)"
/// expected: "001F"
/// ```
/// ```yaml,docs
/// related:
///   - HEX2DEC
///   - DEC2BIN
///   - DEC2OCT
/// faq:
///   - q: "How are negative values formatted by `DEC2HEX`?"
///     a: "Negative outputs use 10-digit two's-complement hexadecimal representation."
/// ```
#[derive(Debug)]
pub struct Dec2HexFn;
/// [formualizer-docgen:schema:start]
/// Name: DEC2HEX
/// Type: Dec2HexFn
/// Min args: 1
/// Max args: variadic
/// Variadic: true
/// Signature: DEC2HEX(arg1: number@scalar, arg2...: number@scalar)
/// Arg schema: arg1{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}; arg2{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for Dec2HexFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "DEC2HEX"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn variadic(&self) -> bool {
        true
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_NUM_LENIENT_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let n = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => coerce_num(&other)? as i64,
        };

        // Excel limits
        if !(-(1i64 << 39)..=(1i64 << 39) - 1).contains(&n) {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        let places = if args.len() > 1 {
            match args[1].value()?.into_literal() {
                LiteralValue::Error(e) => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
                }
                other => Some(coerce_num(&other)? as usize),
            }
        } else {
            None
        };

        let hex = if n >= 0 {
            format!("{:X}", n)
        } else {
            // Two's complement with 10 hex digits (40 bits)
            format!("{:010X}", (n + (1i64 << 40)) as u64)
        };

        let result = if let Some(p) = places {
            if p < hex.len() || p > 10 {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_num(),
                )));
            }
            format!("{:0>width$}", hex, width = p)
        } else {
            hex
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Converts an octal text value to decimal.
///
/// Supports up to 10 octal digits, including signed two's-complement values.
///
/// # Remarks
/// - Input is coerced to text and must contain only digits `0` through `7`.
/// - 10-digit values beginning with `4`-`7` are interpreted as signed 30-bit numbers.
/// - Returns `#NUM!` for invalid characters or inputs longer than 10 digits.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Convert positive octal"
/// formula: "=OCT2DEC(\"17\")"
/// expected: 15
/// ```
///
/// ```yaml,sandbox
/// title: "Interpret signed 30-bit octal"
/// formula: "=OCT2DEC(\"7777777777\")"
/// expected: -1
/// ```
/// ```yaml,docs
/// related:
///   - DEC2OCT
///   - OCT2BIN
///   - OCT2HEX
/// faq:
///   - q: "How does `OCT2DEC` interpret 10-digit values starting with `4`-`7`?"
///     a: "Those are treated as signed 30-bit two's-complement octal values."
/// ```
#[derive(Debug)]
pub struct Oct2DecFn;
/// [formualizer-docgen:schema:start]
/// Name: OCT2DEC
/// Type: Oct2DecFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: OCT2DEC(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for Oct2DecFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "OCT2DEC"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let text = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_base_text(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        // Excel accepts 10-character octal (30 bits)
        if text.len() > 10 || !text.chars().all(|c| ('0'..='7').contains(&c)) {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        let result = if text.len() == 10 && text.starts_with(|c| c >= '4') {
            // Negative number in two's complement (30 bits)
            let val = i64::from_str_radix(&text, 8).unwrap_or(0);
            val - (1i64 << 30)
        } else {
            i64::from_str_radix(&text, 8).unwrap_or(0)
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
            result as f64,
        )))
    }
}

/// Converts a decimal integer to octal text.
///
/// Optionally pads the result with leading zeros using `places`.
///
/// # Remarks
/// - `number` is coerced to an integer and must be in `[-2^29, 2^29 - 1]`.
/// - Negative values are returned as 10-digit two's-complement octal strings.
/// - `places` must be at least the output width and at most `10`, or `#NUM!` is returned.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Convert decimal to octal"
/// formula: "=DEC2OCT(64)"
/// expected: "100"
/// ```
///
/// ```yaml,sandbox
/// title: "Two's-complement negative output"
/// formula: "=DEC2OCT(-1)"
/// expected: "7777777777"
/// ```
/// ```yaml,docs
/// related:
///   - OCT2DEC
///   - DEC2BIN
///   - DEC2HEX
/// faq:
///   - q: "What range does `DEC2OCT` support?"
///     a: "`number` must be in `[-2^29, 2^29 - 1]`; outside that range returns `#NUM!`."
/// ```
#[derive(Debug)]
pub struct Dec2OctFn;
/// [formualizer-docgen:schema:start]
/// Name: DEC2OCT
/// Type: Dec2OctFn
/// Min args: 1
/// Max args: variadic
/// Variadic: true
/// Signature: DEC2OCT(arg1: number@scalar, arg2...: number@scalar)
/// Arg schema: arg1{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}; arg2{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for Dec2OctFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "DEC2OCT"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn variadic(&self) -> bool {
        true
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_NUM_LENIENT_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let n = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => coerce_num(&other)? as i64,
        };

        // Excel limits: -536870912 to 536870911
        if !(-(1i64 << 29)..=(1i64 << 29) - 1).contains(&n) {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        let places = if args.len() > 1 {
            match args[1].value()?.into_literal() {
                LiteralValue::Error(e) => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
                }
                other => Some(coerce_num(&other)? as usize),
            }
        } else {
            None
        };

        let octal = if n >= 0 {
            format!("{:o}", n)
        } else {
            // Two's complement with 10 octal digits (30 bits)
            format!("{:010o}", (n + (1i64 << 30)) as u64)
        };

        let result = if let Some(p) = places {
            if p < octal.len() || p > 10 {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_num(),
                )));
            }
            format!("{:0>width$}", octal, width = p)
        } else {
            octal
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/* ─────────────────────────── Cross-Base Conversions ──────────────────────────── */

/// Converts a binary text value to hexadecimal text.
///
/// Optionally pads the output with leading zeros using `places`.
///
/// # Remarks
/// - Input must be a binary string up to 10 digits; 10-digit values may be signed.
/// - Signed binary values are converted using two's-complement semantics.
/// - `places` must be at least the output width and at most `10`, or `#NUM!` is returned.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Convert binary to hex"
/// formula: "=BIN2HEX(\"1010\")"
/// expected: "A"
/// ```
///
/// ```yaml,sandbox
/// title: "Pad hexadecimal output"
/// formula: "=BIN2HEX(\"1010\",4)"
/// expected: "000A"
/// ```
/// ```yaml,docs
/// related:
///   - HEX2BIN
///   - BIN2DEC
///   - DEC2HEX
/// faq:
///   - q: "Does `BIN2HEX` preserve signed binary meaning?"
///     a: "Yes. A 10-bit binary with leading `1` is interpreted as signed and converted using two's-complement semantics."
/// ```
#[derive(Debug)]
pub struct Bin2HexFn;
/// [formualizer-docgen:schema:start]
/// Name: BIN2HEX
/// Type: Bin2HexFn
/// Min args: 1
/// Max args: variadic
/// Variadic: true
/// Signature: BIN2HEX(arg1: number@scalar, arg2...: number@scalar)
/// Arg schema: arg1{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}; arg2{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for Bin2HexFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "BIN2HEX"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn variadic(&self) -> bool {
        true
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_NUM_LENIENT_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let text = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_base_text(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        if text.len() > 10 || !text.chars().all(|c| c == '0' || c == '1') {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        // Convert binary to decimal first
        let dec = if text.len() == 10 && text.starts_with('1') {
            let val = i64::from_str_radix(&text, 2).unwrap_or(0);
            val - 1024
        } else {
            i64::from_str_radix(&text, 2).unwrap_or(0)
        };

        let places = if args.len() > 1 {
            match args[1].value()?.into_literal() {
                LiteralValue::Error(e) => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
                }
                other => Some(coerce_num(&other)? as usize),
            }
        } else {
            None
        };

        let hex = if dec >= 0 {
            format!("{:X}", dec)
        } else {
            format!("{:010X}", (dec + (1i64 << 40)) as u64)
        };

        let result = if let Some(p) = places {
            if p < hex.len() || p > 10 {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_num(),
                )));
            }
            format!("{:0>width$}", hex, width = p)
        } else {
            hex
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Converts a hexadecimal text value to binary text.
///
/// Supports optional left-padding through the `places` argument.
///
/// # Remarks
/// - Input must be hexadecimal text up to 10 characters and may be signed two's-complement.
/// - The converted decimal value must be in `[-512, 511]`, or the function returns `#NUM!`.
/// - `places` must be at least the output width and at most `10`, or `#NUM!` is returned.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Convert positive hex to binary"
/// formula: "=HEX2BIN(\"1F\")"
/// expected: "11111"
/// ```
///
/// ```yaml,sandbox
/// title: "Convert signed hex"
/// formula: "=HEX2BIN(\"FFFFFFFFFF\")"
/// expected: "1111111111"
/// ```
/// ```yaml,docs
/// related:
///   - BIN2HEX
///   - HEX2DEC
///   - DEC2BIN
/// faq:
///   - q: "Why can valid hex text still produce `#NUM!` in `HEX2BIN`?"
///     a: "After conversion, the decimal value must fit `[-512, 511]`; otherwise binary output is rejected."
/// ```
#[derive(Debug)]
pub struct Hex2BinFn;
/// [formualizer-docgen:schema:start]
/// Name: HEX2BIN
/// Type: Hex2BinFn
/// Min args: 1
/// Max args: variadic
/// Variadic: true
/// Signature: HEX2BIN(arg1: any@scalar, arg2...: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}; arg2{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for Hex2BinFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "HEX2BIN"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn variadic(&self) -> bool {
        true
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let text = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_base_text(&other) {
                Ok(s) => s.to_uppercase(),
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        if text.len() > 10 || !text.chars().all(|c| c.is_ascii_hexdigit()) {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        // Convert hex to decimal first
        let dec = if text.len() == 10 && text.starts_with(|c| c >= '8') {
            let val = i64::from_str_radix(&text, 16).unwrap_or(0);
            val - (1i64 << 40)
        } else {
            i64::from_str_radix(&text, 16).unwrap_or(0)
        };

        // Check range for binary output (-512 to 511)
        if !(-512..=511).contains(&dec) {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        let places = if args.len() > 1 {
            match args[1].value()?.into_literal() {
                LiteralValue::Error(e) => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
                }
                other => Some(coerce_num(&other)? as usize),
            }
        } else {
            None
        };

        let binary = if dec >= 0 {
            format!("{:b}", dec)
        } else {
            format!("{:010b}", (dec + 1024) as u64)
        };

        let result = if let Some(p) = places {
            if p < binary.len() || p > 10 {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_num(),
                )));
            }
            format!("{:0>width$}", binary, width = p)
        } else {
            binary
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Converts a binary text value to octal text.
///
/// Supports optional left-padding through the `places` argument.
///
/// # Remarks
/// - Input must be binary text up to 10 digits and may be signed two's-complement.
/// - Signed values are preserved through conversion to octal.
/// - `places` must be at least the output width and at most `10`, or `#NUM!` is returned.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Convert binary to octal"
/// formula: "=BIN2OCT(\"111111\")"
/// expected: "77"
/// ```
///
/// ```yaml,sandbox
/// title: "Pad octal output"
/// formula: "=BIN2OCT(\"111111\",4)"
/// expected: "0077"
/// ```
/// ```yaml,docs
/// related:
///   - OCT2BIN
///   - BIN2DEC
///   - DEC2OCT
/// faq:
///   - q: "How are signed 10-bit binaries handled by `BIN2OCT`?"
///     a: "They are first decoded as signed decimal and then re-encoded to octal with two's-complement output for negatives."
/// ```
#[derive(Debug)]
pub struct Bin2OctFn;
/// [formualizer-docgen:schema:start]
/// Name: BIN2OCT
/// Type: Bin2OctFn
/// Min args: 1
/// Max args: variadic
/// Variadic: true
/// Signature: BIN2OCT(arg1: number@scalar, arg2...: number@scalar)
/// Arg schema: arg1{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}; arg2{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for Bin2OctFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "BIN2OCT"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn variadic(&self) -> bool {
        true
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_NUM_LENIENT_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let text = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_base_text(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        if text.len() > 10 || !text.chars().all(|c| c == '0' || c == '1') {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        let dec = if text.len() == 10 && text.starts_with('1') {
            let val = i64::from_str_radix(&text, 2).unwrap_or(0);
            val - 1024
        } else {
            i64::from_str_radix(&text, 2).unwrap_or(0)
        };

        let places = if args.len() > 1 {
            match args[1].value()?.into_literal() {
                LiteralValue::Error(e) => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
                }
                other => Some(coerce_num(&other)? as usize),
            }
        } else {
            None
        };

        let octal = if dec >= 0 {
            format!("{:o}", dec)
        } else {
            format!("{:010o}", (dec + (1i64 << 30)) as u64)
        };

        let result = if let Some(p) = places {
            if p < octal.len() || p > 10 {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_num(),
                )));
            }
            format!("{:0>width$}", octal, width = p)
        } else {
            octal
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Converts an octal text value to binary text.
///
/// Supports optional left-padding through the `places` argument.
///
/// # Remarks
/// - Input must be octal text up to 10 digits and may be signed two's-complement.
/// - Converted values must fall in `[-512, 511]`, or the function returns `#NUM!`.
/// - `places` must be at least the output width and at most `10`, or `#NUM!` is returned.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Convert octal to binary"
/// formula: "=OCT2BIN(\"77\")"
/// expected: "111111"
/// ```
///
/// ```yaml,sandbox
/// title: "Convert signed octal"
/// formula: "=OCT2BIN(\"7777777777\")"
/// expected: "1111111111"
/// ```
/// ```yaml,docs
/// related:
///   - BIN2OCT
///   - OCT2DEC
///   - DEC2BIN
/// faq:
///   - q: "Why does `OCT2BIN` return `#NUM!` for some octal inputs?"
///     a: "After decoding, the value must be within `[-512, 511]` to be representable in Excel-style binary output."
/// ```
#[derive(Debug)]
pub struct Oct2BinFn;
/// [formualizer-docgen:schema:start]
/// Name: OCT2BIN
/// Type: Oct2BinFn
/// Min args: 1
/// Max args: variadic
/// Variadic: true
/// Signature: OCT2BIN(arg1: number@scalar, arg2...: number@scalar)
/// Arg schema: arg1{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}; arg2{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for Oct2BinFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "OCT2BIN"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn variadic(&self) -> bool {
        true
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_NUM_LENIENT_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let text = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_base_text(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        if text.len() > 10 || !text.chars().all(|c| ('0'..='7').contains(&c)) {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        let dec = if text.len() == 10 && text.starts_with(|c| c >= '4') {
            let val = i64::from_str_radix(&text, 8).unwrap_or(0);
            val - (1i64 << 30)
        } else {
            i64::from_str_radix(&text, 8).unwrap_or(0)
        };

        // Check range for binary output (-512 to 511)
        if !(-512..=511).contains(&dec) {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        let places = if args.len() > 1 {
            match args[1].value()?.into_literal() {
                LiteralValue::Error(e) => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
                }
                other => Some(coerce_num(&other)? as usize),
            }
        } else {
            None
        };

        let binary = if dec >= 0 {
            format!("{:b}", dec)
        } else {
            format!("{:010b}", (dec + 1024) as u64)
        };

        let result = if let Some(p) = places {
            if p < binary.len() || p > 10 {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_num(),
                )));
            }
            format!("{:0>width$}", binary, width = p)
        } else {
            binary
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Converts a hexadecimal text value to octal text.
///
/// Supports optional left-padding through the `places` argument.
///
/// # Remarks
/// - Input must be hexadecimal text up to 10 characters and may be signed two's-complement.
/// - Converted values must fit the octal range `[-2^29, 2^29 - 1]`, or `#NUM!` is returned.
/// - `places` must be at least the output width and at most `10`, or `#NUM!` is returned.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Convert hex to octal"
/// formula: "=HEX2OCT(\"1F\")"
/// expected: "37"
/// ```
///
/// ```yaml,sandbox
/// title: "Convert signed hex"
/// formula: "=HEX2OCT(\"FFFFFFFFFF\")"
/// expected: "7777777777"
/// ```
/// ```yaml,docs
/// related:
///   - OCT2HEX
///   - HEX2DEC
///   - DEC2OCT
/// faq:
///   - q: "What causes `HEX2OCT` to return `#NUM!`?"
///     a: "The decoded value must fit octal output range `[-2^29, 2^29 - 1]`, and optional `places` must be valid."
/// ```
#[derive(Debug)]
pub struct Hex2OctFn;
/// [formualizer-docgen:schema:start]
/// Name: HEX2OCT
/// Type: Hex2OctFn
/// Min args: 1
/// Max args: variadic
/// Variadic: true
/// Signature: HEX2OCT(arg1: any@scalar, arg2...: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}; arg2{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for Hex2OctFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "HEX2OCT"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn variadic(&self) -> bool {
        true
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let text = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_base_text(&other) {
                Ok(s) => s.to_uppercase(),
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        if text.len() > 10 || !text.chars().all(|c| c.is_ascii_hexdigit()) {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        let dec = if text.len() == 10 && text.starts_with(|c| c >= '8') {
            let val = i64::from_str_radix(&text, 16).unwrap_or(0);
            val - (1i64 << 40)
        } else {
            i64::from_str_radix(&text, 16).unwrap_or(0)
        };

        // Check range for octal output
        if !(-(1i64 << 29)..=(1i64 << 29) - 1).contains(&dec) {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        let places = if args.len() > 1 {
            match args[1].value()?.into_literal() {
                LiteralValue::Error(e) => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
                }
                other => Some(coerce_num(&other)? as usize),
            }
        } else {
            None
        };

        let octal = if dec >= 0 {
            format!("{:o}", dec)
        } else {
            format!("{:010o}", (dec + (1i64 << 30)) as u64)
        };

        let result = if let Some(p) = places {
            if p < octal.len() || p > 10 {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_num(),
                )));
            }
            format!("{:0>width$}", octal, width = p)
        } else {
            octal
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Converts an octal text value to hexadecimal text.
///
/// Supports optional left-padding through the `places` argument.
///
/// # Remarks
/// - Input must be octal text up to 10 digits and may be signed two's-complement.
/// - Signed values are converted through their decimal representation.
/// - `places` must be at least the output width and at most `10`, or `#NUM!` is returned.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Convert octal to hex"
/// formula: "=OCT2HEX(\"77\")"
/// expected: "3F"
/// ```
///
/// ```yaml,sandbox
/// title: "Convert signed octal"
/// formula: "=OCT2HEX(\"7777777777\")"
/// expected: "FFFFFFFFFF"
/// ```
/// ```yaml,docs
/// related:
///   - HEX2OCT
///   - OCT2DEC
///   - DEC2HEX
/// faq:
///   - q: "How does `OCT2HEX` treat signed octal input?"
///     a: "Signed 10-digit octal is decoded via two's-complement and then emitted as hex, preserving signed meaning."
/// ```
#[derive(Debug)]
pub struct Oct2HexFn;
/// [formualizer-docgen:schema:start]
/// Name: OCT2HEX
/// Type: Oct2HexFn
/// Min args: 1
/// Max args: variadic
/// Variadic: true
/// Signature: OCT2HEX(arg1: number@scalar, arg2...: number@scalar)
/// Arg schema: arg1{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}; arg2{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for Oct2HexFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "OCT2HEX"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn variadic(&self) -> bool {
        true
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_NUM_LENIENT_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let text = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_base_text(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        if text.len() > 10 || !text.chars().all(|c| ('0'..='7').contains(&c)) {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        let dec = if text.len() == 10 && text.starts_with(|c| c >= '4') {
            let val = i64::from_str_radix(&text, 8).unwrap_or(0);
            val - (1i64 << 30)
        } else {
            i64::from_str_radix(&text, 8).unwrap_or(0)
        };

        let places = if args.len() > 1 {
            match args[1].value()?.into_literal() {
                LiteralValue::Error(e) => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
                }
                other => Some(coerce_num(&other)? as usize),
            }
        } else {
            None
        };

        let hex = if dec >= 0 {
            format!("{:X}", dec)
        } else {
            format!("{:010X}", (dec + (1i64 << 40)) as u64)
        };

        let result = if let Some(p) = places {
            if p < hex.len() || p > 10 {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_num(),
                )));
            }
            format!("{:0>width$}", hex, width = p)
        } else {
            hex
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/* ─────────────────────────── Engineering Comparison Functions ──────────────────────────── */

/// Tests whether two numbers are equal.
///
/// Returns `1` when values match and `0` otherwise.
///
/// # Remarks
/// - If `number2` is omitted, it defaults to `0`.
/// - Inputs are numerically coerced.
/// - Uses a small numeric tolerance for floating-point comparison.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Equal values"
/// formula: "=DELTA(5,5)"
/// expected: 1
/// ```
///
/// ```yaml,sandbox
/// title: "Default second argument"
/// formula: "=DELTA(2.5)"
/// expected: 0
/// ```
/// ```yaml,docs
/// related:
///   - GESTEP
/// faq:
///   - q: "Does `DELTA` require exact floating-point equality?"
///     a: "It uses a small tolerance (`1e-12`), so values that differ only by tiny floating noise compare as equal."
/// ```
#[derive(Debug)]
pub struct DeltaFn;
/// [formualizer-docgen:schema:start]
/// Name: DELTA
/// Type: DeltaFn
/// Min args: 1
/// Max args: variadic
/// Variadic: true
/// Signature: DELTA(arg1: number@scalar, arg2...: number@scalar)
/// Arg schema: arg1{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}; arg2{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for DeltaFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "DELTA"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn variadic(&self) -> bool {
        true
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_NUM_LENIENT_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let n1 = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => coerce_num(&other)?,
        };
        let n2 = if args.len() > 1 {
            match args[1].value()?.into_literal() {
                LiteralValue::Error(e) => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
                }
                other => coerce_num(&other)?,
            }
        } else {
            0.0
        };

        let result = if (n1 - n2).abs() < 1e-12 { 1.0 } else { 0.0 };
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
            result,
        )))
    }
}

/// Returns `1` when a number is greater than or equal to a step value.
///
/// Returns `0` when the number is below the step.
///
/// # Remarks
/// - If `step` is omitted, it defaults to `0`.
/// - Inputs are numerically coerced.
/// - Propagates input errors.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Value meets threshold"
/// formula: "=GESTEP(5,3)"
/// expected: 1
/// ```
///
/// ```yaml,sandbox
/// title: "Default threshold of zero"
/// formula: "=GESTEP(-2)"
/// expected: 0
/// ```
/// ```yaml,docs
/// related:
///   - DELTA
/// faq:
///   - q: "What default threshold does `GESTEP` use?"
///     a: "If omitted, `step` defaults to `0`, so the function returns `1` for non-negative inputs."
/// ```
#[derive(Debug)]
pub struct GestepFn;
/// [formualizer-docgen:schema:start]
/// Name: GESTEP
/// Type: GestepFn
/// Min args: 1
/// Max args: variadic
/// Variadic: true
/// Signature: GESTEP(arg1: number@scalar, arg2...: number@scalar)
/// Arg schema: arg1{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}; arg2{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for GestepFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "GESTEP"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn variadic(&self) -> bool {
        true
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_NUM_LENIENT_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let n = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => coerce_num(&other)?,
        };
        let step = if args.len() > 1 {
            match args[1].value()?.into_literal() {
                LiteralValue::Error(e) => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
                }
                other => coerce_num(&other)?,
            }
        } else {
            0.0
        };

        let result = if n >= step { 1.0 } else { 0.0 };
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
            result,
        )))
    }
}

/* ─────────────────────────── Error Function ──────────────────────────── */

/// Approximation of the error function erf(x)
/// Uses the approximation: erf(x) = 1 - (a1*t + a2*t^2 + a3*t^3 + a4*t^4 + a5*t^5) * exp(-x^2)
/// High-precision error function using Cody's rational approximation
/// Achieves precision of about 1e-15 (double precision)
#[allow(clippy::excessive_precision)]
fn erf_approx(x: f64) -> f64 {
    let ax = x.abs();

    // For small x, use series expansion
    if ax < 0.5 {
        // Coefficients for erf(x) = x * P(x^2) / Q(x^2)
        const P: [f64; 5] = [
            3.20937758913846947e+03,
            3.77485237685302021e+02,
            1.13864154151050156e+02,
            3.16112374387056560e+00,
            1.85777706184603153e-01,
        ];
        const Q: [f64; 5] = [
            2.84423748127893300e+03,
            1.28261652607737228e+03,
            2.44024637934444173e+02,
            2.36012909523441209e+01,
            1.00000000000000000e+00,
        ];

        let x2 = x * x;
        let p_val = P[4];
        let p_val = p_val * x2 + P[3];
        let p_val = p_val * x2 + P[2];
        let p_val = p_val * x2 + P[1];
        let p_val = p_val * x2 + P[0];

        let q_val = Q[4];
        let q_val = q_val * x2 + Q[3];
        let q_val = q_val * x2 + Q[2];
        let q_val = q_val * x2 + Q[1];
        let q_val = q_val * x2 + Q[0];

        return x * p_val / q_val;
    }

    // For x in [0.5, 4], use erfc approximation and compute erf = 1 - erfc
    if ax < 4.0 {
        let erfc_val = erfc_mid(ax);
        return if x > 0.0 {
            1.0 - erfc_val
        } else {
            erfc_val - 1.0
        };
    }

    // For large x, erf(x) ≈ ±1
    let erfc_val = erfc_large(ax);
    if x > 0.0 {
        1.0 - erfc_val
    } else {
        erfc_val - 1.0
    }
}

/// erfc for x in [0.5, 4]
#[allow(clippy::excessive_precision)]
fn erfc_mid(x: f64) -> f64 {
    const P: [f64; 9] = [
        1.23033935479799725e+03,
        2.05107837782607147e+03,
        1.71204761263407058e+03,
        8.81952221241769090e+02,
        2.98635138197400131e+02,
        6.61191906371416295e+01,
        8.88314979438837594e+00,
        5.64188496988670089e-01,
        2.15311535474403846e-08,
    ];
    const Q: [f64; 9] = [
        1.23033935480374942e+03,
        3.43936767414372164e+03,
        4.36261909014324716e+03,
        3.29079923573345963e+03,
        1.62138957456669019e+03,
        5.37181101862009858e+02,
        1.17693950891312499e+02,
        1.57449261107098347e+01,
        1.00000000000000000e+00,
    ];

    let p_val = P[8];
    let p_val = p_val * x + P[7];
    let p_val = p_val * x + P[6];
    let p_val = p_val * x + P[5];
    let p_val = p_val * x + P[4];
    let p_val = p_val * x + P[3];
    let p_val = p_val * x + P[2];
    let p_val = p_val * x + P[1];
    let p_val = p_val * x + P[0];

    let q_val = Q[8];
    let q_val = q_val * x + Q[7];
    let q_val = q_val * x + Q[6];
    let q_val = q_val * x + Q[5];
    let q_val = q_val * x + Q[4];
    let q_val = q_val * x + Q[3];
    let q_val = q_val * x + Q[2];
    let q_val = q_val * x + Q[1];
    let q_val = q_val * x + Q[0];

    (-x * x).exp() * p_val / q_val
}

/// erfc for x >= 4
#[allow(clippy::excessive_precision)]
fn erfc_large(x: f64) -> f64 {
    const P: [f64; 6] = [
        6.58749161529837803e-04,
        1.60837851487422766e-02,
        1.25781726111229246e-01,
        3.60344899949804439e-01,
        3.05326634961232344e-01,
        1.63153871373020978e-02,
    ];
    const Q: [f64; 6] = [
        2.33520497626869185e-03,
        6.05183413124413191e-02,
        5.27905102951428412e-01,
        1.87295284992346047e+00,
        2.56852019228982242e+00,
        1.00000000000000000e+00,
    ];

    let x2 = x * x;
    let inv_x2 = 1.0 / x2;

    let p_val = P[5];
    let p_val = p_val * inv_x2 + P[4];
    let p_val = p_val * inv_x2 + P[3];
    let p_val = p_val * inv_x2 + P[2];
    let p_val = p_val * inv_x2 + P[1];
    let p_val = p_val * inv_x2 + P[0];

    let q_val = Q[5];
    let q_val = q_val * inv_x2 + Q[4];
    let q_val = q_val * inv_x2 + Q[3];
    let q_val = q_val * inv_x2 + Q[2];
    let q_val = q_val * inv_x2 + Q[1];
    let q_val = q_val * inv_x2 + Q[0];

    // 1/sqrt(pi) = 0.5641895835477563
    const FRAC_1_SQRT_PI: f64 = 0.5641895835477563;
    (-x2).exp() / x * (FRAC_1_SQRT_PI + inv_x2 * p_val / q_val)
}

/// Direct erfc computation for ERFC function
fn erfc_direct(x: f64) -> f64 {
    if x < 0.0 {
        return 2.0 - erfc_direct(-x);
    }
    if x < 0.5 {
        return 1.0 - erf_approx(x);
    }
    if x < 4.0 {
        return erfc_mid(x);
    }
    erfc_large(x)
}

/// Returns the Gaussian error function over one bound or between two bounds.
///
/// With one argument it returns `erf(x)`; with two it returns `erf(upper) - erf(lower)`.
///
/// # Remarks
/// - Inputs are numerically coerced.
/// - A second argument switches the function to interval mode.
/// - Results are approximate floating-point values.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Single-bound ERF"
/// formula: "=ERF(1)"
/// expected: 0.8427007929497149
/// ```
///
/// ```yaml,sandbox
/// title: "Interval ERF"
/// formula: "=ERF(0,1)"
/// expected: 0.8427007929497149
/// ```
/// ```yaml,docs
/// related:
///   - ERFC
///   - ERF.PRECISE
/// faq:
///   - q: "How does two-argument `ERF` work?"
///     a: "`ERF(lower, upper)` returns `erf(upper) - erf(lower)`, i.e., an interval difference rather than a single-bound value."
/// ```
#[derive(Debug)]
pub struct ErfFn;
/// [formualizer-docgen:schema:start]
/// Name: ERF
/// Type: ErfFn
/// Min args: 1
/// Max args: variadic
/// Variadic: true
/// Signature: ERF(arg1: number@scalar, arg2...: number@scalar)
/// Arg schema: arg1{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}; arg2{kinds=number,required=true,shape=scalar,by_ref=false,coercion=NumberLenientText,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ErfFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "ERF"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn variadic(&self) -> bool {
        true
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_NUM_LENIENT_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let lower = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => coerce_num(&other)?,
        };

        let result = if args.len() > 1 {
            // ERF(lower, upper) = erf(upper) - erf(lower)
            let upper = match args[1].value()?.into_literal() {
                LiteralValue::Error(e) => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
                }
                other => coerce_num(&other)?,
            };
            erf_approx(upper) - erf_approx(lower)
        } else {
            // ERF(x) = erf(x)
            erf_approx(lower)
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
            result,
        )))
    }
}

/// Returns the complementary error function of a number.
///
/// `ERFC(x)` is equivalent to `1 - ERF(x)`.
///
/// # Remarks
/// - Input is numerically coerced.
/// - Results are approximate floating-point values.
/// - Propagates input errors.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Complement at one"
/// formula: "=ERFC(1)"
/// expected: 0.1572992070502851
/// ```
///
/// ```yaml,sandbox
/// title: "Complement at zero"
/// formula: "=ERFC(0)"
/// expected: 1
/// ```
/// ```yaml,docs
/// related:
///   - ERF
///   - ERF.PRECISE
/// faq:
///   - q: "Is `ERFC(x)` equivalent to `1-ERF(x)` here?"
///     a: "Yes. It computes the complementary error function and matches `1 - erf(x)` behavior."
/// ```
#[derive(Debug)]
pub struct ErfcFn;
/// [formualizer-docgen:schema:start]
/// Name: ERFC
/// Type: ErfcFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: ERFC(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ErfcFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "ERFC"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let x = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => coerce_num(&other)?,
        };

        let result = erfc_direct(x);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
            result,
        )))
    }
}

/// Returns the complementary error function of a number.
///
/// Computes `1 - ERF(x)` using the same one-argument precise behavior as Excel
/// `ERFC.PRECISE`.
///
/// # Remarks
/// - Accepts one numeric argument.
/// - Numeric text is coerced using standard function coercion.
/// - Results are approximate floating-point values.
///
/// ```yaml,sandbox
/// title: "Complement at one"
/// formula: "=ERFC.PRECISE(1)"
/// expected: 0.1572992070502851
/// ```
///
/// ```yaml,sandbox
/// title: "Complement at zero"
/// formula: "=ERFC.PRECISE(0)"
/// expected: 1
/// ```
///
/// ```yaml,docs
/// related:
///   - ERFC
///   - ERF.PRECISE
///   - ERF
/// faq:
///   - q: "How is ERFC.PRECISE different from ERFC?"
///     a: "It exposes the precise one-argument complement form; numerically it matches ERFC(x) in this implementation."
/// ```
#[derive(Debug)]
pub struct ErfcPreciseFn;
/// [formualizer-docgen:schema:start]
/// Name: ERFC.PRECISE
/// Type: ErfcPreciseFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: ERFC.PRECISE(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ErfcPreciseFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "ERFC.PRECISE"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        if args.len() != 1 {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_value(),
            )));
        }
        let x = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => coerce_num(&other)?,
        };
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
            erfc_direct(x),
        )))
    }
}

fn eval_bessel<'b, F>(
    args: &[ArgumentHandle<'_, 'b>],
    f: F,
) -> Result<crate::traits::CalcValue<'b>, ExcelError>
where
    F: FnOnce(i32, f64) -> f64,
{
    if args.len() != 2 {
        return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
            ExcelError::new_value(),
        )));
    }
    let x = match args[0].value()?.into_literal() {
        LiteralValue::Error(e) => {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
        }
        other => coerce_num(&other)?,
    };
    let n = match args[1].value()?.into_literal() {
        LiteralValue::Error(e) => {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
        }
        other => coerce_num(&other)?,
    };

    if !x.is_finite() || !n.is_finite() {
        return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
            ExcelError::new_num(),
        )));
    }

    let n_trunc = n.trunc();
    if n_trunc < 0.0 || n_trunc > i32::MAX as f64 {
        return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
            ExcelError::new_num(),
        )));
    }

    let result = f(n_trunc as i32, x);
    if !result.is_finite() {
        return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
            ExcelError::new_num(),
        )));
    }

    Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
        result,
    )))
}

/// Returns the modified Bessel function In(x).
///
/// Computes the modified Bessel function of the first kind for a real value `x`
/// and a non-negative integer order `n`. The order is truncated toward zero,
/// matching spreadsheet behavior.
///
/// # Remarks
/// - Arguments are supplied as `BESSELI(x, n)`.
/// - `n` must truncate to a non-negative integer order.
/// - Invalid domains or non-finite results return `#NUM!`.
///
/// ```yaml,sandbox
/// title: "First-order modified Bessel I"
/// formula: "=BESSELI(0.5,1)"
/// expected: 0.2578943053908963
/// ```
///
/// ```yaml,sandbox
/// title: "Order is truncated"
/// formula: "=BESSELI(0.5,1.9)"
/// expected: 0.2578943053908963
/// ```
///
/// ```yaml,docs
/// related:
///   - BESSELJ
///   - BESSELK
///   - BESSELY
/// faq:
///   - q: "What happens to fractional order values?"
///     a: "The order argument is truncated toward zero before evaluation."
/// ```
#[derive(Debug)]
pub struct BesselIFn;
/// [formualizer-docgen:schema:start]
/// Name: BESSELI
/// Type: BesselIFn
/// Min args: 2
/// Max args: 2
/// Variadic: false
/// Signature: BESSELI(arg1: any@scalar, arg2: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}; arg2{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for BesselIFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "BESSELI"
    }
    fn min_args(&self) -> usize {
        2
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        eval_bessel(args, transcendental::bessel_i)
    }
}

/// Returns the Bessel function Jn(x).
///
/// Computes the Bessel function of the first kind for a real value `x` and a
/// non-negative integer order `n`. The order is truncated toward zero.
///
/// # Remarks
/// - Arguments are supplied as `BESSELJ(x, n)`.
/// - Negative orders return `#NUM!` in the public spreadsheet function.
/// - Results are approximate floating-point values.
///
/// ```yaml,sandbox
/// title: "Third-order Bessel J"
/// formula: "=BESSELJ(0.5,3)"
/// expected: 0.002563729994587244
/// ```
///
/// ```yaml,sandbox
/// title: "Zero input for positive order"
/// formula: "=BESSELJ(0,7)"
/// expected: 0
/// ```
///
/// ```yaml,docs
/// related:
///   - BESSELI
///   - BESSELK
///   - BESSELY
/// faq:
///   - q: "Are negative public orders supported?"
///     a: "No. Negative order arguments return #NUM! for Excel compatibility."
/// ```
#[derive(Debug)]
pub struct BesselJFn;
/// [formualizer-docgen:schema:start]
/// Name: BESSELJ
/// Type: BesselJFn
/// Min args: 2
/// Max args: 2
/// Variadic: false
/// Signature: BESSELJ(arg1: any@scalar, arg2: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}; arg2{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for BesselJFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "BESSELJ"
    }
    fn min_args(&self) -> usize {
        2
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        eval_bessel(args, transcendental::bessel_j)
    }
}

/// Returns the modified Bessel function Kn(x).
///
/// Computes the modified Bessel function of the second kind for a positive real
/// value `x` and a non-negative integer order `n`.
///
/// # Remarks
/// - Arguments are supplied as `BESSELK(x, n)`.
/// - `x` must be positive and `n` must truncate to a non-negative integer.
/// - Invalid domains or non-finite results return `#NUM!`.
///
/// ```yaml,sandbox
/// title: "First-order modified Bessel K"
/// formula: "=BESSELK(0.5,1)"
/// expected: 1.656441120003301
/// ```
///
/// ```yaml,sandbox
/// title: "Zero-order modified Bessel K"
/// formula: "=BESSELK(0.5,0)"
/// expected: 0.9244190712276659
/// ```
///
/// ```yaml,docs
/// related:
///   - BESSELI
///   - BESSELJ
///   - BESSELY
/// faq:
///   - q: "Why can BESSELK return #NUM!?"
///     a: "BESSELK is undefined for non-positive x values and negative orders."
/// ```
#[derive(Debug)]
pub struct BesselKFn;
/// [formualizer-docgen:schema:start]
/// Name: BESSELK
/// Type: BesselKFn
/// Min args: 2
/// Max args: 2
/// Variadic: false
/// Signature: BESSELK(arg1: any@scalar, arg2: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}; arg2{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for BesselKFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "BESSELK"
    }
    fn min_args(&self) -> usize {
        2
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        eval_bessel(args, transcendental::bessel_k)
    }
}

/// Returns the Bessel function Yn(x).
///
/// Computes the Bessel function of the second kind for a positive real value `x`
/// and a non-negative integer order `n`.
///
/// # Remarks
/// - Arguments are supplied as `BESSELY(x, n)`.
/// - Negative orders and invalid domains return `#NUM!`.
/// - Results are approximate floating-point values.
///
/// ```yaml,sandbox
/// title: "Third-order Bessel Y"
/// formula: "=BESSELY(0.5,3)"
/// expected: -42.059494304723883
/// ```
///
/// ```yaml,sandbox
/// title: "Large-input Bessel Y"
/// formula: "=BESSELY(35,3)"
/// expected: -0.13191405300596323
/// ```
///
/// ```yaml,docs
/// related:
///   - BESSELI
///   - BESSELJ
///   - BESSELK
/// faq:
///   - q: "Is BESSELY defined at zero?"
///     a: "No. Singular or otherwise invalid inputs return #NUM!."
/// ```
#[derive(Debug)]
pub struct BesselYFn;
/// [formualizer-docgen:schema:start]
/// Name: BESSELY
/// Type: BesselYFn
/// Min args: 2
/// Max args: 2
/// Variadic: false
/// Signature: BESSELY(arg1: any@scalar, arg2: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}; arg2{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for BesselYFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "BESSELY"
    }
    fn min_args(&self) -> usize {
        2
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        eval_bessel(args, transcendental::bessel_y)
    }
}

/// Returns the error function of a number.
///
/// This is the one-argument precise variant of `ERF`.
///
/// # Remarks
/// - Input is numerically coerced.
/// - Equivalent to `ERF(x)` in single-argument mode.
/// - Results are approximate floating-point values.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Positive input"
/// formula: "=ERF.PRECISE(1)"
/// expected: 0.8427007929497149
/// ```
///
/// ```yaml,sandbox
/// title: "Negative input"
/// formula: "=ERF.PRECISE(-1)"
/// expected: -0.8427007929497149
/// ```
/// ```yaml,docs
/// related:
///   - ERF
///   - ERFC
/// faq:
///   - q: "How is `ERF.PRECISE` different from `ERF`?"
///     a: "`ERF.PRECISE` is the one-argument form only; numerically it matches `ERF(x)` for single input mode."
/// ```
#[derive(Debug)]
pub struct ErfPreciseFn;
/// [formualizer-docgen:schema:start]
/// Name: ERF.PRECISE
/// Type: ErfPreciseFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: ERF.PRECISE(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ErfPreciseFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "ERF.PRECISE"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let x = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => coerce_num(&other)?,
        };

        let result = erf_approx(x);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
            result,
        )))
    }
}

/* ─────────────────────────── Complex Number Functions ──────────────────────────── */

/// Parse a complex number string like "3+4i", "3-4i", "5i", "3", "-2j", etc.
/// Returns (real, imaginary, suffix) where suffix is 'i' or 'j'
fn parse_complex(s: &str) -> Result<(f64, f64, char), ExcelError> {
    let s = s.trim();
    if s.is_empty() {
        return Err(ExcelError::new_num());
    }

    // Determine the suffix (i or j)
    let suffix = if s.ends_with('i') || s.ends_with('I') {
        'i'
    } else if s.ends_with('j') || s.ends_with('J') {
        'j'
    } else {
        // No imaginary suffix - must be purely real
        let real: f64 = s.parse().map_err(|_| ExcelError::new_num())?;
        return Ok((real, 0.0, 'i'));
    };

    // Remove the suffix for parsing
    let s = &s[..s.len() - 1];

    // Handle pure imaginary cases like "i", "-i", "4i"
    if s.is_empty() || s == "+" {
        return Ok((0.0, 1.0, suffix));
    }
    if s == "-" {
        return Ok((0.0, -1.0, suffix));
    }

    // Find the last + or - that separates real and imaginary parts
    // We need to skip the first character (could be a sign) and find operators
    let mut split_pos = None;
    let bytes = s.as_bytes();

    for i in (1..bytes.len()).rev() {
        let c = bytes[i] as char;
        if c == '+' || c == '-' {
            // Make sure this isn't part of an exponent (e.g., "1e-5")
            if i > 0 {
                let prev = bytes[i - 1] as char;
                if prev == 'e' || prev == 'E' {
                    continue;
                }
            }
            split_pos = Some(i);
            break;
        }
    }

    match split_pos {
        Some(pos) => {
            // We have both real and imaginary parts
            let real_str = &s[..pos];
            let imag_str = &s[pos..];

            let real: f64 = if real_str.is_empty() {
                0.0
            } else {
                real_str.parse().map_err(|_| ExcelError::new_num())?
            };

            // Handle imaginary part (could be "+", "-", "+5", "-5", etc.)
            let imag: f64 = if imag_str == "+" {
                1.0
            } else if imag_str == "-" {
                -1.0
            } else {
                imag_str.parse().map_err(|_| ExcelError::new_num())?
            };

            Ok((real, imag, suffix))
        }
        None => {
            // Pure imaginary number (no real part), e.g., "5" (before suffix was removed)
            let imag: f64 = s.parse().map_err(|_| ExcelError::new_num())?;
            Ok((0.0, imag, suffix))
        }
    }
}

/// Clean up floating point noise by rounding values very close to integers
fn clean_float(val: f64) -> f64 {
    let rounded = val.round();
    if (val - rounded).abs() < 1e-10 {
        rounded
    } else {
        val
    }
}

/// Format a complex number as a string
fn format_complex(real: f64, imag: f64, suffix: char) -> String {
    // Clean up floating point noise
    let real = clean_float(real);
    let imag = clean_float(imag);

    // Handle special cases for cleaner output
    let real_is_zero = real.abs() < 1e-15;
    let imag_is_zero = imag.abs() < 1e-15;

    if real_is_zero && imag_is_zero {
        return "0".to_string();
    }

    if imag_is_zero {
        // Purely real
        if real == real.trunc() && real.abs() < 1e15 {
            return format!("{}", real as i64);
        }
        return format!("{}", real);
    }

    if real_is_zero {
        // Purely imaginary
        if (imag - 1.0).abs() < 1e-15 {
            return format!("{}", suffix);
        }
        if (imag + 1.0).abs() < 1e-15 {
            return format!("-{}", suffix);
        }
        if imag == imag.trunc() && imag.abs() < 1e15 {
            return format!("{}{}", imag as i64, suffix);
        }
        return format!("{}{}", imag, suffix);
    }

    // Both parts are non-zero
    let real_str = if real == real.trunc() && real.abs() < 1e15 {
        format!("{}", real as i64)
    } else {
        format!("{}", real)
    };

    let imag_str = if (imag - 1.0).abs() < 1e-15 {
        format!("+{}", suffix)
    } else if (imag + 1.0).abs() < 1e-15 {
        format!("-{}", suffix)
    } else if imag > 0.0 {
        if imag == imag.trunc() && imag.abs() < 1e15 {
            format!("+{}{}", imag as i64, suffix)
        } else {
            format!("+{}{}", imag, suffix)
        }
    } else if imag == imag.trunc() && imag.abs() < 1e15 {
        format!("{}{}", imag as i64, suffix)
    } else {
        format!("{}{}", imag, suffix)
    };

    format!("{}{}", real_str, imag_str)
}

/// Coerce a LiteralValue to a complex number string
fn coerce_complex_str(v: &LiteralValue) -> Result<String, ExcelError> {
    match v {
        LiteralValue::Text(s) => Ok(s.clone()),
        LiteralValue::Int(i) => Ok(i.to_string()),
        LiteralValue::Number(n) => Ok(n.to_string()),
        LiteralValue::Error(e) => Err(e.clone()),
        _ => Err(ExcelError::new_value()),
    }
}

/// Three-argument schema for COMPLEX function
static ARG_COMPLEX_THREE: std::sync::LazyLock<Vec<ArgSchema>> =
    std::sync::LazyLock::new(|| vec![ArgSchema::any(), ArgSchema::any(), ArgSchema::any()]);

/// Builds a complex number text value from real and imaginary coefficients.
///
/// Returns canonical text such as `3+4i` or `-2j`.
///
/// # Remarks
/// - `real_num` and `i_num` are numerically coerced.
/// - `suffix` may be `"i"`, `"j"`, empty text, or omitted; empty/omitted defaults to `i`.
/// - Any other suffix returns `#VALUE!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Build with default suffix"
/// formula: "=COMPLEX(3,4)"
/// expected: "3+4i"
/// ```
///
/// ```yaml,sandbox
/// title: "Build with j suffix"
/// formula: "=COMPLEX(0,-1,\"j\")"
/// expected: "-j"
/// ```
/// ```yaml,docs
/// related:
///   - IMREAL
///   - IMAGINARY
///   - IMSUM
/// faq:
///   - q: "Which suffix values are valid in `COMPLEX`?"
///     a: "Only suffixes i or j are accepted (empty or omitted defaults to i); other suffix strings return `#VALUE!`."
/// ```
#[derive(Debug)]
pub struct ComplexFn;
/// [formualizer-docgen:schema:start]
/// Name: COMPLEX
/// Type: ComplexFn
/// Min args: 2
/// Max args: variadic
/// Variadic: true
/// Signature: COMPLEX(arg1: any@scalar, arg2: any@scalar, arg3...: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}; arg2{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}; arg3{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ComplexFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "COMPLEX"
    }
    fn min_args(&self) -> usize {
        2
    }
    fn variadic(&self) -> bool {
        true
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_COMPLEX_THREE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let real = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => coerce_num(&other)?,
        };

        let imag = match args[1].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => coerce_num(&other)?,
        };

        let suffix = if args.len() > 2 {
            match args[2].value()?.into_literal() {
                LiteralValue::Error(e) => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
                }
                LiteralValue::Text(s) => {
                    let s = s.to_lowercase();
                    if s == "i" {
                        'i'
                    } else if s == "j" {
                        'j'
                    } else if s.is_empty() {
                        'i' // Default to 'i' for empty string
                    } else {
                        return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                            ExcelError::new_value(),
                        )));
                    }
                }
                LiteralValue::Empty => 'i',
                _ => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                        ExcelError::new_value(),
                    )));
                }
            }
        } else {
            'i'
        };

        let result = format_complex(real, imag, suffix);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Returns the real coefficient of a complex number.
///
/// Accepts complex text (for example `a+bi`) or numeric values.
///
/// # Remarks
/// - Inputs are coerced to complex-number text before parsing.
/// - Purely imaginary values return `0`.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Real part from a+bi"
/// formula: "=IMREAL(\"3+4i\")"
/// expected: 3
/// ```
///
/// ```yaml,sandbox
/// title: "Real part of pure imaginary"
/// formula: "=IMREAL(\"5j\")"
/// expected: 0
/// ```
/// ```yaml,docs
/// related:
///   - IMAGINARY
///   - COMPLEX
///   - IMABS
/// faq:
///   - q: "What does `IMREAL` return for a purely imaginary input?"
///     a: "It returns `0` because the real coefficient is zero."
/// ```
#[derive(Debug)]
pub struct ImRealFn;
/// [formualizer-docgen:schema:start]
/// Name: IMREAL
/// Type: ImRealFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMREAL(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImRealFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMREAL"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let inumber = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let (real, _, _) = match parse_complex(&inumber) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(real)))
    }
}

/// Returns the imaginary coefficient of a complex number.
///
/// Accepts complex text (for example `a+bi`) or numeric values.
///
/// # Remarks
/// - Inputs are coerced to complex-number text before parsing.
/// - Purely real values return `0`.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Imaginary part from a+bi"
/// formula: "=IMAGINARY(\"3+4i\")"
/// expected: 4
/// ```
///
/// ```yaml,sandbox
/// title: "Imaginary part with j suffix"
/// formula: "=IMAGINARY(\"-2j\")"
/// expected: -2
/// ```
/// ```yaml,docs
/// related:
///   - IMREAL
///   - COMPLEX
///   - IMABS
/// faq:
///   - q: "What does `IMAGINARY` return for a real-only input?"
///     a: "It returns `0` because there is no imaginary component."
/// ```
#[derive(Debug)]
pub struct ImaginaryFn;
/// [formualizer-docgen:schema:start]
/// Name: IMAGINARY
/// Type: ImaginaryFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMAGINARY(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImaginaryFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMAGINARY"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let inumber = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let (_, imag, _) = match parse_complex(&inumber) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(imag)))
    }
}

/// Returns the modulus (absolute value) of a complex number.
///
/// Computes `sqrt(real^2 + imaginary^2)`.
///
/// # Remarks
/// - Inputs are coerced to complex-number text before parsing.
/// - Returns a non-negative real number.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "3-4-5 triangle modulus"
/// formula: "=IMABS(\"3+4i\")"
/// expected: 5
/// ```
///
/// ```yaml,sandbox
/// title: "Purely real input"
/// formula: "=IMABS(\"5\")"
/// expected: 5
/// ```
/// ```yaml,docs
/// related:
///   - IMREAL
///   - IMAGINARY
///   - IMARGUMENT
/// faq:
///   - q: "Can `IMABS` return a negative result?"
///     a: "No. It computes the modulus `sqrt(a^2+b^2)`, which is always non-negative."
/// ```
#[derive(Debug)]
pub struct ImAbsFn;
/// [formualizer-docgen:schema:start]
/// Name: IMABS
/// Type: ImAbsFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMABS(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImAbsFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMABS"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let inumber = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let (real, imag, _) = match parse_complex(&inumber) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        let abs = (real * real + imag * imag).sqrt();
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(abs)))
    }
}

/// Returns the argument (angle in radians) of a complex number.
///
/// The angle is measured from the positive real axis.
///
/// # Remarks
/// - Inputs are coerced to complex-number text before parsing.
/// - Returns `#DIV/0!` for `0+0i`, where the angle is undefined.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "First-quadrant angle"
/// formula: "=IMARGUMENT(\"1+i\")"
/// expected: 0.7853981633974483
/// ```
///
/// ```yaml,sandbox
/// title: "Negative real axis"
/// formula: "=IMARGUMENT(\"-1\")"
/// expected: 3.141592653589793
/// ```
/// ```yaml,docs
/// related:
///   - IMABS
///   - IMLN
///   - IMSQRT
/// faq:
///   - q: "Why does `IMARGUMENT(0)` return `#DIV/0!`?"
///     a: "The argument (angle) of `0+0i` is undefined, so the function returns `#DIV/0!`."
/// ```
#[derive(Debug)]
pub struct ImArgumentFn;
/// [formualizer-docgen:schema:start]
/// Name: IMARGUMENT
/// Type: ImArgumentFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMARGUMENT(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImArgumentFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMARGUMENT"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let inumber = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let (real, imag, _) = match parse_complex(&inumber) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        // Excel returns #DIV/0! for IMARGUMENT(0)
        if real.abs() < 1e-15 && imag.abs() < 1e-15 {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_div(),
            )));
        }

        let arg = imag.atan2(real);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(arg)))
    }
}

/// Returns the complex conjugate of a complex number.
///
/// Negates the imaginary coefficient and keeps the real coefficient unchanged.
///
/// # Remarks
/// - Inputs are coerced to complex-number text before parsing.
/// - Preserves the original suffix style (`i` or `j`) when possible.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Conjugate with i suffix"
/// formula: "=IMCONJUGATE(\"3+4i\")"
/// expected: "3-4i"
/// ```
///
/// ```yaml,sandbox
/// title: "Conjugate with j suffix"
/// formula: "=IMCONJUGATE(\"-2j\")"
/// expected: "2j"
/// ```
/// ```yaml,docs
/// related:
///   - IMSUB
///   - IMPRODUCT
///   - IMDIV
/// faq:
///   - q: "Does `IMCONJUGATE` keep the `i`/`j` suffix style?"
///     a: "Yes. It negates only the imaginary coefficient and preserves the parsed suffix form."
/// ```
#[derive(Debug)]
pub struct ImConjugateFn;
/// [formualizer-docgen:schema:start]
/// Name: IMCONJUGATE
/// Type: ImConjugateFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMCONJUGATE(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImConjugateFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMCONJUGATE"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let inumber = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let (real, imag, suffix) = match parse_complex(&inumber) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        let result = format_complex(real, -imag, suffix);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Helper to check if two complex numbers have compatible suffixes
fn check_suffix_compatibility(s1: char, s2: char) -> Result<char, ExcelError> {
    // If both have the same suffix, use it
    // If one is from a purely real number (default 'i'), use the other's suffix
    // Excel doesn't allow mixing 'i' and 'j' when both are explicit
    if s1 == s2 {
        Ok(s1)
    } else {
        // For simplicity, treat 'i' as the default and allow mixed
        // In strict Excel mode, this would error
        Ok(s1)
    }
}

/// Returns the sum of one or more complex numbers.
///
/// Adds real parts together and imaginary parts together.
///
/// # Remarks
/// - Each argument is coerced to complex-number text before parsing.
/// - Accepts any number of arguments from one upward.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Add multiple complex values"
/// formula: "=IMSUM(\"3+4i\",\"1-2i\",\"5\")"
/// expected: "9+2i"
/// ```
///
/// ```yaml,sandbox
/// title: "Add j-suffix values"
/// formula: "=IMSUM(\"2j\",\"-j\")"
/// expected: "j"
/// ```
/// ```yaml,docs
/// related:
///   - IMSUB
///   - IMPRODUCT
///   - COMPLEX
/// faq:
///   - q: "Can `IMSUM` take more than two arguments?"
///     a: "Yes. It is variadic and sums all provided complex arguments in sequence."
/// ```
#[derive(Debug)]
pub struct ImSumFn;
/// [formualizer-docgen:schema:start]
/// Name: IMSUM
/// Type: ImSumFn
/// Min args: 1
/// Max args: variadic
/// Variadic: true
/// Signature: IMSUM(arg1...: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImSumFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMSUM"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn variadic(&self) -> bool {
        true
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let mut sum_real = 0.0;
        let mut sum_imag = 0.0;
        let mut result_suffix = 'i';
        let mut first = true;

        for arg in args {
            let inumber = match arg.value()?.into_literal() {
                LiteralValue::Error(e) => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
                }
                other => match coerce_complex_str(&other) {
                    Ok(s) => s,
                    Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
                },
            };

            let (real, imag, suffix) = match parse_complex(&inumber) {
                Ok(c) => c,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            };

            if first {
                result_suffix = suffix;
                first = false;
            } else {
                result_suffix = check_suffix_compatibility(result_suffix, suffix)?;
            }

            sum_real += real;
            sum_imag += imag;
        }

        let result = format_complex(sum_real, sum_imag, result_suffix);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Returns the difference between two complex numbers.
///
/// Subtracts the second complex value from the first.
///
/// # Remarks
/// - Inputs are coerced to complex-number text before parsing.
/// - Output keeps the suffix style from the parsed inputs.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Subtract a+bi values"
/// formula: "=IMSUB(\"5+3i\",\"2+i\")"
/// expected: "3+2i"
/// ```
///
/// ```yaml,sandbox
/// title: "Subtract pure imaginary from real"
/// formula: "=IMSUB(\"4\",\"7j\")"
/// expected: "4-7j"
/// ```
/// ```yaml,docs
/// related:
///   - IMSUM
///   - IMDIV
///   - COMPLEX
/// faq:
///   - q: "How is subtraction ordered in `IMSUB`?"
///     a: "It always computes `inumber1 - inumber2`; swapping arguments changes the sign of the result."
/// ```
#[derive(Debug)]
pub struct ImSubFn;
/// [formualizer-docgen:schema:start]
/// Name: IMSUB
/// Type: ImSubFn
/// Min args: 2
/// Max args: 2
/// Variadic: false
/// Signature: IMSUB(arg1: any@scalar, arg2: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}; arg2{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImSubFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMSUB"
    }
    fn min_args(&self) -> usize {
        2
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let inumber1 = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let inumber2 = match args[1].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let (real1, imag1, suffix1) = match parse_complex(&inumber1) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        let (real2, imag2, suffix2) = match parse_complex(&inumber2) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        let result_suffix = check_suffix_compatibility(suffix1, suffix2)?;
        let result = format_complex(real1 - real2, imag1 - imag2, result_suffix);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Returns the product of one or more complex numbers.
///
/// Multiplies values sequentially using complex multiplication rules.
///
/// # Remarks
/// - Each argument is coerced to complex-number text before parsing.
/// - Accepts any number of arguments from one upward.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Multiply conjugates"
/// formula: "=IMPRODUCT(\"1+i\",\"1-i\")"
/// expected: "2"
/// ```
///
/// ```yaml,sandbox
/// title: "Scale an imaginary value"
/// formula: "=IMPRODUCT(\"2i\",\"3\")"
/// expected: "6i"
/// ```
/// ```yaml,docs
/// related:
///   - IMDIV
///   - IMSUM
///   - IMPOWER
/// faq:
///   - q: "Can `IMPRODUCT` multiply a single argument?"
///     a: "Yes. With one argument it returns that parsed complex value in canonical formatted form."
/// ```
#[derive(Debug)]
pub struct ImProductFn;
/// [formualizer-docgen:schema:start]
/// Name: IMPRODUCT
/// Type: ImProductFn
/// Min args: 1
/// Max args: variadic
/// Variadic: true
/// Signature: IMPRODUCT(arg1...: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImProductFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMPRODUCT"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn variadic(&self) -> bool {
        true
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let mut prod_real = 1.0;
        let mut prod_imag = 0.0;
        let mut result_suffix = 'i';
        let mut first = true;

        for arg in args {
            let inumber = match arg.value()?.into_literal() {
                LiteralValue::Error(e) => {
                    return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
                }
                other => match coerce_complex_str(&other) {
                    Ok(s) => s,
                    Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
                },
            };

            let (real, imag, suffix) = match parse_complex(&inumber) {
                Ok(c) => c,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            };

            if first {
                result_suffix = suffix;
                prod_real = real;
                prod_imag = imag;
                first = false;
            } else {
                result_suffix = check_suffix_compatibility(result_suffix, suffix)?;
                // (a + bi) * (c + di) = (ac - bd) + (ad + bc)i
                let new_real = prod_real * real - prod_imag * imag;
                let new_imag = prod_real * imag + prod_imag * real;
                prod_real = new_real;
                prod_imag = new_imag;
            }
        }

        let result = format_complex(prod_real, prod_imag, result_suffix);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Returns the quotient of two complex numbers.
///
/// Divides the first complex value by the second.
///
/// # Remarks
/// - Inputs are coerced to complex-number text before parsing.
/// - Returns `#DIV/0!` when the divisor is `0+0i`.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Divide complex numbers"
/// formula: "=IMDIV(\"3+4i\",\"1-i\")"
/// expected: "-0.5+3.5i"
/// ```
///
/// ```yaml,sandbox
/// title: "Division by zero complex"
/// formula: "=IMDIV(\"2+i\",\"0\")"
/// expected: "#DIV/0!"
/// ```
/// ```yaml,docs
/// related:
///   - IMPRODUCT
///   - IMSUB
///   - IMCONJUGATE
/// faq:
///   - q: "When does `IMDIV` return `#DIV/0!`?"
///     a: "If the divisor is `0+0i` (denominator magnitude near zero), division is undefined and returns `#DIV/0!`."
/// ```
#[derive(Debug)]
pub struct ImDivFn;
/// [formualizer-docgen:schema:start]
/// Name: IMDIV
/// Type: ImDivFn
/// Min args: 2
/// Max args: 2
/// Variadic: false
/// Signature: IMDIV(arg1: any@scalar, arg2: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}; arg2{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImDivFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMDIV"
    }
    fn min_args(&self) -> usize {
        2
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let inumber1 = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let inumber2 = match args[1].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let (a, b, suffix1) = match parse_complex(&inumber1) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        let (c, d, suffix2) = match parse_complex(&inumber2) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        // Division by zero check - returns #DIV/0! for Excel compatibility
        let denom = c * c + d * d;
        if denom.abs() < 1e-15 {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_div(),
            )));
        }

        let result_suffix = check_suffix_compatibility(suffix1, suffix2)?;

        // (a + bi) / (c + di) = ((ac + bd) + (bc - ad)i) / (c^2 + d^2)
        let real = (a * c + b * d) / denom;
        let imag = (b * c - a * d) / denom;

        let result = format_complex(real, imag, result_suffix);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Returns the complex exponential of a complex number.
///
/// Computes `e^(a+bi)` and returns the result as complex text.
///
/// # Remarks
/// - Input is coerced to complex-number text before parsing.
/// - Uses Euler's identity for the imaginary component.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Exponential of zero"
/// formula: "=IMEXP(\"0\")"
/// expected: "1"
/// ```
///
/// ```yaml,sandbox
/// title: "Exponential of a real value"
/// formula: "=IMEXP(\"1\")"
/// expected: "2.718281828459045"
/// ```
/// ```yaml,docs
/// related:
///   - IMLN
///   - IMPOWER
///   - IMSIN
///   - IMCOS
/// faq:
///   - q: "Does `IMEXP` return text or a numeric complex type?"
///     a: "It returns a canonical complex text string, consistent with other `IM*` functions."
/// ```
#[derive(Debug)]
pub struct ImExpFn;
/// [formualizer-docgen:schema:start]
/// Name: IMEXP
/// Type: ImExpFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMEXP(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImExpFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMEXP"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let inumber = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let (a, b, suffix) = match parse_complex(&inumber) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        // e^(a+bi) = e^a * (cos(b) + i*sin(b))
        let exp_a = a.exp();
        let real = exp_a * b.cos();
        let imag = exp_a * b.sin();

        let result = format_complex(real, imag, suffix);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Returns the natural logarithm of a complex number.
///
/// Produces the principal complex logarithm as text.
///
/// # Remarks
/// - Input is coerced to complex-number text before parsing.
/// - Returns `#NUM!` for zero input because `ln(0)` is undefined.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Natural log of 1"
/// formula: "=IMLN(\"1\")"
/// expected: "0"
/// ```
///
/// ```yaml,sandbox
/// title: "Natural log on imaginary axis"
/// formula: "=IMLN(\"i\")"
/// expected: "1.5707963267948966i"
/// ```
/// ```yaml,docs
/// related:
///   - IMEXP
///   - IMLOG10
///   - IMLOG2
/// faq:
///   - q: "Why does `IMLN(0)` return `#NUM!`?"
///     a: "The complex logarithm at zero is undefined, so this implementation returns `#NUM!`."
/// ```
#[derive(Debug)]
pub struct ImLnFn;
/// [formualizer-docgen:schema:start]
/// Name: IMLN
/// Type: ImLnFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMLN(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImLnFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMLN"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let inumber = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let (a, b, suffix) = match parse_complex(&inumber) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        // ln(0) is undefined
        let modulus = (a * a + b * b).sqrt();
        if modulus < 1e-15 {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        // ln(z) = ln(|z|) + i*arg(z)
        let real = modulus.ln();
        let imag = b.atan2(a);

        let result = format_complex(real, imag, suffix);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Returns the base-10 logarithm of a complex number.
///
/// Produces the principal complex logarithm in base 10.
///
/// # Remarks
/// - Input is coerced to complex-number text before parsing.
/// - Returns `#NUM!` for zero input.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Base-10 log of a real value"
/// formula: "=IMLOG10(\"10\")"
/// expected: "1"
/// ```
///
/// ```yaml,sandbox
/// title: "Base-10 log on imaginary axis"
/// formula: "=IMLOG10(\"i\")"
/// expected: "0.6821881769209206i"
/// ```
/// ```yaml,docs
/// related:
///   - IMLN
///   - IMLOG2
///   - IMEXP
/// faq:
///   - q: "What branch of the logarithm does `IMLOG10` use?"
///     a: "It returns the principal complex logarithm (base 10), derived from principal argument `atan2(imag, real)`."
/// ```
#[derive(Debug)]
pub struct ImLog10Fn;
/// [formualizer-docgen:schema:start]
/// Name: IMLOG10
/// Type: ImLog10Fn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMLOG10(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImLog10Fn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMLOG10"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let inumber = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let (a, b, suffix) = match parse_complex(&inumber) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        // log10(0) is undefined
        let modulus = (a * a + b * b).sqrt();
        if modulus < 1e-15 {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        // log10(z) = ln(z) / ln(10) = (ln(|z|) + i*arg(z)) / ln(10)
        let ln10 = 10.0_f64.ln();
        let real = modulus.ln() / ln10;
        let imag = b.atan2(a) / ln10;

        let result = format_complex(real, imag, suffix);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Returns the base-2 logarithm of a complex number.
///
/// Produces the principal complex logarithm in base 2.
///
/// # Remarks
/// - Input is coerced to complex-number text before parsing.
/// - Returns `#NUM!` for zero input.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Base-2 log of a real value"
/// formula: "=IMLOG2(\"8\")"
/// expected: "3"
/// ```
///
/// ```yaml,sandbox
/// title: "Base-2 log on imaginary axis"
/// formula: "=IMLOG2(\"i\")"
/// expected: "2.266180070913597i"
/// ```
/// ```yaml,docs
/// related:
///   - IMLN
///   - IMLOG10
///   - IMEXP
/// faq:
///   - q: "When does `IMLOG2` return `#NUM!`?"
///     a: "It returns `#NUM!` for invalid complex text or zero input, where logarithm is undefined."
/// ```
#[derive(Debug)]
pub struct ImLog2Fn;
/// [formualizer-docgen:schema:start]
/// Name: IMLOG2
/// Type: ImLog2Fn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMLOG2(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImLog2Fn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMLOG2"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let inumber = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let (a, b, suffix) = match parse_complex(&inumber) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        // log2(0) is undefined
        let modulus = (a * a + b * b).sqrt();
        if modulus < 1e-15 {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                ExcelError::new_num(),
            )));
        }

        // log2(z) = ln(z) / ln(2) = (ln(|z|) + i*arg(z)) / ln(2)
        let ln2 = 2.0_f64.ln();
        let real = modulus.ln() / ln2;
        let imag = b.atan2(a) / ln2;

        let result = format_complex(real, imag, suffix);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Raises a complex number to a real power.
///
/// Uses polar form and returns the principal-value result as complex text.
///
/// # Remarks
/// - `inumber` is coerced to complex-number text; `n` is numerically coerced.
/// - Returns `#NUM!` for undefined zero-power cases such as `0^0` or `0^-1`.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Square a complex value"
/// formula: "=IMPOWER(\"1+i\",2)"
/// expected: "2i"
/// ```
///
/// ```yaml,sandbox
/// title: "Negative real exponent"
/// formula: "=IMPOWER(\"2\",-1)"
/// expected: "0.5"
/// ```
/// ```yaml,docs
/// related:
///   - IMSQRT
///   - IMEXP
///   - IMLN
/// faq:
///   - q: "How does `IMPOWER` handle zero base with non-positive exponent?"
///     a: "`0^0` and `0` raised to a negative exponent are treated as undefined and return `#NUM!`."
/// ```
#[derive(Debug)]
pub struct ImPowerFn;
/// [formualizer-docgen:schema:start]
/// Name: IMPOWER
/// Type: ImPowerFn
/// Min args: 2
/// Max args: 2
/// Variadic: false
/// Signature: IMPOWER(arg1: any@scalar, arg2: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}; arg2{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImPowerFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMPOWER"
    }
    fn min_args(&self) -> usize {
        2
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_TWO[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let inumber = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let n = match args[1].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => coerce_num(&other)?,
        };

        let (a, b, suffix) = match parse_complex(&inumber) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        let modulus = (a * a + b * b).sqrt();
        let theta = b.atan2(a);

        // Handle 0^n cases
        if modulus < 1e-15 {
            if n > 0.0 {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(
                    "0".to_string(),
                )));
            } else {
                // 0^0 or 0^negative is undefined
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_num(),
                )));
            }
        }

        // z^n = |z|^n * (cos(n*theta) + i*sin(n*theta))
        let r_n = modulus.powf(n);
        let n_theta = n * theta;
        let real = r_n * n_theta.cos();
        let imag = r_n * n_theta.sin();

        let result = format_complex(real, imag, suffix);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Returns the principal square root of a complex number.
///
/// Computes the root in polar form and returns complex text.
///
/// # Remarks
/// - Input is coerced to complex-number text before parsing.
/// - Returns the principal branch of the square root.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Square root of a negative real"
/// formula: "=IMSQRT(\"-4\")"
/// expected: "2i"
/// ```
///
/// ```yaml,sandbox
/// title: "Square root of a+bi"
/// formula: "=IMSQRT(\"3+4i\")"
/// expected: "2+i"
/// ```
/// ```yaml,docs
/// related:
///   - IMPOWER
///   - IMABS
///   - IMARGUMENT
/// faq:
///   - q: "Which square root does `IMSQRT` return for complex inputs?"
///     a: "It returns the principal branch (half-angle polar form), matching spreadsheet-style principal-value behavior."
/// ```
#[derive(Debug)]
pub struct ImSqrtFn;
/// [formualizer-docgen:schema:start]
/// Name: IMSQRT
/// Type: ImSqrtFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMSQRT(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImSqrtFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMSQRT"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let inumber = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let (a, b, suffix) = match parse_complex(&inumber) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        let modulus = (a * a + b * b).sqrt();
        let theta = b.atan2(a);

        // sqrt(z) = sqrt(|z|) * (cos(theta/2) + i*sin(theta/2))
        let sqrt_r = modulus.sqrt();
        let half_theta = theta / 2.0;
        let real = sqrt_r * half_theta.cos();
        let imag = sqrt_r * half_theta.sin();

        let result = format_complex(real, imag, suffix);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Returns the sine of a complex number.
///
/// Evaluates complex sine and returns the result as complex text.
///
/// # Remarks
/// - Input is coerced to complex-number text before parsing.
/// - Uses hyperbolic components for the imaginary part.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Sine of zero"
/// formula: "=IMSIN(\"0\")"
/// expected: "0"
/// ```
///
/// ```yaml,sandbox
/// title: "Sine on imaginary axis"
/// formula: "=IMSIN(\"i\")"
/// expected: "1.1752011936438014i"
/// ```
/// ```yaml,docs
/// related:
///   - IMCOS
///   - IMEXP
/// faq:
///   - q: "Why can `IMSIN` return non-zero imaginary output for real-looking formulas?"
///     a: "For complex inputs `a+bi`, sine uses hyperbolic terms (`cosh`, `sinh`), so imaginary components are expected."
/// ```
#[derive(Debug)]
pub struct ImSinFn;
/// [formualizer-docgen:schema:start]
/// Name: IMSIN
/// Type: ImSinFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMSIN(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImSinFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMSIN"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let inumber = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let (a, b, suffix) = match parse_complex(&inumber) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        // sin(a+bi) = sin(a)*cosh(b) + i*cos(a)*sinh(b)
        let real = a.sin() * b.cosh();
        let imag = a.cos() * b.sinh();

        let result = format_complex(real, imag, suffix);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

/// Returns the cosine of a complex number.
///
/// Evaluates complex cosine and returns the result as complex text.
///
/// # Remarks
/// - Input is coerced to complex-number text before parsing.
/// - Uses hyperbolic components for the imaginary part.
/// - Invalid complex text returns `#NUM!`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Cosine of zero"
/// formula: "=IMCOS(\"0\")"
/// expected: "1"
/// ```
///
/// ```yaml,sandbox
/// title: "Cosine on imaginary axis"
/// formula: "=IMCOS(\"i\")"
/// expected: "1.5430806348152437"
/// ```
/// ```yaml,docs
/// related:
///   - IMSIN
///   - IMEXP
/// faq:
///   - q: "Why is the imaginary part negated in `IMCOS`?"
///     a: "Complex cosine uses `cos(a+bi)=cos(a)cosh(b)-i sin(a)sinh(b)`, so the imaginary term carries a minus sign."
/// ```
#[derive(Debug)]
pub struct ImCosFn;
/// [formualizer-docgen:schema:start]
/// Name: IMCOS
/// Type: ImCosFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMCOS(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImCosFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMCOS"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        let inumber = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => match coerce_complex_str(&other) {
                Ok(s) => s,
                Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
            },
        };

        let (a, b, suffix) = match parse_complex(&inumber) {
            Ok(c) => c,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        };

        // cos(a+bi) = cos(a)*cosh(b) - i*sin(a)*sinh(b)
        let real = a.cos() * b.cosh();
        let imag = -a.sin() * b.sinh();

        let result = format_complex(real, imag, suffix);
        Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(result)))
    }
}

fn eval_complex_unary<'a, 'b, 'c, F>(
    args: &'c [ArgumentHandle<'a, 'b>],
    f: F,
) -> Result<crate::traits::CalcValue<'b>, ExcelError>
where
    F: FnOnce(f64, f64, char) -> Result<(f64, f64, char), ExcelError>,
{
    if args.len() != 1 {
        return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
            ExcelError::new_value(),
        )));
    }
    let inumber = match args[0].value()?.into_literal() {
        LiteralValue::Error(e) => {
            return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
        }
        other => match coerce_complex_str(&other) {
            Ok(s) => s,
            Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        },
    };
    let (a, b, suffix) = match parse_complex(&inumber) {
        Ok(c) => c,
        Err(e) => return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
    };
    let (real, imag, suffix) = f(a, b, suffix)?;
    if real.is_nan() || imag.is_nan() || real.is_infinite() || imag.is_infinite() {
        return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
            ExcelError::new_num(),
        )));
    }
    Ok(crate::traits::CalcValue::Scalar(LiteralValue::Text(
        format_complex(real, imag, suffix),
    )))
}

/// Returns the hyperbolic cosine of a complex number.
///
/// Accepts an Excel-style complex number string and returns the complex
/// hyperbolic cosine as text.
///
/// # Remarks
/// - The input may use either `i` or `j` as the imaginary suffix.
/// - Invalid complex text returns `#NUM!`.
///
/// ```yaml,sandbox
/// title: "Hyperbolic cosine of zero"
/// formula: '=IMCOSH("0")'
/// expected: "1"
/// ```
///
/// ```yaml,docs
/// related:
///   - IMSINH
///   - IMSECH
///   - IMCOS
/// faq:
///   - q: "Does IMCOSH preserve the imaginary suffix?"
///     a: "Results preserve the input's i/j suffix when an imaginary part is present."
/// ```
#[derive(Debug)]
pub struct ImCoshFn;
/// [formualizer-docgen:schema:start]
/// Name: IMCOSH
/// Type: ImCoshFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMCOSH(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImCoshFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMCOSH"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        eval_complex_unary(args, |a, b, suffix| {
            Ok((a.cosh() * b.cos(), a.sinh() * b.sin(), suffix))
        })
    }
}

/// Returns the hyperbolic sine of a complex number.
///
/// Accepts an Excel-style complex number string and returns the complex
/// hyperbolic sine as text.
///
/// ```yaml,sandbox
/// title: "Hyperbolic sine of zero"
/// formula: '=IMSINH("0")'
/// expected: "0"
/// ```
///
/// ```yaml,docs
/// related:
///   - IMCOSH
///   - IMTAN
///   - IMSIN
/// faq:
///   - q: "What input format is accepted?"
///     a: 'Use standard spreadsheet complex-number text such as "1+2i" or "1+2j".'
/// ```
#[derive(Debug)]
pub struct ImSinhFn;
/// [formualizer-docgen:schema:start]
/// Name: IMSINH
/// Type: ImSinhFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMSINH(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImSinhFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMSINH"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        eval_complex_unary(args, |a, b, suffix| {
            Ok((a.sinh() * b.cos(), a.cosh() * b.sin(), suffix))
        })
    }
}

/// Returns the secant of a complex number.
///
/// Computes `1 / IMCOS(inumber)` for an Excel-style complex number string.
///
/// ```yaml,sandbox
/// title: "Secant of zero"
/// formula: '=IMSEC("0")'
/// expected: "1"
/// ```
///
/// ```yaml,docs
/// related:
///   - IMCOS
///   - IMSECH
///   - IMCSC
/// faq:
///   - q: "How are poles represented?"
///     a: "Inputs that lead to non-finite results return #NUM!."
/// ```
#[derive(Debug)]
pub struct ImSecFn;
/// [formualizer-docgen:schema:start]
/// Name: IMSEC
/// Type: ImSecFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMSEC(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImSecFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMSEC"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        eval_complex_unary(args, |a, b, suffix| {
            let cos_a = a.cos();
            let sin_a = a.sin();
            let cosh_b = b.cosh();
            let sinh_b = b.sinh();
            let denom = cos_a * cos_a * cosh_b * cosh_b + sin_a * sin_a * sinh_b * sinh_b;
            Ok((cos_a * cosh_b / denom, sin_a * sinh_b / denom, suffix))
        })
    }
}

/// Returns the hyperbolic secant of a complex number.
///
/// Computes `1 / IMCOSH(inumber)` for an Excel-style complex number string.
///
/// ```yaml,sandbox
/// title: "Hyperbolic secant of zero"
/// formula: '=IMSECH("0")'
/// expected: "1"
/// ```
///
/// ```yaml,docs
/// related:
///   - IMCOSH
///   - IMSEC
///   - IMCSCH
/// faq:
///   - q: "What does IMSECH return?"
///     a: "It returns a complex number encoded as spreadsheet text."
/// ```
#[derive(Debug)]
pub struct ImSechFn;
/// [formualizer-docgen:schema:start]
/// Name: IMSECH
/// Type: ImSechFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMSECH(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImSechFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMSECH"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        eval_complex_unary(args, |a, b, suffix| {
            let cosh_a = a.cosh();
            let sinh_a = a.sinh();
            let cos_b = b.cos();
            let sin_b = b.sin();
            let denom = cosh_a * cosh_a * cos_b * cos_b + sinh_a * sinh_a * sin_b * sin_b;
            Ok((cosh_a * cos_b / denom, -sinh_a * sin_b / denom, suffix))
        })
    }
}

/// Returns the cosecant of a complex number.
///
/// Computes `1 / IMSIN(inumber)` for an Excel-style complex number string.
///
/// ```yaml,sandbox
/// title: "Cosecant of pi over two"
/// formula: '=IMCSC("1.5707963267948966")'
/// expected: "1"
/// ```
///
/// ```yaml,docs
/// related:
///   - IMSIN
///   - IMCSCH
///   - IMSEC
/// faq:
///   - q: "What happens at a pole?"
///     a: "Inputs such as zero that make the reciprocal undefined return #NUM!."
/// ```
#[derive(Debug)]
pub struct ImCscFn;
/// [formualizer-docgen:schema:start]
/// Name: IMCSC
/// Type: ImCscFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMCSC(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImCscFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMCSC"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        eval_complex_unary(args, |a, b, suffix| {
            let cos_a = a.cos();
            let sin_a = a.sin();
            let cosh_b = b.cosh();
            let sinh_b = b.sinh();
            let denom = sin_a * sin_a * cosh_b * cosh_b + cos_a * cos_a * sinh_b * sinh_b;
            Ok((sin_a * cosh_b / denom, -cos_a * sinh_b / denom, suffix))
        })
    }
}

/// Returns the hyperbolic cosecant of a complex number.
///
/// Computes `1 / IMSINH(inumber)` for an Excel-style complex number string.
///
/// ```yaml,sandbox
/// title: "Hyperbolic cosecant of one"
/// formula: '=IMCSCH("1")'
/// expected: "0.8509181282393216"
/// ```
///
/// ```yaml,docs
/// related:
///   - IMSINH
///   - IMCSC
///   - IMSECH
/// faq:
///   - q: "Can IMCSCH return #NUM!?"
///     a: "Yes. Undefined reciprocal results return #NUM!."
/// ```
#[derive(Debug)]
pub struct ImCschFn;
/// [formualizer-docgen:schema:start]
/// Name: IMCSCH
/// Type: ImCschFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMCSCH(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImCschFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMCSCH"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        eval_complex_unary(args, |a, b, suffix| {
            let cosh_a = a.cosh();
            let sinh_a = a.sinh();
            let cos_b = b.cos();
            let sin_b = b.sin();
            let denom = sinh_a * sinh_a * cos_b * cos_b + cosh_a * cosh_a * sin_b * sin_b;
            Ok((sinh_a * cos_b / denom, -cosh_a * sin_b / denom, suffix))
        })
    }
}

/// Returns the tangent of a complex number.
///
/// Accepts an Excel-style complex number string and returns the complex tangent
/// as text.
///
/// ```yaml,sandbox
/// title: "Tangent of zero"
/// formula: '=IMTAN("0")'
/// expected: "0"
/// ```
///
/// ```yaml,docs
/// related:
///   - IMSIN
///   - IMCOS
///   - IMCOT
/// faq:
///   - q: "How is IMTAN related to sine and cosine?"
///     a: "It computes the complex tangent, equivalent to IMSIN divided by IMCOS."
/// ```
#[derive(Debug)]
pub struct ImTanFn;
/// [formualizer-docgen:schema:start]
/// Name: IMTAN
/// Type: ImTanFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMTAN(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImTanFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMTAN"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        eval_complex_unary(args, |a, b, suffix| {
            let tan_a = a.tan();
            let tanh_b = b.tanh();
            let denom = 1.0 + tan_a * tan_a * tanh_b * tanh_b;
            Ok((
                (tan_a - tan_a * tanh_b * tanh_b) / denom,
                (tanh_b + tan_a * tan_a * tanh_b) / denom,
                suffix,
            ))
        })
    }
}

/// Returns the cotangent of a complex number.
///
/// Computes the reciprocal of the complex tangent for an Excel-style complex
/// number string.
///
/// ```yaml,sandbox
/// title: "Cotangent of one"
/// formula: '=IMCOT("1")'
/// expected: "0.6420926159343306"
/// ```
///
/// ```yaml,docs
/// related:
///   - IMTAN
///   - IMCOS
///   - IMSIN
/// faq:
///   - q: "What happens at undefined inputs?"
///     a: "Inputs that produce non-finite reciprocal results return #NUM!."
/// ```
#[derive(Debug)]
pub struct ImCotFn;
/// [formualizer-docgen:schema:start]
/// Name: IMCOT
/// Type: ImCotFn
/// Min args: 1
/// Max args: 1
/// Variadic: false
/// Signature: IMCOT(arg1: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ImCotFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "IMCOT"
    }
    fn min_args(&self) -> usize {
        1
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_ANY_ONE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        eval_complex_unary(args, |a, b, suffix| {
            if a == 0.0 && b != 0.0 {
                return Ok((0.0, -1.0 / b.tanh(), suffix));
            }
            if b == 0.0 {
                return Ok((1.0 / a.tan(), 0.0, suffix));
            }
            let cot_a = 1.0 / a.tan();
            let coth_b = 1.0 / b.tanh();
            let denom = cot_a * cot_a + coth_b * coth_b;
            Ok((
                (cot_a * coth_b * coth_b - cot_a) / denom,
                (-cot_a * cot_a * coth_b - coth_b) / denom,
                suffix,
            ))
        })
    }
}

/* ─────────────────────────── Unit Conversion (CONVERT) ──────────────────────────── */

/// Unit categories for CONVERT function
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum UnitCategory {
    Length,
    Mass,
    Temperature,
}

/// Information about a unit
struct UnitInfo {
    category: UnitCategory,
    /// Conversion factor to base unit (meters for length, grams for mass)
    /// For temperature, this is special-cased
    to_base: f64,
}

/// Get unit info for a given unit string
fn get_unit_info(unit: &str) -> Option<UnitInfo> {
    // Length units (base: meter)
    match unit {
        // Metric length
        "m" => Some(UnitInfo {
            category: UnitCategory::Length,
            to_base: 1.0,
        }),
        "km" => Some(UnitInfo {
            category: UnitCategory::Length,
            to_base: 1000.0,
        }),
        "cm" => Some(UnitInfo {
            category: UnitCategory::Length,
            to_base: 0.01,
        }),
        "mm" => Some(UnitInfo {
            category: UnitCategory::Length,
            to_base: 0.001,
        }),
        // Imperial length
        "mi" => Some(UnitInfo {
            category: UnitCategory::Length,
            to_base: 1609.344,
        }),
        "ft" => Some(UnitInfo {
            category: UnitCategory::Length,
            to_base: 0.3048,
        }),
        "in" => Some(UnitInfo {
            category: UnitCategory::Length,
            to_base: 0.0254,
        }),
        "yd" => Some(UnitInfo {
            category: UnitCategory::Length,
            to_base: 0.9144,
        }),
        "Nmi" => Some(UnitInfo {
            category: UnitCategory::Length,
            to_base: 1852.0,
        }),

        // Mass units (base: gram)
        "g" => Some(UnitInfo {
            category: UnitCategory::Mass,
            to_base: 1.0,
        }),
        "kg" => Some(UnitInfo {
            category: UnitCategory::Mass,
            to_base: 1000.0,
        }),
        "mg" => Some(UnitInfo {
            category: UnitCategory::Mass,
            to_base: 0.001,
        }),
        "lbm" => Some(UnitInfo {
            category: UnitCategory::Mass,
            to_base: 453.59237,
        }),
        "oz" => Some(UnitInfo {
            category: UnitCategory::Mass,
            to_base: 28.349523125,
        }),
        "ozm" => Some(UnitInfo {
            category: UnitCategory::Mass,
            to_base: 28.349523125,
        }),
        "ton" => Some(UnitInfo {
            category: UnitCategory::Mass,
            to_base: 907184.74,
        }),

        // Temperature units (special handling)
        "C" | "cel" => Some(UnitInfo {
            category: UnitCategory::Temperature,
            to_base: 0.0, // Special-cased
        }),
        "F" | "fah" => Some(UnitInfo {
            category: UnitCategory::Temperature,
            to_base: 0.0, // Special-cased
        }),
        "K" | "kel" => Some(UnitInfo {
            category: UnitCategory::Temperature,
            to_base: 0.0, // Special-cased
        }),

        _ => None,
    }
}

/// Normalize temperature unit name
fn normalize_temp_unit(unit: &str) -> &str {
    match unit {
        "C" | "cel" => "C",
        "F" | "fah" => "F",
        "K" | "kel" => "K",
        _ => unit,
    }
}

/// Convert temperature between units
fn convert_temperature(value: f64, from: &str, to: &str) -> f64 {
    let from = normalize_temp_unit(from);
    let to = normalize_temp_unit(to);

    if from == to {
        return value;
    }

    // First convert to Celsius
    let celsius = match from {
        "C" => value,
        "F" => (value - 32.0) * 5.0 / 9.0,
        "K" => value - 273.15,
        _ => value,
    };

    // Then convert from Celsius to target
    match to {
        "C" => celsius,
        "F" => celsius * 9.0 / 5.0 + 32.0,
        "K" => celsius + 273.15,
        _ => celsius,
    }
}

/// Convert a value between units
fn convert_units(value: f64, from: &str, to: &str) -> Result<f64, ExcelError> {
    let from_info = get_unit_info(from).ok_or_else(ExcelError::new_na)?;
    let to_info = get_unit_info(to).ok_or_else(ExcelError::new_na)?;

    // Check category compatibility
    if from_info.category != to_info.category {
        return Err(ExcelError::new_na());
    }

    // Handle temperature specially
    if from_info.category == UnitCategory::Temperature {
        return Ok(convert_temperature(value, from, to));
    }

    // For other units: convert to base, then to target
    let base_value = value * from_info.to_base;
    Ok(base_value / to_info.to_base)
}

/// Converts a numeric value from one supported unit to another.
///
/// Supports a focused set of length, mass, and temperature units.
///
/// # Remarks
/// - `number` is numerically coerced; unit arguments must be text.
/// - Returns `#N/A` for unknown units or incompatible unit categories.
/// - Temperature conversions support `C/cel`, `F/fah`, and `K/kel`.
///
/// # Examples
/// ```yaml,sandbox
/// title: "Length conversion"
/// formula: "=CONVERT(1,\"km\",\"m\")"
/// expected: 1000
/// ```
///
/// ```yaml,sandbox
/// title: "Temperature conversion"
/// formula: "=CONVERT(32,\"F\",\"C\")"
/// expected: 0
/// ```
/// ```yaml,docs
/// related:
///   - DEC2BIN
///   - DEC2HEX
///   - DEC2OCT
/// faq:
///   - q: "When does `CONVERT` return `#N/A`?"
///     a: "Unknown unit tokens, non-text unit arguments, or mixing incompatible categories (for example length to mass) return `#N/A`."
/// ```
#[derive(Debug)]
pub struct ConvertFn;
/// [formualizer-docgen:schema:start]
/// Name: CONVERT
/// Type: ConvertFn
/// Min args: 3
/// Max args: 3
/// Variadic: false
/// Signature: CONVERT(arg1: any@scalar, arg2: any@scalar, arg3: any@scalar)
/// Arg schema: arg1{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}; arg2{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}; arg3{kinds=any,required=true,shape=scalar,by_ref=false,coercion=None,max=None,repeating=None,default=false}
/// Caps: PURE
/// [formualizer-docgen:schema:end]
impl Function for ConvertFn {
    func_caps!(PURE);
    fn name(&self) -> &'static str {
        "CONVERT"
    }
    fn min_args(&self) -> usize {
        3
    }
    fn arg_schema(&self) -> &'static [ArgSchema] {
        &ARG_COMPLEX_THREE[..]
    }
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Result<crate::traits::CalcValue<'b>, ExcelError> {
        // Get the number value
        let value = match args[0].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            other => coerce_num(&other)?,
        };

        // Get from_unit
        let from_unit = match args[1].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            LiteralValue::Text(s) => s,
            _ => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_na(),
                )));
            }
        };

        // Get to_unit
        let to_unit = match args[2].value()?.into_literal() {
            LiteralValue::Error(e) => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e)));
            }
            LiteralValue::Text(s) => s,
            _ => {
                return Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(
                    ExcelError::new_na(),
                )));
            }
        };

        match convert_units(value, &from_unit, &to_unit) {
            Ok(result) => Ok(crate::traits::CalcValue::Scalar(LiteralValue::Number(
                result,
            ))),
            Err(e) => Ok(crate::traits::CalcValue::Scalar(LiteralValue::Error(e))),
        }
    }
}

pub fn register_builtins() {
    use std::sync::Arc;
    crate::function_registry::register_function(Arc::new(BitAndFn));
    crate::function_registry::register_function(Arc::new(BitOrFn));
    crate::function_registry::register_function(Arc::new(BitXorFn));
    crate::function_registry::register_function(Arc::new(BitLShiftFn));
    crate::function_registry::register_function(Arc::new(BitRShiftFn));
    crate::function_registry::register_function(Arc::new(Bin2DecFn));
    crate::function_registry::register_function(Arc::new(Dec2BinFn));
    crate::function_registry::register_function(Arc::new(Hex2DecFn));
    crate::function_registry::register_function(Arc::new(Dec2HexFn));
    crate::function_registry::register_function(Arc::new(Oct2DecFn));
    crate::function_registry::register_function(Arc::new(Dec2OctFn));
    crate::function_registry::register_function(Arc::new(Bin2HexFn));
    crate::function_registry::register_function(Arc::new(Hex2BinFn));
    crate::function_registry::register_function(Arc::new(Bin2OctFn));
    crate::function_registry::register_function(Arc::new(Oct2BinFn));
    crate::function_registry::register_function(Arc::new(Hex2OctFn));
    crate::function_registry::register_function(Arc::new(Oct2HexFn));
    crate::function_registry::register_function(Arc::new(DeltaFn));
    crate::function_registry::register_function(Arc::new(GestepFn));
    crate::function_registry::register_function(Arc::new(ErfFn));
    crate::function_registry::register_function(Arc::new(ErfcFn));
    crate::function_registry::register_function(Arc::new(ErfPreciseFn));
    crate::function_registry::register_function(Arc::new(ErfcPreciseFn));
    crate::function_registry::register_function(Arc::new(BesselIFn));
    crate::function_registry::register_function(Arc::new(BesselJFn));
    crate::function_registry::register_function(Arc::new(BesselKFn));
    crate::function_registry::register_function(Arc::new(BesselYFn));
    // Complex number functions
    crate::function_registry::register_function(Arc::new(ComplexFn));
    crate::function_registry::register_function(Arc::new(ImRealFn));
    crate::function_registry::register_function(Arc::new(ImaginaryFn));
    crate::function_registry::register_function(Arc::new(ImAbsFn));
    crate::function_registry::register_function(Arc::new(ImArgumentFn));
    crate::function_registry::register_function(Arc::new(ImConjugateFn));
    crate::function_registry::register_function(Arc::new(ImSumFn));
    crate::function_registry::register_function(Arc::new(ImSubFn));
    crate::function_registry::register_function(Arc::new(ImProductFn));
    crate::function_registry::register_function(Arc::new(ImDivFn));
    // Complex number math functions
    crate::function_registry::register_function(Arc::new(ImExpFn));
    crate::function_registry::register_function(Arc::new(ImLnFn));
    crate::function_registry::register_function(Arc::new(ImLog10Fn));
    crate::function_registry::register_function(Arc::new(ImLog2Fn));
    crate::function_registry::register_function(Arc::new(ImPowerFn));
    crate::function_registry::register_function(Arc::new(ImSqrtFn));
    crate::function_registry::register_function(Arc::new(ImSinFn));
    crate::function_registry::register_function(Arc::new(ImCosFn));
    crate::function_registry::register_function(Arc::new(ImCoshFn));
    crate::function_registry::register_function(Arc::new(ImCotFn));
    crate::function_registry::register_function(Arc::new(ImCscFn));
    crate::function_registry::register_function(Arc::new(ImCschFn));
    crate::function_registry::register_function(Arc::new(ImSecFn));
    crate::function_registry::register_function(Arc::new(ImSechFn));
    crate::function_registry::register_function(Arc::new(ImSinhFn));
    crate::function_registry::register_function(Arc::new(ImTanFn));
    // Unit conversion
    crate::function_registry::register_function(Arc::new(ConvertFn));
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::builtins::text::ValueFn;
    use crate::test_workbook::TestWorkbook;
    use formualizer_common::{ExcelErrorKind, LiteralValue};
    use formualizer_parse::parser::parse;
    use std::sync::Arc;

    fn eval(formula: &str) -> LiteralValue {
        let wb = TestWorkbook::new()
            .with_function(Arc::new(ErfcFn))
            .with_function(Arc::new(ErfcPreciseFn))
            .with_function(Arc::new(BesselIFn))
            .with_function(Arc::new(BesselJFn))
            .with_function(Arc::new(BesselKFn))
            .with_function(Arc::new(BesselYFn))
            .with_function(Arc::new(ImCoshFn))
            .with_function(Arc::new(ImCotFn))
            .with_function(Arc::new(ImCscFn))
            .with_function(Arc::new(ImCschFn))
            .with_function(Arc::new(ImSecFn))
            .with_function(Arc::new(ImSechFn))
            .with_function(Arc::new(ImSinhFn))
            .with_function(Arc::new(ImTanFn))
            .with_function(Arc::new(ValueFn));
        let interp = wb.interpreter();
        let ast = parse(formula).expect("parse");
        interp.evaluate_ast(&ast).expect("eval").into_literal()
    }

    fn assert_number_close(value: LiteralValue, expected: f64) {
        match value {
            LiteralValue::Number(n) => assert!((n - expected).abs() < 1e-12, "{n} != {expected}"),
            other => panic!("expected number, got {other:?}"),
        }
    }

    fn assert_number_rel_close(value: LiteralValue, expected: f64, tol: f64) {
        match value {
            LiteralValue::Number(n) => {
                let denom = (n * n + expected * expected).sqrt().max(1.0);
                assert!((n - expected).abs() / denom < tol, "{n} != {expected}");
            }
            other => panic!("expected number, got {other:?}"),
        }
    }

    #[test]
    fn erfc_precise_matches_erfc() {
        assert_number_close(eval("=ERFC.PRECISE(1)"), erfc_direct(1.0));
        assert_eq!(eval("=ERFC.PRECISE(0)"), LiteralValue::Number(1.0));
        // Numeric text is accepted through standard function coercion.
        assert_number_close(eval("=ERFC.PRECISE(\"1\")"), erfc_direct(1.0));
    }

    #[test]
    fn bessel_functions_match_known_values_and_excel_order_truncation() {
        assert_number_rel_close(eval("=BESSELI(0.5,1)"), 0.2578943053908963, 1e-6);
        assert_number_rel_close(eval("=BESSELI(0.5,1.9)"), 0.2578943053908963, 1e-6);
        assert_number_rel_close(eval("=BESSELJ(0.5,3)"), 0.002563729994587244, 1e-13);
        assert_number_rel_close(eval("=BESSELK(0.5,1)"), 1.656441120003301, 1e-6);
        assert_number_rel_close(eval("=BESSELY(0.5,3)"), -42.059494304723883, 1e-13);
    }

    #[test]
    fn bessel_functions_map_invalid_domains_to_num() {
        assert!(
            matches!(eval("=BESSELJ(1,-1)"), LiteralValue::Error(e) if e.kind == ExcelErrorKind::Num)
        );
        assert!(
            matches!(eval("=BESSELY(1,-1)"), LiteralValue::Error(e) if e.kind == ExcelErrorKind::Num)
        );
        assert!(
            matches!(eval("=BESSELK(0,1)"), LiteralValue::Error(e) if e.kind == ExcelErrorKind::Num)
        );
        assert!(
            matches!(eval("=BESSELY(-1,1)"), LiteralValue::Error(e) if e.kind == ExcelErrorKind::Num)
        );
    }

    #[test]
    fn complex_hyperbolic_functions() {
        assert_eq!(eval("=IMCOSH(\"0\")"), LiteralValue::Text("1".into()));
        assert_eq!(eval("=IMSINH(\"0\")"), LiteralValue::Text("0".into()));
        assert_eq!(eval("=IMSECH(\"0\")"), LiteralValue::Text("1".into()));
        assert_eq!(eval("=IMTAN(\"0\")"), LiteralValue::Text("0".into()));
    }

    #[test]
    fn complex_reciprocal_trig_functions() {
        assert_eq!(eval("=IMSEC(\"0\")"), LiteralValue::Text("1".into()));
        assert_eq!(
            eval("=IMCOT(\"1\")"),
            LiteralValue::Text(format_complex(1.0 / 1.0f64.tan(), 0.0, 'i'))
        );
        assert_eq!(
            eval("=IMCSC(\"1.5707963267948966\")"),
            LiteralValue::Text("1".into())
        );
    }

    #[test]
    fn complex_functions_preserve_j_suffix_and_error_on_poles() {
        match eval("=IMSINH(\"j\")") {
            LiteralValue::Text(s) => assert!(s.ends_with('j'), "expected j suffix, got {s}"),
            other => panic!("expected text, got {other:?}"),
        }
        let pole = eval("=IMCSC(\"0\")");
        assert!(matches!(pole, LiteralValue::Error(e) if e.kind == ExcelErrorKind::Num));
    }
}