{
  "category": "Text functions",
  "display_name": "UNICODE",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.UNICODE",
  "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#L256-L259",
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/text_kernels.rs#L455-L461"
      ],
      "repository": "https://github.com/DnaCalc/DnaCalc",
      "shared_code": [
        "ported/text_kernels::text"
      ],
      "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_functions.rs#L256-L259",
      "state": "matches",
      "suite": null,
      "summary": "Matches all 6 recorded answers"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.UNICODE.json",
  "name": "UNICODE",
  "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- [`UNICHAR`](FUNC.UNICHAR.md) — the inverse direction and the sibling in the same implementation\n  module upstream. `UNICODE(UNICHAR(n)) = n` is the round trip.\n- `CODE` — the older counterpart. Upstream's text-core contract records `CODE` as reading only the\n  first UTF-16 code unit and rejecting empty text; `UNICODE` decodes a full scalar. Over the ASCII\n  range the two agree, which is why the difference goes unnoticed until it matters. `CODE` is not\n  superseded; it remains available and is the right function when you genuinely want the legacy\n  character-set number.\n- `CHAR` — `CODE`'s inverse, and the narrower counterpart to `UNICHAR`.\n- `LEN` and `LENB` — the other place where the scalar-versus-code-unit question is observable.\n  Upstream records these two as having diverged for supplementary-plane characters under a current\n  Excel compatibility version, with `LENB` retaining code-unit counting. Anyone reasoning about\n  `UNICODE` should read that fork note before assuming a consistent counting model across the\n  text family.\n- Confused with `VALUE`, which converts a numeral string to the number it denotes — a completely\n  different operation. `UNICODE(\"5\")` is `53`; `VALUE(\"5\")` is `5`.\n\n\n",
    "how-to-implement": "\n### Notes for implementers\n\n\n- **Decode, do not index.** Reading `s[0]` in a UTF-16 buffer gives a code unit. Decode the first\n  scalar, and handle the unpaired-surrogate case deliberately rather than by whatever your string\n  type does when it panics.\n- **Do not route through UTF-8.** A conversion step will reject or replace exactly the inputs whose\n  behaviour is in question.\n- **The result is a `Number`, so it is a double.** Every code point is exactly representable, but\n  do not let a 16-bit integer type into the signature.\n- **Empty text must be checked before decoding**, otherwise the failure surfaces as a panic or an\n  out-of-range read rather than as `#VALUE!`.\n- **Lift over arrays**, which is what makes the code-point-dump idiom work.\n\n\n",
    "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Number` — an integer-valued double, the code point.\n\n`UNICODE` is a scalar kernel and lifts elementwise over array arguments, per\n[coercion and lifting](../model/02-coercion-and-lifting.md); `UNICODE({\"A\",\"B\"})` is a two-element\nnumeric array. That makes `UNICODE` the natural companion to `MID` for dumping a string's code\npoints: `UNICODE(MID(t, SEQUENCE(LEN(t)), 1))`, with the caveat that slicing a supplementary-plane\ncharacter with `MID` may hand `UNICODE` half a pair — which is precisely the input the upstream\nnote observed erroring.\n\nOther edges:\n\n- **Empty text is an error, not zero.** There is no first character to report.\n- **An empty referenced cell** delivers `Empty`, distinct from an omitted argument; see\n  [the value universe](../model/01-value-universe.md).\n- **Errors propagate** from the argument.\n- **The result is not bounded by `0xFFFF`.** Any implementation or consumer that assumes a\n  16-bit result is wrong for emoji and for most of the CJK extensions.\n\n\n\n### Errors\n\n\nMicrosoft's page is the authority on the documented error conditions and is linked below; it was\nnot retrievable while this entry was written, so this section states expectations to be checked\nagainst it rather than quoting it.\n\n",
    "sources": "- Microsoft Support, UNICODE function —\n  <https://support.microsoft.com/en-us/office/unicode-function-adb74aaa-a2a5-4dde-aff6-966e4e81f16f>\n  (the authority for signature, description, and errors; 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` (UTF-16 code units, ill-formed UTF-16 as a\n  reachable state), `02-coercion-and-lifting.md` (to-text coercion of numeric arguments, lifting,\n  error propagation).\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`UNICODE` returns the Unicode code point of the **first character** of a string.\n\nThe whole content of the function is in what \"first character\" means, and this is a place where a\ncareless implementation and a careful one give different answers for real inputs. Worksheet text\nis a sequence of UTF-16 code units (see [the value universe](../model/01-value-universe.md)). If\nthe first code unit is a high surrogate and the second is a low surrogate, they jointly encode one\ncharacter in the supplementary planes. The choices are therefore:\n\n- return the first *code unit* — which for an emoji returns a surrogate value in `0xD800`–`0xDBFF`,\n  a number that is not a code point at all; or\n- decode the first *Unicode scalar* — which for an emoji returns the real code point, above\n  `0xFFFF`.\n\nSo the definition is: decode the first Unicode scalar of the argument text and return its code\npoint as a number. Everything after the first character is ignored.\n\n\n\n### Arguments\n\n\n`UNICODE(text)`\n\n| Argument | Required | Meaning |\n|---|---|---|\n| `text` | yes | The text whose first character's code point is returned. |\n\nOne argument, and one trap: the argument is *text*, so a number arrives as its general-format\nrendering and `UNICODE(0)` asks for the code point of the character `\"0\"` — that is, `48`, not `0`.\nThe generated battery on this page shows exactly that shape of result, and it is a coercion\nconsequence described in [coercion and lifting](../model/02-coercion-and-lifting.md), not a\nfunction-specific rule. Likewise `UNICODE(TRUE)` asks about the string `TRUE` and therefore about\nthe letter `T`.\n\nOnly the first character matters. `UNICODE(\"Hello\")` and `UNICODE(\"H\")` agree.\n\n\n"
  },
  "signature": {
    "display": "UNICODE(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": "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": "Unicode code point of the first character of a text",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": "Returns the number (code point) that corresponds to the first character of the text",
        "microsoft_url": "https://support.microsoft.com/en-us/office/unicode-function-adb74aaa-a2a5-4dde-aff6-966e4e81f16f"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [
        {
          "locale": "ar-SA",
          "name": "UNICODE"
        },
        {
          "locale": "bg-BG",
          "name": "UNICODE"
        },
        {
          "locale": "cs-CZ",
          "name": "UNICODE"
        },
        {
          "locale": "da-DK",
          "name": "UNICODE"
        },
        {
          "locale": "de-DE",
          "name": "UNICODE"
        },
        {
          "locale": "el-GR",
          "name": "UNICODE"
        },
        {
          "locale": "en-AU",
          "name": "UNICODE"
        },
        {
          "locale": "en-GB",
          "name": "UNICODE"
        },
        {
          "locale": "en-US",
          "name": "UNICODE"
        },
        {
          "locale": "es-ES",
          "name": "UNICODE"
        },
        {
          "locale": "et-EE",
          "name": "UNICODE"
        },
        {
          "locale": "fi-FI",
          "name": "UNICODE"
        },
        {
          "locale": "fr-FR",
          "name": "UNICODE*"
        },
        {
          "locale": "he-IL",
          "name": "UNICODE"
        },
        {
          "locale": "hr-HR",
          "name": "UNICODE"
        },
        {
          "locale": "hu-HU",
          "name": "UNICODE"
        },
        {
          "locale": "id-ID",
          "name": "UNICODE"
        },
        {
          "locale": "it-IT",
          "name": "UNICODE"
        },
        {
          "locale": "ja-JP",
          "name": "UNICODE"
        },
        {
          "locale": "ko-KR",
          "name": "UNICODE"
        },
        {
          "locale": "lt-LT",
          "name": "UNICODE"
        },
        {
          "locale": "lv-LV",
          "name": "UNICODE"
        },
        {
          "locale": "nb-NO",
          "name": "UNICODE"
        },
        {
          "locale": "nl-NL",
          "name": "UNICODE"
        },
        {
          "locale": "pl-PL",
          "name": "UNICODE"
        },
        {
          "locale": "pt-BR",
          "name": "UNICODE"
        },
        {
          "locale": "pt-PT",
          "name": "UNICODE"
        },
        {
          "locale": "ro-RO",
          "name": "UNICODE"
        },
        {
          "locale": "ru-RU",
          "name": "UNICODE"
        },
        {
          "locale": "sk-SK",
          "name": "UNICODE"
        },
        {
          "locale": "sl-SI",
          "name": "UNICODE"
        },
        {
          "locale": "sr-Latn-RS",
          "name": "UNIKOD"
        },
        {
          "locale": "sv-SE",
          "name": "UNICODE"
        },
        {
          "locale": "th-TH",
          "name": "UNICODE"
        },
        {
          "locale": "tr-TR",
          "name": "UNICODE"
        },
        {
          "locale": "uk-UA",
          "name": "UNICODE"
        },
        {
          "locale": "vi-VN",
          "name": "UNICODE"
        },
        {
          "locale": "zh-CN",
          "name": "UNICODE"
        },
        {
          "locale": "zh-HK",
          "name": "UNICODE"
        },
        {
          "locale": "zh-TW",
          "name": "UNICODE"
        }
      ],
      "signature": {
        "display": "UNICODE(text)",
        "parameters": [
          {
            "description": null,
            "name": "text",
            "optional": false,
            "repeats": false
          }
        ],
        "trailing_repeats": false
      },
      "surface_name": "UNICODE",
      "version_marker": null,
      "xlcall": {
        "code": "581",
        "symbol": "xlfUnicode"
      }
    },
    "microsoft": "https://support.microsoft.com/en-us/office/unicode-function-adb74aaa-a2a5-4dde-aff6-966e4e81f16f"
  },
  "try_it": {
    "formula": "=UNICODE(0)"
  },
  "url": "https://handbook.dnacalc.com/functions/UNICODE.html",
  "variants": [],
  "versions": []
}