RunMat
GitHub

View all functions

CategoryStrings: Transform

What does the extractBetween function do in MATLAB / RunMat?

extractBetween(text, start, stop) locates the substring that appears between two boundary markers. Markers can be text (string scalars, character vectors, or cells that contain them) or numeric positions. The builtin mirrors MATLAB semantics for broadcasting, missing values, and the optional 'Boundaries' name-value argument.

How does the extractBetween function behave in MATLAB / RunMat?

  • Accepts string scalars, string arrays, character arrays (interpreted row-by-row), and cell arrays that contain string scalars or character vectors. Cell outputs preserve the element type (string vs. char) of each cell.
  • Boundary inputs can be text or numeric positions. Both boundaries in a call must use the same kind of input; mixing text and numeric markers raises a size/type error.
  • Scalar text markers follow MATLAB implicit expansion, applying to every element of the text input. Character-array and cell inputs must exactly match the text shape.
  • The 'Boundaries' name-value pair controls inclusivity. Text markers default to exclusive extraction, while numeric positions default to inclusive behaviour. Values are case-insensitive and must be 'exclusive' or 'inclusive'.
  • Missing string scalars propagate: if the text, start marker, or end marker is <missing>, the result is also <missing>.
  • When the start or end boundary cannot be located, extractBetween returns an empty string (or an appropriately padded empty row for character arrays).
  • Numeric positions use 1-based indexing. Inputs are validated as positive integers, clamped to string length, and honour inclusivity rules exactly as MATLAB does.

extractBetween Function GPU Execution Behaviour

Text manipulation executes on the CPU. When any argument resides on the GPU, RunMat gathers the values to host memory, performs extraction, and leaves the results on the host. No Accelerate provider hooks are required, and the builtin is registered as an Accelerate sink so fusion plans never attempt to keep data on the device for this operation.

Examples of using the extractBetween function in MATLAB / RunMat

Extract text between words in a string

txt = "RunMat accelerates MATLAB workloads";
segment = extractBetween(txt, "RunMat ", " workloads");

Expected output:

segment = "accelerates MATLAB"

Include boundary markers with the 'Boundaries' option

path = "snapshots/run/fusion.mat";
withMarkers = extractBetween(path, "snapshots/", ".mat", "Boundaries", "inclusive");

Expected output:

withMarkers = "snapshots/run/fusion.mat"

Use numeric positions for 1-based indexing

name = "Accelerator";
middle = extractBetween(name, 3, 7);

Expected output:

middle = "celer"

Apply scalar text markers to each element of a string array

files = ["runmat_accel.rs", "runmat_gc.rs"; "runmat_plot.rs", "runmat_cli.rs"];
stems = extractBetween(files, "runmat_", ".rs");

Expected output:

stems = 2×2 string
    "accel"    "gc"
    "plot"     "cli"

Work with character arrays while preserving row padding

chars = char("Device<GPU>", "Planner<Fusion>");
tokens = extractBetween(chars, "<", ">");

Expected output:

tokens =

  2×6 char array

    "GPU   "
    "Fusion"

Preserve element types in cell arrays

C = {'<missing>', 'A[B]C'; "Planner <Fusion>", "Device<GPU>"};
out = extractBetween(C, "<", ">");

Expected output:

out =
  2×2 cell array
    {'<missing>'}    {'B'}
    {"Fusion"}       {"GPU"}

Handle missing strings without throwing errors

txt = ["<missing>", "Planner<GPU>"];
tokens = extractBetween(txt, "<", ">");

Expected output:

tokens = 1×2 string
    "<missing>"    "GPU"

FAQ

Which argument types does extractBetween accept?

The first argument can be a string scalar, string array, character array, or cell array of character vectors / string scalars. Boundary arguments can be text (string, character array, or cell) or numeric positions supplied as scalars, vectors, or arrays.

Can the start and end arguments mix text and numeric positions?

No. Both boundaries must be text markers or both must be numeric positions. Mixing types raises a size/type error, mirroring MATLAB.

What happens when a boundary is not found?

extractBetween returns the empty string (""). Character-array outputs contain space padded rows of the appropriate length.

How does 'Boundaries','inclusive' behave with numeric positions?

Inclusive mode returns the substring that includes both indices. Exclusive mode removes the characters at the specified start and end positions, yielding the text strictly between the two indices.

Does extractBetween support implicit expansion?

Yes. Scalar boundaries expand against array inputs following MATLAB implicit expansion rules. Cell and character array inputs must retain their original shape; attempting to expand them produces a size mismatch error.

Are GPU inputs supported?

Yes. Inputs stored on a GPU are gathered automatically. The function executes on the CPU, returns host-side results, and fusion planning treats the builtin as a residency sink.

See Also

replace, split, join, contains, strfind

Source & Feedback