{ "category": "Text functions", "display_name": "NUMBERVALUE", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.NUMBERVALUE", "implementation_state": { "answer_bank": null, "detail": "Recorded: 8 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 8 recorded answers", "workbook_corpus": { "cells": 8, "matched": 8 } }, "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/text_format.rs#L925-L925", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L355-L414", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L416-L421", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/text_more.rs#L512-L601", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/text_more.rs#L603-L609" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/text_format::read_value", "catalogue/text_format::value", "catalogue/text_format::profile", "catalogue/text_format::rendered", "catalogue/text_format::text", "catalogue/text_format::given", "decimal::low32", "decimal::Natural::zero", "decimal::Natural::from_u64", "decimal::Natural::pow10", "decimal::Natural::normalize", "decimal::Natural::is_zero", "decimal::Natural::mul_add_small", "decimal::Natural::times_pow10", "decimal::Natural::times_pow5", "decimal::Natural::times_pow2", "decimal::ExactDecimal::read", "decimal::ExactDecimal::binary", "format/datetime::has_invalid_exponent", "format/datetime::looks_like_datetime_format", "format/datetime::without_subseconds", "format/datetime::render_with_datetime_tokens", "format/datetime::tokenize_datetime_format", "format/datetime::elapsed_token_at", "format/datetime::classify_minute_tokens", "format/datetime::token_kind", "format/datetime::is_time_neighbor", "format/datetime::push_literal", "format/datetime::render_datetime_literal", "format/datetime::format_elapsed", "format/datetime::TimeParts::from_serial", "format::measured_host", "format::currency_literal", "format::digits", "format::fifteen", "format::split", "format::grouped", "format::general", "format::significant", "format::sections", "format::bracket", "format::is_condition", "format::is_elapsed", "format::condition_holds", "format::condition_of", "format::strip_tokens", "format::choose", "format::items", "format::numeric", "format::literal_text", "format::integer_part", "format::fraction_part", "format::scientific", "format::fraction_code", "format::FractionCode::render", "format::mixed_fraction_under_space_grouping", "format::convergent", "format::text_declared_date_locale", "format::text", "format::text_of_text", "format/names::month_name", "format/names::weekday_name", "format/names::locale_names", "locale::LocaleId::from_bcp47_language_tag", "locale::LocaleId::from_excel_lcid", "locale::short_date_order", "locale::short_date_pattern", "locale::currency_placement", "locale::currency_spacing", "locale::currency_negative_pattern", "locale::format_profile", "locale::days_from_civil", "locale::civil_from_days", "locale::ymd_from_excel_serial", "number_text::decimal", "number_text::first_precision", "number_text::near_tie", "number_text::first_rounding", "number_text::rounded", "number_text::increment", "number_text::ascii", "ported/date_kernels::days_from_civil", "ported/date_kernels::civil_from_days", "ported/date_kernels::serial_unbounded_1900", "ported/date_kernels::ymd_1900", "ported/date_kernels::is_leap", "ported/date_kernels::days_in_month", "ported/date_kernels::whole_serial", "ported/date_kernels::whole", "ported/date_kernels::weekday_sunday_one_based", "ported/date_kernels::remap_weekday", "ported/date_kernels::weekday_of", "ported/date_kernels::weekday", "ported/text_kernels::text", "ported/text_kernels::text_from_str", "ported/text_kernels::date_integer_floor", "ported/text_kernels::push_singleton_or_original", "ported/text_kernels::push_upper", "ported/text_kernels::upper", "value_text::measured_host_reader", "value_text::measured_space", "value_text::read", "value_text::number", "value_text::decimal", "value_text::fraction", "value_text::tokens", "value_text::month_named", "value_text::time_at", "value_text::full_year", "value_text::valid_day", "value_text::this_year", "value_text::serial_1900", "value_text::date_of", "value_text::date_time" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L925-L925", "state": "matches", "suite": null, "summary": "Matches all 8 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.NUMBERVALUE.json", "name": "NUMBERVALUE", "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- **`VALUE`** is the locale-following text-to-number conversion. The pair is not\n legacy/modern — `VALUE` is not superseded and Microsoft continues to document both. They\n differ in one axis only: where the separator characters come from. Reach for `NUMBERVALUE`\n whenever the text's format is a property of the *data* rather than of the *machine* — parsed\n files, web sources, fixed feed formats.\n- **`TEXT`** is the inverse direction and has the mirror-image locale problem: `TEXT` takes a\n format string that is itself interpreted in a language. There is no `TEXT` counterpart to\n `NUMBERVALUE`'s explicit separators; see [TEXT](FUNC.TEXT.md).\n- **Implicit coercion** — what happens when text lands in a numeric argument slot — is a third,\n separate rule set, described in\n [Coercion and lifting](../model/02-coercion-and-lifting.md). It is neither `VALUE` nor\n `NUMBERVALUE`, and the chapter is explicit that Excel's full text-to-number recognizer is\n broader than the pinned baseline.\n- `DOLLAR` and `FIXED` produce formatted numeric text that `NUMBERVALUE` can often read back,\n given the right separators.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\nThe locale dependence does not disappear when the separators are supplied — it only shrinks.\nCurrency symbols, sign conventions and non-ASCII digits are not covered by the two separator\narguments, and Microsoft's page does not say what the parser does with them. An implementation\nhas to decide, and should record the decision as a decision.\n\nCumulative percent handling has to be applied after the numeric parse, not as a prefix scan,\nand each `%` divides once. Implementations that treat `%` as a flag rather than a count will\nbe right on `\"9%\"` and wrong on `\"9%%\"`.\n\nThe \"only the first character is used\" rule for separators means the separator arguments\ncannot be validated by length. They are validated by comparison — the two must differ — and\nthat comparison is on the first characters, not the whole strings.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number`.\n\nDocumented boundary behaviours:\n\n- **Empty `text` returns 0**, not an error and not an empty result. This is a real difference\n from `VALUE`, which does not treat the empty string as zero.\n- Whitespace-only `text` follows from the ignore-whitespace rule and the empty-string rule,\n though Microsoft states the two rules separately rather than combining them.\n\nEmpty cells, missing arguments and incoming error values follow the shared call model; see\n[Coercion and lifting](../model/02-coercion-and-lifting.md). Nothing here is specific to\n`NUMBERVALUE` except the empty-string-is-zero rule above, which is a function-level decision\nrather than an engine one.\n\n\n### Errors\n\n\nAs documented on Microsoft's `NUMBERVALUE` page:\n\n| Error | Condition |\n|---|---|\n| `#VALUE!` | `decimal_separator` and `group_separator` are the same character. |\n| `#VALUE!` | A group separator occurs after the decimal separator in `text`. |\n| `#VALUE!` | Any argument is not valid — including `text` that does not parse under the given separators. |\n\nThe Handbook has not verified this list against Excel, and in particular has not established\nwhether \"not valid\" covers cases such as an empty-string separator argument or a separator\nthat is a digit.\n\n\n", "sources": "\n- Microsoft, \"NUMBERVALUE function\" —\n \n (signature, separator defaults, first-character rule, whitespace rule, cumulative percent\n rule, empty-text-is-zero, and the documented error conditions).\n- Handbook, [Coercion and lifting](../model/02-coercion-and-lifting.md) — the implicit\n text-to-number rules, and the explicit note that Excel's full recognizer is broader than the\n pinned baseline.\n- Handbook, [The value universe](../model/01-value-universe.md) — value kinds and error codes.\n- Handbook projections `data/functions/FUNC.NUMBERVALUE.json` (interface classification\n `locale_default_profiled_parse`) and `data/presence/FUNC.NUMBERVALUE.json` (implementing\n module and the `BUG-FUNC-028` defect stream).\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`NUMBERVALUE(text, [decimal_separator], [group_separator])` parses `text` as a number using\nthe two separator characters you name, instead of the two the host locale would have chosen.\n\nThat is the entire point of the function, and it is worth stating sharply: `VALUE` asks the\nmachine what a decimal point looks like; `NUMBERVALUE` lets the formula say so. A workbook\nthat reads `\"1.234,56\"` with `NUMBERVALUE(A1, \",\", \".\")` gets 1234.56 on every machine on\nearth. The same string through `VALUE` gets a different answer, or an error, depending on\nwhere the workbook is opened.\n\nThe parse Microsoft documents is not a plain decimal scan. Three rules make it its own grammar:\n\n1. **Whitespace is ignored anywhere in `text`**, including in the middle. `\" 3 000 \"` parses\n as 3000 even without a group separator.\n2. **Group separators are cosmetic before the decimal separator and fatal after it.** They may\n appear anywhere in the integer part — Microsoft's page does not require them to be in\n groups of three — but a group separator occurring after the decimal separator is an error.\n3. **Percent signs are trailing and cumulative.** A `%` in `text` divides the result by 100,\n and multiple percent signs compound: `\"9%%\"` is 9 / 100 / 100 = 0.0009.\n\nThe third rule is the one that surprises people. It is not a typo tolerance; it is arithmetic.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Default |\n|---|---|---|\n| `text` | The string to parse. Required. | — |\n| `decimal_separator` | The character separating the integer and fractional parts. | The host locale's decimal separator |\n| `group_separator` | The character separating groups within the integer part. | The host locale's group separator |\n\nTwo documented details about the separator arguments:\n\n- **Only the first character of each is used.** Passing `\",.\"` as a separator is not an error\n and not a two-character separator; it is `,`.\n\n\nIf you are using `NUMBERVALUE` for the reason it was added, supply both separators.\n\n\n" }, "signature": { "display": "NUMBERVALUE(text, [decimal_separator], [group_separator])", "parameters": [ { "description": null, "name": "text", "optional": false, "repeats": false }, { "description": null, "name": "decimal_separator", "optional": true, "repeats": false }, { "description": null, "name": "group_separator", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 3, "min": 1 }, "category": "Text functions", "classification": { "arg_preparation_profile": "ValuesOnlyPreAdapter", "coercion_lift_profile": "Custom", "determinism_class": "Deterministic", "error_collapse_profile": "None", "fec_dependency_profile": "LocaleProfile", "host_interaction_class": "None", "kernel_signature_class": "Custom", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "LocaleProfile", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "Number read from text with the given decimal and group separators", "short_source": "dna-calc-own" }, "docs": { "english_description": "Converts text to number in a locale-independent manner", "microsoft_url": "https://support.microsoft.com/en-us/office/numbervalue-function-1b05c8cf-2bfa-4437-af70-596c7ea7d879" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "NUMBERVALUE" }, { "locale": "bg-BG", "name": "NUMBERVALUE" }, { "locale": "cs-CZ", "name": "NUMBERVALUE" }, { "locale": "da-DK", "name": "TALVÆRDI" }, { "locale": "de-DE", "name": "NUMBERVALUE" }, { "locale": "el-GR", "name": "NUMBERVALUE" }, { "locale": "en-AU", "name": "NUMBERVALUE" }, { "locale": "en-GB", "name": "NUMBERVALUE" }, { "locale": "en-US", "name": "NUMBERVALUE" }, { "locale": "es-ES", "name": "VALOR.NUMERO" }, { "locale": "et-EE", "name": "NUMBERVALUE" }, { "locale": "fi-FI", "name": "NROARVO" }, { "locale": "fr-FR", "name": "VALEURNOMBRE*" }, { "locale": "he-IL", "name": "NUMBERVALUE" }, { "locale": "hr-HR", "name": "NUMBERVALUE" }, { "locale": "hu-HU", "name": "SZÁMÉRTÉK" }, { "locale": "id-ID", "name": "NUMBERVALUE" }, { "locale": "it-IT", "name": "NUMBERVALUE" }, { "locale": "ja-JP", "name": "NUMBERVALUE" }, { "locale": "ko-KR", "name": "NUMBERVALUE" }, { "locale": "lt-LT", "name": "NUMBERVALUE" }, { "locale": "lv-LV", "name": "NUMBERVALUE" }, { "locale": "nb-NO", "name": "NUMBERVALUE" }, { "locale": "nl-NL", "name": "NUMERIEKE.WAARDE" }, { "locale": "pl-PL", "name": "WARTOŚĆ.LICZBOWA" }, { "locale": "pt-BR", "name": "NUMBERVALUE" }, { "locale": "pt-PT", "name": "VALOR.NÚMERO" }, { "locale": "ro-RO", "name": "NUMBERVALUE" }, { "locale": "ru-RU", "name": "ЧЗНАЧ" }, { "locale": "sk-SK", "name": "NUMBERVALUE" }, { "locale": "sl-SI", "name": "NUMBERVALUE" }, { "locale": "sr-Latn-RS", "name": "NUMBERVALUE" }, { "locale": "sv-SE", "name": "TALVÄRDE" }, { "locale": "th-TH", "name": "NUMBERVALUE" }, { "locale": "tr-TR", "name": "SAYIDEĞERİ" }, { "locale": "uk-UA", "name": "NUMBERVALUE" }, { "locale": "vi-VN", "name": "NUMBERVALUE" }, { "locale": "zh-CN", "name": "NUMBERVALUE" }, { "locale": "zh-HK", "name": "NUMBERVALUE" }, { "locale": "zh-TW", "name": "NUMBERVALUE" } ], "signature": { "display": "NUMBERVALUE(text, [decimal_separator], [group_separator])", "parameters": [ { "description": null, "name": "text", "optional": false, "repeats": false }, { "description": null, "name": "decimal_separator", "optional": true, "repeats": false }, { "description": null, "name": "group_separator", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "NUMBERVALUE", "version_marker": null, "xlcall": { "code": "585", "symbol": "xlfNumbervalue" } }, "microsoft": "https://support.microsoft.com/en-us/office/numbervalue-function-1b05c8cf-2bfa-4437-af70-596c7ea7d879" }, "try_it": { "formula": "=NUMBERVALUE(\"1.234,5\",\",\",\".\")" }, "url": "https://handbook.dnacalc.com/functions/NUMBERVALUE.html", "variants": [], "versions": [] }