{ "category": "Text functions", "display_name": "CLEAN", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.CLEAN", "implementation_state": { "answer_bank": null, "detail": "Recorded: 5 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 5 recorded answers", "workbook_corpus": { "cells": 5, "matched": 5 } }, "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#L287-L290", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/text_kernels.rs#L463-L471" ], "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#L287-L290", "state": "matches", "suite": null, "summary": "Matches all 5 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.CLEAN.json", "name": "CLEAN", "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- **`TRIM`** is the whitespace sibling: it removes leading and trailing spaces and collapses\n runs of interior spaces. `CLEAN` and `TRIM` partition the usual import-cleanup job between\n them, and neither does the other's work.\n- **`SUBSTITUTE`** is the escape hatch for the characters `CLEAN` documents itself as leaving\n behind (127, 129, 141, 143, 144, 157), and for the non-breaking space (160), which is not in\n `CLEAN`'s set and is not a space to `TRIM` either. Import-cleanup formulas in the wild are\n usually `TRIM(CLEAN(SUBSTITUTE(x, CHAR(160), \" \")))` for exactly this reason.\n- **`ASC`** and **`DBCS`** are the other width- and encoding-normalising text functions; they\n change characters rather than delete them.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n1. **The removal set is the specification.** Write it as data, not as a range test, so it can\n be diffed against evidence when evidence exists. The two candidate sets differ only at six\n values, and a range test hides that.\n2. **Filter, do not replace.** Indices into the input are invalidated by `CLEAN`, so any code\n that cleans a string and then applies a previously computed `FIND` position is wrong.\n3. **Operate on code units, not on decoded characters.** Decoding first is harmless for\n correctness here but forces a decision about ill-formed UTF-16, which the value-universe\n chapter records as a reachable state in Excel text.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Text`. Notable boundaries:\n\n- **Empty input** yields empty text — there is nothing to filter and nothing to add.\n- **All-nonprinting input** yields empty text, not an error. This is the case worth\n remembering, because a cell holding only control characters is indistinguishable after\n `CLEAN` from an empty cell in every downstream test except `ISBLANK`.\n- **Whitespace is not touched.** Space (32) is outside the removal range; tab (9) and the\n line-break characters (10, 13) are inside it. `CLEAN` therefore joins lines *without*\n inserting a separator — `\"a\" & CHAR(10) & \"b\"` cleans to `ab`, not `a b`. This is the single\n most common surprise, and it is the reason `CLEAN` and `TRIM` are almost always used\n together.\n- Arrays, empty cells and omitted arguments follow the shared call model\n ([chapter 03](../model/03-call-pipeline.md)).\n\n\n\n### Errors\n\n\nThe article does not enumerate error conditions for `CLEAN`, and none of the ordinary text\ninputs suggests one: the function has no domain to violate. The reachable errors are the shared\nones — an error value arriving as the argument propagates\n([chapter 02](../model/02-coercion-and-lifting.md)), and a value kind with no text conversion\nsurfaces `#VALUE!` under the shared coercion rules rather than under any rule of this\nfunction's own.\n\n\n", "sources": "- Microsoft, \"CLEAN function\" —\n \n (the 0–31 design statement; the named Unicode values 127, 129, 141, 143, 144, 157 that\n `CLEAN` does not remove). Retrieved for this page.\n- Handbook `content/model/01-value-universe.md` (UTF-16 code units, ill-formed text as a\n reachable state) and `content/model/02-coercion-and-lifting.md` (to-text conversion, error\n propagation).\n- Handbook `content/evidence/records/EV-STRUCT-0009.json` — cited only to state that `CLEAN`\n appears in that run's group member list and is not one of its subjects.\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`CLEAN` returns its argument with every character in a fixed set deleted. It is a filter, not a\nreplacer: removed characters leave nothing behind, so the result is never longer than the input\nand carries no substitute spaces.\n\nThe set is where the whole content of this function sits, and Microsoft's article is unusually\nexplicit about its history. `CLEAN` was designed to remove \"the first 32 nonprinting characters\nin the 7-bit ASCII code (values 0 through 31)\". The article then states the limitation in its\nown voice: in the Unicode character set there are additional nonprinting characters — it names\nvalues 127, 129, 141, 143, 144 and 157 — and `CLEAN` does not, by itself, remove them.\n\nFiltering is defined over UTF-16 code units (see\n[the value universe](../model/01-value-universe.md)), which matters only in that a surrogate\npair can never be hit by a set of values below 158, so astral characters survive `CLEAN`\nintact.\n\n\n\n### Arguments\n\n\n`text` — required. Microsoft's article describes it as any worksheet information from which you\nwant to remove nonprintable characters. It is a text argument, so a number or logical converts\nto text first and comes back as its rendering: `CLEAN` of a number is text, not a number.\n\nThere is no second argument. The removal set is not configurable, which is why the documented\nworkaround for the remaining Unicode nonprinting characters is to compose `SUBSTITUTE` calls\naround `CLEAN` rather than to parameterise it.\n\n\n" }, "signature": { "display": "CLEAN(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": "None", "host_interaction_class": "None", "kernel_signature_class": "TextToText", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "RefOnly", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "Text with the non-printing control characters taken out", "short_source": "dna-calc-own" }, "docs": { "english_description": "Removes all nonprintable characters from text", "microsoft_url": "https://support.microsoft.com/en-us/office/clean-function-26f3d7c5-475f-4a9c-90e5-4b8ba987ba41" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "CLEAN" }, { "locale": "bg-BG", "name": "CLEAN" }, { "locale": "cs-CZ", "name": "VYČISTIT" }, { "locale": "da-DK", "name": "RENS" }, { "locale": "de-DE", "name": "SÄUBERN" }, { "locale": "el-GR", "name": "CLEAN" }, { "locale": "en-AU", "name": "CLEAN" }, { "locale": "en-GB", "name": "CLEAN" }, { "locale": "en-US", "name": "CLEAN" }, { "locale": "es-ES", "name": "LIMPIAR" }, { "locale": "et-EE", "name": "CLEAN" }, { "locale": "fi-FI", "name": "TYHJENNÄ" }, { "locale": "fr-FR", "name": "EPURAGE" }, { "locale": "he-IL", "name": "CLEAN" }, { "locale": "hr-HR", "name": "CLEAN" }, { "locale": "hu-HU", "name": "TISZTÍT" }, { "locale": "id-ID", "name": "CLEAN" }, { "locale": "it-IT", "name": "LIBERA" }, { "locale": "ja-JP", "name": "CLEAN" }, { "locale": "ko-KR", "name": "CLEAN" }, { "locale": "lt-LT", "name": "CLEAN" }, { "locale": "lv-LV", "name": "CLEAN" }, { "locale": "nb-NO", "name": "RENS" }, { "locale": "nl-NL", "name": "WISSEN.CONTROL" }, { "locale": "pl-PL", "name": "OCZYŚĆ" }, { "locale": "pt-BR", "name": "LIMPAR" }, { "locale": "pt-PT", "name": "LIMPARB" }, { "locale": "ro-RO", "name": "CLEAN" }, { "locale": "ru-RU", "name": "ПЕЧСИМВ" }, { "locale": "sk-SK", "name": "CLEAN" }, { "locale": "sl-SI", "name": "CLEAN" }, { "locale": "sr-Latn-RS", "name": "OČISTI" }, { "locale": "sv-SE", "name": "STÄDA" }, { "locale": "th-TH", "name": "CLEAN" }, { "locale": "tr-TR", "name": "TEMİZ" }, { "locale": "uk-UA", "name": "CLEAN" }, { "locale": "vi-VN", "name": "CLEAN" }, { "locale": "zh-CN", "name": "CLEAN" }, { "locale": "zh-HK", "name": "CLEAN" }, { "locale": "zh-TW", "name": "CLEAN" } ], "signature": { "display": "CLEAN(text)", "parameters": [ { "description": null, "name": "text", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "CLEAN", "version_marker": null, "xlcall": { "code": "162", "symbol": "xlfClean" } }, "microsoft": "https://support.microsoft.com/en-us/office/clean-function-26f3d7c5-475f-4a9c-90e5-4b8ba987ba41" }, "try_it": { "formula": "=CLEAN(\"abc\")" }, "url": "https://handbook.dnacalc.com/functions/CLEAN.html", "variants": [], "versions": [] }