{ "category": "Web functions", "display_name": "ENCODEURL", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.ENCODEURL", "implementation_state": { "answer_bank": null, "detail": "Recorded: 113 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 113 recorded answers", "workbook_corpus": { "cells": 113, "matched": 113 } }, "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#L938-L938", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L677-L700" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/text_format::profile", "catalogue/text_format::rendered", "catalogue/text_format::text", "decimal::low32", "decimal::Natural::zero", "decimal::Natural::from_u64", "decimal::Natural::pow10", "decimal::Natural::normalize", "decimal::Natural::is_zero", "decimal::Natural::mul_add_small", "decimal::Natural::times_pow10", "decimal::Natural::times_pow5", "decimal::Natural::times_pow2", "decimal::ExactDecimal::read", "decimal::ExactDecimal::binary", "format/datetime::has_invalid_exponent", "format/datetime::looks_like_datetime_format", "format/datetime::without_subseconds", "format/datetime::render_with_datetime_tokens", "format/datetime::tokenize_datetime_format", "format/datetime::elapsed_token_at", "format/datetime::classify_minute_tokens", "format/datetime::token_kind", "format/datetime::is_time_neighbor", "format/datetime::push_literal", "format/datetime::render_datetime_literal", "format/datetime::format_elapsed", "format/datetime::TimeParts::from_serial", "format::measured_host", "format::currency_literal", "format::digits", "format::fifteen", "format::split", "format::grouped", "format::general", "format::significant", "format::sections", "format::bracket", "format::is_condition", "format::is_elapsed", "format::condition_holds", "format::condition_of", "format::strip_tokens", "format::choose", "format::items", "format::numeric", "format::literal_text", "format::integer_part", "format::fraction_part", "format::scientific", "format::fraction_code", "format::FractionCode::render", "format::mixed_fraction_under_space_grouping", "format::convergent", "format::text_declared_date_locale", "format::text", "format::text_of_text", "format/names::month_name", "format/names::weekday_name", "format/names::locale_names", "locale::LocaleId::from_bcp47_language_tag", "locale::LocaleId::from_excel_lcid", "locale::short_date_order", "locale::short_date_pattern", "locale::currency_placement", "locale::currency_spacing", "locale::currency_negative_pattern", "locale::format_profile", "locale::days_from_civil", "locale::civil_from_days", "locale::ymd_from_excel_serial", "number_text::decimal", "number_text::first_precision", "number_text::near_tie", "number_text::first_rounding", "number_text::rounded", "number_text::increment", "number_text::ascii", "ported/date_kernels::whole_serial", "ported/date_kernels::whole", "ported/date_kernels::weekday_sunday_one_based", "ported/date_kernels::remap_weekday", "ported/date_kernels::weekday_of", "ported/date_kernels::weekday", "ported/text_kernels::text", "ported/text_kernels::text_from_str", "ported/text_kernels::date_integer_floor", "ported/text_kernels::push_singleton_or_original", "ported/text_kernels::push_upper", "ported/text_kernels::upper" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L938-L938", "state": "matches", "suite": null, "summary": "Matches all 113 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.ENCODEURL.json", "name": "ENCODEURL", "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- **`WEBSERVICE`** — the intended consumer. Microsoft's own examples compose them:\n `=WEBSERVICE(\"…?symbol=\"&ENCODEURL(C2))`, and the `WEBSERVICE` page recommends encoding the\n URL before use. The composition is the point of the function.\n- **`FILTERXML`** — the third member of the trio, applied to what `WEBSERVICE` returns.\n Microsoft's documented three-function idiom is\n `=FILTERXML(WEBSERVICE(\"…\"&ENCODEURL(C2)), \"//path\")`.\n- **`SUBSTITUTE`** — what workbooks used before `ENCODEURL` existed, chained once per character\n class. Anyone maintaining such a formula is looking at a hand-rolled, usually incomplete,\n version of this function.\n- **`HYPERLINK`** — frequently confused with it. `HYPERLINK` builds a clickable link;\n `ENCODEURL` produces text. Encoding a whole URL and passing it to `HYPERLINK` produces a link\n that does not resolve, for the component-encoder reason given above.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n- The unreserved set is the whole specification, and the documentation does not give it. RFC\n 3986 leaves `A–Z a–z 0–9 - . _ ~` unencoded; older `escape`-style encoders also pass `!`,\n `*`, `'`, `(`, `)`. Which of these Excel passes through is unknown to the Handbook and cannot\n be inferred from the single documented example, whose input contains none of them.\n- Percent-encoding operates on bytes, so a text-to-bytes step is required and its encoding\n choice is observable. UTF-8 is the modern assumption; a Windows-API-backed implementation\n could plausibly do something else for non-ASCII input.\n- Hexadecimal case (`%2F` versus `%2f`) is a free choice for an encoder and a fixed fact for a\n compatibility implementation. The documented example uses uppercase.\n- The output length can exceed the input length by up to a factor of nine for astral characters\n (four UTF-8 bytes at three characters each, from two UTF-16 input units). Any implementation\n that pre-sizes a buffer from input length is wrong.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nText. The published result is subject to the ordinary 32,767-code-unit cell limit described in\n[the value universe](../model/01-value-universe.md), and percent-encoding *expands* its input —\nup to threefold per byte — so a long input can cross the cap after encoding even though it was\ncomfortably under it before. That interaction is not something the documentation mentions and\nis the most likely practical failure mode.\n\nTwo edges the documentation leaves open, and which this page will not guess at:\n\n- **Empty input.** Whether an empty string or an empty referenced cell yields an empty string.\n- **Non-BMP characters.** Emoji and other astral characters occupy two UTF-16 code units each\n (see the value-universe chapter's text model). Percent-encoding is defined over *bytes*, so\n the function must be performing a UTF-8 (or other) transcoding step that the documentation\n never names.\n\n\n\n### Errors\n\n\nMicrosoft's `ENCODEURL` page documents no error conditions. That is not the same as the\nfunction being infallible — the cell text cap alone gives it a reachable failure mode — but the\nHandbook has nothing to cite here.\n\nThe platform restriction is stated firmly and belongs in this section as much as in any:\nMicrosoft documents that `ENCODEURL` is **not available in Excel for the web or Excel for Mac**,\nand adds that it \"may appear in Excel for Mac's function gallery, but it relies on Windows\noperating system features, so it will not return results on Mac\". A function that appears in\nthe gallery and then does not work is a distinct, poorly-signposted state, and it is\nparticularly striking for `ENCODEURL`, since percent-encoding has no obvious dependency on\nWindows at all. The dependency is inherited from the family's implementation, not from the\nmathematics.\n\n\n", "sources": "- Microsoft, \"ENCODEURL function\" —\n \n (syntax, the `text` argument, the worked encoding example quoted above, the composed\n `WEBSERVICE` and `FILTERXML` examples, and the Mac/web availability statement).\n- Microsoft, \"WEBSERVICE function\" —\n \n (the recommendation to encode URLs before inclusion in the formula).\n- Handbook `data/presence/FUNC.ENCODEURL.json` — the implementing module\n `earlier-implementation/web_text_xml_family.rs` and its surface-dispatch entry.\n- Handbook `content/model/01-value-universe.md` and `content/model/02-coercion-and-lifting.md`\n — the UTF-16 text model with its 32,767-code-unit cap, and the to-text coercion rules.\n- IETF RFC 3986, section 2.3 (unreserved characters) — named above as the standard against\n which the unknown character set would be compared, not as a statement of Excel's behaviour.\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`ENCODEURL` is the odd one out among Excel's three Web functions. `WEBSERVICE` makes a network\nrequest and `FILTERXML` parses what comes back; `ENCODEURL` does neither. It is a string\ntransformation, computable offline, deterministic, with no host and no service behind it.\n\n\n`ENCODEURL(text)` returns a URL-encoded copy of `text`: Microsoft's description is that it\nreplaces certain non-alphanumeric characters with \"the percentage symbol (%) and a hexadecimal\nnumber\".\n\nThe documented example fixes the *strength* of the encoding, which is the fact worth taking\naway from this page. Given\n\n```\nhttp://contoso.sharepoint.com/Finance/Profit and Loss Statement.xlsx\n```\n\nMicrosoft documents the result as\n\n```\nhttp%3A%2F%2Fcontoso.sharepoint.com%2FFinance%2FProfit%20and%20Loss%20Statement.xlsx\n```\n\nTwo things follow directly from that one example:\n\n1. **It is a component encoder, not a URL sanitizer.** The colon and the slashes of the scheme\n and path are themselves encoded (`%3A`, `%2F`). `ENCODEURL` does not preserve URL structure\n — it destroys it. Feeding a whole URL to `ENCODEURL` and using the result as a URL will not\n work. The function is for encoding *a value you are about to place inside* a URL: a query\n parameter, a path segment, a search term.\n2. **Space becomes `%20`, not `+`.** The two conventions differ (`+` belongs to\n `application/x-www-form-urlencoded`), and mixing them is a classic source of silently wrong\n query strings. The documented example settles which one Excel uses.\n\nThat is the whole of what the documentation pins. It does not enumerate the character set that\nsurvives unencoded, and it does not state how non-ASCII text is handled — both are listed under\nwhat has not been checked.\n\n\n\n### Arguments\n\n- **`text`** (required) — Microsoft: \"A string to be URL encoded\".\n\nThe function declares a `TextToText` kernel, so a non-text argument reaches it through ordinary\nscalar coercion — numbers and logicals convert to text under the rules in\n[coercion and lifting](../model/02-coercion-and-lifting.md), and an error argument propagates\nrather than being encoded. Nothing here is specific to `ENCODEURL`; the shared chapter governs\nit.\n\n\n" }, "signature": { "display": "ENCODEURL(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": "Web 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": "TextToText", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "None", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "Text made safe for a URL by percent-encoding", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns a URL-encoded string", "microsoft_url": "https://support.microsoft.com/en-us/office/encodeurl-function-07c7fb90-7c60-4bff-8687-fac50fe33d0e" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "ENCODEURL" }, { "locale": "bg-BG", "name": "ENCODEURL" }, { "locale": "cs-CZ", "name": "ENCODEURL" }, { "locale": "da-DK", "name": "KODNINGSURL" }, { "locale": "de-DE", "name": "ENCODEURL" }, { "locale": "el-GR", "name": "ENCODEURL" }, { "locale": "en-AU", "name": "ENCODEURL" }, { "locale": "en-GB", "name": "ENCODEURL" }, { "locale": "en-US", "name": "ENCODEURL" }, { "locale": "es-ES", "name": "URLCODIF" }, { "locale": "et-EE", "name": "ENCODEURL" }, { "locale": "fi-FI", "name": "URLKOODAUS" }, { "locale": "fr-FR", "name": "URLENCODAGE*" }, { "locale": "he-IL", "name": "ENCODEURL" }, { "locale": "hr-HR", "name": "ENCODEURL" }, { "locale": "hu-HU", "name": "URL.KÓDOL" }, { "locale": "id-ID", "name": "ENCODEURL" }, { "locale": "it-IT", "name": "ENCODEURL" }, { "locale": "ja-JP", "name": "ENCODEURL" }, { "locale": "ko-KR", "name": "ENCODEURL" }, { "locale": "lt-LT", "name": "ENCODEURL" }, { "locale": "lv-LV", "name": "ENCODEURL" }, { "locale": "nb-NO", "name": "URL.KODE" }, { "locale": "nl-NL", "name": "URL.CODEREN" }, { "locale": "pl-PL", "name": "ENCODEURL" }, { "locale": "pt-BR", "name": "ENCODEURL" }, { "locale": "pt-PT", "name": "CODIFICAÇÃOURL" }, { "locale": "ro-RO", "name": "ENCODEURL" }, { "locale": "ru-RU", "name": "КОДИР.URL" }, { "locale": "sk-SK", "name": "ENCODEURL" }, { "locale": "sl-SI", "name": "ENCODEURL" }, { "locale": "sr-Latn-RS", "name": "ENCODEURL" }, { "locale": "sv-SE", "name": "KODAWEBBADRESS" }, { "locale": "th-TH", "name": "ENCODEURL" }, { "locale": "tr-TR", "name": "URLKODLA" }, { "locale": "uk-UA", "name": "ENCODEURL" }, { "locale": "vi-VN", "name": "ENCODEURL" }, { "locale": "zh-CN", "name": "ENCODEURL" }, { "locale": "zh-HK", "name": "ENCODEURL" }, { "locale": "zh-TW", "name": "ENCODEURL" } ], "signature": { "display": "ENCODEURL(text)", "parameters": [ { "description": null, "name": "text", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "ENCODEURL", "version_marker": null, "xlcall": { "code": "597", "symbol": "xlfEncodeurl" } }, "microsoft": "https://support.microsoft.com/en-us/office/encodeurl-function-07c7fb90-7c60-4bff-8687-fac50fe33d0e" }, "try_it": { "formula": "=ENCODEURL(\"abc\")" }, "url": "https://handbook.dnacalc.com/functions/ENCODEURL.html", "variants": [], "versions": [] }