{
  "category": "Text functions",
  "display_name": "ASC",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.ASC",
  "implementation_state": {
    "answer_bank": null,
    "detail": "Recorded: 14 workbook cells.",
    "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87",
    "in_catalogue": true,
    "state": "matches",
    "state_label": "Matches every recorded Excel answer",
    "summary": "Matches all 14 recorded answers",
    "workbook_corpus": {
      "cells": 14,
      "matched": 14
    }
  },
  "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#L929-L929"
      ],
      "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#L929-L929",
      "state": "matches",
      "suite": null,
      "summary": "Matches all 14 recorded answers"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.ASC.json",
  "name": "ASC",
  "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- [`DBCS`](FUNC.DBCS.md) — the exact inverse direction: half-width to full-width. Same host\n  dependency, same module upstream.\n- `LEN` versus `LENB` — the width distinction shows up again in the byte-counting functions, and\n  the `*B` family (`LEFTB`, `MIDB`, `FINDB`, …) exists for the same East Asian reasons. Upstream\n  records those as current-baseline delegates to their non-`B` counterparts rather than as\n  independent byte-semantic implementations.\n- [`UPPER`](FUNC.UPPER.md) and `LOWER` — case conversion, frequently confused with width conversion\n  because both \"change the letters\". They are independent axes: `Ａ` and `ａ` differ in case, `A`\n  and `Ａ` differ in width.\n- Unicode's own NFKC normalisation performs a superset of `ASC`'s Latin mapping. It is not a\n  substitute — NFKC also folds ligatures, superscripts and much else.\n\n\n",
    "how-to-implement": "\n### Notes for implementers\n\n\n- **Do not implement this as a local text function without a host query.** The upstream design —\n  ask the host for the mode, then apply the transformation — is the shape that matches observed\n  behaviour. A port that always narrows will disagree with Excel on every host where conversion is\n  inactive, which upstream observed to include a real one.\n- **The mapping table must handle the voiced katakana decomposition**, which is one-to-two. Build it\n  as a table, not as an arithmetic offset, even though the Latin block is tantalisingly regular\n  (`U+FF01`–`U+FF5E` maps to `U+0021`–`U+007E` by subtracting `0xFEE0`).\n- **The full-width space `U+3000` maps to the ordinary space `U+0020`**, which interacts with\n  [`TRIM`](FUNC.TRIM.md): narrowing first can change what a later `TRIM` removes.\n- **Work in UTF-16 code units** and be prepared for the output to be longer.\n- **Record the host profile in any test fixture.** A width-conversion test with no environment\n  recorded is not reproducible, and is arguably not evidence at all.\n\n\n",
    "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Text`.\n\n- **Characters with no half-width form pass through**, so `ASC` applied to hiragana or kanji is the\n  identity.\n- **The result can be longer than the input** in UTF-16 code units, because of the voiced-katakana\n  decomposition described above. Any assumption that `LEN(ASC(x)) <= LEN(x)` is false in general —\n  it is false in exactly the case the function exists for.\n- **On a host where width conversion is not active, `ASC` is the identity function** on all input.\n  This is the case the upstream replay observed. A workbook that relies on `ASC` therefore computes\n  different values on different machines, which makes it unsuitable for anything auditable without\n  pinning the environment.\n- **Errors propagate**, and an empty referenced cell delivers `Empty` rather than a missing\n  argument; see [the value universe](../model/01-value-universe.md).\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`#NAME?` for an *existing* function is jarring, and worth explaining: it is the worksheet's answer\nwhen a name is not recognised in the current environment, which is what a compatibility function\nlooks like on a host that does not admit it.\n\n\n",
    "sources": "- Microsoft Support, ASC function —\n  <https://support.microsoft.com/en-us/office/asc-function-0b6abf1c-c663-4004-a964-ebc00b723266>\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` (text as UTF-16 code units, Empty versus Missing),\n  `02-coercion-and-lifting.md` (to-text coercion, 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`ASC` converts full-width (double-byte) characters in a string to their half-width (single-byte)\nequivalents.\n\nThe concepts come from East Asian text handling and predate Unicode. In the legacy double-byte\ncharacter sets used for Japanese, Korean and Chinese text, Latin letters, digits and katakana each\nexisted in two forms: a *half-width* form occupying one byte and one display column, and a\n*full-width* form occupying two bytes and two display columns. Unicode preserved both, so the\ndistinction survives as separate code points — `A` (U+0041) versus `Ａ` (U+FF21), `ｱ` (U+FF71)\nversus `ア` (U+30A2). `ASC` maps the wide forms down to the narrow ones. The mapping is not a\nrounding or an approximation; it is a table.\n\nTwo details make the katakana half of the mapping harder than the Latin half:\n\n1. **Voiced katakana are one character wide and two characters narrow.** Full-width `ガ` is a single\n   code point; its half-width form is the pair `ｶ` + `ﾞ` (a base kana and a combining-style voiced\n   sound mark). So `ASC` can *lengthen* a string, and a naive one-to-one mapping table is wrong.\n2. **Not everything has a half-width form.** Hiragana, kanji, and most full-width punctuation\n   outside the ASCII-mirror block have no narrow counterpart and pass through untouched.\n\nNow the part that matters most for this entry, and which is easy to get wrong by reading only the\nconcept: **whether `ASC` converts anything at all depends on the host environment.** The function is\npart of the East Asian compatibility surface, and its behaviour is tied to the language settings of\nthe Excel installation rather than being a fixed text transformation.\n\nSo the operational definition of `ASC` is two-stage: *ask the environment whether width conversion\nis active for this function; if it is, apply the full-width-to-half-width table; if it is not,\nreturn the text unchanged.* That is a genuinely unusual shape for a worksheet function, and it is\nthe reason this page is careful.\n\n\n\n### Arguments\n\n\n`ASC(text)`\n\n| Argument | Required | Meaning |\n|---|---|---|\n| `text` | yes | The text containing characters to narrow. |\n\nOne argument, no options — no way to ask for only the Latin part, only the katakana part, or a\nspecific mapping table. Non-text arguments convert to text by the ordinary rules in\n[coercion and lifting](../model/02-coercion-and-lifting.md).\n\n\n"
  },
  "signature": {
    "display": "ASC(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 full-width (double-byte) characters turned into their half-width forms",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": "Changes full-width (double-byte) English letters or katakana within a character string to half-width (single-byte) characters",
        "microsoft_url": "https://support.microsoft.com/en-us/office/asc-function-0b6abf1c-c663-4004-a964-ebc00b723266"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [
        {
          "locale": "ar-SA",
          "name": "ASC"
        },
        {
          "locale": "bg-BG",
          "name": "ASC"
        },
        {
          "locale": "cs-CZ",
          "name": "ASC"
        },
        {
          "locale": "da-DK",
          "name": "ASC"
        },
        {
          "locale": "de-DE",
          "name": "ASC"
        },
        {
          "locale": "el-GR",
          "name": "ASC"
        },
        {
          "locale": "en-AU",
          "name": "ASC"
        },
        {
          "locale": "en-GB",
          "name": "ASC"
        },
        {
          "locale": "en-US",
          "name": "ASC"
        },
        {
          "locale": "es-ES",
          "name": "ASC"
        },
        {
          "locale": "et-EE",
          "name": "ASC"
        },
        {
          "locale": "fi-FI",
          "name": "ASC"
        },
        {
          "locale": "fr-FR",
          "name": "ASC"
        },
        {
          "locale": "he-IL",
          "name": "ASC"
        },
        {
          "locale": "hr-HR",
          "name": "ASC"
        },
        {
          "locale": "hu-HU",
          "name": "ASC"
        },
        {
          "locale": "id-ID",
          "name": "ASC"
        },
        {
          "locale": "it-IT",
          "name": "ASC"
        },
        {
          "locale": "ja-JP",
          "name": "ASC"
        },
        {
          "locale": "ko-KR",
          "name": "ASC"
        },
        {
          "locale": "lt-LT",
          "name": "ASC"
        },
        {
          "locale": "lv-LV",
          "name": "ASC"
        },
        {
          "locale": "nb-NO",
          "name": "ASC"
        },
        {
          "locale": "nl-NL",
          "name": "ASC"
        },
        {
          "locale": "pl-PL",
          "name": "ASC"
        },
        {
          "locale": "pt-BR",
          "name": "ASC"
        },
        {
          "locale": "pt-PT",
          "name": "ASC"
        },
        {
          "locale": "ro-RO",
          "name": "ASC"
        },
        {
          "locale": "ru-RU",
          "name": "ASC"
        },
        {
          "locale": "sk-SK",
          "name": "ASC"
        },
        {
          "locale": "sl-SI",
          "name": "ASC"
        },
        {
          "locale": "sr-Latn-RS",
          "name": "ASC"
        },
        {
          "locale": "sv-SE",
          "name": "ASC"
        },
        {
          "locale": "th-TH",
          "name": "ASC"
        },
        {
          "locale": "tr-TR",
          "name": "ASC"
        },
        {
          "locale": "uk-UA",
          "name": "ASC"
        },
        {
          "locale": "vi-VN",
          "name": "ASC"
        },
        {
          "locale": "zh-CN",
          "name": "ASC"
        },
        {
          "locale": "zh-HK",
          "name": "ASC"
        },
        {
          "locale": "zh-TW",
          "name": "ASC"
        }
      ],
      "signature": {
        "display": "ASC(text)",
        "parameters": [
          {
            "description": null,
            "name": "text",
            "optional": false,
            "repeats": false
          }
        ],
        "trailing_repeats": false
      },
      "surface_name": "ASC",
      "version_marker": null,
      "xlcall": {
        "code": "214",
        "symbol": "xlfAsc"
      }
    },
    "microsoft": "https://support.microsoft.com/en-us/office/asc-function-0b6abf1c-c663-4004-a964-ebc00b723266"
  },
  "try_it": {
    "formula": "=ASC(\"ＡＢＣ　１２３\")"
  },
  "url": "https://handbook.dnacalc.com/functions/ASC.html",
  "variants": [],
  "versions": []
}