{ "category": "Text functions", "display_name": "REPLACEB", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.REPLACEB", "implementation_state": { "answer_bank": null, "detail": "Recorded: 7 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 7 recorded answers", "workbook_corpus": { "cells": 7, "matched": 7 } }, "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#L308-L311" ], "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::replace", "catalogue/text_functions::capped", "ported/text_kernels::text", "ported/text_kernels::unit_width", "ported/text_kernels::character_boundary", "ported/text_kernels::truncated", "ported/text_kernels::positive", "ported/text_kernels::nonnegative", "ported/text_kernels::replace" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_functions.rs#L308-L311", "state": "matches", "suite": null, "summary": "Matches all 7 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.REPLACEB.json", "name": "REPLACEB", "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- **[REPLACE](FUNC.REPLACE.md)** — the character-addressed twin, documented by Microsoft on the\n same page. The Handbook publishes them as two entries because they address in two different\n units.\n- **[SUBSTITUTE](FUNC.SUBSTITUTE.md)** — the by-content alternative, and the one to reach for\n under DBCS, because matching a substring sidesteps byte-offset arithmetic entirely. There is\n no `SUBSTITUTEB`; the by-content route simply does not need one.\n- `LENB` and `FINDB` are the functions that make `REPLACEB` usable at all, because they are the\n only ones that produce coordinates in the same byte space.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n`REPLACEB` inherits everything hard about `REPLACE` — three-piece reconstruction, growth past\nthe text cap, edges of the window past the end of the string — and adds the byte question on\ntop.\n\nThe practical consequence for verification: a `REPLACEB` test vector that does not record the\ndefault editing language is not a test vector. The same inputs legitimately produce two\ndifferent correct answers.\n\nThe mixed-unit boundary deserves an explicit, recorded decision. `old_text` arrives as UTF-16\ncode units; `start_num` and `num_bytes` are code-page bytes; `new_text` arrives as UTF-16\nagain. An implementation is converting between two coordinate systems on every call, and a\npartial-character window is where the conversion stops being a bijection.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Text`.\n\nMicrosoft's `REPLACE, REPLACEB` page states the signature and argument meanings and does not\nenumerate boundary behaviours. Everything below the signature is therefore unverified here.\n\nThe distinctively `REPLACEB` question is the one the documentation does not touch: **what\nhappens when `start_num` or `start_num + num_bytes` falls inside a double-byte character\nrather than on its boundary.** Overwriting half of a character has no obviously correct\nanswer — drop the partial character, keep its orphaned byte, round the boundary outward,\nerror — and Microsoft names none of them. Under DBCS this is not exotic: any arithmetic on\nbyte offsets over mixed-width text reaches it on the first mixed string.\n\n\n### Errors\n\n\nMicrosoft's page carries no error table for `REPLACEB`. The reachable errors are the shared\nones: an error value in any argument propagates, and non-numeric text in `start_num` or\n`num_bytes` surfaces `#VALUE!` under the shared coercion rules. Whether a partial-character\nwindow is an error condition is exactly the open question above.\n\n\n", "sources": "- Microsoft, \"REPLACE, REPLACEB functions\" —\n \n (signature, argument meanings, and the DBCS default-language condition for the B family).\n- Handbook, [The value universe](../model/01-value-universe.md) — worksheet text as UTF-16\n code units and the 32,767-unit cap, which the byte view must be reconciled against.\n- Handbook, [Coercion and lifting](../model/02-coercion-and-lifting.md) — numeric-argument\n coercion and error propagation.\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`REPLACEB(old_text, start_num, num_bytes, new_text)` returns `old_text` with the window of\n`num_bytes` **bytes** beginning at byte position `start_num` removed and `new_text` put in its\nplace. Byte positions are counted from 1.\n\nIt differs from [REPLACE](FUNC.REPLACE.md) in exactly one respect — the unit in which the\nwindow is addressed — and that difference only exists under one condition. Microsoft's rule for\nthe whole B family:\n\n> The B functions count each double-byte character as 2 **only when a DBCS language has been\n> enabled for editing and set as the default language**. Otherwise they count each character\n> as 1.\n\nOn a machine whose default editing language is not one of the DBCS languages, `REPLACEB` is\n`REPLACE`. On a machine whose default is Japanese, Chinese or Korean, the same formula\naddresses a different window of the same string. The active language is an unlisted input to\nthis function.\n\nThe bytes are those of the **DBCS code page for the active language** — Shift-JIS, GBK, Big5,\nEUC-KR — not UTF-8 and not UTF-16.\n\n\n\n### Arguments\n\n\n| Argument | Meaning |\n|---|---|\n| `old_text` | The string to modify. Required. |\n| `start_num` | 1-based **byte** position of the first byte to replace. Required. |\n| `num_bytes` | How many bytes to remove. Required. |\n| `new_text` | What to put in their place. Required. |\n\nAll four are required. The signature is `REPLACE`'s with `num_chars` renamed; the arity and\npositions are identical.\n\n`new_text` is inserted as text, not as bytes. There is no requirement that its byte length\nmatch `num_bytes`, and no documented rule connecting the two.\n\n\n" }, "signature": { "display": "REPLACEB(old_text, start_num, num_bytes, new_text)", "parameters": [ { "description": null, "name": "old_text", "optional": false, "repeats": false }, { "description": null, "name": "start_num", "optional": false, "repeats": false }, { "description": null, "name": "num_bytes", "optional": false, "repeats": false }, { "description": null, "name": "new_text", "optional": false, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 4, "min": 4 }, "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 with a span of bytes replaced by other text, for double-byte languages", "short_source": "dna-calc-own" }, "docs": { "english_description": "Replaces characters within text", "microsoft_url": "https://support.microsoft.com/en-us/office/replace-function-8d799074-2425-4a8a-84bc-82472868878a" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "REPLACEB" }, { "locale": "bg-BG", "name": "REPLACEB" }, { "locale": "da-DK", "name": "ERSTATB" }, { "locale": "de-DE", "name": "REPLACEB" }, { "locale": "el-GR", "name": "REPLACEB" }, { "locale": "en-AU", "name": "REPLACEB" }, { "locale": "en-GB", "name": "REPLACEB" }, { "locale": "en-US", "name": "REPLACEB" }, { "locale": "es-ES", "name": "REEMPLAZARB" }, { "locale": "et-EE", "name": "REPLACEB" }, { "locale": "fi-FI", "name": "KORVAAB" }, { "locale": "fr-FR", "name": "REMPLACERB" }, { "locale": "he-IL", "name": "REPLACEB" }, { "locale": "hr-HR", "name": "REPLACEB" }, { "locale": "hu-HU", "name": "CSERE2" }, { "locale": "id-ID", "name": "REPLACEB" }, { "locale": "it-IT", "name": "REPLACEB" }, { "locale": "ja-JP", "name": "REPLACEB" }, { "locale": "ko-KR", "name": "REPLACEB" }, { "locale": "lt-LT", "name": "REPLACEB" }, { "locale": "lv-LV", "name": "REPLACEB" }, { "locale": "nb-NO", "name": "REPLACEB" }, { "locale": "nl-NL", "name": "VERVANGENB" }, { "locale": "pl-PL", "name": "ZASTĄP.B" }, { "locale": "pt-BR", "name": "REPLACEB" }, { "locale": "pt-PT", "name": "SUBSTITUIRB" }, { "locale": "ro-RO", "name": "REPLACEB" }, { "locale": "ru-RU", "name": "ЗАМЕНИТЬБ" }, { "locale": "sk-SK", "name": "REPLACEB" }, { "locale": "sl-SI", "name": "REPLACEB" }, { "locale": "sr-Latn-RS", "name": "REPLACEB" }, { "locale": "sv-SE", "name": "ERSÄTTB" }, { "locale": "th-TH", "name": "REPLACEB" }, { "locale": "tr-TR", "name": "DEĞİŞTİRB işlevleri" }, { "locale": "uk-UA", "name": "REPLACEB" }, { "locale": "vi-VN", "name": "REPLACEB" }, { "locale": "zh-CN", "name": "REPLACEB" }, { "locale": "zh-HK", "name": "REPLACEB" }, { "locale": "zh-TW", "name": "REPLACEB" } ], "signature": { "display": "REPLACEB(old_text, start_num, num_bytes, new_text)", "parameters": [ { "description": null, "name": "old_text", "optional": false, "repeats": false }, { "description": null, "name": "start_num", "optional": false, "repeats": false }, { "description": null, "name": "num_bytes", "optional": false, "repeats": false }, { "description": null, "name": "new_text", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "REPLACEB", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/replace-function-8d799074-2425-4a8a-84bc-82472868878a" }, "try_it": { "formula": "=REPLACEB(\"日本語\", 3, 2, \"X\")" }, "url": "https://handbook.dnacalc.com/functions/REPLACEB.html", "variants": [], "versions": [] }