{ "category": "Text functions", "display_name": "LEFTB", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.LEFTB", "implementation_state": { "answer_bank": null, "detail": "Recorded: 5 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 5 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#L277-L277" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/text_functions::single_byte", "catalogue/text_functions::side_count", "catalogue/text_functions::left", "ported/text_kernels::text", "ported/text_kernels::text_from_str", "ported/text_kernels::date_integer_floor", "ported/text_kernels::nonnegative_count", "ported/text_kernels::unit_width", "ported/text_kernels::character_boundary", "ported/text_kernels::slice_character_count", "ported/text_kernels::character_scan_end", "ported/text_kernels::len_character_count", "ported/text_kernels::take_left", "ported/text_kernels::truncated", "ported/text_kernels::push_singleton_or_original", "ported/text_kernels::push_upper", "ported/text_kernels::upper" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_functions.rs#L277-L277", "state": "matches", "suite": null, "summary": "Matches all 5 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.LEFTB.json", "name": "LEFTB", "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- **[`LEFT`](FUNC.LEFT.md)** is the character-counting partner, documented in the same article,\n which marks `LEFTB` deprecated. `LEFT` is the function to use in new work.\n- **`RIGHTB`, `MIDB`, [`LENB`](FUNC.LENB.md), [`FINDB`](FUNC.FINDB.md), `SEARCHB`, `REPLACEB`**\n are the rest of the byte-variant family. The unit is one shared decision across all seven,\n and so is the mid-character rule.\n- **`ASC` and `DBCS`** convert between half-width and full-width forms and are the functions\n people actually reach for when the problem is character width rather than storage width.\n\n", "how-to-implement": "\n### Notes for implementers\n\n1. **Do not implement `LEFTB` as `LEFT`.** They coincide only on single-byte text, and aliasing\n them is implementing the non-DBCS specialisation. Say so if that is what you are shipping.\n2. **Name the encoding.** A byte count is meaningless without one, and the historical answer —\n the host's system code page — makes this function environment-dependent in a way `LEFT` is\n not.\n3. **Write the mid-character rule down**, whatever you choose, and test it first; it is the\n only behaviour a byte-slicer has that a character-slicer does not.\n4. **Guard the text-cap and surrogate interactions.** A byte slicer built over UTF-16 storage\n can produce ill-formed text through two independent mechanisms — surrogate splitting and\n DBCS splitting — and the value-universe chapter records ill-formed UTF-16 as a reachable\n state that downstream code must survive.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Text`.\n\n- **On single-byte text the result equals `LEFT`'s.** That is the definition specialising, not\n a coincidence, and it is why an all-ASCII test suite cannot distinguish the two functions.\n- **A count landing mid-character** is the interesting case, and it is undefined by every\n source this page can cite.\n- **A count beyond the byte length** is expected to yield the whole text, by analogy with\n `LEFT`; unverified.\n- **Astral characters** have no natural DBCS byte length at all, so the interaction between\n `LEFTB` and the surrogate handling that the Compatibility Version feature changed is doubly\n undefined.\n\n\n\n### Errors\n\n\nThe article enumerates no error conditions for the B variant. Reachable errors are the shared\nones: propagation of an error argument, and `#VALUE!` for a value kind with no text conversion\n([chapter 02](../model/02-coercion-and-lifting.md)). Whether a negative `num_bytes` errors the\nsame way a negative `num_chars` does is unverified.\n\n\n", "sources": "- Microsoft, \"LEFT function\" (the article that covers the pair) —\n \n (\"The LEFTB function is deprecated\"; the Compatibility Version 2 surrogate note; the\n `num_chars` rules quoted here as the expected shape for `num_bytes`; no DBCS or language\n statement in the text retrieved). 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/01-value-universe.md` (ill-formed UTF-16 as a reachable state).\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`LEFTB` returns the leading portion of a text string measured in **bytes**, where\n[`LEFT`](FUNC.LEFT.md) measures in characters. The unit is the only difference between them,\nand it is why the Handbook publishes the pair as two entries against Microsoft's one article.\n(Seven published rows document a byte-variant pair this way; splitting all seven is the whole\nof the difference between 534 published Excel rows and 541 Handbook entries.)\n\n**What \"bytes\" means here.** The byte variants come from the era of *double-byte character\nsets* (DBCS): host encodings in which some characters occupy one byte and others two. Asking\nfor the first `n` bytes of such a string is a different question from asking for the first `n`\ncharacters, because the two counts advance at different rates through the same text. Where\nevery character in the string is single-byte, the two questions coincide and `LEFTB` and `LEFT`\nreturn the same result; they diverge only on text containing double-byte characters, under a\nhost whose language setting supports DBCS.\n\n`LEFTB` carries one problem `LENB` does not: **a byte count can land in the middle of a\ncharacter.** `LEFTB(t, 1)` applied to a string beginning with a double-byte character asks for\nhalf of that character. Every implementation of a byte-slicing function must have a rule for\nthat case — return a half character, drop it, or pad — and no source cited on this page states\nwhich rule Excel uses. That is the central unresolved question about this function, and it has\nno analogue in the character-counting variant.\n\n**What the documentation now says.** The Microsoft article that covers the pair states that\n\"the LEFTB function is deprecated\", and adds that `LEFT` now handles Unicode surrogates through\nthe Compatibility Version feature (Version 2) — the modern replacement for the problem byte\ncounting was once used to work around. The text retrieved for this page contains no DBCS\nstatement, no list of affected languages or language settings, and no definition of the byte\ncount or of the split-character rule. The Handbook records the byte semantics as the function's\nstated purpose and historical definition, and records that the current article does not define\nthem. It does not assert which locales are affected, because the article does not say.\n\nThe definition survives elsewhere in Microsoft's own documentation: the `FIND, FINDB` article\nstill carries the SBCS/DBCS paragraph and the condition under which a byte variant counts a\ndouble-byte character as 2. That paragraph is quoted on [`FINDB`](FUNC.FINDB.md), and it is the\nbest surviving statement of what byte counting means anywhere in this family — including for\n`LEFTB`, whose own article no longer says.\n\n\n\n### Arguments\n\n\n`text` — required, the text string containing the characters to extract.\n\n`num_bytes` — optional, specifying how many characters to extract **in bytes**. The\ncorresponding `LEFT` argument is documented as defaulting to 1, requiring a value greater than\nor equal to zero, and returning the whole text when it exceeds the length; the same shape is\nthe natural reading here, and this page treats it as the expected behaviour rather than a\ndocumented one, since the retrieved article states those rules for `LEFT` under the name\n`num_chars`.\n\n\n" }, "signature": { "display": "LEFTB(text, [num_bytes])", "parameters": [ { "description": null, "name": "text", "optional": false, "repeats": false }, { "description": null, "name": "num_bytes", "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": "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": "The first characters of a text, counted in bytes for double-byte languages", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the leftmost characters from a text value", "microsoft_url": "https://support.microsoft.com/en-us/office/left-function-9203d2d2-7960-479b-84c6-1ea52b99640c" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "LEFTB" }, { "locale": "bg-BG", "name": "LEFTB" }, { "locale": "cs-CZ", "name": "LEFTB" }, { "locale": "da-DK", "name": "VENSTREB" }, { "locale": "de-DE", "name": "LEFTB" }, { "locale": "el-GR", "name": "LEFTB" }, { "locale": "en-AU", "name": "LEFTB" }, { "locale": "en-GB", "name": "LEFTB" }, { "locale": "en-US", "name": "LEFTB" }, { "locale": "es-ES", "name": "IZQUIERDAB" }, { "locale": "et-EE", "name": "LEFTB" }, { "locale": "fi-FI", "name": "VASENB" }, { "locale": "fr-FR", "name": "GAUCHEB" }, { "locale": "he-IL", "name": "LEFTB" }, { "locale": "hr-HR", "name": "LEFTB" }, { "locale": "hu-HU", "name": "BAL2" }, { "locale": "id-ID", "name": "LEFTB" }, { "locale": "it-IT", "name": "LEFTB" }, { "locale": "ja-JP", "name": "LEFTB" }, { "locale": "ko-KR", "name": "LEFTB" }, { "locale": "lt-LT", "name": "LEFTB" }, { "locale": "lv-LV", "name": "LEFTB" }, { "locale": "nb-NO", "name": "LEFTB" }, { "locale": "nl-NL", "name": "LINKSB" }, { "locale": "pl-PL", "name": "LEWYB" }, { "locale": "pt-BR", "name": "LEFTB" }, { "locale": "pt-PT", "name": "ESQUERDAB" }, { "locale": "ro-RO", "name": "LEFTB" }, { "locale": "ru-RU", "name": "ЛЕВБ" }, { "locale": "sk-SK", "name": "LEFTB" }, { "locale": "sl-SI", "name": "LEFTB" }, { "locale": "sr-Latn-RS", "name": "LEFTB" }, { "locale": "sv-SE", "name": "VÄNSTERB" }, { "locale": "th-TH", "name": "LEFTB" }, { "locale": "tr-TR", "name": "SOLB işlevleri" }, { "locale": "uk-UA", "name": "LEFTB" }, { "locale": "vi-VN", "name": "LEFTB" }, { "locale": "zh-CN", "name": "LEFTB" }, { "locale": "zh-HK", "name": "LEFTB" }, { "locale": "zh-TW", "name": "LEFTB" } ], "signature": { "display": "LEFTB(text, [num_bytes])", "parameters": [ { "description": null, "name": "text", "optional": false, "repeats": false }, { "description": null, "name": "num_bytes", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "LEFTB", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/left-function-9203d2d2-7960-479b-84c6-1ea52b99640c" }, "try_it": { "formula": "=LEFTB(\"handbook\",4)" }, "url": "https://handbook.dnacalc.com/functions/LEFTB.html", "variants": [], "versions": [] }