{ "category": "Text functions", "display_name": "DOLLAR", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.DOLLAR", "implementation_state": { "answer_bank": null, "detail": "Recorded: 7 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 7 recorded answers", "workbook_corpus": { "cells": 7, "matched": 7 } }, "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#L924-L924", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L166-L172", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/format/mod.rs#L172-L196" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/text_format::profile", "catalogue/text_format::rendered", "catalogue/text_format::text", "catalogue/text_format::places", "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::fixed", "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::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" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L924-L924", "state": "matches", "suite": null, "summary": "Matches all 7 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.DOLLAR.json", "name": "DOLLAR", "notes": [ { "basis": "Four recorded readings of the same value.", "documentation": null, "evidence": [ { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheets qt169 to qt172", "note": "recorded readings", "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-text-controls.capture.json", "repository": "DnaCalc" }, { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "recorded_dollar_retains_a_negative_sign_after_rounding", "note": "DOLLAR readings pinned", "path": "apps/dna-onecalc/tests/acceptance.rs", "repository": "DnaCalc" } ], "functions": [ "FUNC.DOLLAR", "FUNC.FIXED", "FUNC.TEXT" ], "inferred": null, "kind": "quirk", "note_id": "FN-DOLLAR-001", "open": [], "recorded_on": "2026-11-04", "repros": [ { "call": "=DOLLAR(-0.005,0)", "correct": null, "excel": { "bits": null, "display": "-R0", "kind": "text" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet qt172, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-text-controls.capture.json", "repository": "DnaCalc" } }, { "call": "=FIXED(-0.005,0)", "correct": null, "excel": { "bits": null, "display": "0", "kind": "text" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet qt171, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-text-controls.capture.json", "repository": "DnaCalc" } }, { "call": "=TEXT(-0.005,0)", "correct": null, "excel": { "bits": null, "display": "0", "kind": "text" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet qt169, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-text-controls.capture.json", "repository": "DnaCalc" } }, { "call": "=TEXT(-0.005,\"0\")", "correct": null, "excel": { "bits": null, "display": "0", "kind": "text" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet qt170, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn4_questions/functions-fn4-text-controls.capture.json", "repository": "DnaCalc" } } ], "schema": "efh.function-note/v1", "statement": "-0.005 rounded to no decimals is zero. DOLLAR(-0.005,0) shows that as -R0 in en-ZA settings, keeping the sign of the input, while FIXED(-0.005,0), TEXT(-0.005,0) and TEXT(-0.005,\"0\") show 0.", "status": "measured", "title": "DOLLAR keeps the minus sign on an amount that rounds to zero; FIXED and TEXT drop it" } ], "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- **`FIXED`** is the near-twin: same rounding-then-render-as-text shape, no currency symbol,\n and an explicit `no_commas` switch that `DOLLAR` does not have. If you want grouped decimal\n text without a currency symbol, `FIXED` is the function. See [`FIXED`](FUNC.FIXED.md).\n- **`TEXT`** is the general case, taking an arbitrary format string; `DOLLAR` is `TEXT` with\n the currency format baked in and the format argument replaced by a decimals count. The two\n differ on an amount that rounds to zero: `DOLLAR` keeps the minus sign, `TEXT` drops it\n (FN-DOLLAR-001).\n- **`VALUE`** and **`NUMBERVALUE`** are the inverse direction, parsing formatted text back to a\n number — and `NUMBERVALUE` exists precisely because the inverse is locale-dependent too.\n- **`DOLLARDE` and `DOLLARFR`** share the word but not the job: they convert between fractional\n and decimal *notations* of a price and return numbers, not text. They are unrelated to this\n function despite the name collision, and readers confuse them regularly.\n- **Cell number formatting** is the non-function alternative the documentation recommends.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n1. **The locale profile is an input.** An implementation that hard-codes `$` and `,` is\n implementing the en-US instance of this function, not the function. State the profile as\n part of the result's scope, exactly as an Excel build and platform would be.\n2. **Round before rendering, once.** Rounding inside the formatter and rounding beforehand can\n differ at ties; the documented behaviour is a rounding step with an explicit decimals\n argument, so keep it explicit.\n3. **Negative `decimals` is a rounding magnitude, not a formatting flag**, and must still\n render with the format's decimal count — `FIXED(1234.567,-1)` is documented as `1,230`, and\n the analogous `DOLLAR` case is worth pinning by probe rather than by analogy.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Text`. That is the most consequential fact on this page, and Microsoft's\narticle puts a warning box around it: numbers stored as text are a common cause of spreadsheet\nerrors, because many functions ignore them — `SUM`, `AVERAGE`, `MIN`, `MAX`. The article's own\nadvice is to use the Format Cells dialog or the Accounting Number Format instead, which keeps\nthe value numeric.\n\nThe Handbook's coercion chapter explains why the trap is asymmetric and therefore hard to\nnotice: `SUM(DOLLAR(5))` as a **direct argument** coerces the text back to a number and gives\n5, while the same text sitting in a cell and reached through a **range scan** is ignored and\ncontributes 0. The same string, the same function, two answers, decided by how the value\narrived ([chapter 02](../model/02-coercion-and-lifting.md)).\n\nOther boundaries:\n\n- **Zero and negatives** render through the format's negative branch, which is parenthesised in\n the documented US format and is a leading minus in the recorded en-ZA settings, where\n `DOLLAR(-0.005,0)` is `-R0` (FN-DOLLAR-001). This is a locale-visible difference in the\n *shape* of the output, not only in the symbol.\n- **An empty cell** as `number` converts to zero under the ordinary numeric coercion, so\n `DOLLAR` of a blank is a rendering of zero rather than empty text.\n- **Very large magnitudes** must eventually exceed what a fixed-decimal rendering can express;\n where that boundary lies, and whether it produces an error, is not documented in the article.\n\n\n\n### Errors\n\n\nThe article does not enumerate error conditions. The reachable errors are the shared ones: an\nerror value in either argument propagates, and non-numeric text as `number` fails to-number\nconversion and surfaces `#VALUE!` under the shared coercion rules\n([chapter 02](../model/02-coercion-and-lifting.md)).\n\nBecause step 3 above involves a host facility, a fourth failure mode exists in principle — a\nlocale profile that cannot render the requested combination — with no documented\nworksheet-visible behaviour. Nothing about it has been observed here.\n\n\n", "sources": "- Microsoft, \"DOLLAR function\" —\n \n (the `$#,##0.00_);($#,##0.00)` format and its language-setting dependence; `decimals`\n defaulting to 2; negative `decimals` rounding to the left of the decimal point; the\n numbers-stored-as-text warning and the Format Cells recommendation). Retrieved for this page.\n- Handbook `content/model/02-coercion-and-lifting.md` (the direct-argument versus range-scan\n asymmetry that makes the text trap observable).\n- Handbook `content/evidence/records/EV-STRUCT-0009.json` — cited only to state that `DOLLAR`\n appears in that run's group member list and is not one of its subjects.\n\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`DOLLAR` rounds a number to a given number of decimal places and returns it as **text**,\nformatted as currency. Microsoft's article names the format applied: `$#,##0.00_);($#,##0.00)`\n— thousands separated, two decimals by default, negatives in parentheses — and states that the\ncurrency symbol actually used depends on your language settings.\n\nDecomposed, the operation is:\n\n1. convert the argument to a number by the ordinary rules;\n2. round it to `decimals` places — with negative `decimals` rounding to the left of the decimal\n point, so `-1` rounds to the nearest ten;\n3. render the rounded value through the locale's currency format, including symbol placement,\n grouping separator, decimal separator, and the negative-number convention, which follows the\n sign of the input even when the value rounds to zero (FN-DOLLAR-001);\n4. return the rendering as `Text`.\n\nStep 3 is not a pure function of the arguments, and no argument can override it.\n\n\n\n### Arguments\n\n\n`number` — required. The article describes it as a number, a reference to a cell containing a\nnumber, or a formula that evaluates to a number.\n\n`decimals` — optional, the number of digits to the right of the decimal point. **Defaults to 2\nwhen omitted**, per the article. A negative value rounds the number to the left of the decimal\npoint.\n\nTwo positions that get misread:\n\n- `decimals` controls *rounding*, not just display. `DOLLAR(1234.567, -1)` is not `1234.567`\n displayed coarsely; the value rendered has been rounded first, and the digits are gone.\n- Whether a non-integer `decimals` is truncated, rounded, or rejected is not stated in the\n article and has not been checked here.\n\n\n" }, "signature": { "display": "DOLLAR(number, [decimals])", "parameters": [ { "description": null, "name": "number", "optional": false, "repeats": false }, { "description": null, "name": "decimals", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 2, "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": "Composite", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "A number as currency text, rounded to a number of decimals", "short_source": "dna-calc-own" }, "docs": { "english_description": "Converts a number to text, using the $ (dollar) currency format", "microsoft_url": "https://support.microsoft.com/en-us/office/dollar-function-a6cd05d9-9740-4ad3-a469-8109d18ff611" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "DOLLAR" }, { "locale": "bg-BG", "name": "DOLLAR" }, { "locale": "cs-CZ", "name": "KČ" }, { "locale": "da-DK", "name": "KR" }, { "locale": "de-DE", "name": "DOLLAR" }, { "locale": "el-GR", "name": "DOLLAR" }, { "locale": "en-AU", "name": "DOLLAR" }, { "locale": "en-GB", "name": "DOLLAR" }, { "locale": "en-US", "name": "DOLLAR" }, { "locale": "es-ES", "name": "MONEDA" }, { "locale": "et-EE", "name": "DOLLAR" }, { "locale": "fi-FI", "name": "DOLLARI" }, { "locale": "fr-FR", "name": "DEVISE" }, { "locale": "he-IL", "name": "DOLLAR" }, { "locale": "hr-HR", "name": "DOLLAR" }, { "locale": "hu-HU", "name": "FORINT" }, { "locale": "id-ID", "name": "DOLLAR" }, { "locale": "it-IT", "name": "VALUTA" }, { "locale": "ja-JP", "name": "DOLLAR" }, { "locale": "ko-KR", "name": "DOLLAR" }, { "locale": "lt-LT", "name": "DOLLAR" }, { "locale": "lv-LV", "name": "DOLLAR" }, { "locale": "nb-NO", "name": "VALUTA" }, { "locale": "nl-NL", "name": "DOLLAR" }, { "locale": "pl-PL", "name": "KWOTA" }, { "locale": "pt-BR", "name": "DÓLAR" }, { "locale": "pt-PT", "name": "MOEDA" }, { "locale": "ro-RO", "name": "DOLLAR" }, { "locale": "ru-RU", "name": "РУБЛЬ" }, { "locale": "sk-SK", "name": "DOLLAR" }, { "locale": "sl-SI", "name": "DOLLAR" }, { "locale": "sr-Latn-RS", "name": "DOLLAR" }, { "locale": "sv-SE", "name": "VALUTA" }, { "locale": "th-TH", "name": "DOLLAR" }, { "locale": "tr-TR", "name": "LİRA" }, { "locale": "uk-UA", "name": "DOLLAR" }, { "locale": "vi-VN", "name": "DOLLAR" }, { "locale": "zh-CN", "name": "DOLLAR" }, { "locale": "zh-HK", "name": "DOLLAR" }, { "locale": "zh-TW", "name": "DOLLAR" } ], "signature": { "display": "DOLLAR(number, [decimals])", "parameters": [ { "description": null, "name": "number", "optional": false, "repeats": false }, { "description": null, "name": "decimals", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "DOLLAR", "version_marker": null, "xlcall": { "code": "13", "symbol": "xlfDollar" } }, "microsoft": "https://support.microsoft.com/en-us/office/dollar-function-a6cd05d9-9740-4ad3-a469-8109d18ff611" }, "try_it": { "formula": "=DOLLAR(1234.567, -1)" }, "url": "https://handbook.dnacalc.com/functions/DOLLAR.html", "variants": [], "versions": [ { "behaviour": "=DOLLAR(-0.005,0) returned -R0. Inputs were supplied through formula literals. These are controls from this environment, not a same-input comparison with another build.", "excel_build": "16.0.20527.20088", "observations": [ { "call": "=DOLLAR(-0.005,0)", "excel": { "bits": null, "display": "-R0", "kind": "text" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA" } ], "platform": "Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "sources": [ "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/3345a87/content/notes/FN-DOLLAR-001.json" ] } ] }