{ "category": "Text functions", "display_name": "VALUETOTEXT", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.VALUETOTEXT", "implementation_state": { "answer_bank": null, "detail": "Recorded: 6 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 6 recorded answers", "workbook_corpus": { "cells": 6, "matched": 6 } }, "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#L926-L926", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L327-L331" ], "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", "catalogue/text_format::binary_flag", "catalogue/text_format::value_text", "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", "ported/text_more::error_literal", "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#L926-L926", "state": "matches", "suite": null, "summary": "Matches all 6 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.VALUETOTEXT.json", "name": "VALUETOTEXT", "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- [`ARRAYTOTEXT`](FUNC.ARRAYTOTEXT.md) — the array counterpart, introduced alongside this function\n and sharing its `format` argument and its two registers. The pair splits by input shape: one\n value, or a grid.\n- `TEXT` — the *formatting* function, and the one readers confuse with this. `TEXT(x, fmt)` applies\n a number-format string you supply; `VALUETOTEXT` applies General formatting or a fixed strict\n grammar. `TEXT` cannot render a logical or an error usefully; `VALUETOTEXT` is defined for every\n value kind.\n- [`VALUE`](FUNC.VALUE.md) — despite the name, not the inverse. `VALUE` parses text into a number\n under locale rules; `VALUETOTEXT` renders any value as text. The nearest thing to an inverse of\n strict mode is the formula parser itself.\n- `T` — the old narrow relative: returns the text if the argument is text and the empty string\n otherwise. It is a filter, not a renderer.\n- `CONCAT` and `&` perform implicit to-text conversion by the general rule in\n [coercion and lifting](../model/02-coercion-and-lifting.md). That conversion is not guaranteed to\n agree with `VALUETOTEXT(x, 0)` for every kind, and where they differ is worth knowing.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n- **Do not write your own number renderer.** Concise mode is *defined* as General-format rendering,\n so it inherits every subtlety of that: the switch to scientific notation, the significant-digit\n budget, negative-zero handling. Reusing the engine's General formatter is the only way to stay\n consistent; a fresh `format!(\"{}\", x)` will diverge.\n- **Strict mode is a grammar, so write it as one.** Quoting, quote-escaping (doubling), the\n column separator, and the row separator are all part of a syntax that must reparse. The separator\n characters are locale-dependent in Excel's formula language, which means strict mode has a locale\n dependency that concise mode does not obviously share.\n- **The two modes must agree on nothing.** Do not implement strict as concise-plus-quotes; the\n number renderings can legitimately differ.\n- **Decide the error question explicitly** and test it: error as argument, error inside an array,\n and error as the `format` argument are three different paths.\n- **Validate `format` before rendering**, so that `VALUETOTEXT(error_value, 7)` has a defined\n precedence between the two failures.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Text`. Upstream's contract records the result as always a scalar text value.\n\n- **Errors are rendered, not propagated, in one specific sense — and propagated in another.**\n Microsoft's strict-mode description says errors are left unquoted, which implies they are\n rendered as their error text. Upstream's contract, by contrast, records error values in the first\n argument as *propagating* in both format modes. These two readings can both be true of different\n situations — an error inside an array being rendered, versus an error arriving as the whole\n scalar argument — but the Handbook has not established which applies where. This is a genuine\n open point and it is listed below rather than resolved by assertion.\n- **Numbers render as decimal strings** in concise mode, which means the General-format rendering,\n including its width-dependent behaviour in a cell. Whether `VALUETOTEXT`'s rendering depends on\n column width the way a cell's does is not established and is a probe worth running.\n- **The empty string is distinguishable in strict mode** (`\"\"`) and not in concise mode.\n- **An empty referenced cell** delivers `Empty`, distinct from an omitted argument; see\n [the value universe](../model/01-value-universe.md).\n- **Array arguments.** [`ARRAYTOTEXT`](FUNC.ARRAYTOTEXT.md) is the function for arrays. Whether\n `VALUETOTEXT` lifts elementwise over an array or delegates to array rendering is a shape question\n the Handbook has not settled; see the probes below.\n\n\n\n### Errors\n\nThe tension between error *propagation* and error *rendering* noted above is unresolved; treat the\nsecond row as upstream's reading rather than as settled Handbook fact.\n\n\n", "sources": "- Microsoft Support, VALUETOTEXT function —\n \n (retrieved for this page; source of the signature, the two format-mode descriptions, and the\n documented `#VALUE!` for a `format` outside `{0,1}`).\n- Handbook `content/model/01-value-universe.md` (value kinds, rich values and core projections,\n Empty versus Missing), `02-coercion-and-lifting.md` (to-text conversion, error propagation).\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`VALUETOTEXT` renders a value as text. Its reason to exist is that Excel has two different, equally\nlegitimate answers to \"what does this value look like as text\", and this function lets you ask for\neither one.\n\n**Concise (`format = 0`, the default)** returns the value as it would be *rendered in a cell with\nGeneral formatting*. This is the display register: it is what a human reading the sheet sees.\nMicrosoft's page states this equivalence explicitly, and it is the useful anchor — the output is\ndefined by reference to General-format rendering, not by an independent formatting rule.\n\n**Strict (`format = 1`)** returns the value in a form suitable for *embedding in a formula*.\nMicrosoft's page describes it as including escape characters and row delimiters, and generating a\nstring that can be parsed when entered into the formula bar. Text is quoted, with inner quotes\nescaped; Booleans, numbers and errors are left unquoted. This is the round-trip register: the point\nis that pasting the result into the formula bar reconstructs the value.\n\nThe distinction is exactly the distinction between showing a value and *denoting* it. `\"Hello\"`\ndisplays as `Hello` and denotes as `\"Hello\"`. The empty string displays as nothing and denotes as\n`\"\"` — and only the second of those two is recoverable.\n\nFor anyone building tooling on top of a workbook, that makes strict mode the interesting one: it is\nthe only ordinary worksheet function that produces a machine-reparseable rendering of an arbitrary\nvalue.\n\n\n\n### Arguments\n\n\n`VALUETOTEXT(value, [format])`\n\n| Argument | Required | Meaning (as documented by Microsoft) |\n|---|---|---|\n| `value` | yes | The value to return as text. |\n| `format` | no | `0` (default) concise; `1` strict. Anything else is documented as `#VALUE!`. |\n\nThe `format` argument is a mode selector with exactly two admitted values, and this is one of the\nfew places in the text family where an out-of-range option is documented as an error rather than\nbeing clamped or ignored. Do not pass `TRUE` expecting it to mean `1` without checking; whether the\nlogical coerces into the admitted set is not something this page asserts.\n\nThe first position takes *any* value, which is the function's whole point. It is not restricted to\nscalars in the sense of rejecting other kinds — it is the scalar renderer, and how it responds to\nan array argument is discussed below.\n\n\n" }, "signature": { "display": "VALUETOTEXT(value, [format])", "parameters": [ { "description": null, "name": "value", "optional": false, "repeats": false }, { "description": null, "name": "format", "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": "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": "Text for any value, in a concise or a formula-ready form", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns text from any specified value", "microsoft_url": "https://support.microsoft.com/en-us/office/valuetotext-function-5fff61a2-301a-4ab2-9ffa-0a5242a08fea" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "VALUETOTEXT" }, { "locale": "bg-BG", "name": "VALUETOTEXT" }, { "locale": "cs-CZ", "name": "VALUETOTEXT" }, { "locale": "da-DK", "name": "VÆRDITILTEKST" }, { "locale": "de-DE", "name": "VALUETOTEXT" }, { "locale": "el-GR", "name": "VALUETOTEXT" }, { "locale": "en-AU", "name": "VALUETOTEXT" }, { "locale": "en-GB", "name": "VALUETOTEXT" }, { "locale": "en-US", "name": "VALUETOTEXT" }, { "locale": "es-ES", "name": "VALORATEXTO" }, { "locale": "et-EE", "name": "VALUETOTEXT" }, { "locale": "fi-FI", "name": "ARVO.TEKSTIKSI" }, { "locale": "fr-FR", "name": "VALEUR.EN.TEXTE*" }, { "locale": "he-IL", "name": "VALUETOTEXT" }, { "locale": "hr-HR", "name": "VALUETOTEXT" }, { "locale": "hu-HU", "name": "ÉRTÉK.SZÖVEGGÉ" }, { "locale": "id-ID", "name": "VALUETOTEXT" }, { "locale": "it-IT", "name": "VALUETOTEXT" }, { "locale": "ja-JP", "name": "VALUETOTEXT" }, { "locale": "ko-KR", "name": "VALUETOTEXT" }, { "locale": "lt-LT", "name": "VALUETOTEXT" }, { "locale": "lv-LV", "name": "VALUETOTEXT" }, { "locale": "nb-NO", "name": "VALUETOTEXT" }, { "locale": "nl-NL", "name": "VALUETOTEXT" }, { "locale": "pl-PL", "name": "WARTOŚĆ.NA.TEKST" }, { "locale": "pt-BR", "name": "VALUETOTEXT" }, { "locale": "pt-PT", "name": "VALORPARATEXTO" }, { "locale": "ro-RO", "name": "VALUETOTEXT" }, { "locale": "ru-RU", "name": "ЗНАЧЕНИЕВТЕКСТ" }, { "locale": "sk-SK", "name": "VALUETOTEXT" }, { "locale": "sl-SI", "name": "VALUETOTEXT" }, { "locale": "sr-Latn-RS", "name": "VALUETOTEXT" }, { "locale": "sv-SE", "name": "VÄRDETILLTEXT" }, { "locale": "th-TH", "name": "VALUETOTEXT" }, { "locale": "tr-TR", "name": "DEĞERMETİN" }, { "locale": "uk-UA", "name": "VALUETOTEXT" }, { "locale": "vi-VN", "name": "VALUETOTEXT" }, { "locale": "zh-CN", "name": "VALUETOTEXT" }, { "locale": "zh-HK", "name": "VALUETOTEXT" }, { "locale": "zh-TW", "name": "VALUETOTEXT" } ], "signature": { "display": "VALUETOTEXT(value, [format])", "parameters": [ { "description": null, "name": "value", "optional": false, "repeats": false }, { "description": null, "name": "format", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "VALUETOTEXT", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/valuetotext-function-5fff61a2-301a-4ab2-9ffa-0a5242a08fea" }, "try_it": { "formula": "=VALUETOTEXT({1,2})" }, "url": "https://handbook.dnacalc.com/functions/VALUETOTEXT.html", "variants": [], "versions": [] }