RunMat
GitHub

View all functions

CategoryStrings: Transform

What does the replace function do in MATLAB / RunMat?

replace(str, old, new) substitutes every occurrence of old found in str with new. The builtin accepts string scalars, string arrays, character arrays, and cell arrays of character vectors or strings, matching MATLAB semantics. Multiple search terms are supported—each matched entry is replaced by its corresponding replacement text.

How does the replace function behave in MATLAB / RunMat?

  • 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.

replace Function GPU Execution Behaviour

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 residency in RunMat (Do I need gpuArray?)

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 of using the replace function in MATLAB / RunMat

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", "Ignition Interpreter" };
renamed = replace(cells, " ", "_");

Expected output:

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

Preserve missing strings during replacement

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

Expected output:

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

FAQ

What sizes are allowed for old and new inputs?

old must contain at least one search term. new may be a scalar or contain the same number of elements as old. Otherwise, replace raises a size-mismatch error matching MATLAB behaviour.

Does replace modify the original input?

No. The builtin returns a new value with substitutions applied. The original inputs are left untouched.

How are character arrays padded after replacement?

Each row is expanded or truncated according to the longest resulting row. Shorter rows are padded with space characters so the output remains a proper char matrix.

How are missing strings handled?

Missing string scalars (<missing>) propagate unchanged. Replacements never convert a missing value into a non-missing string.

Can I replace with an empty string?

Yes. Provide "" (empty string) or '' as the replacement to remove matched substrings entirely.

Does replace support overlapping matches?

Replacements are non-overlapping and proceed from left to right, matching MATLAB’s behaviour for replace.

How does replace behave with GPU data?

RunMat gathers GPU-resident inputs to host memory before performing replacements. The resulting value is returned on the host. Providers do not need to implement a GPU kernel for this builtin.

See Also

regexprep, string, char, strtrim, strip

Source & Feedback