{ "category": "Text functions", "display_name": "ARRAYTOTEXT", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.ARRAYTOTEXT", "implementation_state": { "answer_bank": null, "detail": "Recorded: 13 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 13 recorded answers", "workbook_corpus": { "cells": 13, "matched": 13 } }, "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#L927-L927", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L333-L353" ], "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#L927-L927", "state": "matches", "suite": null, "summary": "Matches all 13 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.ARRAYTOTEXT.json", "name": "ARRAYTOTEXT", "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- [`VALUETOTEXT`](FUNC.VALUETOTEXT.md) — the scalar counterpart, same `format` argument, same two\n registers. The pair splits on input shape.\n- [`TEXTSPLIT`](FUNC.TEXTSPLIT.md) — the closest thing to an inverse, and its sibling in the same\n upstream implementation module. `TEXTSPLIT` turns a delimited string into a grid; concise\n `ARRAYTOTEXT` turns a grid into a delimited string. They do not compose cleanly, because concise\n mode drops row structure and quotes nothing.\n- `TEXTJOIN` — the older and more controllable flattener: you choose the delimiter and whether to\n ignore empties, but you get no shape and no quoting. `TEXTJOIN(\", \", FALSE, range)` is the\n hand-rolled approximation of concise mode, and it differs at least in how it renders errors and\n formatted numbers.\n- `CONCAT` — flattens a range with no delimiter at all.\n- `TEXT` — formats a single number with a supplied format string; unrelated except by name\n confusion.\n- Strict mode is the function to reach for when you want to *see* what a dynamic-array formula\n actually produced, which makes it a debugging tool as much as a data function.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n- **Reuse the engine's General-format renderer**, exactly as for `VALUETOTEXT`. Concise mode is\n defined by reference to cell display, and the documented example shows that cell *formatting*\n reaches the output. An implementation that renders from the underlying double will disagree with\n Excel on every formatted cell.\n- **Strict mode's separators are formula-language separators**, which are locale-dependent in\n Excel. A strict rendering that is meant to reparse must use the separators of the locale it will\n be pasted into. This is a real portability hazard and deserves a test.\n- **Quote only what needs quoting.** The documented example quotes text and leaves Booleans,\n numbers and errors bare; a uniform-quoting implementation is visibly wrong.\n- **Escape inner quotes** by doubling, and test with a string that contains one.\n- **Traverse row-major** and do not assume square.\n- **Check the result against the text cap** and decide which failure mode you implement.\n- **Decide what an empty cell renders as** and write it down; it is the most likely silent\n divergence.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Text` — always a single scalar string, never an array. `ARRAYTOTEXT` is a\nreducer: it is the one place in this part of the catalogue where a grid goes in and a scalar comes\nout.\n\n- **The 32,767-code-unit cap is genuinely reachable.** Rendering a large range produces a long\n string, and strict mode adds quoting overhead. The cap and its two enforcement paths — truncation\n on the interop path, `#VALUE!` on the formula path — are described in\n [the value universe](../model/01-value-universe.md). Which one `ARRAYTOTEXT` meets has not been\n probed.\n- **Errors inside the array are rendered, not propagated**, in the documented example. That is a\n striking exception to the usual discipline in\n [coercion and lifting](../model/02-coercion-and-lifting.md), where coercion never silently\n discards a worksheet error — here the error is neither discarded nor propagated but *displayed*.\n Whether an error arriving as the whole `array` argument behaves the same way is a separate\n question and is not settled here.\n- **Empty cells inside a range** have no obvious rendering. Whether they contribute an empty\n element, a zero, or nothing at all to the concise join is not established.\n- **Row-major order is the documented traversal**, so concise mode reading order matches how you\n read the range on screen.\n- **Concise mode loses shape irreversibly.** If you need the shape back, use strict mode.\n\n\n\n### Errors\n\n\n| Error | Basis |\n|---|---|\n| `#VALUE!` when `format` is anything other than `0` or `1` | documented on Microsoft's page (retrieved for this entry) |\n| `#VALUE!` if the rendered result exceeds the worksheet text cap on the formula path | expected from the value-universe chapter's account of the cap; not probed for this function |\n| any error value arriving as the `array` argument itself | behaviour not established here — see below |\n\n\n", "sources": "- Microsoft Support, ARRAYTOTEXT function —\n \n (retrieved for this page; source of the signature, both format-mode descriptions, the worked\n concise and strict examples quoted above, and the documented `#VALUE!` for a `format` outside\n `{0,1}`).\n- Handbook `content/model/01-value-universe.md` (arrays, the text cap and its two enforcement\n paths, rich values), `02-coercion-and-lifting.md` (error discipline), `03-call-pipeline.md`\n (reference resolution before the function runs).\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`ARRAYTOTEXT` renders a whole array — or a range — as a single string.\n\nIt has the same two registers as its scalar sibling [`VALUETOTEXT`](FUNC.VALUETOTEXT.md), and the\ndifference between them is sharper here because an array has structure to lose.\n\n**Concise (`format = 0`, the default)** walks the array in row-major order and joins the elements'\nGeneral-format renderings with `\", \"`. Row structure is *not* preserved: a 3×2 array and a 1×6\narray with the same elements in the same order render identically. Microsoft's page shows this\ndirectly — a two-column, three-row range renders as a single comma-separated run.\n\n**Strict (`format = 1`)** renders an array literal: braces around the whole thing, commas between\ncolumns, semicolons between rows, text elements quoted, and Booleans, numbers and errors left\nunquoted. This preserves shape and kind, and it reparses. Microsoft's page shows a 3×2 range\nbecoming `{TRUE,#VALUE!;1234.01234,\"Seattle\";\"Hello\",\"1,123\"}` — which is worth studying, because\nit contains the two facts that matter most: an error appears as bare `#VALUE!` (a rendered error,\nnot a propagated one) and the number `1123` formatted with a thousands separator appears as the\n*quoted string* `\"1,123\"`, because concise/strict rendering follows the cell's displayed text, not\nits underlying number.\n\nThat last point is the trap. `ARRAYTOTEXT` renders what the cells *show*, so a formatted number can\ncome back as text that no longer parses as that number.\n\n\n### Arguments\n\n\n`ARRAYTOTEXT(array, [format])`\n\n| Argument | Required | Meaning (as documented by Microsoft) |\n|---|---|---|\n| `array` | yes | The array or range to render as text. |\n| `format` | no | `0` (default) concise; `1` strict. Anything else returns `#VALUE!`. |\n\nTwo things about the first position. It accepts a **range**, not only an array value — which is the\nusual way it is used, and which means the reference is resolved to values before the function sees\nit (see [the call pipeline](../model/03-call-pipeline.md)). And a **scalar is accepted**, promoted\nto a 1×1 array; upstream records that promotion explicitly, and it is why `ARRAYTOTEXT(\"abc\")` is\nnot an error.\n\nThe `format` argument admits exactly `0` and `1`; Microsoft documents anything else as `#VALUE!`.\n\n\n" }, "signature": { "display": "ARRAYTOTEXT(array, [format])", "parameters": [ { "description": null, "name": "array", "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": "TextToText", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "RefOnly", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "One text holding all the values of an array or range", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns an array of text values from any specified range", "microsoft_url": "https://support.microsoft.com/en-us/office/arraytotext-function-9cdcad46-2fa5-4c6b-ac92-14e7bc862b8b" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "ARRAYTOTEXT" }, { "locale": "bg-BG", "name": "ARRAYTOTEXT" }, { "locale": "cs-CZ", "name": "ARRAYTOTEXT" }, { "locale": "da-DK", "name": "MATRIXTILTEKST" }, { "locale": "de-DE", "name": "ARRAYTOTEXT" }, { "locale": "el-GR", "name": "ARRAYTOTEXT" }, { "locale": "en-AU", "name": "ARRAYTOTEXT" }, { "locale": "en-GB", "name": "ARRAYTOTEXT" }, { "locale": "en-US", "name": "ARRAYTOTEXT" }, { "locale": "es-ES", "name": "MATRIZATEXTO" }, { "locale": "et-EE", "name": "ARRAYTOTEXT" }, { "locale": "fi-FI", "name": "MATRIISI.TEKSTIKSI" }, { "locale": "fr-FR", "name": "TABLEAU.EN.TEXTE*" }, { "locale": "he-IL", "name": "ARRAYTOTEXT" }, { "locale": "hr-HR", "name": "ARRAYTOTEXT" }, { "locale": "hu-HU", "name": "TÖMB.SZÖVEGGÉ" }, { "locale": "id-ID", "name": "ARRAYTOTEXT" }, { "locale": "it-IT", "name": "ARRAYTOTEXT" }, { "locale": "ja-JP", "name": "ARRAYTOTEXT" }, { "locale": "ko-KR", "name": "ARRAYTOTEXT" }, { "locale": "lt-LT", "name": "ARRAYTOTEXT" }, { "locale": "lv-LV", "name": "ARRAYTOTEXT" }, { "locale": "nb-NO", "name": "ARRAYTOTEXT" }, { "locale": "nl-NL", "name": "ARRAYTOTEXT" }, { "locale": "pl-PL", "name": "TABLICA.NA.TEKST" }, { "locale": "pt-BR", "name": "ARRAYTOTEXT" }, { "locale": "pt-PT", "name": "MATRIZPARATEXTO" }, { "locale": "ro-RO", "name": "ARRAYTOTEXT" }, { "locale": "ru-RU", "name": "МАССИВВТЕКСТ" }, { "locale": "sk-SK", "name": "ARRAYTOTEXT" }, { "locale": "sl-SI", "name": "ARRAYTOTEXT" }, { "locale": "sr-Latn-RS", "name": "ARRAYTOTEXT" }, { "locale": "sv-SE", "name": "MATRISTILLTEXT" }, { "locale": "th-TH", "name": "ARRAYTOTEXT" }, { "locale": "tr-TR", "name": "DİZİMETİN" }, { "locale": "uk-UA", "name": "ARRAYTOTEXT" }, { "locale": "vi-VN", "name": "ARRAYTOTEXT" }, { "locale": "zh-CN", "name": "ARRAYTOTEXT" }, { "locale": "zh-HK", "name": "ARRAYTOTEXT" }, { "locale": "zh-TW", "name": "ARRAYTOTEXT" } ], "signature": { "display": "ARRAYTOTEXT(array, [format])", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false }, { "description": null, "name": "format", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "ARRAYTOTEXT", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/arraytotext-function-9cdcad46-2fa5-4c6b-ac92-14e7bc862b8b" }, "try_it": { "formula": "=ARRAYTOTEXT(\"abc\")" }, "url": "https://handbook.dnacalc.com/functions/ARRAYTOTEXT.html", "variants": [], "versions": [] }