regexpi — Match text case-insensitively with regular expressions.
regexpi(text, pattern) ignores case by default and can return indices, matches, capture tokens, token extents, named tokens, and split text. Common MATLAB output and option forms are supported; advanced MATLAB pattern syntax is not yet available.
Syntax
out = regexpi(subject, pattern)
out = regexpi(subject, pattern, options...)
[start,end_idx,token_extents,match,tokens,names,split] = regexpi(subject, pattern, options...)Inputs
subject- Type
Any- Required
- Yes
- Description
- Input text (char/string/string-array/cellstr).
pattern- Type
StringScalar- Required
- Yes
- Description
- Regular-expression pattern.
options- Type
Any- Required
- Variadic
- Description
- Output selectors and regexp options.
Returns
out- Type
Any- Description
- Primary regexpi output (depends on options and requested output count).
start- Type
Any- Description
- 1-based match start indices.
end_idx- Type
Any- Description
- 1-based inclusive match end indices.
token_extents- Type
Any- Description
- 1-based start and end indices of capture tokens.
match- Type
Any- Description
- Matched substrings.
tokens- Type
Any- Description
- Capture-group token outputs.
names- Type
Any- Description
- Named capture-group outputs.
split- Type
Any- Description
- Split output around regex matches.
Returned values from regexpi depend on how many outputs the caller requests.
Errors
RunMat:regexpi:InvalidArgument- When
- Input/options are malformed or unsupported.
- Message
regexpi: invalid argument
RunMat:regexpi:PatternInvalid- When
- Pattern cannot be compiled as a regular expression.
- Message
regexpi: invalid regular expression pattern
RunMat:regexpi:Internal- When
- Internal regexpi output assembly fails.
- Message
regexpi: internal operation failed
Behavior
Case-insensitive matching is the default; include 'matchcase' when you need case-sensitive behaviour.
With one output and no output selector, regexpi returns a numeric row vector of 1-based match start indices.
Without output keywords, successive outputs are match starts, match ends, token extents, matched substrings, capture tokens, named tokens, and split text.
When the input is a string array or cell array of character vectors, outputs are cell arrays whose shape matches the input container.
'forceCellOutput' forces cell outputs even for scalar inputs, matching MATLAB semantics.
'once' limits each element to its first match, influencing every requested output.
Zero-length matches are omitted by default; 'emptymatch' includes them and 'noemptymatch' restores the default. RunMat also accepts its older two-argument allow/remove form.
Dot (.) matches newlines by default. Pass 'dotexceptnewline' to exclude them. The Rust regex engine does not support MATLAB lookaround, backreferences, atomic groups, or dynamic expressions.
Named tokens (using (?<name>...)) produce a cell of scalar structs for scalar text when 'names' is requested, or one struct with 'once'. Array subjects add an outer cell matching the input shape. Unmatched names resolve to empty strings for MATLAB compatibility.
Integer semantics: numeric match locations are outputs only. Numeric, logical, symbolic, and provider-resident inputs or options are rejected by the shared regular-expression admission boundary before gather or provider access.
Placement and effects
Matching operates on host text. The builtin has no text GPU kernel or fusion form; numeric and resident text-role inputs reject before provider access. It may throw for malformed arguments and options, but does not mutate workspace state or access files, network, randomness, or time.
An unused result is still evaluated and discarded. Ordinary host-text distribution is distinct from distributed-input support for this builtin.
Examples
Finding indices regardless of case
idx = regexpi('Abracadabra', 'a')Expected output:
idx =
1 4 6 8 11Returning matched substrings ignoring case
matches = regexpi('abcXYZ123', '[a-z]{3}', 'match')Expected output:
matches =
1×2 cell array
{'abc'} {'XYZ'}Extracting capture tokens case-insensitively
tokens = regexpi('ID:AB12', '(?<prefix>[a-z]+)(?<digits>\d+)', 'tokens');
first = tokens{1}{1}
second = tokens{1}{2}Expected output:
first =
'AB'
second =
'12'Limiting regexpi to the first match
firstMatch = regexpi('aXaXaX', 'ax', 'match', 'once')Expected output:
firstMatch =
'aX'Splitting a string array without worrying about letter case
parts = regexpi(["Color:Red"; "COLOR:Blue"], 'color:', 'split')Expected output:
parts =
2×1 cell array
{1×2 cell}
{1×2 cell}
parts{2}{2}
ans =
'Blue'Enforcing case-sensitive matches with 'matchcase'
idx = regexpi('CaseTest', 'case', 'matchcase')Expected output:
idx =
[]Using regexpi with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how regexpi changes the result.
Run a small regexpi example, explain the result, then change one input and compare the output.
FAQ
How are the outputs ordered when I request several?⌄
Without output keywords, the default order is match starts, match ends, token extents, matched substrings, capture tokens, named tokens, then split text. Output keywords such as 'match' or 'tokens' select only the requested outputs.
Can I make regexpi behave like regexp with case sensitivity?⌄
Yes. Include the 'matchcase' flag to disable the default case-insensitive mode. You can also pass 'ignorecase' explicitly to emphasise the default.
Does regexpi support string arrays and cell arrays?⌄
Yes. Outputs mirror the input container shape, and each element stores results for the corresponding string or character vector.
How do zero-length matches behave?⌄
Zero-length matches are omitted by default. Use 'emptymatch' to include them or 'noemptymatch' to restore the default. The older two-argument allow/remove form also works in RunMat.
Does regexpi run on the GPU?⌄
Text matching runs on the host and has no GPU text kernel. Numeric or resident values in text roles are rejected before provider access; supported scalar controls are handled separately.
Are named tokens supported?⌄
Yes. Use the (?<name>...) syntax and request the 'names' output flag. Each match produces a scalar struct with fields for every named group.
What happens with 'once'?⌄
'once' restricts each input element to the first match. For scalar text with a match, start/end indices, matched text, and named tokens become scalar values; capture tokens and splits remain cells, while token extents remain a matrix.
Can I keep scalar outputs in cells?⌄
Yes. Pass 'forceCellOutput' to wrap even scalar results in cells, which is useful when writing code that must treat scalar and array inputs uniformly.
Related Strings functions
Text Analytics
addDependencyDetails · addEntityDetails · addLemmaDetails · addPartOfSpeechDetails · addSentenceDetails · addTypeDetails · bagOfNgrams · bagOfWords · cosineSimilarity · doc2sequence · encode · extractFileText · extractHTMLText · fastTextWordEmbedding · findElement · getAttribute · htmlTree · ind2word · isVocabularyWord · normalizeWords · readWordEmbedding · removeLongWords · removeShortWords · removeStopWords · removeWords · stopWords · tokenDetails · tokenizedDocument · trainWordEmbedding · vaderSentimentScores · vec2word · word2ind · word2vec · wordEncoding · writeWordEmbedding
Transform
append · deblank · erase · eraseBetween · erasePunctuation · eraseURLs · extractAfter · extractBefore · extractBetween · insertAfter · insertBefore · join · lower · pad · replace · replaceBetween · reverse · split · splitlines · strcat · strip · strjoin · strjust · strrep · strsplit · strtrim · upper
Core
blanks · char · compose · convertCharsToStrings · convertContainedStringsToChars · convertStringsToChars · genvarname · int2str · isletter · isspace · isStringScalar · isstrprop · mat2str · native2unicode · newline · num2str · sprintf · sscanf · str2double · str2num · strcmp · strcmpi · string · string.empty · strings · strlength · strncmp · strncmpi · strtok · unicode2native
Search
contains · endsWith · matches · startsWith · strfind
Pattern
digitsPattern · lettersPattern · pattern · regexpPattern · textBoundary · wildcardPattern
Source you can read
Every RunMat function's source is public. Read exactly how regexpi is executed, line by line, in Rust.
- View the source for regexpi in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.