{
  "category": "Text functions",
  "display_name": "CONCAT",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.CONCAT",
  "implementation_state": {
    "answer_bank": {
      "excel_builds": [
        "20527"
      ],
      "larger_numeric": 0,
      "last_bit": 0,
      "matched": 15,
      "other_mismatch": 5,
      "refused": 0,
      "rows": 20,
      "unread": 0,
      "worst_ulp": 0
    },
    "detail": "Of 63 recorded answers (20 in the answer bank and 43 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 63 recorded answers",
    "workbook_corpus": {
      "cells": 43,
      "matched": 43
    }
  },
  "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#L339-L339",
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_functions.rs#L153-L166"
      ],
      "repository": "https://github.com/DnaCalc/DnaCalc",
      "shared_code": [
        "catalogue/text_functions::cells",
        "catalogue/text_functions::cell_text"
      ],
      "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_functions.rs#L339-L339",
      "state": "differs",
      "suite": null,
      "summary": "Known larger differences on 5 of 63 recorded answers"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.CONCAT.json",
  "name": "CONCAT",
  "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- **`CONCATENATE`** is the function `CONCAT` replaces; Microsoft retains it for workbook\n  compatibility and its own article warns that it may not be available in future versions. The\n  two differ in range handling, in argument limits, and — per the axis chip this page renders —\n  in array lifting. See [`CONCATENATE`](FUNC.CONCATENATE.md).\n- **`TEXTJOIN`** is the third member of the family and the one to reach for by default: it adds\n  the delimiter and ignore-empty arguments that `CONCAT` deliberately lacks.\n- **`&` (`FUNC.OP_CONCAT`)** is the operator form. For two or three scalars it is shorter and\n  equivalent in intent; it has no range behaviour.\n- **`TEXTSPLIT`** is the modern inverse direction.\n\n\n",
    "how-to-implement": "\n### Notes for implementers\n\n1. **Expansion order is part of the contract.** Row-major within each argument, arguments in\n   written order. Any other order is a different function, and the difference only shows on\n   multi-row, multi-column ranges — which is exactly the shape casual tests omit.\n2. **Check the length cap incrementally.** A single append that crosses 32,767 must produce the\n   error rather than a truncated string; building the whole result and testing afterwards is\n   correct but can allocate absurdly on adversarial input.\n3. **The cap counts UTF-16 code units**, so a result made of astral characters reaches it at\n   half the number of visible characters.\n\n\n",
    "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Text`.\n\n- **The 32,767-character cap is a real boundary, and it errors.** Microsoft's article states\n  that a result longer than 32,767 characters returns `#VALUE!`. That is the cell text limit\n  from [chapter 01](../model/01-value-universe.md), surfacing here as an error rather than as\n  truncation — consistent with what that chapter records for the formula path generally.\n- **Empty cells inside a range contribute nothing**, so `CONCAT` over a sparse column silently\n  closes the gaps. There is no way to tell afterwards how many cells were empty.\n- **Numbers and logicals convert to text.** A number contributes its General rendering, so a\n  value displayed as `1 234,57` by a cell format contributes the unformatted digits. Wrap in\n  `TEXT` when the rendering matters.\n- Reference and array arguments are resolved and expanded before conversion, per\n  [chapter 03](../model/03-call-pipeline.md).\n\n\n\n### Errors\n\n\n- `#VALUE!` when the joined result would exceed 32,767 characters (documented).\n- An error value anywhere in the input propagates\n  ([chapter 02](../model/02-coercion-and-lifting.md)) — including an error sitting in one cell\n  of a range argument, which is the case where `CONCAT` differs most sharply from an aggregate\n  that could choose to skip it.\n- A value kind with no text conversion surfaces `#VALUE!` under the shared coercion rules.\n\n\n",
    "sources": "- Microsoft, \"CONCAT function\" —\n  <https://support.microsoft.com/en-us/office/concat-function-9b1a9a3f-94ff-41af-9736-694cbd6b4ca2>\n  (that it replaces `CONCATENATE`; up to 253 text arguments; the 32,767-character `#VALUE!`\n  boundary; the absence of delimiter and IgnoreEmpty arguments; the `TEXTJOIN` recommendation).\n  Retrieved for this page.\n- Handbook `content/model/01-value-universe.md` (the text cap and the formula-path error) and\n  `content/model/03-call-pipeline.md` (argument preparation and expansion).\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`CONCAT` joins text end to end and returns the result as one text value. Nothing is inserted\nbetween the pieces, nothing is skipped, and the order is the order the arguments are written.\n\nThe property that makes it a new function rather than a rename of `CONCATENATE` is how it\nconsumes a **range**. `CONCAT` flattens a multi-cell argument and joins every cell in it;\n`CONCATENATE` does not accept one. `CONCAT(A1:A3)` is a legal, meaningful call.\n\nStated as an operation: let each argument be expanded to a sequence of scalar values — an array\nor range expands in row-major order, a scalar expands to itself — and let each scalar be\nconverted to text by the ordinary to-text rules. `CONCAT` returns the concatenation of all\nthose texts, in argument order, with the expansions inlined in place. Empty cells contribute\nempty text, which is the same as contributing nothing.\n\nMicrosoft's article states the replacement relationship plainly: `CONCAT` \"replaces the\nCONCATENATE function\", though `CONCATENATE` remains available for backward compatibility.\n\n\n\n### Arguments\n\n\n`text1` — required; `text2, …` — optional, up to 253 text arguments in total per the article.\nEach argument may be a string or an array such as a cell range.\n\nTwo argument-level points worth stating:\n\n- **The 253 limit is on argument *slots*, not on cells.** A single range argument can\n  contribute far more than 253 values. This is the point readers most often get backwards when\n  migrating from `CONCATENATE`, whose 255 slots each had to be written out.\n\n\n"
  },
  "signature": {
    "display": "CONCAT(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": 254,
        "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": "All the texts of the arguments and ranges joined end to end",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": "Combines the text from multiple ranges and/or strings, but it doesn't provide the delimiter or IgnoreEmpty arguments.",
        "microsoft_url": "https://support.microsoft.com/en-us/office/concat-function-9b1a9a3f-94ff-41af-9736-694cbd6b4ca2"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [
        {
          "locale": "ar-SA",
          "name": "CONCAT"
        },
        {
          "locale": "bg-BG",
          "name": "CONCAT"
        },
        {
          "locale": "cs-CZ",
          "name": "CONCAT"
        },
        {
          "locale": "da-DK",
          "name": "SAMMENKÆDNING"
        },
        {
          "locale": "de-DE",
          "name": "CONCAT"
        },
        {
          "locale": "el-GR",
          "name": "CONCAT"
        },
        {
          "locale": "en-AU",
          "name": "CONCAT"
        },
        {
          "locale": "en-GB",
          "name": "CONCAT"
        },
        {
          "locale": "en-US",
          "name": "CONCAT"
        },
        {
          "locale": "es-ES",
          "name": "CONCAT"
        },
        {
          "locale": "et-EE",
          "name": "CONCAT"
        },
        {
          "locale": "fi-FI",
          "name": "YHDISTÄ"
        },
        {
          "locale": "fr-FR",
          "name": "CONCAT*"
        },
        {
          "locale": "he-IL",
          "name": "CONCAT"
        },
        {
          "locale": "hr-HR",
          "name": "CONCAT"
        },
        {
          "locale": "hu-HU",
          "name": "FŰZ"
        },
        {
          "locale": "id-ID",
          "name": "CONCAT"
        },
        {
          "locale": "it-IT",
          "name": "CONCAT"
        },
        {
          "locale": "ja-JP",
          "name": "CONCAT"
        },
        {
          "locale": "ko-KR",
          "name": "CONCAT"
        },
        {
          "locale": "lt-LT",
          "name": "CONCAT"
        },
        {
          "locale": "lv-LV",
          "name": "CONCAT"
        },
        {
          "locale": "nb-NO",
          "name": "CONCAT"
        },
        {
          "locale": "nl-NL",
          "name": "TEKST.SAMENV"
        },
        {
          "locale": "pl-PL",
          "name": "ZŁĄCZ.TEKST"
        },
        {
          "locale": "pt-BR",
          "name": "CONCAT"
        },
        {
          "locale": "pt-PT",
          "name": "CONCAT"
        },
        {
          "locale": "ro-RO",
          "name": "CONCAT"
        },
        {
          "locale": "ru-RU",
          "name": "СЦЕП"
        },
        {
          "locale": "sk-SK",
          "name": "CONCAT"
        },
        {
          "locale": "sl-SI",
          "name": "CONCAT"
        },
        {
          "locale": "sr-Latn-RS",
          "name": "CONCAT"
        },
        {
          "locale": "sv-SE",
          "name": "SAMMAN"
        },
        {
          "locale": "th-TH",
          "name": "CONCAT"
        },
        {
          "locale": "tr-TR",
          "name": "ARALIKBİRLEŞTİR"
        },
        {
          "locale": "uk-UA",
          "name": "CONCAT"
        },
        {
          "locale": "vi-VN",
          "name": "CONCAT"
        },
        {
          "locale": "zh-CN",
          "name": "CONCAT"
        },
        {
          "locale": "zh-HK",
          "name": "CONCAT"
        },
        {
          "locale": "zh-TW",
          "name": "CONCAT"
        }
      ],
      "signature": {
        "display": "CONCAT(text1, [text2], ...)",
        "parameters": [
          {
            "description": null,
            "name": "text1",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "text2",
            "optional": true,
            "repeats": true
          }
        ],
        "trailing_repeats": true
      },
      "surface_name": "CONCAT",
      "version_marker": null,
      "xlcall": null
    },
    "microsoft": "https://support.microsoft.com/en-us/office/concat-function-9b1a9a3f-94ff-41af-9736-694cbd6b4ca2"
  },
  "try_it": {
    "formula": "=CONCAT(\"abc\")"
  },
  "url": "https://handbook.dnacalc.com/functions/CONCAT.html",
  "variants": [],
  "versions": []
}