ARABIC

What it does

ARABIC(text)

ARABIC(text) reads a Roman numeral and returns its value as a number.

Roman numeration is non-positional. A digit's contribution does not depend on where it sits in a place-value column; it depends on the digit itself and on whether a larger digit follows it. The seven symbols and their values:

The standard evaluation rule is one pass, right to left or left to right, with a single comparison:

value(s) = sum over i of   +v(i)   if v(i) >= v(i+1)
                           -v(i)   if v(i) <  v(i+1)

where v(i) is the value of the i-th symbol and the last symbol always contributes positively. That rule reads IX as -1 + 10 = 9 and XI as 10 + 1 = 11. It is the rule every implementation uses, and it is far more permissive than the notation people think of as Roman: it happily evaluates IIX as 8, VV as 10, and IM as 999, none of which is classical usage.

This is the mathematically important fact about ARABIC: the map from strings to numbers is many-to-one and its domain is a matter of choice, not of arithmetic. There is no canonical Roman grammar — the subtractive forms IV, IX, XL, XC, CD, CM were never universal in Roman practice, and modern "rules" are a nineteenth-century tidying. So a function that converts Roman to decimal has to decide how permissive to be, and that decision is behaviour, not mathematics.

ARABIC is therefore best understood as a parser with an undocumented grammar. What the grammar accepts is the whole content of this function, and none of it is documented on any page the Handbook has retrieved.

Arguments

Microsoft's Learn reference types the argument as String and describes it as "the Roman numeral that you want to convert", and types the return as Double. That is the entirety of the documentation retrieved for this function: no grammar, no case rule, no length limit, no range, no sign handling, and no error condition.

Try it

Quirks

Result and edge cases

Returns Number.

The questions that decide this function's behaviour, and the state of each:

Every row in that table is a real behavioural fact that a formula can depend on, and every one of them is currently unpublished. This page states the shape of the ignorance rather than filling it in.

Errors

The condition column is deliberately vague because the grammar is unknown. "Not admissible" is precisely as specific as the published record allows, and sharpening it is what the probe list below is for.

How to implement

Notes for implementers

The one-pass rule is the whole algorithm, and it is three lines. The interesting work is entirely in deciding what to reject before running it.

Validation is a policy, not a correctness requirement. A permissive implementation runs the sum and returns a number for anything built from the seven letters. A strict one enforces the classical constraints: at most three consecutive repeats of I, X, C, M; no repeats of V, L, D; only I before V or X, only X before L or C, only C before D or M; at most one subtractive pair per magnitude. Both are defensible. They differ on a large set of inputs, and which one Excel implements is unknown here.

Case folding. If the function is case-insensitive, that is an invariant fold, not a locale one — the seven letters are all ASCII and have no Turkish-i style hazard. If it is case-sensitive, that is a decision worth documenting. Neither is on record.

Exactness. Every reachable value is a small integer, well inside the exactly-representable range of binary64, so there is no rounding question anywhere in this function. That is unusual for a math-category surface and is worth stating so that readers do not go looking for one.

Failure kind. A parser has two failure modes — "these characters are not in the alphabet" and "these characters are in the alphabet but not in this order" — and an implementation should decide whether they produce the same error. If they do, a caller cannot tell a typo from a non-canonical spelling.

Round-trip as the test harness. ARABIC(ROMAN(n, f)) over all n in range and all f is a complete self-consistency suite that requires no oracle, and it is the cheapest way to find disagreements between a pair of implementations.

Rust code

41 arabic "ARABIC" (1, 1) [V "text"] |s, a, sv| {
    let t = text(s, a, 0)?;
    out(s, k::arabic_fn::arabic_kernel(&ExcelText::from_interop_assignment(&t)))
}

fn roman_value(ch: char) -> Option<i64> {
    match ch {
        'I' => Some(1),
        'V' => Some(5),
        'X' => Some(10),
        'L' => Some(50),
        'C' => Some(100),
        'D' => Some(500),
        'M' => Some(1000),
        _ => None,
    }
}

pub fn arabic_kernel(text: &ExcelText) -> Result<f64, WorksheetErrorCode> {
    let s = String::from_utf16_lossy(text.utf16_code_units()).to_uppercase();
    if s.is_empty() {
        return Ok(0.0);
    }
    let mut total = 0i64;
    let mut prev = 0i64;
    for ch in s.chars().rev() {
        let value = roman_value(ch).ok_or(WorksheetErrorCode::Value)?;
        if value < prev {
            total -= value;
        } else {
            total += value;
            prev = value;
        }
    }
    Ok(total as f64)
}

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

Version differences

No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.

Alternatives

Relationships

• ROMAN — the counterpart in the other direction, and not an inverse. ROMAN takes an optional form argument selecting among several degrees of abbreviation, so it is one-to-many; ARABIC is many-to-one. ARABIC(ROMAN(n)) should recover n for every form and every n in range, and that round trip is the best available consistency test for the pair. ROMAN(ARABIC(s)) does not recover s in general, because non-canonical spellings normalise away.
• DECIMAL — the positional counterpart: text in a stated radix to a number. ARABIC is the non-positional member of the same job. DECIMAL shares this surface's evidence record.
• BASE — DECIMAL's inverse, and therefore the positional analogue of ROMAN.
• VALUE and NUMBERVALUE — the general text-to-number readers, which do not understand Roman numerals at all.
• Confused with: the Arabic language or Arabic-Indic digits. The function name refers to Arabic numerals in the ordinary English sense — the digits 0-9 — and has nothing to do with locale or script.

Named variants

No named variants are recorded yet.