{ "category": "Text functions", "display_name": "REGEXREPLACE", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.REGEXREPLACE", "implementation_state": { "answer_bank": null, "detail": "Recorded: 8 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 8 recorded answers", "workbook_corpus": { "cells": 8, "matched": 8 } }, "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#L937-L937", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L515-L548" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/text_format::read_value", "catalogue/text_format::value", "catalogue/text_format::profile", "catalogue/text_format::rendered", "catalogue/text_format::text", "catalogue/text_format::given", "catalogue/text_format::binary_flag", "catalogue/text_format::case_sensitive", "catalogue/text_format::regex", "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::days_from_civil", "ported/date_kernels::civil_from_days", "ported/date_kernels::serial_unbounded_1900", "ported/date_kernels::ymd_1900", "ported/date_kernels::is_leap", "ported/date_kernels::days_in_month", "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::is_well_formed", "ported/text_kernels::upper", "ported/text_more::is_word_char", "ported/text_more::chars_equal", "ported/text_more::range_contains", "ported/text_more::folded_range", "ported/text_more::class_item_matches", "ported/text_more::is_word_boundary", "ported/text_more::zero_width_atom_matches", "ported/text_more::atom_consumes_input", "ported/text_more::consuming_atom_matches", "ported/text_more::match_atom_once", "ported/text_more::match_tokens_from", "ported/text_more::find_first_match_from", "ported/text_more::find_all_matches", "ported/text_more::escaped_literal_char", "ported/text_more::parse_escape_atom", "ported/text_more::parse_class_piece", "ported/text_more::parse_char_class", "ported/text_more::parse_regex_pattern", "ported/text_more::regex_matches", "value_text::measured_host_reader", "value_text::measured_space", "value_text::read", "value_text::number", "value_text::decimal", "value_text::fraction", "value_text::tokens", "value_text::month_named", "value_text::time_at", "value_text::full_year", "value_text::valid_day", "value_text::this_year", "value_text::serial_1900", "value_text::date_of", "value_text::date_time" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L937-L937", "state": "matches", "suite": null, "summary": "Matches all 8 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.REGEXREPLACE.json", "name": "REGEXREPLACE", "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- [`REGEXTEST`](FUNC.REGEXTEST.md) — the predicate. Use it to find out whether a replace would do\n anything.\n- [`REGEXEXTRACT`](FUNC.REGEXEXTRACT.md) — the extractor. Same engine; returns the match instead of\n rewriting around it.\n- `SUBSTITUTE` — the direct predecessor and still the right tool for literal text. It takes an\n `instance_num` in the same spirit as `occurrence`, and upstream records its rules for the current\n baseline: an empty `old_text` leaves the source unchanged, and `instance_num < 1` is `#VALUE!`.\n `SUBSTITUTE` is not superseded and is clearer for any non-pattern replacement.\n- `REPLACE` — positional replacement by start and length; a different job entirely despite the\n near-identical name. Readers confuse `REPLACE` and `REGEXREPLACE` constantly; the first takes\n character positions, the second takes a pattern.\n- [`TRIM`](FUNC.TRIM.md) — worth mentioning because `REGEXREPLACE(x, \"\\s+\", \" \")` is the obvious\n \"trim with a wider whitespace set\" idiom, and is the standard workaround for `TRIM` not touching\n non-breaking spaces. Whether Excel's `\\s` includes the non-breaking space is itself unprobed.\n- `TEXTJOIN`, [`TEXTSPLIT`](FUNC.TEXTSPLIT.md) — the delimiter tools, usually a better fit than a\n regex when the structure really is a separator.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n- **Decide and document the default-occurrence question.** It is the single most visible behaviour\n of the function and the sources consulted here do not settle it. Do not copy a default from\n another language's `replace`.\n- **Decide whether `replacement` is a template or a literal**, and be loud about it. If it is a\n template, `$` becomes a metacharacter and every user string containing a dollar sign is a latent\n bug; if it is literal, capture-group substitution is impossible and users will ask why.\n- **Advance past zero-width matches** or the global replace does not terminate.\n- **Splice, do not rebuild by repeated search.** Repeatedly searching the partially rewritten string\n can match text that the replacement itself introduced — a classic and silent defect.\n- **The escape set is part of the contract.** The upstream record's live-Excel comparison lists as\n admitted, on the build it tested: `\\d \\D \\w \\W \\s \\S`; `\\A \\Z \\z \\b \\B`; `\\n \\t \\r \\f \\v \\e \\h`;\n and the escaped literals `\\. \\* \\+ \\? \\[ \\] \\( \\) \\| \\^ \\$ \\/ \\\\`; and lists unknown letter\n escapes such as `\\q \\k \\m \\g \\p \\c \\x \\y \\j \\o` as rejected. Upstream observation on one Excel\n build, not a Handbook claim.\n- **Check the result against the text cap** and decide which failure you implement.\n- **Bound the match effort**, or a pathological pattern hangs a recalculation.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind is `Text`.\n\n- **No match returns the input unchanged.** This is the natural reading and is how every replace\n function in common use behaves, but note that it differs from\n [`REGEXEXTRACT`](FUNC.REGEXEXTRACT.md), which returns `#N/A` on no match. If your formula needs\n to know whether anything was replaced, `REGEXREPLACE` will not tell you — pair it with\n [`REGEXTEST`](FUNC.REGEXTEST.md).\n- **Zero-width matches need an advance rule.** A pattern that can match the empty string, replaced\n globally, would otherwise loop or insert the replacement between every character. Which of those\n Excel does is unprobed.\n- **The result can grow past the text cap.** Replacing a short pattern with a long replacement in a\n long string is the easiest way in the text family to exceed 32,767 code units. The cap and its\n two enforcement paths are described in [the value universe](../model/01-value-universe.md).\n- **Non-text arguments coerce to text** by the ordinary rules in\n [coercion and lifting](../model/02-coercion-and-lifting.md). The generated battery rows that pass\n a number in all three positions are coercion artefacts, not regex behaviour.\n- **Errors propagate** ahead of matching.\n- **An empty referenced cell** delivers `Empty`, distinct from an omitted argument.\n- **Array arguments** are not asserted here.\n\n\n\n### Errors\n\n\nMicrosoft's page is the authority on documented error conditions; it was not retrievable while this\nentry was written, so this section states bases rather than quoting it.\n\n| Error | Basis |\n|---|---|\n| any error value arriving in an argument | propagates, per the universal rule in the coercion chapter |\n| `#VALUE!` for a pattern the engine will not compile | expected; the exact rejected set is **not** established |\n| `#VALUE!` for an `occurrence` outside the admitted domain (`0`, negative, non-integer) | expected; unprobed |\n| `#VALUE!` if the result exceeds the text cap on the formula path | expected from the value-universe chapter; unprobed for this function |\n\n\n", "sources": "- Microsoft Support, REGEXREPLACE function —\n \n (the authority for the signature, argument names and documented errors; not retrievable while\n this entry was written, so it is cited by reference and nothing here paraphrases it).\n- Microsoft Support, REGEXTEST function —\n \n (retrieved; carries the family-wide PCRE2 statement).\n- Handbook `content/model/01-value-universe.md` (the text cap), `02-coercion-and-lifting.md`.\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`REGEXREPLACE` finds matches of a regular expression in a string and substitutes replacement text\nfor them, returning the rewritten string.\n\nThe operation is: scan `text` for non-overlapping matches of `pattern` from the left; for the\nmatch or matches selected by the `occurrence` argument, splice `replacement` in place of the\nmatched substring; leave everything else untouched; return the result. The unmatched parts of the\nstring pass through verbatim, which is what distinguishes a *replace* from an *extract*.\n\nThe dialect is PCRE2, per the family statement on Microsoft's `REGEXTEST` page.\n\nWhat the same replay does pin, as an upstream observation, is the selective form:\n`REGEXREPLACE(\"abc123def\", \"[a-z]+\", \"X\", 2) -> abc123X` — a positive `occurrence` of `2` rewriting\nthe second match and leaving the first alone.\n\n\n\n### Arguments\n\n\n`REGEXREPLACE(text, pattern, replacement, [occurrence], [case_sensitivity])`\n\n| Argument | Required | Meaning |\n|---|---|---|\n| `text` | yes | The text to rewrite. |\n| `pattern` | yes | The regular expression identifying what to replace. |\n| `replacement` | yes | The text substituted for each selected match. |\n| `occurrence` | no | Which match to replace. Upstream records a positive `n` as replacing the `n`-th match; the omitted default is unresolved — see above. |\n| `case_sensitivity` | no | `0` case-sensitive, `1` case-insensitive, matching the family's polarity. |\n\n" }, "signature": { "display": "REGEXREPLACE(text, pattern, replacement, [occurrence], [case_sensitivity])", "parameters": [ { "description": null, "name": "text", "optional": false, "repeats": false }, { "description": null, "name": "pattern", "optional": false, "repeats": false }, { "description": null, "name": "replacement", "optional": false, "repeats": false }, { "description": null, "name": "occurrence", "optional": true, "repeats": false }, { "description": null, "name": "case_sensitivity", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 5, "min": 3 }, "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": "Text with the matches of a regular expression replaced", "short_source": "dna-calc-own" }, "docs": { "english_description": "Replaces strings within the provided text that matches the pattern with replacement", "microsoft_url": "https://support.microsoft.com/en-us/office/regexreplace-function-9c030bb2-5e47-4efc-bad5-4582d7100897" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "REGEXREPLACE" }, { "locale": "bg-BG", "name": "REGEXREPLACE" }, { "locale": "cs-CZ", "name": "REGEXNAHRADIT" }, { "locale": "da-DK", "name": "REGEXERSTAT" }, { "locale": "de-DE", "name": "REGEXREPLACE" }, { "locale": "el-GR", "name": "REGEXREPLACE" }, { "locale": "en-AU", "name": "REGEXREPLACE" }, { "locale": "en-GB", "name": "REGEXREPLACE" }, { "locale": "en-US", "name": "REGEXREPLACE" }, { "locale": "es-ES", "name": "REGEXREEMPLAZAR" }, { "locale": "et-EE", "name": "REGEXREPLACE" }, { "locale": "fi-FI", "name": "REGEXKORVAA" }, { "locale": "fr-FR", "name": "REGEX.REMPLACER*" }, { "locale": "he-IL", "name": "REGEXREPLACE" }, { "locale": "hr-HR", "name": "REGEXREPLACE" }, { "locale": "hu-HU", "name": "REGKIFCSERE" }, { "locale": "id-ID", "name": "REGEXREPLACE" }, { "locale": "it-IT", "name": "REGEXREPLACE" }, { "locale": "ja-JP", "name": "REGEXREPLACE" }, { "locale": "ko-KR", "name": "REGEXREPLACE" }, { "locale": "lt-LT", "name": "REGEXREPLACE" }, { "locale": "lv-LV", "name": "REGEXREPLACE" }, { "locale": "nb-NO", "name": "REGEXREPLACE" }, { "locale": "nl-NL", "name": "REGEXVERVANGEN" }, { "locale": "pl-PL", "name": "REGEXZASTĄP" }, { "locale": "pt-BR", "name": "REGEXREPLACE" }, { "locale": "pt-PT", "name": "REGEX.SUBSTITUIR" }, { "locale": "ro-RO", "name": "REGEXREPLACE" }, { "locale": "ru-RU", "name": "РЕГЗАМЕНИТЬ" }, { "locale": "sk-SK", "name": "REGEXREPLACE" }, { "locale": "sl-SI", "name": "REGEXREPLACE" }, { "locale": "sr-Latn-RS", "name": "REGEXREPLACE" }, { "locale": "sv-SE", "name": "REGEXERSÄTT" }, { "locale": "th-TH", "name": "REGEXREPLACE" }, { "locale": "tr-TR", "name": "NORMİFADEDEĞİŞTİR" }, { "locale": "uk-UA", "name": "REGEXREPLACE" }, { "locale": "vi-VN", "name": "REGEXREPLACE" }, { "locale": "zh-CN", "name": "REGEXREPLACE" }, { "locale": "zh-HK", "name": "REGEXREPLACE" }, { "locale": "zh-TW", "name": "REGEXREPLACE" } ], "signature": { "display": "REGEXREPLACE(text, pattern, replacement, [occurrence], [case_sensitivity])", "parameters": [ { "description": null, "name": "text", "optional": false, "repeats": false }, { "description": null, "name": "pattern", "optional": false, "repeats": false }, { "description": null, "name": "replacement", "optional": false, "repeats": false }, { "description": null, "name": "occurrence", "optional": true, "repeats": false }, { "description": null, "name": "case_sensitivity", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "REGEXREPLACE", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/regexreplace-function-9c030bb2-5e47-4efc-bad5-4582d7100897" }, "try_it": { "formula": "=REGEXREPLACE(\"a1b2c3\", \"\\d\", \"X\")" }, "url": "https://handbook.dnacalc.com/functions/REGEXREPLACE.html", "variants": [], "versions": [] }