{ "category": "Text functions", "display_name": "DBCS", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.DBCS", "implementation_state": { "answer_bank": null, "detail": "Recorded: 17 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 17 recorded answers", "workbook_corpus": { "cells": 17, "matched": 17 } }, "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_format.rs#L930-L930" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/text_format::profile", "catalogue/text_format::width_conversion" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L930-L930", "state": "matches", "suite": null, "summary": "Matches all 17 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.DBCS.json", "name": "DBCS", "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- [`ASC`](FUNC.ASC.md) — the inverse direction, same host dependency, same module upstream. They\n are inverses in intent but not exactly: `DBCS(ASC(x))` need not be `x`, because narrowing loses\n the distinction between characters that share a half-width form and widening composes sequences\n that were not composed before.\n- `LENB`, `LEFTB`, `MIDB`, `FINDB`, `SEARCHB`, `REPLACEB` — the byte-oriented compatibility family\n that exists for the same East Asian reasons. Upstream records them as current-baseline delegates\n to their non-`B` counterparts, with `LENB` explicitly retaining UTF-16 code-unit counting after\n `LEN` moved to Unicode-scalar counting.\n- [`UPPER`](FUNC.UPPER.md) and `LOWER` — a different axis entirely. Width and case are independent.\n- Unicode NFKC normalisation goes the *other* way (it narrows), so it is not a substitute for\n `DBCS` in any direction.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n- **Query the host before transforming.** A port that always widens will disagree with Excel on\n every host where conversion is inactive — a configuration upstream actually observed.\n- **Compose the kana, do not map them.** The `ｶ` + `ﾞ` → `ガ` case requires a two-character lookahead\n and a composition table. An offset-based implementation over the ASCII range will pass every\n Latin test and fail every kana one.\n- **Handle the space explicitly.** `U+0020` → `U+3000` is outside the arithmetic range and is the\n most common non-Latin case in real data.\n- **Be prepared for the output to be shorter**, and do not size the output buffer from the input\n length without allowing for it.\n- **Record the host profile in every fixture.** Without it, a width-conversion result is not\n reproducible evidence.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Text`.\n\n- **The result can be shorter than the input** in UTF-16 code units, because of kana composition.\n The dual of the `ASC` warning: `LEN(DBCS(x)) >= LEN(x)` is not a safe assumption either.\n- **On a host where width conversion is inactive, `DBCS` is the identity.** This is what the\n upstream replay observed. A workbook that depends on `DBCS` therefore computes different values\n on different machines.\n- **Characters with no full-width form pass through.**\n- **Errors propagate**; an empty referenced cell delivers `Empty`, distinct from an omitted\n argument (see [the value universe](../model/01-value-universe.md)).\n- **The generated battery on this page cannot dispatch `DBCS`** — the upstream reference\n implementation reports it as requiring a host facility, so the standard probe rows have no\n outcome. That is the honest result for a function whose semantics are host-supplied.\n\n\n\n### Errors\n\n\nMicrosoft's page is the authority and is linked below; it was not retrievable while this entry was\nwritten, so this section states expectations rather than quoting it.\n\n", "sources": "- Microsoft Support, DBCS function —\n \n (the authority for signature and documented description; not retrievable while this entry was\n written, so it is cited by reference and nothing here paraphrases it).\n- Handbook `content/model/01-value-universe.md`, `02-coercion-and-lifting.md`.\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`DBCS` converts half-width (single-byte) characters in a string to their full-width (double-byte)\nequivalents. It is the inverse direction of [`ASC`](FUNC.ASC.md), and the background there applies\nhere unchanged: the half-width/full-width distinction comes from the legacy East Asian double-byte\ncharacter sets, where Latin letters, digits and katakana each had a one-column narrow form and a\ntwo-column wide form, and Unicode preserved both as separate code points. `DBCS` maps narrow to\nwide — `A` (U+0041) to `Ａ` (U+FF21), `ｱ` (U+FF71) to `ア` (U+30A2).\n\nThe widening direction has its own asymmetries, and they are not the mirror image of the narrowing\nones:\n\n1. **Widening can *shorten* the string.** The half-width sequence `ｶ` + `ﾞ` (base kana plus voiced\n sound mark) widens to the single character `ガ`. So `DBCS` performs a composition, which means it\n must look ahead: a character-by-character map is wrong precisely where the function is most\n used.\n2. **Almost everything ASCII has a full-width form.** Unlike narrowing, where much of the\n full-width repertoire has no counterpart, the `U+0021`–`U+007E` range maps cleanly into\n `U+FF01`–`U+FF5E`. That regularity makes the Latin half of `DBCS` deceptively easy and tempts\n implementers into an arithmetic offset that then mishandles the kana.\n3. **The space is a special case.** The ordinary space `U+0020` widens to the ideographic space\n `U+3000`, which is not in the arithmetic range.\n\nSo the operational definition is: *ask the environment whether width conversion is active; if it\nis, apply the half-width-to-full-width mapping with kana composition; if it is not, return the text\nunchanged.*\n\n\n\n### Arguments\n\n\n`DBCS(text)`\n\n| Argument | Required | Meaning |\n|---|---|---|\n| `text` | yes | The text containing characters to widen. |\n\nOne argument and no options. Non-text arguments convert to text by the ordinary rules in\n[coercion and lifting](../model/02-coercion-and-lifting.md) — which, note, means `DBCS(123)` asks\nabout the string `\"123\"` and would widen the digits if conversion were active.\n\n\n" }, "signature": { "display": "DBCS(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": "Composite", "host_interaction_class": "ApplicationState", "kernel_signature_class": "Custom", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "Composite", "thread_safety_class": "HostSerialized", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "Text with half-width (single-byte) characters turned into their full-width forms", "short_source": "dna-calc-own" }, "docs": { "english_description": "Changes half-width (single-byte) English letters or katakana within a character string to full-width (double-byte) characters", "microsoft_url": "https://support.microsoft.com/en-us/office/dbcs-function-a4025e73-63d2-4958-9423-21a24794c9e5" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "DBCS" }, { "locale": "bg-BG", "name": "DBCS" }, { "locale": "cs-CZ", "name": "DBCS" }, { "locale": "da-DK", "name": "DBCS" }, { "locale": "de-DE", "name": "DBCS" }, { "locale": "el-GR", "name": "DBCS" }, { "locale": "en-AU", "name": "DBCS" }, { "locale": "en-GB", "name": "DBCS" }, { "locale": "en-US", "name": "DBCS" }, { "locale": "es-ES", "name": "DBCS" }, { "locale": "et-EE", "name": "DBCS" }, { "locale": "fi-FI", "name": "DBCS" }, { "locale": "fr-FR", "name": "DBCS*" }, { "locale": "he-IL", "name": "DBCS" }, { "locale": "hr-HR", "name": "DBCS" }, { "locale": "hu-HU", "name": "KBKK" }, { "locale": "id-ID", "name": "DBCS" }, { "locale": "it-IT", "name": "DBCS" }, { "locale": "ja-JP", "name": "DBCS" }, { "locale": "ko-KR", "name": "DBCS" }, { "locale": "lt-LT", "name": "DBCS" }, { "locale": "lv-LV", "name": "DBCS" }, { "locale": "nb-NO", "name": "DBCS" }, { "locale": "nl-NL", "name": "DBCS" }, { "locale": "pl-PL", "name": "DBCS" }, { "locale": "pt-BR", "name": "DBCS" }, { "locale": "pt-PT", "name": "DBCS" }, { "locale": "ro-RO", "name": "DBCS" }, { "locale": "ru-RU", "name": "БДЦС" }, { "locale": "sk-SK", "name": "DBCS" }, { "locale": "sl-SI", "name": "DBCS" }, { "locale": "sr-Latn-RS", "name": "DBCS" }, { "locale": "sv-SE", "name": "DBCS" }, { "locale": "th-TH", "name": "DBCS" }, { "locale": "tr-TR", "name": "DBCS" }, { "locale": "uk-UA", "name": "DBCS" }, { "locale": "vi-VN", "name": "DBCS" }, { "locale": "zh-CN", "name": "DBCS" }, { "locale": "zh-HK", "name": "DBCS" }, { "locale": "zh-TW", "name": "DBCS" } ], "signature": { "display": "DBCS(text)", "parameters": [ { "description": null, "name": "text", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "DBCS", "version_marker": null, "xlcall": { "code": "215", "symbol": "xlfDbcs" } }, "microsoft": "https://support.microsoft.com/en-us/office/dbcs-function-a4025e73-63d2-4958-9423-21a24794c9e5" }, "try_it": { "formula": "=DBCS(123)" }, "url": "https://handbook.dnacalc.com/functions/DBCS.html", "variants": [], "versions": [] }