DECIMAL

What it does

DECIMAL(text, radix)

DECIMAL(text, radix) reads text as a numeral written in base radix and returns its value as a worksheet number. It is a parser, not an arithmetic function — the "decimal" in the name refers to the output being an ordinary number rather than a digit string, not to base 10 having any special role in the computation.

The definition is positional notation. For a digit string d_{n-1} … d_1 d_0 in base b:

value = Σ_{i=0}^{n-1} d_i · b^i

with the digit alphabet 0–9 then A–Z supplying values 0–35, and the reading case-insensitive.

The documented value bound is the interesting one: 2^53 is exactly the point at which binary64 stops being able to represent every integer. Microsoft's page draws the boundary there and adds that text resolving to values above it may lose precision. That is not a limitation of radix conversion; it is a limitation of the result type, stated honestly on the documentation page.

Arguments

Both slots take the shared coercion rules, with the wrinkle that the first slot is a text slot that will often receive a number: DECIMAL(1010, 2) passes a number where a numeral was asked for, and the number must be rendered to text before it can be parsed. Which rendering — general format, full precision, locale-dependent — is not stated on Microsoft's page, and the Handbook has not checked. That is a real question, not a pedantic one: a large numeric first argument could render in scientific notation and then contain characters that are not digits in any radix.

Try it

Quirks

Result and edge cases

Returns Number.

• Empty text — not documented. An empty numeral has no value; whether Excel returns 0 or an error is unchecked.
• Leading and trailing spaces — not documented.
• Digits out of range for the radix — e.g. DECIMAL("2", 2), where 2 is not a binary digit. Microsoft's page says arguments outside the stated constraints may return #NUM! or #VALUE!, without saying which applies here.
• Non-integer radix — the page documents radix as an integer; whether a fractional radix truncates or errors is not stated.
• Values at and above 2^53 — documented as possible precision loss rather than as an error. Note the asymmetry with the lower bound, which is documented as a constraint: a negative value is out of range, an over-large value is merely imprecise.
• A leading minus sign — the documented range starts at 0, so signed input is outside the documented domain. What happens is not stated.

Every one of these is a boundary the documentation leaves open, and together they are why this page's probe list is longer than its behaviour section.

Errors

Microsoft's page states the error conditions jointly and loosely: arguments outside the stated constraints may return #NUM! or #VALUE!. It does not map individual violations to individual error values.

That is an unusually weak error specification for a function with five separate documented constraints, and it is recorded here as a documentation gap rather than paraphrased into a precision the source does not have.

How to implement

Numerical notes

Radix conversion is exact arithmetic dressed as parsing, and its accuracy story is short but not empty.

Within the documented range, the answer is exact and there is no excuse for anything less. Every integer below 2^53 is a binary64 value, so Horner's rule over the digits — acc ← acc·b + d — computes the value with no rounding at all, provided each intermediate stays below 2^53. Since the intermediates of a correct parse are prefixes of the final value, they do. Knuth TAOCP volume 2 §4.4 is the standard treatment.

Outside it, the choices start to matter. For a numeral whose value exceeds 2^53, Horner-in-binary64 rounds at every step, and the accumulated result can differ from the correctly rounded value of the numeral by several ulp. The correct approach — the one a math-correct flavour would take — accumulates in an exact integer type and rounds once at the end. Microsoft's page documents that precision may be lost without saying which discipline applies, so the difference between "rounds once" and "rounds every step" is unspecified and observable. It is the sharpest numerical question on this page.

Powers of two are the special case. When the radix is 2, 4, 8, 16 or 32, digits map onto fixed bit-fields and the conversion is a shift-and-or with no multiplication at all. An implementation that special-cases them is exact for longer and faster; one that does not is neither. Whether Excel distinguishes them is unchecked, and the discriminating probe is a long numeral in base 16 against the same value in base 10.

Length versus value. The documented 255-character limit and the documented 2^53 value limit are not the same constraint: a 255-character base-2 numeral of all zeros followed by a one has a tiny value, and a 12-character base-36 numeral exceeds 2^53. Which limit is checked first, and whether the length limit is on the text or on its significant digits, is not documented.

Rust code

44 decimal "DECIMAL" (2, 2) [V "text", V "radix"] |s, a, sv| {
    let t = text(s, a, 0)?;
    let radix = num(s, a, 1)?;
    out(s, k::decimal_fn::decimal_kernel(&t, radix))
}

fn digit_value(c: char) -> Option<u32> {
    match c {
        '0'..='9' => Some((c as u8 - b'0') as u32),
        'A'..='Z' => Some((c as u8 - b'A') as u32 + 10),
        _ => None,
    }
}

pub fn decimal_kernel(text: &str, radix: f64) -> Result<f64, WorksheetErrorCode> {
    let radix = radix.trunc();
    if !(2.0..=36.0).contains(&radix) {
        return Err(WorksheetErrorCode::Num);
    }
    let radix = radix as u32;
    let normalized = text.trim_start().to_ascii_uppercase();
    if normalized.is_empty() {
        return Ok(0.0);
    }

    let mut value: u128 = 0;
    for ch in normalized.chars() {
        let Some(digit) = digit_value(ch) else {
            return Err(WorksheetErrorCode::Num);
        };
        if digit >= radix {
            return Err(WorksheetErrorCode::Num);
        }
        value = value
            .checked_mul(radix as u128)
            .and_then(|v| v.checked_add(digit as u128))
            .ok_or(WorksheetErrorCode::Num)?;
    }
    Ok(value as f64)
}

No implementation has been published with a Handbook test suite for this function.

Version differences

The recorded environments below distinguish a reading from a same-input comparison. Counts describe captured inputs in each environment; overlapping captures and comparisons are not totals of unique worksheet calls.

The record contains no same-input comparison between these environments. Reading different inputs on different builds does not establish either a version change or cross-build agreement.

Recorded environments and comparison details.

Alternatives

Relationships

• BASE — the documented inverse: BASE writes a number as a digit string in a given radix, DECIMAL reads one back. DECIMAL(BASE(n, b), b) = n is the round trip, and it is the natural metamorphic test for both surfaces.
• BIN2DEC, OCT2DEC, HEX2DEC — the fixed-radix predecessors from the Analysis ToolPak, for bases 2, 8 and 16. They differ from DECIMAL in a way that matters: they interpret their input as a two's-complement value of fixed width, so a leading digit can mean a negative number, while DECIMAL is documented over non-negative values only. Replacing HEX2DEC with DECIMAL(…, 16) silently changes the meaning of every input whose top bit is set.
• DEC2BIN, DEC2OCT, DEC2HEX — the corresponding writers, and BASE's predecessors.
• VALUE, NUMBERVALUE — the base-10 text-to-number parsers, locale-aware where DECIMAL is not documented to be.
• ARABIC — the other non-positional numeral parser on the worksheet surface, and DECIMAL's co-subject in the evidence record attached to this page.

Named variants

No named variants are recorded yet.