replace — Replace substring occurrences in string, char, and cell-text data with MATLAB-compatible mapping behavior.

replace(str, old, new) substitutes every occurrence of old in str with new. It supports string scalars/arrays, character arrays, and cell arrays of text, including MATLAB-compatible multi-pattern replacement mapping.

Syntax

newText = replace(str, oldText, newText)

Inputs

Returns

Errors

How replace works

• String scalars remain strings. Missing string scalars (<missing>) propagate unchanged.
• String arrays are processed element wise while preserving shape.
• Character arrays are handled row by row. Rows expand or shrink as needed and are padded with spaces so the result remains a rectangular char array, just like MATLAB.
• Cell arrays must contain string scalars or character vectors. The result is a cell array with the same size and element types mirrored after replacement.
• The old and new inputs can be string scalars, string arrays, character arrays, or cell arrays of character vectors / strings. new must be a scalar or match the number of search terms in old.
• Non-text inputs (numeric, logical, structs, GPU tensors, etc.) produce MATLAB-compatible errors.

Does RunMat run replace on the GPU?

replace executes on the CPU. The builtin registers as an Accelerate sink, so the fusion planner never attempts to keep results on the device. When any argument is GPU-resident, RunMat gathers it to host memory before performing replacements. Providers do not need special kernels for this builtin, and GPU-resident results are returned on the host.

GPU memory and residency

No. replace automatically gathers GPU inputs back to the host when necessary. Because it is marked with a gather-immediately residency policy, both inputs and outputs live on the CPU, so you never have to move text values manually. This mirrors MATLAB behaviour where string manipulation runs on the CPU.

Examples

Replace all instances of a word in a string

txt = "RunMat accelerates MATLAB code";
result = replace(txt, "RunMat", "RunMat Accelerate")

Expected output:

result = "RunMat Accelerate accelerates MATLAB code"

Replace multiple terms in a string array

labels = ["GPU pipeline"; "CPU pipeline"];
result = replace(labels, ["GPU", "CPU"], ["Device", "Host"])

Expected output:

result = 2×1 string
    "Device pipeline"
    "Host pipeline"

Replace substrings in a character array while preserving padding

chars = char("alpha", "beta ");
out = replace(chars, "a", "A")

Expected output:

out =

  2×5 char array

    'AlphA'
    'betA '

Replace text within a cell array of character vectors

C = {'Kernel Fusion', 'GPU Planner'};
updated = replace(C, {'Kernel', 'GPU'}, {'Shader', 'Device'})

Expected output:

updated = 1×2 cell array
    {'Shader Fusion'}    {'Device Planner'}

Remove substrings by replacing with empty text

paths = ["runmat/bin", "runmat/lib"];
clean = replace(paths, "runmat/", "")

Expected output:

clean = 1×2 string
    "bin"    "lib"

Replace using scalar replacement for multiple search terms

message = "OpenCL or CUDA or Vulkan";
unified = replace(message, ["OpenCL", "CUDA", "Vulkan"], "GPU backend")

Expected output:

unified = "GPU backend or GPU backend or GPU backend"

Replace text stored inside a cell array of strings

cells = { "Snapshot", "VM Interpreter" };
renamed = replace(cells, " ", "_")

Expected output:

renamed = 1×2 cell array
    {"Snapshot"}    {"VM_Interpreter"}

Preserve missing strings during replacement

vals = ["runmat", "<missing>", "accelerate"];
out = replace(vals, "runmat", "RunMat")

Expected output:

out = 1×3 string
    "RunMat"    <missing>    "accelerate"

Using replace with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how replace changes the result.

FAQ

Related Strings functions

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how replace is executed, line by line, in Rust.

• View the source for replace 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.

Getting started · Benchmarks · Pricing