{ "category": "Text functions", "display_name": "CHAR", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.CHAR", "implementation_state": { "answer_bank": null, "detail": "Recorded: 145 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 145 recorded answers", "workbook_corpus": { "cells": 145, "matched": 145 } }, "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#L244-L247", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/text_kernels.rs#L372-L385" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_functions.rs#L244-L247", "state": "matches", "suite": null, "summary": "Matches all 145 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.CHAR.json", "name": "CHAR", "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- **`CODE`** is the inverse direction — character to number — and shares the same\n host-character-set dependency and therefore the same open question.\n- **`UNICHAR`** and **`UNICODE`** are the Unicode-explicit pair. They are the functions to\n reach for when the code point matters and the host must not: `UNICHAR` takes a Unicode code\n point rather than a byte-sized index. `CHAR` is not deprecated in favour of them; both pairs\n are live.\n- Readers routinely reach for `CHAR(10)` to embed a line break in a formula-built string, and\n for `CHAR(34)` to embed a double quote. Neither use is a special case in the function; they\n are just the two control characters that formula text cannot easily carry literally.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\nThe interesting decision is the 128–159 window. In Windows-1252 (the encoding usually meant by\n\"ANSI\" on a Western Windows install) that window holds printable characters — the euro sign,\ncurly quotes, the en and em dashes — mapped to Unicode code points scattered far outside\n128–159. In a \"code unit equals code number\" implementation the same window holds the C1\ncontrol characters. A program that treats `CHAR` as `chr()` over UTF-16 code units and one that\ntreats it as a Windows-1252 decode agree everywhere except here, and disagree visibly on the\nmost commonly typed non-ASCII characters in English text.\n\nA second decision follows from the first: \"the ANSI character set\" is not one encoding. The\nsystem ANSI code page differs by Windows locale (1252, 1251, 1250, 932, …), so a faithful\nhost-dependent implementation is locale-sensitive in a way the function's axis chips do not\ncurrently record.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Text`, always exactly one character long when the call succeeds.\n\nTwo boundaries are specific enough to state:\n\n- **Non-integer arguments.** The admissible range is documented as a range of numbers, not of\n integers, so some truncation or rounding rule must exist. Which one Excel applies —\n truncation toward zero, floor, or round-half-away — is not stated in Microsoft's article and\n has not been checked here.\n- **Excel for the web.** Microsoft's article carries an explicit platform restriction: on Excel\n for the web only `CHAR(9)`, `CHAR(10)`, `CHAR(13)` and `CHAR(32)` and above are supported.\n This is a documented per-surface difference, not a quirk of one build, and any implementation\n claiming to match \"Excel\" must say which Excel.\n\nArray arguments, empty cells and omitted arguments follow the shared call model; nothing about\n`CHAR` overrides it.\n\n\n\n### Errors\n\nError inputs propagate rather than convert, per the universal rule in\n[chapter 02](../model/02-coercion-and-lifting.md).\n\n\n", "sources": "- Microsoft, \"CHAR function\" —\n \n (argument range 1–255; the ANSI/Macintosh character-set statement; the Excel-for-the-web\n restriction). Retrieved for this page.\n- Handbook `content/model/01-value-universe.md` (what `Text` is) and\n `content/model/02-coercion-and-lifting.md` (to-number coercion, 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`CHAR` maps a small integer to the single character that the integer designates *in some\ncharacter set*, and returns that character as a one-character text value. The whole content of\nthe function is the question \"which character set?\", and the answer is not a mathematical\nconstant: Microsoft's article states that the character returned comes from the character set\nused by your computer, and names two — the ANSI character set on Windows, the Macintosh\ncharacter set on Macintosh.\n\nSo the function is best read as a two-step composition, not a one-step map:\n\n1. the argument is truncated to an integer and checked against the admissible range 1–255;\n2. that integer is interpreted as an index into a host-dependent single-byte character set, and\n the resulting character is delivered as `Text` — which, in the Handbook's value model, is a\n sequence of UTF-16 code units (see [the value universe](../model/01-value-universe.md)).\n\nStep 2 is where implementations can legitimately differ, because the two steps only agree\ntrivially on the ASCII subrange 32–126, where every candidate encoding coincides. Above 127 the\nidentity \"code number 128 means the character U+0080\" and the identity \"code number 128 means\nthe Windows-1252 character €\" are different functions, and the argument range 1–255 spans both.\n\n\n\n### Arguments\n\n\n`number` — required, the code number. Microsoft's article states it as a number between 1 and\n255 specifying which character you want. The argument is numeric, so the ordinary to-number\ncoercion of [chapter 02](../model/02-coercion-and-lifting.md) applies: a logical, or text that\nreads as a number, converts before the range check.\n\nThere is no second argument and no encoding selector. A formula that needs a specific encoding\ncannot express it through `CHAR`; that is the reason `UNICHAR` exists.\n\n\n" }, "signature": { "display": "CHAR(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": "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": "Character with a given code in the system character set", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the character specified by the code number", "microsoft_url": "https://support.microsoft.com/en-us/office/char-function-bbd249c8-b36e-4a91-8017-1c133f9b837a" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "CHAR" }, { "locale": "bg-BG", "name": "CHAR" }, { "locale": "cs-CZ", "name": "CHAR" }, { "locale": "da-DK", "name": "TEGN" }, { "locale": "de-DE", "name": "CHAR" }, { "locale": "el-GR", "name": "CHAR" }, { "locale": "en-AU", "name": "CHAR" }, { "locale": "en-GB", "name": "CHAR" }, { "locale": "en-US", "name": "CHAR" }, { "locale": "es-ES", "name": "CARÁCTER" }, { "locale": "et-EE", "name": "CHAR" }, { "locale": "fi-FI", "name": "CHAR" }, { "locale": "fr-FR", "name": "CHAR" }, { "locale": "he-IL", "name": "CHAR" }, { "locale": "hr-HR", "name": "CHAR" }, { "locale": "hu-HU", "name": "CHAR" }, { "locale": "id-ID", "name": "CHAR" }, { "locale": "it-IT", "name": "CODICE.CARATT" }, { "locale": "ja-JP", "name": "CHAR" }, { "locale": "ko-KR", "name": "CHAR" }, { "locale": "lt-LT", "name": "CHAR" }, { "locale": "lv-LV", "name": "CHAR" }, { "locale": "nb-NO", "name": "CHAR" }, { "locale": "nl-NL", "name": "TEKEN" }, { "locale": "pl-PL", "name": "CHAR" }, { "locale": "pt-BR", "name": "CHAR" }, { "locale": "pt-PT", "name": "CHAR" }, { "locale": "ro-RO", "name": "CHAR" }, { "locale": "ru-RU", "name": "СИМВОЛ" }, { "locale": "sk-SK", "name": "CHAR" }, { "locale": "sl-SI", "name": "CHAR" }, { "locale": "sr-Latn-RS", "name": "CHAR" }, { "locale": "sv-SE", "name": "CHAR" }, { "locale": "th-TH", "name": "CHAR" }, { "locale": "tr-TR", "name": "DAMGA" }, { "locale": "uk-UA", "name": "CHAR" }, { "locale": "vi-VN", "name": "CHAR" }, { "locale": "zh-CN", "name": "CHAR" }, { "locale": "zh-HK", "name": "CHAR" }, { "locale": "zh-TW", "name": "CHAR" } ], "signature": { "display": "CHAR(number)", "parameters": [ { "description": null, "name": "number", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "CHAR", "version_marker": null, "xlcall": { "code": "111", "symbol": "xlfChar" } }, "microsoft": "https://support.microsoft.com/en-us/office/char-function-bbd249c8-b36e-4a91-8017-1c133f9b837a" }, "try_it": { "formula": "=CHAR(9)" }, "url": "https://handbook.dnacalc.com/functions/CHAR.html", "variants": [], "versions": [] }