regexprep — Replace text with regular expressions across char, string, and cell-text inputs using MATLAB-compatible rules.
regexprep(str, pattern, replacement) searches str for regular-expression matches and replaces them with replacement. It supports character vectors, string arrays, and cell arrays of text, with MATLAB-compatible container and option semantics.
Syntax
out = regexprep(subject, pattern, replacement)
out = regexprep(subject, pattern, replacement, options...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
subject | Any | Yes | — | Input text (char/string/string-array/cellstr). |
pattern | Any | Yes | — | Pattern text (scalar, sequence, or elementwise list). |
replacement | Any | Yes | — | Replacement text (scalar, sequence, or elementwise list). |
options | Any | Variadic | — | Regex replacement options (case/lineanchors/dotall/once/emptymatch/...). |
Returns
| Name | Type | Description |
|---|---|---|
out | Any | Text with replacements applied (preserves scalar/array shape semantics). |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:regexprep:InvalidArgument | Input/options are malformed, unsupported, or shape-incompatible. | regexprep: invalid argument |
RunMat:regexprep:PatternInvalid | Pattern cannot be compiled as a regular expression. | regexprep: invalid regular expression pattern |
RunMat:regexprep:Internal | Internal regex replacement or output reconstruction fails. | regexprep: internal operation failed |
How regexprep works
- With scalar text inputs, the result is a scalar of the same kind (
charinputs staychar, string scalars stay string scalars). - String arrays and cell arrays are processed element-wise and produce containers with matching shapes. When patterns and replacements are provided as arrays of the same size, they are paired element-by-element; otherwise, scalar patterns/replacements broadcast to every element.
- Cell or string arrays of patterns apply sequentially: each
(pattern, replacement)pair is applied in order to every element. - The
'once'flag limits each element to the first match.'emptymatch','remove'(default) skips zero-length matches, while'emptymatch','allow'lets them participate. 'ignorecase'and'matchcase'control case sensitivity.'lineanchors','dotall', and'dotExceptNewline'toggle multiline and dot behaviours in the same way asregexp.'preservecase'adjusts the replacement text so the case pattern of the first match (all upper, all lower, or title case) is preserved.
Does RunMat run regexprep on the GPU?
regexprep executes entirely on the CPU. When the subject, pattern, or replacement values originate from GPU-resident arrays, RunMat gathers them to host memory before performing the replacements. Results remain on the host; callers that need GPU residency should explicitly move the values back afterwards (e.g. with gpuArray).
Examples
Replacing vowels in a character vector
clean = regexprep('abracadabra', '[aeiou]', 'X')Expected output:
clean =
'XbrXcXdXbrX'Applying multiple pattern/replacement pairs sequentially
result = regexprep("Color: red", {'Color', 'red'}, {'Shade', 'blue'})Expected output:
result = "Shade: blue"Performing case-insensitive replacements
names = regexprep(["Alpha"; "beta"; "GaMmA"], 'a', '_', 'ignorecase')Expected output:
names =
3×1 string array
"_lph_"
"bet_"
"G__mM_"Preserving case of the original match
words = regexprep('MATLAB and matlab', 'matlab', 'runmat', 'preservecase')Expected output:
words =
'RUNMAT and runmat'Limiting replacements to the first match with 'once'
out = regexprep("abababa", 'ba', 'XY', 'once')Expected output:
out = "aXYbaba"Using element-wise patterns for a string array
expr = ["foo", "bar"];
pat = ["f", "ar"];
rep = ["F", "AR"];
exact = regexprep(expr, pat, rep)Expected output:
exact = 1×2 string
"Foo" "bAR"Using regexprep with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how regexprep changes the result.
Run a small regexprep example, explain the result, then change one input and compare the output.
FAQ
How are container outputs shaped?⌄
Outputs mirror the input container. Character vectors return character vectors, string arrays return string arrays with the same size, and cell arrays return cell arrays with matching shape.
Can I supply multiple patterns at once?⌄
Yes. Provide pattern and replacement as equally-sized cell or string arrays. Each pair is applied sequentially to every element, mirroring MATLAB's behaviour.
What if my replacement needs capture-group text?⌄
Use $1, $2, … for numbered groups or ${name} for named groups inside the replacement text. These tokens expand to the corresponding captured substrings.
Does regexprep support case-insensitive matching?⌄
Yes. Pass the 'ignorecase' option (or 'matchcase' to revert). You can also request multiline anchors or dot behaviour changes with 'lineanchors', 'dotall', or 'dotExceptNewline'.
What does 'preservecase' do?⌄
When enabled, regexprep inspects the alphabetic characters in the matched text. If they are all uppercase, lowercase, or title-cased, the replacement text is adjusted to match that style.
Does regexprep execute on the GPU?⌄
No. All matching and replacement runs on the CPU. GPU inputs are downloaded automatically, but the results remain in host memory.
Related Strings functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how regexprep is executed, line by line, in Rust.
- View the source for regexprep 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.