{
  "category": "Text functions",
  "display_name": "LEN",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.LEN",
  "implementation_state": {
    "answer_bank": null,
    "detail": "Recorded: 48 workbook cells.",
    "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87",
    "in_catalogue": true,
    "state": "matches",
    "state_label": "Matches every recorded Excel answer",
    "summary": "Matches all 48 recorded answers",
    "workbook_corpus": {
      "cells": 48,
      "matched": 48
    }
  },
  "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#L260-L268"
      ],
      "repository": "https://github.com/DnaCalc/DnaCalc",
      "shared_code": [
        "catalogue/text_functions::count_surrogate_pairs",
        "ported/text_kernels::text",
        "ported/text_kernels::slice_character_count",
        "ported/text_kernels::character_scan_end",
        "ported/text_kernels::len_character_count"
      ],
      "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_functions.rs#L260-L268",
      "state": "matches",
      "suite": null,
      "summary": "Matches all 48 recorded answers"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.LEN.json",
  "name": "LEN",
  "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- **`LENB`** is the byte-counting variant. Microsoft's article now states in one line that \"the\n  LENB function is deprecated\", and the Handbook publishes it as a separate entry because it is\n  a different function. See [`LENB`](FUNC.LENB.md) for what byte counting means and for what\n  the current documentation no longer says about it.\n- **`LEFT`, `RIGHT`, `MID`** index into the same string in the same units, which is why they\n  belong to one family: `LEFT(a, LEN(a))` should be `a` under any consistent unit choice, and\n  that identity is the cheapest self-consistency test for an implementation.\n- **`TRIM`** and **`CLEAN`** are the usual companions when a `LEN` result is surprising: the\n  extra characters are almost always whitespace or control characters.\n- **`SUBSTITUTE`** underlies the standard counting idiom `LEN(a)-LEN(SUBSTITUTE(a,x,\"\"))`,\n  which counts occurrences of `x` — an idiom whose correctness depends on `LEN`'s unit and\n  `SUBSTITUTE`'s matching using the same unit.\n\n\n",
    "how-to-implement": "\n### Notes for implementers\n\n1. **The counting unit is a declared axis, not a detail.** Three candidates are live — UTF-16\n   code units, Unicode code points, grapheme clusters — and Microsoft's documentation now\n   places Excel on the first for legacy workbooks and the second for Compatibility Version 2,\n   explicitly not the third.\n2. **Compatibility version is an observation-context axis.** Any claim about `LEN` on astral\n   text has to name it, in the same way a numeric claim names the Excel build. The Handbook's\n   existing observation-context vocabulary already carries a workbook-mode field; this is what\n   it is for.\n3. **Ill-formed UTF-16 is reachable.** The value-universe chapter records interop truncation\n   producing a dangling high surrogate. A code-point counter must decide what an unpaired\n   surrogate contributes before it meets one.\n\n\n",
    "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Number`, always a non-negative integer.\n\n- **Empty text is 0**; an empty cell converts to empty text and is likewise 0. `LEN` therefore\n  cannot distinguish a blank cell from a cell containing `=\"\"` — use `ISBLANK`.\n- **Trailing spaces count**, which is the standard way of detecting them:\n  `LEN(a)<>LEN(TRIM(a))`.\n- **Formatting never counts.** A cell displayed as `$1,234.57` holding the number 1234.567 has\n  the `LEN` of `1234.567`, not of the display. Compose with `TEXT` when the display is what you\n  mean.\n- **The cell text cap is 32,767 code units**, so `LEN` on ordinary cell content is bounded by\n  that; values built inside a formula are bounded the same way\n  ([chapter 01](../model/01-value-universe.md)).\n\n\n\n### Errors\n\n\nThe article lists no error conditions for `LEN`, and the function has no domain to violate.\nReachable errors are the shared ones: an error value in the argument propagates, and a value\nkind with no text conversion surfaces `#VALUE!` under the shared coercion rules\n([chapter 02](../model/02-coercion-and-lifting.md)).\n\n\n",
    "sources": "- Microsoft, \"LEN function\" —\n  <https://support.microsoft.com/en-us/office/len-function-29236f94-cedc-429d-affd-b5e33d2c67cb>\n  (\"Spaces count as characters\"; \"The LENB function is deprecated\"; the Compatibility Version 2\n  surrogate-pair change and the variation-selector exception). Retrieved for this page.\n- Handbook `content/model/01-value-universe.md` (worksheet text as UTF-16 code units, the\n  32,767 cap, the reachable dangling-surrogate state) and\n  `content/model/02-coercion-and-lifting.md`.\n- Handbook `data/presence/FUNC.LEN.json` (the low name-match confidence noted above).\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`LEN` returns the number of characters in a text string. Microsoft's article adds the\nclarification readers most often need: \"Spaces count as characters.\" `LEN` measures the stored\ntext, not the displayed text and not the visible ink.\n\nThe entire subtlety of this function is the word *character*, and Excel's own answer to it has\nchanged. The Handbook's value-universe chapter records the historical model — worksheet text is\na sequence of **UTF-16 code units**, so a character outside the Basic Multilingual Plane\noccupies two units and `LEN` of a single emoji is 2. Microsoft's current article records a\nchange to exactly that:\n\n> in workbooks set to Compatibility Version 2, `LEN` has improved behavior with surrogate\n> pairs, counting them as one character instead of two, while variation selectors (commonly\n> used with emojis) are still counted as separate characters.\n\nSo `LEN` is now a **two-answer function**, and which answer you get is a property of the\nworkbook, not of the input. A page that states one number for `LEN(\"😀\")` without naming the\ncompatibility version is stating half a fact.\n\nNote also what the change does *not* cover: a variation selector still counts on its own. So a\ncomposed emoji — a base character, a variation selector, possibly a zero-width joiner and a\nskin-tone modifier — still counts as several under Compatibility Version 2, even though it\nrenders as one glyph. The counting unit under Version 2 is the Unicode code point, not the\ngrapheme cluster.\n\n\n\n### Arguments\n\n\n`text` — required; the article describes it as the text whose length you want, and states that\nspaces count. It is a text argument, so numbers and logicals convert first: `LEN` of a number\nis the length of that number's General rendering, which is why `LEN(1/3)` is a large number and\nnot something meaningful about the value.\n\nThere is no second argument — no counting mode, and in particular no way to ask for the other\ncompatibility version's answer.\n\n\n"
  },
  "signature": {
    "display": "LEN(text)",
    "parameters": [
      {
        "description": null,
        "name": "text",
        "optional": false,
        "repeats": false
      }
    ],
    "trailing_repeats": false
  },
  "sources": {
    "metadata": {
      "admission": {
        "label": "implemented",
        "reason": null
      },
      "arity": {
        "max": 1,
        "min": 1
      },
      "category": "Text functions",
      "classification": {
        "arg_preparation_profile": "ValuesOnlyPreAdapter",
        "coercion_lift_profile": "None",
        "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 length in characters",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": "Returns the number of characters in a text string",
        "microsoft_url": "https://support.microsoft.com/en-us/office/len-function-29236f94-cedc-429d-affd-b5e33d2c67cb"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [
        {
          "locale": "ar-SA",
          "name": "LEN"
        },
        {
          "locale": "bg-BG",
          "name": "LEN"
        },
        {
          "locale": "cs-CZ",
          "name": "LEN"
        },
        {
          "locale": "da-DK",
          "name": "LÆNGDE"
        },
        {
          "locale": "de-DE",
          "name": "LEN"
        },
        {
          "locale": "el-GR",
          "name": "LEN"
        },
        {
          "locale": "en-AU",
          "name": "LEN"
        },
        {
          "locale": "en-GB",
          "name": "LEN"
        },
        {
          "locale": "en-US",
          "name": "LEN"
        },
        {
          "locale": "es-ES",
          "name": "LARGO"
        },
        {
          "locale": "et-EE",
          "name": "LEN"
        },
        {
          "locale": "fi-FI",
          "name": "PITUUS"
        },
        {
          "locale": "fr-FR",
          "name": "NBCAR"
        },
        {
          "locale": "he-IL",
          "name": "LEN"
        },
        {
          "locale": "hr-HR",
          "name": "LEN"
        },
        {
          "locale": "hu-HU",
          "name": "HOSSZ"
        },
        {
          "locale": "id-ID",
          "name": "LEN"
        },
        {
          "locale": "it-IT",
          "name": "LEN"
        },
        {
          "locale": "ja-JP",
          "name": "LEN"
        },
        {
          "locale": "ko-KR",
          "name": "LEN"
        },
        {
          "locale": "lt-LT",
          "name": "LEN"
        },
        {
          "locale": "lv-LV",
          "name": "LEN"
        },
        {
          "locale": "nb-NO",
          "name": "LENGDE"
        },
        {
          "locale": "nl-NL",
          "name": "LENGTE"
        },
        {
          "locale": "pl-PL",
          "name": "DŁ"
        },
        {
          "locale": "pt-BR",
          "name": "LEN"
        },
        {
          "locale": "pt-PT",
          "name": "NÚM.CARAT"
        },
        {
          "locale": "ro-RO",
          "name": "LEN"
        },
        {
          "locale": "ru-RU",
          "name": "ДЛСТР"
        },
        {
          "locale": "sk-SK",
          "name": "LEN"
        },
        {
          "locale": "sl-SI",
          "name": "LEN"
        },
        {
          "locale": "sr-Latn-RS",
          "name": "LEN"
        },
        {
          "locale": "sv-SE",
          "name": "LÄNGD"
        },
        {
          "locale": "th-TH",
          "name": "LEN"
        },
        {
          "locale": "tr-TR",
          "name": "UZUNLUK"
        },
        {
          "locale": "uk-UA",
          "name": "LEN"
        },
        {
          "locale": "vi-VN",
          "name": "LEN"
        },
        {
          "locale": "zh-CN",
          "name": "LEN"
        },
        {
          "locale": "zh-HK",
          "name": "LEN"
        },
        {
          "locale": "zh-TW",
          "name": "LEN"
        }
      ],
      "signature": {
        "display": "LEN(text)",
        "parameters": [
          {
            "description": null,
            "name": "text",
            "optional": false,
            "repeats": false
          }
        ],
        "trailing_repeats": false
      },
      "surface_name": "LEN",
      "version_marker": null,
      "xlcall": null
    },
    "microsoft": "https://support.microsoft.com/en-us/office/len-function-29236f94-cedc-429d-affd-b5e33d2c67cb"
  },
  "try_it": {
    "formula": "=LEN(\"handbook\")"
  },
  "url": "https://handbook.dnacalc.com/functions/LEN.html",
  "variants": [
    {
      "code": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_functions.rs#L260-L268",
      "difference": "A surrogate pair counts as two characters.",
      "error_bound": null,
      "evidence": [
        {
          "commit": "",
          "locator": "",
          "note": "",
          "path": "https://support.microsoft.com/en-gb/excel/compatibility-versions",
          "repository": ""
        }
      ],
      "key": {
        "cpu": "Any",
        "excel_build_range": "Compatibility Version 1, all Excel versions"
      },
      "kind": "environment",
      "name": "LEN at Compatibility Version 1",
      "onecalc_udf": null,
      "state": "selected",
      "state_summary": "Implemented; selected by the workbook's Compatibility Version."
    },
    {
      "code": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_functions.rs#L260-L268",
      "difference": "A surrogate pair counts as one character. Characters combined from several code points still count separately.",
      "error_bound": null,
      "evidence": [
        {
          "commit": "",
          "locator": "",
          "note": "",
          "path": "https://support.microsoft.com/en-gb/excel/compatibility-versions",
          "repository": ""
        }
      ],
      "key": {
        "cpu": "Any",
        "excel_build_range": "Compatibility Version 2, Excel for Microsoft 365"
      },
      "kind": "environment",
      "name": "LEN at Compatibility Version 2",
      "onecalc_udf": null,
      "state": "selected",
      "state_summary": "Implemented; selected by the workbook's Compatibility Version."
    }
  ],
  "versions": []
}