{
  "category": "Math and trigonometry functions",
  "display_name": "DECIMAL",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.DECIMAL",
  "implementation_state": {
    "answer_bank": {
      "excel_builds": [
        "20430"
      ],
      "larger_numeric": 0,
      "last_bit": 0,
      "matched": 1230,
      "other_mismatch": 0,
      "refused": 0,
      "rows": 1230,
      "unread": 0,
      "worst_ulp": 0
    },
    "detail": "Recorded: 1,230 in the answer bank and 4 workbook cells.",
    "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87",
    "in_catalogue": true,
    "state": "matches",
    "state_label": "Matches every recorded Excel answer",
    "summary": "Matches all 1,234 recorded answers",
    "workbook_corpus": {
      "cells": 4,
      "matched": 4
    }
  },
  "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#L188-L192",
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/decimal_fn.rs#L3-L9",
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/decimal_fn.rs#L11-L36"
      ],
      "repository": "https://github.com/DnaCalc/DnaCalc",
      "shared_code": [],
      "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/math.rs#L188-L192",
      "state": "matches",
      "suite": null,
      "summary": "Matches all 1,234 recorded answers"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.DECIMAL.json",
  "name": "DECIMAL",
  "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- **`BASE`** — the documented inverse: `BASE` writes a number as a digit string in a given\n  radix, `DECIMAL` reads one back. `DECIMAL(BASE(n, b), b) = n` is the round trip, and it is\n  the natural metamorphic test for both surfaces.\n- **`BIN2DEC`, `OCT2DEC`, `HEX2DEC`** — the fixed-radix predecessors from the Analysis\n  ToolPak, for bases 2, 8 and 16. They differ from `DECIMAL` in a way that matters: they\n  interpret their input as a **two's-complement** value of fixed width, so a leading digit can\n  mean a negative number, while `DECIMAL` is documented over non-negative values only. Replacing\n  `HEX2DEC` with `DECIMAL(…, 16)` silently changes the meaning of every input whose top bit is\n  set.\n- **`DEC2BIN`, `DEC2OCT`, `DEC2HEX`** — the corresponding writers, and `BASE`'s predecessors.\n- **`VALUE`, `NUMBERVALUE`** — the base-10 text-to-number parsers, locale-aware where `DECIMAL`\n  is not documented to be.\n- **`ARABIC`** — the other non-positional numeral parser on the worksheet surface, and\n  `DECIMAL`'s co-subject in the evidence record attached to this page.\n\n\n",
    "how-to-implement": "\n### Numerical notes\n\n\nRadix conversion is exact arithmetic dressed as parsing, and its accuracy story is short but\nnot empty.\n\n**Within the documented range, the answer is exact and there is no excuse for anything less.**\nEvery integer below `2^53` is a binary64 value, so Horner's rule over the digits —\n`acc ← acc·b + d` — computes the value with no rounding at all, provided each intermediate stays\nbelow `2^53`. Since the intermediates of a correct parse are prefixes of the final value, they\ndo. Knuth TAOCP volume 2 §4.4 is the standard treatment.\n\n**Outside it, the choices start to matter.** For a numeral whose value exceeds `2^53`,\nHorner-in-binary64 rounds at every step, and the accumulated result can differ from the\ncorrectly rounded value of the numeral by several ulp. The correct approach — the one a\n`math-correct` flavour would take — accumulates in an exact integer type and rounds **once** at\nthe end. Microsoft's page documents that precision may be lost without saying which discipline\napplies, so the difference between \"rounds once\" and \"rounds every step\" is unspecified and\nobservable. It is the sharpest numerical question on this page.\n\n**Powers of two are the special case.** When the radix is 2, 4, 8, 16 or 32, digits map onto\nfixed bit-fields and the conversion is a shift-and-or with no multiplication at all. An\nimplementation that special-cases them is exact for longer and faster; one that does not is\nneither. Whether Excel distinguishes them is unchecked, and the discriminating probe is a long\nnumeral in base 16 against the same value in base 10.\n\n**Length versus value.** The documented 255-character limit and the documented `2^53` value\nlimit are not the same constraint: a 255-character base-2 numeral of all zeros followed by a one\nhas a tiny value, and a 12-character base-36 numeral exceeds `2^53`. Which limit is checked\nfirst, and whether the length limit is on the text or on its significant digits, is not\ndocumented.\n\n\n",
    "quirks": "\n### Result and edge cases\n\n\nReturns `Number`.\n\n- **Empty text** — not documented. An empty numeral has no value; whether Excel returns `0` or\n  an error is unchecked.\n- **Leading and trailing spaces** — not documented.\n- **Digits out of range for the radix** — e.g. `DECIMAL(\"2\", 2)`, where `2` is not a binary\n  digit. Microsoft's page says arguments outside the stated constraints may return `#NUM!` or\n  `#VALUE!`, without saying which applies here.\n- **Non-integer radix** — the page documents *radix* as an integer; whether a fractional radix\n  truncates or errors is not stated.\n- **Values at and above `2^53`** — documented as possible precision loss rather than as an\n  error. Note the asymmetry with the *lower* bound, which is documented as a constraint: a\n  negative value is out of range, an over-large value is merely imprecise.\n- **A leading minus sign** — the documented range starts at `0`, so signed input is outside the\n  documented domain. What happens is not stated.\n\nEvery one of these is a boundary the documentation leaves open, and together they are why this\npage's probe list is longer than its behaviour section.\n\n\n\n### Errors\n\n\nMicrosoft's page states the error conditions **jointly and loosely**: arguments outside the\nstated constraints may return `#NUM!` or `#VALUE!`. It does not map individual violations to\nindividual error values.\n\n| Error | Condition (as documented, loosely) |\n|---|---|\n| `#NUM!` or `#VALUE!` | an argument is outside its documented constraints |\n\nThat is an unusually weak error specification for a function with five separate documented\nconstraints, and it is recorded here as a documentation gap rather than paraphrased into a\nprecision the source does not have.\n\n\n",
    "sources": "- Handbook evidence record `EV-STRUCT-0009` — the structural sweep naming `ARABIC` and\n  `DECIMAL`, with no per-surface split and an explicit prohibition on deriving one. Read its\n  reader warning.\n- Knuth, *TAOCP* volume 2 §4.4 — radix conversion.\n- Muller et al., *Handbook of Floating-Point Arithmetic* — exactness of integer conversion in\n  binary64.\n- Handbook, [Coercion and lifting](../model/02-coercion-and-lifting.md) and\n  [The value universe](../model/01-value-universe.md).\n- Handbook projections `data/functions/FUNC.DECIMAL.json` (the `Custom` coercion and kernel\n  classifications) and `data/presence/FUNC.DECIMAL.json` (implementing module and the open\n  conversion/coercion defect stream).\n\n",
    "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.\n\n| Excel 16.0 build | Platform and CPU | Captured inputs |\n|---|---|---:|\n| 20430 | Windows, 64-bit, CPU not recorded | 1,230 |\n\nThe 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.\n\n[Recorded environments and comparison details](https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.DECIMAL.json).",
    "what-it-does": "\n`DECIMAL(text, radix)` reads *text* as a numeral written in base *radix* and returns its value\nas a worksheet number. It is a parser, not an arithmetic function — the \"decimal\" in the name\nrefers to the output being an ordinary number rather than a digit string, not to base 10 having\nany special role in the computation.\n\nThe definition is positional notation. For a digit string `d_{n-1} … d_1 d_0` in base `b`:\n\n    value = Σ_{i=0}^{n-1} d_i · b^i\n\nwith the digit alphabet `0`–`9` then `A`–`Z` supplying values `0`–`35`, and the reading\ncase-insensitive.\n\n| Property | Statement |\n|---|---|\n| Radix range (documented) | `2 ≤ radix ≤ 36` |\n| Text length (documented) | at most 255 characters |\n| Value range (documented) | the text must resolve to a number `≥ 0` and `< 2^53` |\n| Digit alphabet | `0`–`9`, then `A`–`Z`, case-insensitive |\n| Result kind | `Number` |\n| Exactness | every value below `2^53` is exactly representable, so the conversion is exact within the documented range |\n| Inverse | `BASE(number, radix)` — the digit-string producer |\n\nThe documented value bound is the interesting one: `2^53` is exactly the point at which binary64\nstops being able to represent every integer. Microsoft's page draws the boundary there and adds\nthat text resolving to values above it may lose precision. That is not a limitation of radix\nconversion; it is a limitation of the result type, stated honestly on the documentation page.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Constraint (as documented) |\n|---|---|---|\n| `text` | The numeral to read. Required. | at most 255 characters; alphanumeric characters valid for the radix |\n| `radix` | The base to read it in. Required. | an integer, at least 2 and at most 36 |\n\nBoth slots take the shared coercion rules, with the wrinkle that the first slot is a *text*\nslot that will often receive a number: `DECIMAL(1010, 2)` passes a number where a numeral was\nasked for, and the number must be rendered to text before it can be parsed. Which rendering —\ngeneral format, full precision, locale-dependent — is not stated on Microsoft's page, and the\nHandbook has not checked. That is a real question, not a pedantic one: a large numeric first\nargument could render in scientific notation and then contain characters that are not digits in\nany radix.\n\n"
  },
  "signature": {
    "display": "DECIMAL(text, radix)",
    "parameters": [
      {
        "description": null,
        "name": "text",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "radix",
        "optional": false,
        "repeats": false
      }
    ],
    "trailing_repeats": false
  },
  "sources": {
    "metadata": {
      "admission": {
        "label": "implemented",
        "reason": null
      },
      "arity": {
        "max": 2,
        "min": 2
      },
      "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": "Value of a number written as text in a given base",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": "Converts a text representation of a number in a given base into a decimal number",
        "microsoft_url": "https://support.microsoft.com/en-us/office/decimal-function-ee554665-6176-46ef-82de-0a283658da2e"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [
        {
          "locale": "ar-SA",
          "name": "DECIMAL"
        },
        {
          "locale": "bg-BG",
          "name": "DECIMAL"
        },
        {
          "locale": "cs-CZ",
          "name": "DECIMAL"
        },
        {
          "locale": "da-DK",
          "name": "DECIMAL"
        },
        {
          "locale": "de-DE",
          "name": "DECIMAL"
        },
        {
          "locale": "el-GR",
          "name": "DECIMAL"
        },
        {
          "locale": "en-AU",
          "name": "DECIMAL"
        },
        {
          "locale": "en-GB",
          "name": "DECIMAL"
        },
        {
          "locale": "en-US",
          "name": "DECIMAL"
        },
        {
          "locale": "es-ES",
          "name": "CONV.DECIMAL"
        },
        {
          "locale": "et-EE",
          "name": "DECIMAL"
        },
        {
          "locale": "fi-FI",
          "name": "DESIMAALI"
        },
        {
          "locale": "fr-FR",
          "name": "DECIMAL*"
        },
        {
          "locale": "he-IL",
          "name": "DECIMAL"
        },
        {
          "locale": "hr-HR",
          "name": "DECIMAL"
        },
        {
          "locale": "hu-HU",
          "name": "TIZEDES"
        },
        {
          "locale": "id-ID",
          "name": "DECIMAL"
        },
        {
          "locale": "it-IT",
          "name": "DECIMAL"
        },
        {
          "locale": "ja-JP",
          "name": "DECIMAL"
        },
        {
          "locale": "ko-KR",
          "name": "DECIMAL"
        },
        {
          "locale": "lt-LT",
          "name": "DECIMAL"
        },
        {
          "locale": "lv-LV",
          "name": "DECIMAL"
        },
        {
          "locale": "nb-NO",
          "name": "DECIMAL"
        },
        {
          "locale": "nl-NL",
          "name": "DECIMAAL"
        },
        {
          "locale": "pl-PL",
          "name": "DZIESIĘTNA"
        },
        {
          "locale": "pt-BR",
          "name": "DECIMAL"
        },
        {
          "locale": "pt-PT",
          "name": "DECIMAL"
        },
        {
          "locale": "ro-RO",
          "name": "DECIMAL"
        },
        {
          "locale": "ru-RU",
          "name": "ДЕС"
        },
        {
          "locale": "sk-SK",
          "name": "DECIMAL"
        },
        {
          "locale": "sl-SI",
          "name": "DECIMAL"
        },
        {
          "locale": "sr-Latn-RS",
          "name": "DECIMALNI"
        },
        {
          "locale": "sv-SE",
          "name": "DECIMAL"
        },
        {
          "locale": "th-TH",
          "name": "DECIMAL"
        },
        {
          "locale": "tr-TR",
          "name": "ONDALIK"
        },
        {
          "locale": "uk-UA",
          "name": "DECIMAL"
        },
        {
          "locale": "vi-VN",
          "name": "DECIMAL"
        },
        {
          "locale": "zh-CN",
          "name": "DECIMAL"
        },
        {
          "locale": "zh-HK",
          "name": "DECIMAL"
        },
        {
          "locale": "zh-TW",
          "name": "DECIMAL"
        }
      ],
      "signature": {
        "display": "DECIMAL(text, radix)",
        "parameters": [
          {
            "description": null,
            "name": "text",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "radix",
            "optional": false,
            "repeats": false
          }
        ],
        "trailing_repeats": false
      },
      "surface_name": "DECIMAL",
      "version_marker": null,
      "xlcall": {
        "code": "572",
        "symbol": "xlfDecimal"
      }
    },
    "microsoft": "https://support.microsoft.com/en-us/office/decimal-function-ee554665-6176-46ef-82de-0a283658da2e"
  },
  "try_it": {
    "formula": "=DECIMAL(\"FF\",16)"
  },
  "url": "https://handbook.dnacalc.com/functions/DECIMAL.html",
  "variants": [],
  "versions": [
    {
      "behaviour": "1,230 captured inputs are indexed for this environment. Capture dates: 2026-09-29 to 2026-09-29. This is a reading count, not a comparison with another build.",
      "excel_build": "16.0 build 20430",
      "platform": "Windows, 64-bit, CPU not recorded",
      "sources": [
        "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.DECIMAL.json"
      ]
    }
  ]
}