Apple Numbers REGEX Function: ICU Patterns and Typed Conditions
Use REGEX wrappers with COUNTIF, COUNTMATCHES and TEXTBEFORE, including complete ASCII fixtures, case controls and concatenation behavior.
Verification status: See the evidence and test scope described in this guide. How formula examples are checked
REGEX creates a regular-expression value for another function to use as a condition or text-matching pattern. It is not itself a Boolean test of a separate input string. When used on its own rather than as a matching condition, Apple says it returns the underlying pattern as a string.
This wrapper distinction matters when building a formula: COUNTMATCHES or COUNTIF performs the operation on the data, while REGEX supplies the pattern and its case mode.
Availability and verification
The official REGEX reference was retrieved October 15, 2026. The original function-introduction release and last functioning version are unknown from the checked sources. Current shared function documentation is not a last-working-build test or evidence of identical behavior on every older Mac, iPad, iPhone and iCloud client.
No native Numbers session was executed. The examples use independent arithmetic or constrained text models, with data-dependent results identified explicitly. Public-source retrieval is separate from native verification.
Syntax and case sensitivity
REGEX(regular-expression-string, case-sensitive)
The pattern is text. Optional case-sensitive defaults to TRUE; FALSE requests case-insensitive matching. Apple specifies the ICU regular-expression standard.
The independent fixtures below use a small ASCII subset: character classes, repetition, anchors and literal separators. A Python or JavaScript match on those controls is not a test of every ICU feature, Unicode boundary or native Numbers coercion.
Complete code-validation fixture
Put these strings into A2:A7: AB-123, AB-12, ab-123, AB-1234, prefix AB-123, and XY-009.
=COUNTIF(A2:A7,REGEX("^[A-Z]{2}-[0-9]{3}$",TRUE))
The independent expected count is 2: AB-123 and XY-009. The pattern requires exactly two uppercase ASCII letters, a hyphen and three digits, with no prefix or suffix.
Changing the case argument to FALSE gives 3, adding ab-123. It does not fix the short, long or prefixed inputs. The zero characters in XY-009 are part of the string, not a numeric-format instruction.
Example: count matches inside a string
For "Item1, item2, item3", =COUNTMATCHES("Item1, item2, item3",REGEX("item[0-9]")) has target 2 because the omitted case argument is sensitive. Supplying FALSE inside REGEX changes the target to 3, matching Apple’s examples.
These formulas count matching occurrences in one string. COUNTIF instead counts qualifying cells in a range. If one cell contains two occurrences, those two operations need not return the same count.
Example: extract the prefix before digits
=TEXTBEFORE("Order AB-123 ready",REGEX("[0-9]+")) has independent target Order AB-, including the final hyphen. The digit run begins at 123, so the prefix includes everything before that run.
With input Batch 007 done, the corresponding target is **Batch **, including the trailing space. That space is part of the returned prefix. Removing it would be an additional cleaning step, not the documented match itself.
Advanced: build a pattern from regex pieces
Apple distinguishes concatenating two REGEX values from concatenating a REGEX value with ordinary text. Two REGEX pieces preserve regex behavior; mixing with a regular string produces an ordinary string.
For the code fixture, the composed condition REGEX("^[A-Z]{2}-") & REGEX("[0-9]{3}$") represents the same sensitive pattern as the complete expression above and has independent target count 2. Both pieces use the same default case mode, avoiding an unsupported rule for combining different case settings.
Do not replace the second REGEX wrapper with an ordinary quoted fragment and assume the result remains a regex condition. Inspect the final expression’s type as well as the visible pattern characters.
Advanced: distinguish occurrence counts from row counts
Use A10:A12 containing code 12 and 34, code 56, and no digits. Counting digit runs in each string with COUNTMATCHES and pattern REGEX("[0-9]+") has targets 2, 1 and 0. There are three occurrences across the fixture, but only two cells containing at least one occurrence.
A COUNTIF over those cells with the same unanchored REGEX condition targets 2. This is useful when defining a report: decide whether the metric is matching records or individual tokens before summing counts.
Errors, boundaries and source caveats
The reference includes a complex email-replacement example whose printed result is inconsistent with the displayed capture-group boundaries. This guide does not repeat it as verified output or claim that a simple regex certifies a valid email address.
The dedicated entry does not supply a complete native error matrix for malformed patterns, unsupported arguments or empty matches. Newline handling, Unicode classes, lookbehind and replacement-group syntax are outside the executed independent fixtures.
If a count is wrong, check case mode, anchors, the data range and whether a concatenation converted the expression into plain text. A syntactically valid pattern can still encode the wrong acceptance rule; retain both matching and nonmatching controls whenever editing it.