{ "category": "Text functions", "display_name": "TRIM", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.TRIM", "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#L283-L286", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/text_kernels.rs#L402-L421" ], "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#L283-L286", "state": "matches", "suite": null, "summary": "Matches all 5 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.TRIM.json", "name": "TRIM", "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- `CLEAN` — the neighbouring \"tidy the text\" function, and the one `TRIM` is most often confused\n with. `CLEAN` removes non-printable control characters; `TRIM` normalises spaces. Neither does\n the other's job, and `TRIM(CLEAN(x))` is the common pairing.\n- `SUBSTITUTE` — removes or replaces a specified character. This is the escape hatch for\n whitespace `TRIM` will not touch, notably `UNICHAR(160)`.\n- [`TEXTSPLIT`](FUNC.TEXTSPLIT.md) with `ignore_empty` performs the same \"drop empty pieces\"\n operation on a general delimiter, which is `TRIM`'s rule in generalised form.\n- `TEXTJOIN` with `ignore_empty` set is the rejoining half of the same idea.\n- `TRIMRANGE` and the trim-reference operators are *not* related despite the name: they trim empty\n rows and columns from a reference, not spaces from a string.\n- `EXACT` and `=` comparisons are where untrimmed data usually announces itself, which is why\n `TRIM` shows up so often in lookup keys.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n- **The character set is the specification.** Implement `TRIM` against an explicit list of code\n points, not against a library's `is_whitespace` predicate. A Unicode-aware `is_whitespace`\n matches tab, newline, non-breaking space, en quad, ideographic space and more; the evidence\n recorded upstream says the non-breaking space at least survives Excel's `TRIM`. Using the\n language's default whitespace class here is the single most likely way to diverge.\n- **Collapse, don't just strip.** A port that reuses a host-language `trim()` produces wrong\n interior results for every string with a double space.\n- **Tabs and newlines are a separate question** from the non-breaking space, and this Handbook\n does not have an answer for them. Do not assume they behave like the space just because the\n language you are porting from groups them together.\n- **The 32,767-code-unit text cap** applies to the result as to any string; see\n [the value universe](../model/01-value-universe.md). `TRIM` only ever shortens, so it cannot\n create a cap violation, but it can be the step that makes an over-long input fit.\n- **Lift a single array-valued argument** rather than rejecting arrays outright — that is the\n behaviour the upstream record pins.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Text`. `TRIM` of the empty string is the empty string; `TRIM` of a string of\nnothing but spaces is the empty string.\n\nOther boundaries:\n\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.** `TRIM` has no error-masking policy.\n- **Astral characters are unaffected**, but note that the model's text is a sequence of UTF-16\n code units, so a `TRIM` implemented over code units and one implemented over Unicode scalars will\n agree here only because no space character is astral. Do not generalise from that to the rest of\n the text family.\n\n\n\n### Errors\n\n\nMicrosoft's page documents no error conditions for `TRIM` beyond the ordinary ones (see Sources).\nIn practice the reachable errors are:\n\n| Error | Condition |\n|---|---|\n| any error value | Propagated from the argument; coercion does not discard worksheet errors. |\n| `#VALUE!` | An argument whose kind has no text conversion in this context. |\n\nThe Handbook has not established which argument kinds fall in that second row for `TRIM`\nspecifically.\n\n\n", "sources": "- Microsoft Support, TRIM function —\n \n (the authority on the documented description and on which space characters are in scope; the\n page was not retrievable at the time this entry was written, so it is cited by reference only and\n nothing on this page paraphrases it).\n- Handbook `content/model/01-value-universe.md` (text as UTF-16 code units, the 32,767 cap),\n `02-coercion-and-lifting.md` (to-text coercion, lifting, 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`TRIM` is not the `trim` you know from other languages. Most languages' `trim` removes leading and\ntrailing whitespace and leaves the interior alone. Excel's `TRIM` also **collapses interior runs**.\n\nThe rule, stated exactly: take the text, delete every leading space, delete every trailing space,\nand replace each remaining run of consecutive spaces with a single space. Equivalently — and this\nis the formulation to implement — split the text on spaces, discard empty pieces, and rejoin with\none space between pieces.\n\nTwo things follow that catch people out:\n\n1. **`TRIM` is not idempotent-by-accident, it is idempotent by construction.** `TRIM(TRIM(x))` is\n `TRIM(x)`, because the output contains no leading, trailing, or doubled spaces by definition.\n2. **`TRIM` changes the interior of your data.** If your text is fixed-width or contains\n deliberate alignment padding, `TRIM` destroys it. `SUBSTITUTE(x, \" \", \"\")` removes spaces;\n `TRIM` normalises them; they are different tools and neither is a general \"clean up\" function.\n\n\n### Arguments\n\n\n`TRIM(text)`\n\n| Argument | Required | Meaning |\n|---|---|---|\n| `text` | yes | The text to normalise. |\n\nThere is exactly one argument and no options. There is no way to ask `TRIM` to strip the ends\nwithout collapsing the interior, and no way to widen its notion of whitespace.\n\nNon-text arguments convert to text first, by the ordinary rules in\n[coercion and lifting](../model/02-coercion-and-lifting.md): a number arrives as its general-format\nrendering, `TRUE` as the string `TRUE`. Since none of those renderings contains a space that a\nnaïve reading would expect to survive, `TRIM` of a non-text scalar is generally that scalar's text\nform unchanged.\n\n\n" }, "signature": { "display": "TRIM(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 spaces removed at both ends and runs of spaces inside cut to one", "short_source": "dna-calc-own" }, "docs": { "english_description": "Removes spaces from text", "microsoft_url": "https://support.microsoft.com/en-us/office/trim-function-410388fa-c5df-49c6-b16c-9e5630b479f9" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "TRIM" }, { "locale": "bg-BG", "name": "TRIM" }, { "locale": "cs-CZ", "name": "TRIM" }, { "locale": "da-DK", "name": "TRIM" }, { "locale": "de-DE", "name": "TRIM" }, { "locale": "el-GR", "name": "TRIM" }, { "locale": "en-AU", "name": "TRIM" }, { "locale": "en-GB", "name": "TRIM" }, { "locale": "en-US", "name": "TRIM" }, { "locale": "es-ES", "name": "TRIM" }, { "locale": "et-EE", "name": "TRIM" }, { "locale": "fi-FI", "name": "POISTA.VÄLIT" }, { "locale": "fr-FR", "name": "SUPPRESPACE" }, { "locale": "he-IL", "name": "TRIM" }, { "locale": "hr-HR", "name": "TRIM" }, { "locale": "hu-HU", "name": "TRIM" }, { "locale": "id-ID", "name": "TRIM" }, { "locale": "it-IT", "name": "TRIM" }, { "locale": "ja-JP", "name": "TRIM" }, { "locale": "ko-KR", "name": "TRIM" }, { "locale": "lt-LT", "name": "TRIM" }, { "locale": "lv-LV", "name": "TRIM" }, { "locale": "nb-NO", "name": "TRIM" }, { "locale": "nl-NL", "name": "TRIM" }, { "locale": "pl-PL", "name": "TRIM" }, { "locale": "pt-BR", "name": "TRIM" }, { "locale": "pt-PT", "name": "TRIM" }, { "locale": "ro-RO", "name": "TRIM" }, { "locale": "ru-RU", "name": "TRIM" }, { "locale": "sk-SK", "name": "TRIM" }, { "locale": "sl-SI", "name": "TRIM" }, { "locale": "sr-Latn-RS", "name": "TRIM" }, { "locale": "sv-SE", "name": "TRIM" }, { "locale": "th-TH", "name": "TRIM" }, { "locale": "tr-TR", "name": "KIRP" }, { "locale": "uk-UA", "name": "TRIM" }, { "locale": "vi-VN", "name": "TRIM" }, { "locale": "zh-CN", "name": "TRIM" }, { "locale": "zh-HK", "name": "TRIM" }, { "locale": "zh-TW", "name": "TRIM" } ], "signature": { "display": "TRIM(text)", "parameters": [ { "description": null, "name": "text", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "TRIM", "version_marker": null, "xlcall": { "code": "118", "symbol": "xlfTrim" } }, "microsoft": "https://support.microsoft.com/en-us/office/trim-function-410388fa-c5df-49c6-b16c-9e5630b479f9" }, "try_it": { "formula": "=TRIM({\" a \",\" b \"})" }, "url": "https://handbook.dnacalc.com/functions/TRIM.html", "variants": [], "versions": [] }