{ "category": "Text functions", "display_name": "REGEXEXTRACT", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.REGEXEXTRACT", "implementation_state": { "answer_bank": null, "detail": "Recorded: 26 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 26 recorded answers", "workbook_corpus": { "cells": 26, "matched": 26 } }, "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#L936-L936", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L455-L513" ], "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#L936-L936", "state": "matches", "suite": null, "summary": "Matches all 26 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.REGEXEXTRACT.json", "name": "REGEXEXTRACT", "notes": [ { "basis": "22 recorded TEXTSPLIT and REGEXEXTRACT readings, questions 049 to 093.", "documentation": null, "evidence": [ { "commit": "78b470c77271d6af938e16d5493882b8300cee62", "locator": "roots 078 and 079", "note": "REGEXEXTRACT results in the product", "path": "apps/dna-onecalc/tests/acceptance.rs", "repository": "DnaCalc" } ], "functions": [ "FUNC.REGEXEXTRACT", "FUNC.TEXTSPLIT" ], "inferred": null, "kind": "quirk", "note_id": "FN-TEXTSPLIT-002", "open": [], "recorded_on": "2026-11-04", "repros": [ { "call": "=TEXTSPLIT({\"a,b,c\",\"d,e\"},\",\")", "correct": null, "excel": { "bits": null, "display": "{\"a\",\"d\"}", "kind": "array" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "eceb809985e244e9d0a20f905e58fe57b8741ed8", "locator": "sheet fn2_q049, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } }, { "call": "=TEXTSPLIT({\"a,b\"},\",\")", "correct": null, "excel": { "bits": null, "display": "a", "kind": "text" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "eceb809985e244e9d0a20f905e58fe57b8741ed8", "locator": "sheet fn2_q093, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } }, { "call": "=REGEXEXTRACT(\"a12b34\",\"[0-9]+\",{0,1,2})", "correct": null, "excel": { "bits": null, "display": "{\"12\",\"12\",#VALUE!}", "kind": "array" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "eceb809985e244e9d0a20f905e58fe57b8741ed8", "locator": "sheet fn2_q079, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } }, { "call": "=MAP({\"a,b\",\"c,d\"},LAMBDA(txt,TEXTSPLIT(txt,\",\")))", "correct": null, "excel": { "bits": null, "display": "#CALC!", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "eceb809985e244e9d0a20f905e58fe57b8741ed8", "locator": "sheet fn2_q088, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } }, { "call": "=BYROW({\"a,b\";\"c,d\"},LAMBDA(txt,TEXTSPLIT(txt,\",\")))", "correct": null, "excel": { "bits": null, "display": "{\"a\";\"c\"}", "kind": "array" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "eceb809985e244e9d0a20f905e58fe57b8741ed8", "locator": "sheet fn2_q089, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } } ], "schema": "efh.function-note/v1", "statement": "When TEXTSPLIT's text is an array, even a 1 by 1 array, the call lifts over the elements and each returns only its first piece. MAP over the same lambda gives #CALC!, while BYROW gives the first pieces. REGEXEXTRACT lifted over return_mode does the same, and mode 2 on a pattern with no capture group gives #VALUE!.", "status": "measured", "title": "Over an array, TEXTSPLIT and REGEXEXTRACT keep only the first piece of each element" } ], "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 version. Use it when you only need to know\n whether a match exists; it avoids the `#N/A`-handling that `REGEXEXTRACT` forces on you.\n- [`REGEXREPLACE`](FUNC.REGEXREPLACE.md) — the rewriting version, same engine.\n- [`TEXTAFTER`](FUNC.TEXTAFTER.md), [`TEXTBEFORE`](FUNC.TEXTBEFORE.md),\n [`TEXTSPLIT`](FUNC.TEXTSPLIT.md) — the delimiter-based extraction family. For anything that is\n genuinely delimiter-shaped, these are clearer, cheaper and far easier to audit than a regex.\n Reach for `REGEXEXTRACT` when the structure is a *pattern*, not a *separator*.\n- `MID` with `FIND`/`SEARCH` — the legacy extraction idiom. Not superseded; still the right tool\n when the position is known.\n- [`VALUE`](FUNC.VALUE.md) and `NUMBERVALUE` — the necessary second step whenever what you extracted\n was a number.\n- `FILTER` and `IFNA` — the usual companions for mode-1 results.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n- **Mode 2 is where the design decisions live.** Group numbering, group `0`, unmatched optional\n groups, named groups, and result orientation are five separate choices, and this Handbook has\n evidence for none of them. Write down what you chose.\n- **Advance past zero-width matches** in mode 1, or the all-matches loop does not terminate. The\n standard rule is to bump the search position by one when a match is empty; whether Excel does\n that, and whether the empty match is included in the output, is unprobed.\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 `\\. \\* \\+ \\? \\[ \\] \\( \\) \\| \\^ \\$ \\/ \\\\`. It lists unknown letter escapes\n such as `\\q \\k \\m \\g \\p \\c \\x \\y \\j \\o` as rejected. That is an upstream observation on one Excel\n build, not a Handbook claim; re-probe before depending on it.\n- **Results are text, so do not helpfully convert.** Returning a number because the match looked\n numeric would be a divergence from the documented contract.\n- **Decide the no-match shape for modes 1 and 2 explicitly**, since an empty array is not\n representable.\n- **Bound the match effort.** A pathological pattern in a recalculating workbook is a hang.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind depends on `return_mode`: `Text` in mode `0`, `Array` of text in modes `1` and `2`.\nArray results are published by the host-side adaptation step described in\n[the call pipeline](../model/03-call-pipeline.md), which is also where `#SPILL!` comes from.\n\n- **Everything comes back as text.** Documented, and worth repeating because it is the most common\n source of downstream surprise.\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 where a\n number is passed as both `text` and `pattern` are coercion artefacts, not regex behaviour.\n- **Errors propagate** ahead of matching.\n- **An empty referenced cell** delivers `Empty`, distinct from an omitted argument; see\n [the value universe](../model/01-value-universe.md).\n- **Array-valued `text`** — the obvious way to extract from a column — is not asserted here, and it\n interacts badly with modes `1` and `2` in any case: an array of arrays is not a value this model\n admits (see [the value universe](../model/01-value-universe.md)), so lifting cannot be\n unconditional.\n\n\n\n### Errors\n\n\nMicrosoft's page publishes no explicit error table for this function (confirmed on the retrieved\npage). What can be stated:\n\n", "sources": "- Microsoft Support, REGEXEXTRACT function —\n \n (retrieved for this page; source of the signature, the three `return_mode` values, and the note\n that results are always text and can be converted with `VALUE`. The page publishes no error\n table.)\n- Microsoft Support, REGEXTEST function —\n \n (retrieved; carries the family-wide statement that the regex flavour is PCRE2).\n- Handbook `content/model/01-value-universe.md`, `02-coercion-and-lifting.md`,\n `03-call-pipeline.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`REGEXEXTRACT` searches `text` for the regular expression `pattern` and returns what it matched.\n\nUnlike its siblings it is not one function but three, selected by `return_mode`, and the three\ndiffer in *shape* as well as in content:\n\n| `return_mode` | What is returned | Shape |\n|---|---|---|\n| `0` (default) | The first match | scalar text |\n| `1` | Every match, in order | array |\n| `2` | The capturing groups of the first match | array |\n\nThat table is the whole function, and each row deserves a sentence.\n\n**Mode 0** performs a leftmost search and returns the matched substring. Not the whole text, not\nthe position — the matched text itself.\n\n**Mode 1** returns all non-overlapping matches. This is the mode that makes `REGEXEXTRACT` a\ndynamic-array function: the result spills, and its length depends on the data, which is exactly the\ncase that dynamic arrays were introduced for. The scan order and the non-overlap rule are standard\nregex semantics (each search resumes after the previous match), though nothing consulted here\nstates how a zero-width match is advanced past — a real question, since a pattern that can match\nempty would otherwise loop.\n\n**Mode 2** returns the capture groups of the first match. This is the mode that turns a regex into\na parser: one pattern with parenthesised groups splits a string into its parts in a single call.\nNote what it does *not* say — whether group `0` (the whole match) is included, whether unmatched\noptional groups appear as empty strings or `#N/A`, and what the shape is (row or column). None of\nthose is settled here.\n\nThe dialect is PCRE2, documented on the family's `REGEXTEST` page. And one further documented note\nmatters more than it looks: **`REGEXEXTRACT` always returns text values.** Extracting `\"123\"` gives\nyou the string `\"123\"`, and Microsoft's page explicitly points you at `VALUE` to convert it — which\ndrags in every locale question on the [`VALUE`](FUNC.VALUE.md) page. For numeric extraction,\n`NUMBERVALUE` with explicit separators is the more portable second step.\n\n\n\n### Arguments\n\n\n`REGEXEXTRACT(text, pattern, [return_mode], [case_sensitivity])`\n\n| Argument | Required | Meaning (as documented by Microsoft) |\n|---|---|---|\n| `text` | yes | The text, or reference to a cell containing text, to extract from. |\n| `pattern` | yes | The regular expression describing what to extract. |\n| `return_mode` | no | `0` first match (default), `1` all matches as an array, `2` capturing groups of the first match. |\n| `case_sensitivity` | no | `0` case-sensitive, `1` case-insensitive. |\n\nTwo argument positions cause trouble.\n\n`return_mode` is the position readers get wrong when porting from other spreadsheet dialects, where\nthe equivalent function's third argument means something else entirely. It is a *shape* selector:\nchanging it changes whether you get a scalar or an array, which changes whether the formula spills,\nwhich changes whether it fits where you put it.\n\n`case_sensitivity` has the same inverted-looking polarity as elsewhere in the family: `0` is\ncase-*sensitive*. It also overlaps with PCRE2's inline `(?i)` flag, and nothing consulted here\nstates which wins if they disagree.\n\n\n" }, "signature": { "display": "REGEXEXTRACT(text, pattern, [return_mode], [case_sensitivity])", "parameters": [ { "description": null, "name": "text", "optional": false, "repeats": false }, { "description": null, "name": "pattern", "optional": false, "repeats": false }, { "description": null, "name": "return_mode", "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": 4, "min": 2 }, "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 matched by a regular expression", "short_source": "dna-calc-own" }, "docs": { "english_description": "Extracts strings within the provided text that matches the pattern", "microsoft_url": "https://support.microsoft.com/en-us/office/regexextract-function-4b96c140-9205-4b6e-9fbe-6aa9e783ff57" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "REGEXEXTRACT" }, { "locale": "bg-BG", "name": "REGEXEXTRACT" }, { "locale": "cs-CZ", "name": "REGEXEXTRAHOVAT" }, { "locale": "da-DK", "name": "REGEXUDTRÆK" }, { "locale": "de-DE", "name": "REGEXEXTRACT" }, { "locale": "el-GR", "name": "REGEXEXTRACT" }, { "locale": "en-AU", "name": "REGEXEXTRACT" }, { "locale": "en-GB", "name": "REGEXEXTRACT" }, { "locale": "en-US", "name": "REGEXEXTRACT" }, { "locale": "es-ES", "name": "REGEXEXTRACCION" }, { "locale": "et-EE", "name": "REGEXEXTRACT" }, { "locale": "fi-FI", "name": "REGEXPOIMI" }, { "locale": "fr-FR", "name": "REGEX.EXTRAIRE*" }, { "locale": "he-IL", "name": "REGEXEXTRACT" }, { "locale": "hr-HR", "name": "REGEXEXTRACT" }, { "locale": "hu-HU", "name": "REGIKIFRÉSZ" }, { "locale": "id-ID", "name": "REGEXEXTRACT" }, { "locale": "it-IT", "name": "REGEXEXTRACT" }, { "locale": "ja-JP", "name": "REGEXEXTRACT" }, { "locale": "ko-KR", "name": "REGEXEXTRACT" }, { "locale": "lt-LT", "name": "REGEXEXTRACT" }, { "locale": "lv-LV", "name": "REGEXEXTRACT" }, { "locale": "nb-NO", "name": "REGEXEXTRACT" }, { "locale": "nl-NL", "name": "REGEXEXTRAHEREN" }, { "locale": "pl-PL", "name": "REGEXWYODRĘBNIJ" }, { "locale": "pt-BR", "name": "REGEXEXTRACT" }, { "locale": "pt-PT", "name": "REGEX.EXTRAIR" }, { "locale": "ro-RO", "name": "REGEXEXTRACT" }, { "locale": "ru-RU", "name": "РЕГИЗВЛЕЧЬ" }, { "locale": "sk-SK", "name": "REGEXEXTRACT" }, { "locale": "sl-SI", "name": "REGEXEXTRACT" }, { "locale": "sr-Latn-RS", "name": "REGEXEXTRACT" }, { "locale": "sv-SE", "name": "REGEXUTDRAG" }, { "locale": "th-TH", "name": "REGEXEXTRACT" }, { "locale": "tr-TR", "name": "NORMİFADEAYIKLA" }, { "locale": "uk-UA", "name": "REGEXEXTRACT" }, { "locale": "vi-VN", "name": "REGEXEXTRACT" }, { "locale": "zh-CN", "name": "REGEXEXTRACT" }, { "locale": "zh-HK", "name": "REGEXEXTRACT" }, { "locale": "zh-TW", "name": "REGEXEXTRACT" } ], "signature": { "display": "REGEXEXTRACT(text, pattern, [return_mode], [case_sensitivity])", "parameters": [ { "description": null, "name": "text", "optional": false, "repeats": false }, { "description": null, "name": "pattern", "optional": false, "repeats": false }, { "description": null, "name": "return_mode", "optional": true, "repeats": false }, { "description": null, "name": "case_sensitivity", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "REGEXEXTRACT", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/regexextract-function-4b96c140-9205-4b6e-9fbe-6aa9e783ff57" }, "try_it": { "formula": "=REGEXEXTRACT(\"a1b2c3\", \"\\d\", 1)" }, "url": "https://handbook.dnacalc.com/functions/REGEXEXTRACT.html", "variants": [], "versions": [ { "behaviour": "=REGEXEXTRACT(\"a12b34\",\"[0-9]+\",{0,1,2}) returned {\"12\",\"12\",#VALUE!}. Inputs were supplied through formula literals. These are controls from this environment, not a same-input comparison with another build.", "excel_build": "16.0.20527.20088", "observations": [ { "call": "=REGEXEXTRACT(\"a12b34\",\"[0-9]+\",{0,1,2})", "excel": { "bits": null, "display": "{\"12\",\"12\",#VALUE!}", "kind": "array" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA" } ], "platform": "Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "sources": [ "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/3345a87/content/notes/FN-TEXTSPLIT-002.json" ] } ] }