{ "category": "Compatibility", "display_name": "CONCATENATE", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.CONCATENATE", "implementation_state": { "answer_bank": { "excel_builds": [ "20527" ], "larger_numeric": 0, "last_bit": 0, "matched": 5, "other_mismatch": 5, "refused": 0, "rows": 10, "unread": 0, "worst_ulp": 0 }, "detail": "Of 15 recorded answers (10 in the answer bank and 5 workbook cells), 5 do not match: 5 differ in kind or value.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "differs", "state_label": "Known larger differences", "summary": "Known larger differences on 5 of 15 recorded answers", "workbook_corpus": { "cells": 5, "matched": 5 } }, "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_functions.rs#L338-L338", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_functions.rs#L168-L179" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/text_functions::cell_text" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_functions.rs#L338-L338", "state": "differs", "suite": null, "summary": "Known larger differences on 5 of 15 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.CONCATENATE.json", "name": "CONCATENATE", "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- **`CONCAT`** is the modern replacement, named as such by Microsoft. It accepts ranges and\n carries different limits. See [`CONCAT`](FUNC.CONCAT.md).\n- **`TEXTJOIN`** adds a delimiter and an ignore-empty flag, and is usually the better migration\n target for a `CONCATENATE` chain that interleaves separator literals.\n- **`&` (`FUNC.OP_CONCAT`)** is the operator form; the article itself recommends it as the\n simpler syntax. It is not identical in shape to either function — it is a binary operator\n with the operator pipeline's own lifting behaviour.\n- **`TEXT`** is what the article recommends composing with when the joined pieces need\n formatting; `CONCATENATE` will not format anything for you.\n\nDespite its status, `CONCATENATE` is **not** in Excel's Compatibility category. It sits in the\nText category alongside `CONCAT`, and Microsoft's deprecation statement is in prose rather than\nin the category taxonomy.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n1. **Do not implement `CONCATENATE` as `CONCAT` with a different arity.** The range behaviour\n and the position-dependent lifting are genuinely different, and the difference is observable\n in ordinary workbooks.\n2. **Carry both documented limits separately** (255 slots, 8,192 characters here; 253 and\n 32,767 there). They are not derived from a shared constant.\n3. **The lift positions are irreducible structure.** The `[0,1,2]` position list is not a rule\n with a reason; it is a fact to be copied, and the call-pipeline chapter says so about this\n whole axis.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Text`.\n\n- Numbers and logicals convert to text by the ordinary rules; a number contributes its General\n rendering, not its displayed format.\n- Empty cells contribute empty text.\n\n\n\n### Errors\n\n\n- An error value in any argument propagates\n ([chapter 02](../model/02-coercion-and-lifting.md)).\n- A value kind with no text conversion surfaces `#VALUE!` under the shared coercion rules.\n- Microsoft's article documents `#NAME?` as the usual symptom of a common authoring mistake —\n missing quotation marks around a text argument. That is a formula-entry problem rather than a\n behaviour of the function, and it is listed here because the article lists it and readers\n arrive looking for it.\n\nThe article's other two \"common problems\" are also authoring issues rather than function\nsemantics: quotation marks appearing in the result usually mean a missing comma between\narguments, and words running together mean no space argument was supplied. `CONCATENATE`\ninserts nothing on its own.\n\n\n", "sources": "- Microsoft, \"CONCATENATE function\" —\n \n (that it has been replaced by `CONCAT` and may not be available in future versions; up to 255\n items totalling 8,192 characters; the `&` and `TEXT` recommendations; the `#NAME?` and\n missing-comma common problems). Retrieved for this page.\n- Handbook `content/model/03-call-pipeline.md` (the `ByIndexScalarArrayLift` axis and its\n empirically-pinned status) and `content/model/02-coercion-and-lifting.md` (to-text\n conversion, error propagation).\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`CONCATENATE` joins two or more text strings into one string, in argument order, with nothing\ninserted between them.\n\nIt is the legacy member of its family. Microsoft's article states that it \"has been replaced\nwith the CONCAT function\", recommends `CONCAT` going forward, and warns that `CONCATENATE` \"may\nnot be available in future versions of Excel\". Excel keeps the name so that existing workbooks\nkeep calculating; new formulas should use `CONCAT`, `TEXTJOIN`, or `&`.\n\nThe substantive difference from `CONCAT` is not the name. `CONCATENATE` is **scalar-shaped**:\neach argument contributes one value, not a flattened range. A multi-cell range handed to\n`CONCATENATE` does not join its cells.\n\n\n\n### Arguments\n\n\n`text1` — required, the first item to join; may be text, a number, or a cell reference. `text2,\n…` — optional. The article states the ceiling as up to 255 items totalling a maximum of 8,192\ncharacters.\n\nNote that those are two different limits from the ones `CONCAT` carries (253 slots, 32,767\ncharacters), and the 8,192-character figure is documented for `CONCATENATE` specifically. If\nyou are migrating formulas between the two functions, both limits change.\n\nThe argument position that most often surprises readers is any position holding a multi-cell\nrange. `CONCAT` accepts it and flattens; `CONCATENATE` does not consume it as a range at all,\nand what happens instead depends on the shared array/implicit-intersection machinery rather\nthan on this function.\n\n\n" }, "signature": { "display": "CONCATENATE(text1, [text2], ...)", "parameters": [ { "description": null, "name": "text1", "optional": false, "repeats": false }, { "description": null, "name": "text2", "optional": true, "repeats": true } ], "trailing_repeats": true }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 255, "min": 1 }, "category": "Compatibility", "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": "Two or more texts joined end to end", "short_source": "dna-calc-own" }, "docs": { "english_description": "Joins two or more text strings into one string", "microsoft_url": "https://support.microsoft.com/en-us/office/concatenate-function-8f8ae884-2ca8-4f7a-b093-75d702bea31d" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "CONCATENATE" }, { "locale": "bg-BG", "name": "CONCATENATE" }, { "locale": "cs-CZ", "name": "CONCATENATE" }, { "locale": "da-DK", "name": "SAMMENKÆDE" }, { "locale": "de-DE", "name": "VERKETTEN" }, { "locale": "el-GR", "name": "CONCATENATE" }, { "locale": "en-AU", "name": "CONCATENATE" }, { "locale": "en-GB", "name": "CONCATENATE" }, { "locale": "en-US", "name": "CONCATENATE" }, { "locale": "es-ES", "name": "CONCATENAR" }, { "locale": "et-EE", "name": "CONCATENATE" }, { "locale": "fi-FI", "name": "KETJUTA" }, { "locale": "fr-FR", "name": "CONCATENER" }, { "locale": "he-IL", "name": "CONCATENATE" }, { "locale": "hr-HR", "name": "CONCATENATE" }, { "locale": "hu-HU", "name": "ÖSSZEFŰZ" }, { "locale": "id-ID", "name": "CONCATENATE" }, { "locale": "it-IT", "name": "CONCATENA" }, { "locale": "ja-JP", "name": "CONCATENATE" }, { "locale": "ko-KR", "name": "CONCATENATE" }, { "locale": "lt-LT", "name": "CONCATENATE" }, { "locale": "lv-LV", "name": "CONCATENATE" }, { "locale": "nb-NO", "name": "KJEDE.SAMMEN" }, { "locale": "nl-NL", "name": "TEKST.SAMENVOEGEN" }, { "locale": "pl-PL", "name": "ZŁĄCZ.TEKSTY" }, { "locale": "pt-BR", "name": "CONCATENAR" }, { "locale": "pt-PT", "name": "CONCATENAR" }, { "locale": "ro-RO", "name": "CONCATENATE" }, { "locale": "ru-RU", "name": "СЦЕПИТЬ" }, { "locale": "sk-SK", "name": "CONCATENATE" }, { "locale": "sl-SI", "name": "CONCATENATE" }, { "locale": "sr-Latn-RS", "name": "CONCATENATE" }, { "locale": "sv-SE", "name": "SAMMANFOGA" }, { "locale": "th-TH", "name": "CONCATENATE" }, { "locale": "tr-TR", "name": "BİRLEŞTİR" }, { "locale": "uk-UA", "name": "CONCATENATE" }, { "locale": "vi-VN", "name": "Hàm CONCATENATE" }, { "locale": "zh-CN", "name": "CONCATENATE" }, { "locale": "zh-HK", "name": "CONCATENATE" }, { "locale": "zh-TW", "name": "CONCATENATE" } ], "signature": { "display": "CONCATENATE(text1, [text2], ...)", "parameters": [ { "description": null, "name": "text1", "optional": false, "repeats": false }, { "description": null, "name": "text2", "optional": true, "repeats": true } ], "trailing_repeats": true }, "surface_name": "CONCATENATE", "version_marker": null, "xlcall": { "code": "336", "symbol": "xlfConcatenate" } }, "microsoft": "https://support.microsoft.com/en-us/office/concatenate-function-8f8ae884-2ca8-4f7a-b093-75d702bea31d" }, "try_it": { "formula": "=CONCATENATE(\"abc\")" }, "url": "https://handbook.dnacalc.com/functions/CONCATENATE.html", "variants": [], "versions": [] }