regexpi — Run case-insensitive regular-expression matching with MATLAB-compatible outputs and options.
regexpi(text, pattern) evaluates regular-expression matches while ignoring case by default. It supports MATLAB-compatible outputs for indices, matches, capture tokens, token extents, named tokens, and split text, plus flags like 'once', 'emptymatch', and case/newline toggles.
Syntax
out = regexpi(subject, pattern)
out = regexpi(subject, pattern, options...)
[start,end_idx,match,tokens,names,split] = regexpi(subject, pattern, options...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
subject | Any | Yes | — | Input text (char/string/string-array/cellstr). |
pattern | StringScalar | Yes | — | Regular-expression pattern. |
options | Any | Variadic | — | Output selectors and regexp options. |
Returns
| Name | Type | Description |
|---|---|---|
out | Any | Primary regexpi output (depends on options and requested output count). |
start | Any | 1-based match start indices. |
end_idx | Any | 1-based inclusive match end indices. |
match | Any | Matched substrings. |
tokens | Any | Capture-group token outputs. |
names | Any | Named capture-group outputs. |
split | Any | Split output around regex matches. |
Returned values from regexpi depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:regexpi:InvalidArgument | Input/options are malformed or unsupported. | regexpi: invalid argument |
RunMat:regexpi:PatternInvalid | Pattern cannot be compiled as a regular expression. | regexpi: invalid regular expression pattern |
RunMat:regexpi:Internal | Internal regexpi output assembly fails. | regexpi: internal operation failed |
How regexpi works
- Case-insensitive matching is the default; include
'matchcase'when you need case-sensitive behaviour. - With one output,
regexpireturns a numeric row vector of 1-based match start indices. - With multiple outputs, the default order is match starts, match ends, matched substrings.
- 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.'emptymatch','allow'keeps zero-length matches;'emptymatch','remove'is the default filter.- Named tokens (using
(?<name>...)) return scalar struct values per match when'names'is requested. Unmatched names resolve to empty strings for MATLAB compatibility.
Does RunMat run regexpi on the GPU?
regexpi executes entirely on the CPU. If inputs or previously computed intermediates are resident on the GPU, RunMat gathers the necessary data before evaluation and returns host-side outputs. Acceleration providers do not offer specialised hooks today; computed tensors remain on the host unless explicit GPU transfers are requested later.
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?⌄
If you do not specify explicit output flags, the default order is match starts, match ends, and matched substrings—identical to MATLAB. Providing flags such as 'match' or 'tokens' returns 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?⌄
By default ('emptymatch','remove'), zero-length matches are omitted. Use 'emptymatch','allow' to keep them, which is helpful when inspecting optional pattern components.
Does regexpi run on the GPU?⌄
No. All matching occurs on the CPU. RunMat gathers GPU-resident inputs before processing and leaves outputs on the host. Explicit gpuArray calls are required if you want to move the results back to the GPU.
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. All requested outputs honour that limit, returning scalars instead of per-match cells.
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
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. 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 an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 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.