{ "category": "Math and trigonometry functions", "display_name": "ARABIC", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.ARABIC", "implementation_state": { "answer_bank": null, "detail": "Recorded: 3 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 3 recorded answers", "workbook_corpus": { "cells": 3, "matched": 3 } }, "implementations": [ { "commit": "9e1884369a678158dd82d3d74188daf986995e87", "flavour": "excel-compatibility-candidate", "language": "Rust", "name": "CalcFunc", "own_code": [ "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/math.rs#L163-L166", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/arabic_fn.rs#L4-L15", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/arabic_fn.rs#L17-L34" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/math.rs#L163-L166", "state": "matches", "suite": null, "summary": "Matches all 3 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.ARABIC.json", "name": "ARABIC", "notes": [], "schema": "efh.function-reference/v1", "section_order": [ "what-it-does", "try-it", "quirks", "how-to-implement", "version-differences", "alternatives" ], "sections": { "alternatives": "\n### Relationships\n\n\n- **`ROMAN`** — the counterpart in the other direction, and *not* an inverse. `ROMAN` takes an\n optional `form` argument selecting among several degrees of abbreviation, so it is one-to-many;\n `ARABIC` is many-to-one. `ARABIC(ROMAN(n))` should recover `n` for every form and every `n` in\n range, and that round trip is the best available consistency test for the pair. `ROMAN(ARABIC(s))`\n does *not* recover `s` in general, because non-canonical spellings normalise away.\n- **`DECIMAL`** — the positional counterpart: text in a stated radix to a number. `ARABIC` is the\n non-positional member of the same job. `DECIMAL` shares this surface's evidence record.\n- **`BASE`** — `DECIMAL`'s inverse, and therefore the positional analogue of `ROMAN`.\n- **`VALUE`** and **`NUMBERVALUE`** — the general text-to-number readers, which do not understand\n Roman numerals at all.\n- **Confused with**: the Arabic *language* or Arabic-Indic *digits*. The function name refers to\n Arabic numerals in the ordinary English sense — the digits 0-9 — and has nothing to do with\n locale or script.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n**The one-pass rule is the whole algorithm**, and it is three lines. The interesting work is\nentirely in deciding what to reject before running it.\n\n**Validation is a policy, not a correctness requirement.** A permissive implementation runs the\nsum and returns a number for anything built from the seven letters. A strict one enforces the\nclassical constraints: at most three consecutive repeats of `I`, `X`, `C`, `M`; no repeats of `V`,\n`L`, `D`; only `I` before `V` or `X`, only `X` before `L` or `C`, only `C` before `D` or `M`; at\nmost one subtractive pair per magnitude. Both are defensible. They differ on a large set of inputs,\nand which one Excel implements is unknown here.\n\n**Case folding.** If the function is case-insensitive, that is an invariant fold, not a locale one\n— the seven letters are all ASCII and have no Turkish-i style hazard. If it is case-sensitive, that\nis a decision worth documenting. Neither is on record.\n\n**Exactness.** Every reachable value is a small integer, well inside the exactly-representable\nrange of binary64, so there is no rounding question anywhere in this function. That is unusual for\na math-category surface and is worth stating so that readers do not go looking for one.\n\n**Failure kind.** A parser has two failure modes — \"these characters are not in the alphabet\" and\n\"these characters are in the alphabet but not in this order\" — and an implementation should decide\nwhether they produce the same error. If they do, a caller cannot tell a typo from a non-canonical\nspelling.\n\n**Round-trip as the test harness.** `ARABIC(ROMAN(n, f))` over all `n` in range and all `f` is a\ncomplete self-consistency suite that requires no oracle, and it is the cheapest way to find\ndisagreements between a pair of implementations.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number`.\n\nThe questions that decide this function's behaviour, and the state of each:\n\nEvery row in that table is a real behavioural fact that a formula can depend on, and every one of\nthem is currently unpublished. This page states the shape of the ignorance rather than filling it\nin.\n\n\n### Errors\n\nThe condition column is deliberately vague because the grammar is unknown. \"Not admissible\" is\nprecisely as specific as the published record allows, and sharpening it is what the probe list\nbelow is for.\n\n\n", "sources": "- Microsoft Learn, \"WorksheetFunction.Arabic method (Excel)\" —\n (retrieved: the\n description, the `String` argument type and the `Double` return type; **no grammar, range, case\n rule or error condition is stated there**).\n- Ifrah, *The Universal History of Numbers*, chapters on Roman numeration — the historical basis\n for the claim that no canonical grammar exists.\n- Handbook evidence record `EV-STRUCT-0009` (subjects include `FUNC.ARABIC`) — a structural\n comparison is on record with a per-surface witness; the count is a group total and carries a\n reader warning against per-surface attribution.\n- Handbook projections `data/functions/FUNC.ARABIC.json` (arity, `Custom` coercion-lift and kernel\n signature) and `data/presence/FUNC.ARABIC.json` (implementing module; the `BUG-FUNC-028` defect\n stream).\n- Handbook [The value universe](../model/01-value-universe.md) (text as UTF-16 code units; the\n `Empty` versus `Missing` distinction) and\n [Coercion and lifting](../model/02-coercion-and-lifting.md).\n\n", "version-differences": "No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.", "what-it-does": "\n`ARABIC(text)` reads a Roman numeral and returns its value as a number.\n\nRoman numeration is **non-positional**. A digit's contribution does not depend on where it sits in\na place-value column; it depends on the digit itself and on whether a larger digit follows it. The\nseven symbols and their values:\n\n| Symbol | `I` | `V` | `X` | `L` | `C` | `D` | `M` |\n|---|---|---|---|---|---|---|---|\n| Value | 1 | 5 | 10 | 50 | 100 | 500 | 1000 |\n\nThe standard evaluation rule is one pass, right to left or left to right, with a single\ncomparison:\n\n value(s) = sum over i of +v(i) if v(i) >= v(i+1)\n -v(i) if v(i) < v(i+1)\n\nwhere `v(i)` is the value of the *i*-th symbol and the last symbol always contributes positively.\nThat rule reads `IX` as `-1 + 10 = 9` and `XI` as `10 + 1 = 11`. It is the rule every\nimplementation uses, and it is far more permissive than the notation people think of as Roman: it\nhappily evaluates `IIX` as 8, `VV` as 10, and `IM` as 999, none of which is classical usage.\n\n**This is the mathematically important fact about `ARABIC`**: the map from strings to numbers is\nmany-to-one and its domain is a matter of choice, not of arithmetic. There is no canonical Roman\ngrammar — the subtractive forms `IV`, `IX`, `XL`, `XC`, `CD`, `CM` were never universal in Roman\npractice, and modern \"rules\" are a nineteenth-century tidying. So a function that converts Roman to\ndecimal has to *decide* how permissive to be, and that decision is behaviour, not mathematics.\n\n`ARABIC` is therefore best understood as a parser with an undocumented grammar. What the grammar\naccepts is the whole content of this function, and none of it is documented on any page the\nHandbook has retrieved.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Default |\n|---|---|---|\n| `text` | The Roman numeral to convert. Required. | — |\n\nMicrosoft's Learn reference types the argument as **String** and describes it as \"the Roman numeral\nthat you want to convert\", and types the return as **Double**. That is the entirety of the\ndocumentation retrieved for this function: no grammar, no case rule, no length limit, no range, no\nsign handling, and no error condition.\n\n" }, "signature": { "display": "ARABIC(text)", "parameters": [ { "description": null, "name": "text", "optional": false, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 1, "min": 1 }, "category": "Math and trigonometry functions", "classification": { "arg_preparation_profile": "ValuesOnlyPreAdapter", "coercion_lift_profile": "Custom", "determinism_class": "Deterministic", "error_collapse_profile": "None", "fec_dependency_profile": "None", "host_interaction_class": "None", "kernel_signature_class": "Custom", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "RefOnly", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "Number written by a Roman numeral", "short_source": "dna-calc-own" }, "docs": { "english_description": "Converts a Roman number to Arabic, as a number", "microsoft_url": "https://support.microsoft.com/en-us/office/arabic-function-9a8da418-c17b-4ef9-a657-9370a30a674f" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "ARABIC" }, { "locale": "bg-BG", "name": "ARABIC" }, { "locale": "cs-CZ", "name": "ARABIC" }, { "locale": "da-DK", "name": "ARABISK" }, { "locale": "de-DE", "name": "ARABIC" }, { "locale": "el-GR", "name": "ARABIC" }, { "locale": "en-AU", "name": "ARABIC" }, { "locale": "en-GB", "name": "ARABIC" }, { "locale": "en-US", "name": "ARABIC" }, { "locale": "es-ES", "name": "NUMERO.ARABE" }, { "locale": "et-EE", "name": "ARABIC" }, { "locale": "fi-FI", "name": "ARABIA" }, { "locale": "fr-FR", "name": "ARABE" }, { "locale": "he-IL", "name": "ARABIC" }, { "locale": "hr-HR", "name": "ARABIC" }, { "locale": "hu-HU", "name": "ARAB" }, { "locale": "id-ID", "name": "ARABIC" }, { "locale": "it-IT", "name": "ARABIC" }, { "locale": "ja-JP", "name": "ARABIC" }, { "locale": "ko-KR", "name": "ARABIC" }, { "locale": "lt-LT", "name": "ARABIC" }, { "locale": "lv-LV", "name": "ARABIC" }, { "locale": "nb-NO", "name": "ARABIC" }, { "locale": "nl-NL", "name": "ARABIC" }, { "locale": "pl-PL", "name": "ARABSKIE" }, { "locale": "pt-BR", "name": "ÁRABE" }, { "locale": "pt-PT", "name": "ÁRABE" }, { "locale": "ro-RO", "name": "ARABIC" }, { "locale": "ru-RU", "name": "АРАБСКОЕ" }, { "locale": "sk-SK", "name": "ARABIC" }, { "locale": "sl-SI", "name": "ARABŠČINA" }, { "locale": "sr-Latn-RS", "name": "ARAPSKI" }, { "locale": "sv-SE", "name": "ARABIC" }, { "locale": "th-TH", "name": "ARABIC" }, { "locale": "tr-TR", "name": "ARAP" }, { "locale": "uk-UA", "name": "ARABIC" }, { "locale": "vi-VN", "name": "ARABIC" }, { "locale": "zh-CN", "name": "ARABIC" }, { "locale": "zh-HK", "name": "ARABIC" }, { "locale": "zh-TW", "name": "ARABIC" } ], "signature": { "display": "ARABIC(text)", "parameters": [ { "description": null, "name": "text", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "ARABIC", "version_marker": null, "xlcall": { "code": "583", "symbol": "xlfArabic" } }, "microsoft": "https://support.microsoft.com/en-us/office/arabic-function-9a8da418-c17b-4ef9-a657-9370a30a674f" }, "try_it": { "formula": "=ARABIC(\"MMXXVI\")" }, "url": "https://handbook.dnacalc.com/functions/ARABIC.html", "variants": [], "versions": [] }