{ "category": "Text functions", "display_name": "FINDB", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.FINDB", "implementation_state": { "answer_bank": null, "detail": "Recorded: 6 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 6 recorded answers", "workbook_corpus": { "cells": 6, "matched": 6 } }, "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#L302-L302" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/text_functions::count_surrogate_pairs", "catalogue/text_functions::single_byte", "catalogue/text_functions::start", "catalogue/text_functions::find", "ported/text_kernels::text", "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::truncated", "ported/text_kernels::positive", "ported/text_kernels::find" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_functions.rs#L302-L302", "state": "matches", "suite": null, "summary": "Matches all 6 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.FINDB.json", "name": "FINDB", "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- **[`FIND`](FUNC.FIND.md)** is the character-counting partner, documented in the same article.\n It is the function to use unless you specifically need byte offsets.\n- **`SEARCHB`** is the case-insensitive, wildcard-aware byte variant — `FINDB` is to `SEARCHB`\n as `FIND` is to `SEARCH`.\n- **[`LEFTB`](FUNC.LEFTB.md), `RIGHTB`, `MIDB`, [`LENB`](FUNC.LENB.md), `REPLACEB`** are the\n rest of the byte-variant family, and are the functions a `FINDB` result must be fed into for\n the units to agree. Note that the `LEFT` and `LEN` articles now mark their byte variants\n deprecated and no longer state the DBCS mechanism at all; this article still does, which\n makes it the best surviving documentation of what byte counting means anywhere in the family.\n- **`ASC` and `DBCS`** convert between half-width and full-width forms.\n\n", "how-to-implement": "\n### Notes for implementers\n\n1. **Do not implement `FINDB` as `FIND`.** They coincide only under the non-DBCS condition, and\n aliasing them ships that specialisation. Say so if that is what you are shipping.\n2. **The DBCS condition is host state, not text state.** An implementation faithful to the\n documentation needs the enabled-languages and default-language settings as inputs, which\n makes this function's observation context wider than an Excel build and a platform.\n3. **Byte positions and character positions must not be interchanged internally**, or the bug\n the function exists to avoid reappears inside the implementation.\n4. **Write down the mid-character rules** for both `start_num` and the returned position.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Number`.\n\n- **A `start_num` or a result can fall inside a character.** This is the byte-variant hazard\n with no character-variant analogue: byte position 2 of a string beginning with a double-byte\n character is the second half of that character. What `FINDB` does when a match would begin\n there, and what it does when `start_num` names such a position, is undefined by every source\n this page can cite.\n- **Under the non-DBCS condition the function coincides with `FIND`**, per the article's own\n statement.\n- **Astral characters** have no natural DBCS byte length at all, and the Compatibility Version\n feature that Microsoft documents for surrogate handling elsewhere in the text family has no\n stated interaction with byte counting.\n\n\n\n### Errors\n\n\n- **`#VALUE!` when `find_text` does not appear in `within_text`** — stated in the article for\n both members of the pair.\n- Microsoft publishes a dedicated article on correcting `#VALUE!` in `FIND`/`FINDB` and\n `SEARCH`/`SEARCHB`.\n- Whether an out-of-range or mid-character `start_num` errors, and with which code, is not\n stated in the retrieved text.\n- Error inputs propagate, and a value kind with no text conversion surfaces `#VALUE!` under the\n shared coercion rules ([chapter 02](../model/02-coercion-and-lifting.md)).\n\n\n", "sources": "- Microsoft, \"FIND, FINDB functions\" —\n \n (the SBCS/DBCS paragraph, including the \"counts each double-byte character as 2 when you have\n enabled the editing of a language that supports DBCS and then set it as the default language\"\n condition; the argument descriptions; case sensitivity and the absence of wildcards; the\n `#VALUE!` on not-found). Retrieved for this page through a search result for that article; a\n direct request for the same URL did not serve it.\n- Microsoft, \"How to correct a #VALUE! error in FIND/FINDB and SEARCH/SEARCHB functions\" —\n \n- Handbook `CHARTER.md` section 4 (the seven split byte-variant rows).\n- Handbook `data/functions/FUNC.FINDB.json` (the paired description and localized-name\n projections 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`FINDB` locates one text string inside another and returns the starting position of the first\noccurrence, exactly as [`FIND`](FUNC.FIND.md) does — but the position is counted in **bytes**\nrather than in characters. It is case sensitive and does not allow wildcards, on the same terms\nas `FIND`.\n\nMicrosoft's article states the distinction more precisely than any other article in the\nbyte-variant set, and this page quotes its content rather than reconstructing it: `FIND` is\nintended for use with languages that use the **single-byte character set** (SBCS), whereas\n`FINDB` is intended for languages that use the **double-byte character set** (DBCS). `FIND`\nalways counts each character, whether single-byte or double-byte, as 1, no matter what the\ndefault language setting is. `FINDB` counts each double-byte character as 2 **when you have\nenabled the editing of a language that supports DBCS and then set it as the default language**.\n\nThat last clause is the part worth reading twice, because it makes `FINDB`'s answer depend on\nthree things rather than one:\n\n1. the text — how many of its characters are double-byte under the host encoding;\n2. the host's enabled editing languages;\n3. which of them is set as the default language.\n\nChange none of the text and only the third, and the same formula returns a different number.\nThis is the sharpest statement in Microsoft's documentation that the byte variants are\nenvironment-dependent functions, and it is why the Handbook publishes `FINDB` as a separate\nentry rather than as a note on `FIND`. (Seven published rows document a byte-variant pair this\nway; splitting all seven is the whole of the difference between 534 published Excel rows and\n541 Handbook entries.)\n\nTwo consequences follow directly. When the DBCS condition is not met, `FINDB` counts every\ncharacter as 1 and its results coincide with `FIND`'s — so an all-ASCII or Western-host test\nsuite cannot distinguish the two functions at all. And when it is met, a returned byte position\nis *not* a valid character position: feeding a `FINDB` result into `MID` rather than `MIDB` is\na byte/character unit error that produces plausible wrong answers rather than errors.\n\nThe article text retrieved for this page states the DBCS condition in terms of enabled and\ndefault editing languages, and does not, in that text, enumerate which languages support DBCS.\nThis page therefore does not name them.\n\n\n\n### Arguments\n\n\n`find_text` — required, the text you want to find.\n\n`within_text` — required, the text containing the text you want to find.\n\n`start_num` — optional, the character at which to start the search; the first character in\n`within_text` is character number 1, and omitting it is documented as assuming 1. Note that the\narticle's argument description speaks of *characters* for this argument while the returned\nposition is in bytes for `FINDB`; whether `start_num` is interpreted in bytes or characters\nunder the DBCS condition is a real question that the retrieved text does not resolve.\n\nAs with `FIND`, the needle comes first. `FINDB(within, needle)` is a silent bug.\n\n\n" }, "signature": { "display": "FINDB(find_text, within_text, [start_num])", "parameters": [ { "description": null, "name": "find_text", "optional": false, "repeats": false }, { "description": null, "name": "within_text", "optional": false, "repeats": false }, { "description": null, "name": "start_num", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 3, "min": 2 }, "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": "Position of one text inside another, case-sensitive, counted in bytes for double-byte languages", "short_source": "dna-calc-own" }, "docs": { "english_description": "Finds one text value within another (case-sensitive)", "microsoft_url": "https://support.microsoft.com/en-us/office/find-function-c7912941-af2a-4bdf-a553-d0d89b0a0628" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "FINDB" }, { "locale": "bg-BG", "name": "FINDB" }, { "locale": "cs-CZ", "name": "FINDB" }, { "locale": "da-DK", "name": "FINDB" }, { "locale": "de-DE", "name": "FINDENB" }, { "locale": "el-GR", "name": "FINDB" }, { "locale": "en-AU", "name": "FINDB" }, { "locale": "en-GB", "name": "FINDB" }, { "locale": "en-US", "name": "FINDB" }, { "locale": "es-ES", "name": "ENCONTRARB" }, { "locale": "et-EE", "name": "FINDB" }, { "locale": "fi-FI", "name": "ETSIB" }, { "locale": "fr-FR", "name": "TROUVERB" }, { "locale": "he-IL", "name": "FINDB" }, { "locale": "hr-HR", "name": "FINDB" }, { "locale": "hu-HU", "name": "SZÖVEG.TALÁL2" }, { "locale": "id-ID", "name": "FINDB" }, { "locale": "it-IT", "name": "TROVA.B" }, { "locale": "ja-JP", "name": "FINDB" }, { "locale": "ko-KR", "name": "FINDB" }, { "locale": "lt-LT", "name": "FINDB" }, { "locale": "lv-LV", "name": "FINDB" }, { "locale": "nb-NO", "name": "FINNB" }, { "locale": "nl-NL", "name": "VIND.ALLES.B." }, { "locale": "pl-PL", "name": "ZNAJDŹB" }, { "locale": "pt-BR", "name": "PROCURARB" }, { "locale": "pt-PT", "name": "LOCALIZARB" }, { "locale": "ro-RO", "name": "FINDB" }, { "locale": "ru-RU", "name": "НАЙТИБ" }, { "locale": "sk-SK", "name": "FINDB" }, { "locale": "sl-SI", "name": "FINDB" }, { "locale": "sr-Latn-RS", "name": "FINDB" }, { "locale": "sv-SE", "name": "HITTAB" }, { "locale": "th-TH", "name": "FINDB" }, { "locale": "tr-TR", "name": "BULB" }, { "locale": "uk-UA", "name": "FINDB" }, { "locale": "vi-VN", "name": "FINDB" }, { "locale": "zh-CN", "name": "FINDB" }, { "locale": "zh-HK", "name": "FINDB" }, { "locale": "zh-TW", "name": "FINDB" } ], "signature": { "display": "FINDB(find_text, within_text, [start_num])", "parameters": [ { "description": null, "name": "find_text", "optional": false, "repeats": false }, { "description": null, "name": "within_text", "optional": false, "repeats": false }, { "description": null, "name": "start_num", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "FINDB", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/find-function-c7912941-af2a-4bdf-a553-d0d89b0a0628" }, "try_it": { "formula": "=FINDB(\"\",\"abc\")" }, "url": "https://handbook.dnacalc.com/functions/FINDB.html", "variants": [], "versions": [] }