{ "category": "Text functions", "display_name": "LENB", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.LENB", "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_functions.rs#L272-L276" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/text_functions::single_byte" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_functions.rs#L272-L276", "state": "matches", "suite": null, "summary": "Matches all 13 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.LENB.json", "name": "LENB", "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- **[`LEN`](FUNC.LEN.md)** is the character-counting partner and the function to use in new\n work. Microsoft documents both in one article and marks `LENB` deprecated there.\n- **`LEFTB`, `RIGHTB`, `MIDB`, `FINDB`, `SEARCHB`, `REPLACEB`** are the rest of the\n byte-variant family. They share the same unit substitution and the same deprecation posture,\n and an implementation should treat the unit as one shared decision rather than seven. See\n [`LEFTB`](FUNC.LEFTB.md) and [`FINDB`](FUNC.FINDB.md).\n- **`ASC` and `DBCS`** are the width-conversion functions from the same lineage, converting\n between full-width and half-width forms.\n\n", "how-to-implement": "\n### Notes for implementers\n\n1. **Do not implement `LENB` as `LEN`.** They coincide only on single-byte text. An\n implementation that aliases them is implementing the non-DBCS specialisation and should say\n so rather than claim the function.\n2. **The byte count needs a named encoding.** \"Bytes\" is meaningless without one. An\n implementation must state which encoding it measures in and where that encoding comes from\n (system ANSI code page, workbook setting, or a fixed choice).\n3. **Astral characters need a stated policy** for the reason given above: they have no natural\n DBCS byte length.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Number`, a non-negative integer.\n\n- **Empty text is 0** under any encoding.\n- **On single-byte text the result equals `LEN`'s.** That is not a coincidence to be worked\n around; it is the definition specialising.\n- The astral-character question that dominates [`LEN`](FUNC.LEN.md) — surrogate pairs, and the\n Compatibility Version 2 change to how they are counted — has no documented counterpart here.\n What a byte count is supposed to mean for a character that the historical DBCS encodings\n could not represent at all is undefined by any source this page can cite.\n\n\n\n### Errors\n\n\nThe article enumerates no error conditions. Reachable errors are the shared ones: propagation\nof an error argument, and `#VALUE!` for a value kind with no text conversion\n([chapter 02](../model/02-coercion-and-lifting.md)).\n\n\n", "sources": "- Microsoft, \"LEN function\" (the article that covers the pair) —\n \n (\"The LENB function is deprecated\"; no DBCS or language statement in the text retrieved).\n Retrieved for this page.\n- Microsoft, \"FIND, FINDB functions\" — cited only for the surviving SBCS/DBCS paragraph:\n \n- Handbook `CHARTER.md` section 4 (the seven split byte-variant rows) and\n `content/model/02-coercion-and-lifting.md`.\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`LENB` returns the number of **bytes** used to represent a text string, where `LEN` returns the\nnumber of characters. That one substitution — bytes for characters — is the entire difference\nbetween the two functions, and it is why the Handbook publishes them as two entries against\nMicrosoft's one article. (Seven published rows document a byte-variant pair this way; the\nHandbook splits all seven, which is the whole of the difference between 534 published Excel\nrows and 541 Handbook entries.)\n\n**What \"bytes\" means here.** The byte-variant functions come from the era in which East Asian\ntext was stored in a *double-byte character set* (DBCS): a host encoding in which some\ncharacters occupy one byte and others two. Under such an encoding a string's byte length is not\na fixed multiple of its character length — it is one byte per single-byte character plus two\nper double-byte character — so \"how many bytes is this string\" and \"how many characters is this\nstring\" are genuinely different questions with genuinely different answers, and a program\nworking against fixed-width record layouts needs the first one.\n\nThe standard consequence follows arithmetically: where every character in the string is\nsingle-byte, `LENB` and `LEN` return the same number. The two functions diverge only on text\ncontaining double-byte characters, under a host whose language setting supports DBCS. This\nmakes `LENB` an easy function to believe you have tested when you have not — an all-ASCII test\nsuite cannot tell the two functions apart at all.\n\n**What the documentation now says.** The Microsoft article that covers this pair states, in one\nline, that \"the LENB function is deprecated\". The text retrieved for this page contains no\nstatement about DBCS, no list of the languages or language settings under which `LENB` differs\nfrom `LEN`, and no definition of the byte count. The Handbook therefore records the\nbyte-versus-character distinction as the function's *stated purpose and historical definition*,\nand records that the current article does not define it. It does not assert which languages or\ncode pages are affected, because the article does not say.\n\nThe definition has not vanished from Microsoft's documentation altogether: the `FIND, FINDB`\narticle still carries the SBCS/DBCS paragraph, including the condition under which a byte\nvariant counts a double-byte character as 2. That paragraph is quoted on\n[`FINDB`](FUNC.FINDB.md), and it is the best surviving statement of what byte counting means\nanywhere in this family — including for `LENB`, whose own article no longer says.\n\n\n\n### Arguments\n\n\n`text` — required, the text whose byte length you want. It is the same argument as `LEN`'s,\nwith the same to-text conversion of numbers and logicals.\n\nThere is no encoding argument. The encoding is the host's, which is exactly why this function's\nanswer is environment-dependent in a way `LEN`'s (mostly) is not.\n\n\n" }, "signature": { "display": "LENB(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": "Number of bytes a text takes in double-byte languages", "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": "LENB" }, { "locale": "bg-BG", "name": "LENB" }, { "locale": "cs-CZ", "name": "LENB" }, { "locale": "da-DK", "name": "LÆNGDEB" }, { "locale": "de-DE", "name": "LENB" }, { "locale": "el-GR", "name": "LENB" }, { "locale": "en-AU", "name": "LENB" }, { "locale": "en-GB", "name": "LENB" }, { "locale": "en-US", "name": "LENB" }, { "locale": "es-ES", "name": "LARGOB" }, { "locale": "et-EE", "name": "LENB" }, { "locale": "fi-FI", "name": "PITUUSB" }, { "locale": "fr-FR", "name": "LENB" }, { "locale": "he-IL", "name": "LENB" }, { "locale": "hr-HR", "name": "LENB" }, { "locale": "hu-HU", "name": "HOSSZ2" }, { "locale": "id-ID", "name": "LENB" }, { "locale": "it-IT", "name": "LENB" }, { "locale": "ja-JP", "name": "LENB" }, { "locale": "ko-KR", "name": "LENB" }, { "locale": "lt-LT", "name": "LENB" }, { "locale": "lv-LV", "name": "LENB" }, { "locale": "nb-NO", "name": "LENGDEB" }, { "locale": "nl-NL", "name": "LENGTEB" }, { "locale": "pl-PL", "name": "DŁ.B" }, { "locale": "pt-BR", "name": "LENB" }, { "locale": "pt-PT", "name": "NÚM.CARATB" }, { "locale": "ro-RO", "name": "LENB" }, { "locale": "ru-RU", "name": "ДЛИНБ" }, { "locale": "sk-SK", "name": "LENB" }, { "locale": "sl-SI", "name": "LENB" }, { "locale": "sr-Latn-RS", "name": "LENB" }, { "locale": "sv-SE", "name": "LÄNGDB" }, { "locale": "th-TH", "name": "LENB" }, { "locale": "tr-TR", "name": "UZUNLUKB işlevleri" }, { "locale": "uk-UA", "name": "LENB" }, { "locale": "vi-VN", "name": "LENB" }, { "locale": "zh-CN", "name": "LENB" }, { "locale": "zh-HK", "name": "LENB" }, { "locale": "zh-TW", "name": "LENB" } ], "signature": { "display": "LENB(text)", "parameters": [ { "description": null, "name": "text", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "LENB", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/len-function-29236f94-cedc-429d-affd-b5e33d2c67cb" }, "try_it": { "formula": "=LENB(\"handbook\")" }, "url": "https://handbook.dnacalc.com/functions/LENB.html", "variants": [], "versions": [] }