{ "category": "Text functions", "display_name": "UNICHAR", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.UNICHAR", "implementation_state": { "answer_bank": null, "detail": "Recorded: 285 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 285 recorded answers", "workbook_corpus": { "cells": 285, "matched": 285 } }, "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#L252-L255", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/text_kernels.rs#L442-L453" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "ported/text_kernels::text_from_str" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_functions.rs#L252-L255", "state": "matches", "suite": null, "summary": "Matches all 285 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.UNICHAR.json", "name": "UNICHAR", "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- `CHAR` — the older, narrower counterpart. `CHAR` takes a number in a single-byte range and is\n interpreted through the system character set; `UNICHAR` takes a Unicode code point directly.\n `CHAR` is not deprecated and is not superseded by `UNICHAR`; the two answer different questions,\n and they agree only over the ASCII range.\n- `CODE` — `CHAR`'s inverse, and the older counterpart to `UNICODE`.\n- `TEXT`, `VALUE` — unrelated despite the naming; those convert between numbers and *formatted*\n representations, not between numbers and code points.\n- Readers confuse `UNICHAR(65)` with `\"65\"`. It is `\"A\"`.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n- **Truncate before validating, and say which you do first.** `UNICHAR(65.9)` and `UNICHAR(-0.5)`\n land differently depending on the order, and the second is the interesting one: truncation toward\n zero turns `-0.5` into `0`, which is documented as an error anyway, but truncation toward\n negative infinity would give `-1`. Order matters for the error *reason*, and may matter for the\n error at all.\n- **Decide the surrogate policy explicitly.** Rust's `char`, .NET's `Rune`, and Python's `chr`\n disagree about lone surrogates: two of them refuse, one produces them. Whichever your host\n language does by default will silently become your `UNICHAR` behaviour if you do not intervene.\n- **Do not route through UTF-8 and back.** A round trip through a UTF-8 string type will reject or\n mangle exactly the inputs whose behaviour is most in question. Work in UTF-16 code units, which\n is the model the worksheet uses.\n- **The result must be able to hold an unpaired surrogate** if you decide to admit one, which means\n your text type cannot be a validated-UTF-8 or validated-UTF-16 string. The value-universe chapter\n records that ill-formed UTF-16 is a reachable state in Excel by another route (interop\n truncation splitting a pair), so this is not a hypothetical requirement.\n- **Lift over arrays.** The sweep idiom depends on it.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Text`: a string of one Unicode scalar, which is one or two UTF-16 code units.\n\n`UNICHAR` is a scalar kernel and lifts elementwise over array arguments; the rules, including\nelement-local errors, are in [coercion and lifting](../model/02-coercion-and-lifting.md). This is\nwhat makes `UNICHAR(SEQUENCE(n) + k)` the standard idiom for generating a character sweep, and it\nis worth knowing that a single bad element in that sweep yields an error in that cell only, not a\nfailed call.\n\nSpecific edges:\n\n- **`UNICHAR(10)` and `UNICHAR(13)`** produce line-break characters, which is the usual reason to\n reach for this function outside Unicode work — though `CHAR` is the more common idiom there.\n- **`UNICHAR(160)`** produces the non-breaking space, the character [`TRIM`](FUNC.TRIM.md) does\n not remove. This pairing is the standard repair for web-pasted text.\n- **Errors propagate** from the argument ahead of any domain check.\n- **An empty referenced cell** delivers `Empty`, which is distinct from an omitted argument; see\n [the value universe](../model/01-value-universe.md).\n\n\n\n### Errors\n\n\nMicrosoft's page is the authority on the documented error conditions and is linked below; the\nHandbook could not retrieve it while this entry was written, so this section states expectations to\nbe checked against it rather than quoting it.\n\n| Error | Status |\n|---|---|\n| `#VALUE!` for `number = 0`, negative, or above the largest valid code point | expected; confirm against Microsoft's page and by probe |\n| `#VALUE!` for text that does not read as a number | expected from the shared to-number coercion rule, not from a function-specific statement |\n| any error value, propagated from the argument | follows from the universal error-propagation rule in the coercion chapter |\n\nThe status of the surrogate range `0xD800`–`0xDFFF` is not something this page asserts at all. It\nis listed as an open probe below.\n\n\n", "sources": "- Microsoft Support, UNICHAR function —\n \n (the documented signature, description, and error conditions; the page was not retrievable while\n this entry was written, so it is cited by reference and its exact wording is not reproduced).\n- Handbook `content/model/01-value-universe.md` (text as UTF-16 code units; ill-formed UTF-16 as a\n reachable state), `02-coercion-and-lifting.md` (to-number coercion and array lifting).\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`UNICHAR` maps a number to the text consisting of the single Unicode character with that code\npoint.\n\nPrecisely: given a number `n`, truncate it to an integer, interpret that integer as a Unicode code\npoint, and return a one-character string containing it. \"One character\" here means one Unicode\nscalar value — which, in the UTF-16 code-unit model this Handbook uses for worksheet text (see\n[the value universe](../model/01-value-universe.md)), is *two* code units when the code point is\noutside the Basic Multilingual Plane. So `UNICHAR(128512)` is one character but occupies two code\nunits, and functions that count code units will say so.\n\nThe interesting part of `UNICHAR` is not the mapping, which is trivial, but the domain. Three\nregions of the integer line behave differently and the distinction is the whole function:\n\n1. **Valid scalar values** — `1` through `0xD7FF` and `0xE000` through `0x10FFFF`. These are the\n code points that can be encoded in UTF-16 and stored in a worksheet string.\n2. **Surrogate code points** — `0xD800` through `0xDFFF`. These are not characters. They exist\n only as the two halves of a UTF-16 surrogate pair, and asking for one on its own is a request\n for half a character. Whether Excel refuses this or produces an unpaired surrogate is exactly\n the kind of question this Handbook does not answer from memory; see below.\n3. **Out of range** — `0`, negatives, and anything above `0x10FFFF`. Microsoft's page documents\n these as errors.\n\nThis is why `UNICHAR` is the right tool for constructing test data. It is the only ordinary way to\nwrite an arbitrary code point into a worksheet from a formula, which makes it the entry point for\nprobing every other text function's Unicode behaviour.\n\n\n\n### Arguments\n\n\n`UNICHAR(number)`\n\n| Argument | Required | Meaning |\n|---|---|---|\n| `number` | yes | The Unicode code point, as a number. |\n\nThere is only one argument, and only one subtlety in it: it is a *number*, so text that reads as a\nnumber converts (see [coercion and lifting](../model/02-coercion-and-lifting.md)) and `TRUE`\nconverts to `1`. Fractional values are truncated toward zero rather than rejected — the Handbook\nstates that as the expected behaviour for this family and lists it below as unverified.\n\nThe argument is a code point, not a byte and not a UTF-16 code unit. That distinction is invisible\nbelow `0x10000` and decisive above it.\n\n\n" }, "signature": { "display": "UNICHAR(number)", "parameters": [ { "description": null, "name": "number", "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": "Custom", "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": "Character with a given Unicode code point", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the Unicode character that is references by the given numeric value", "microsoft_url": "https://support.microsoft.com/en-us/office/unichar-function-ffeb64f5-f131-44c6-b332-5cd72f0659b8" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "UNICHAR" }, { "locale": "bg-BG", "name": "UNICHAR" }, { "locale": "cs-CZ", "name": "UNICHAR" }, { "locale": "da-DK", "name": "UNICHAR" }, { "locale": "de-DE", "name": "UNICHAR" }, { "locale": "el-GR", "name": "UNICHAR" }, { "locale": "en-AU", "name": "UNICHAR" }, { "locale": "en-GB", "name": "UNICHAR" }, { "locale": "en-US", "name": "UNICHAR" }, { "locale": "es-ES", "name": "UNICAR" }, { "locale": "et-EE", "name": "UNICHAR" }, { "locale": "fi-FI", "name": "UNICODEMERKKI" }, { "locale": "fr-FR", "name": "UNICAR*" }, { "locale": "he-IL", "name": "UNICHAR" }, { "locale": "hr-HR", "name": "UNICHAR" }, { "locale": "hu-HU", "name": "UNIKARAKTER" }, { "locale": "id-ID", "name": "UNICHAR" }, { "locale": "it-IT", "name": "UNICHAR" }, { "locale": "ja-JP", "name": "UNICHAR" }, { "locale": "ko-KR", "name": "UNICHAR" }, { "locale": "lt-LT", "name": "UNICHAR" }, { "locale": "lv-LV", "name": "UNICHAR" }, { "locale": "nb-NO", "name": "UNICHAR" }, { "locale": "nl-NL", "name": "UNITEKEN" }, { "locale": "pl-PL", "name": "ZNAK.UNICODE" }, { "locale": "pt-BR", "name": "UNICHAR" }, { "locale": "pt-PT", "name": "UNICARÁT" }, { "locale": "ro-RO", "name": "UNICHAR" }, { "locale": "ru-RU", "name": "ЮНИСИМВ" }, { "locale": "sk-SK", "name": "UNICHAR" }, { "locale": "sl-SI", "name": "UNICHAR" }, { "locale": "sr-Latn-RS", "name": "UNICHAR" }, { "locale": "sv-SE", "name": "UNITECKENKOD" }, { "locale": "th-TH", "name": "UNICHAR" }, { "locale": "tr-TR", "name": "UNICODEKARAKTERİ" }, { "locale": "uk-UA", "name": "UNICHAR" }, { "locale": "vi-VN", "name": "UNICHAR" }, { "locale": "zh-CN", "name": "UNICHAR" }, { "locale": "zh-HK", "name": "UNICHAR" }, { "locale": "zh-TW", "name": "UNICHAR" } ], "signature": { "display": "UNICHAR(number)", "parameters": [ { "description": null, "name": "number", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "UNICHAR", "version_marker": null, "xlcall": { "code": "580", "symbol": "xlfUnichar" } }, "microsoft": "https://support.microsoft.com/en-us/office/unichar-function-ffeb64f5-f131-44c6-b332-5cd72f0659b8" }, "try_it": { "formula": "=UNICHAR(128512)" }, "url": "https://handbook.dnacalc.com/functions/UNICHAR.html", "variants": [], "versions": [] }