RunMat
GitHub

View all functions

CategoryStrings: Search

startsWith — Check whether text inputs start with specific patterns using MATLAB-compatible broadcasting and case handling.

startsWith(str, pattern) returns a logical result indicating whether each element of str begins with the corresponding text in pattern. The builtin supports string arrays, character vectors/arrays, and cell arrays of character vectors, mirroring MATLAB's implicit expansion semantics.

How does the startsWith function behave in MATLAB / RunMat?

  • Accepts text inputs as string scalars/arrays, character vectors/arrays, or cell arrays of character vectors.
  • Accepts patterns in the same formats; scalar inputs expand across the other argument following MATLAB broadcast rules.
  • Missing strings (<missing>) never match any pattern.
  • Empty patterns ("" or '') always match non-missing text elements.
  • Patterns that are <missing> never match and therefore return false.
  • Character arrays treat each row as an independent element; zero-row character arrays yield empty outputs.
  • The optional IgnoreCase flag can be supplied either as a trailing scalar or via the 'IgnoreCase', value name-value pair. It accepts logical/numeric scalars and the strings 'on', 'off', 'true', and 'false' (default is case-sensitive).
  • Returns a logical scalar when the broadcasted size is one element, otherwise returns a logical array.

GPU behavior

startsWith performs host-side prefix comparison. When inputs currently live on the GPU, RunMat gathers them back to the host before evaluation so the behaviour is identical to MATLAB. No acceleration provider hooks are required for this builtin.

GPU residency

You usually do NOT need to call gpuArray yourself in RunMat (unlike MATLAB).

startsWith always executes on the host, but RunMat's runtime automatically gathers any GPU-resident inputs before evaluating the prefix check. Because the builtin registers a ResidencyPolicy::GatherImmediately, the planner gathers device handles eagerly and computes the logical result on the CPU. You may still call gpuArray manually for compatibility with MATLAB code; the runtime gathers the inputs just in time, so results match MATLAB precisely.

Examples of using startsWith in MATLAB / RunMat

Determine whether a string starts with a prefix

tf = startsWith("RunMat Accelerate", "RunMat")

Expected output:

tf = logical
   1

Perform a case-insensitive prefix check

tf = startsWith("RunMat", "run", 'IgnoreCase', true)

Expected output:

tf = logical
   1

Ignore case using the legacy logical flag

tf = startsWith("RUNMAT", "run", true)

Expected output:

tf = logical
   1

Apply a scalar prefix to every element of a string array

labels = ["alpha" "beta" "gamma"];
tf = startsWith(labels, "a")

Expected output:

tf = 1×3 logical array
   1   0   0

Match element-wise prefixes with implicit expansion

names = ["hydrogen"; "helium"; "lithium"];
prefixes = ["hyd"; "hel"; "lit"];
tf = startsWith(names, prefixes)

Expected output:

tf = 3×1 logical array
   1
   1
   1

Test prefixes for a cell array of character vectors

C = {'Mercury', 'Venus', 'Mars'};
tf = startsWith(C, 'M')

Expected output:

tf = 1×3 logical array
   1   0   1

Provide multiple prefixes as a column vector

tf = startsWith("saturn", ['s'; 'n'; 'x'])

Expected output:

tf = 3×1 logical array
   1
   0
   0

Handle empty and missing values

texts = ["", "<missing>"];
tf = startsWith(texts, "")

Expected output:

tf = 1×2 logical array
   1   0

FAQ

What types can I pass to startsWith?

Use string scalars/arrays, character vectors/arrays, or cell arrays of character vectors for both arguments. Mixed combinations are accepted, and RunMat performs MATLAB-style implicit expansion when the array sizes differ.

How do I ignore letter case?

Supply 'IgnoreCase', true (or 'on') after the pattern argument. The option is case-insensitive, so 'ignorecase' also works. The default is false, matching MATLAB.

What happens with empty patterns?

Empty patterns ("" or '') always match non-missing text elements. When the text element is missing (<missing>), the result is false.

Can I provide multiple prefixes at once?

Yes. Provide pattern as a string array, character array, or cell array of character vectors. RunMat applies implicit expansion so that scalar inputs expand across the other argument automatically.

How are missing strings treated?

Missing string scalars (displayed as <missing>) never match any pattern and produce false in the result. Use ismissing if you need to handle missing values separately.

Does startsWith run on the GPU?

No. The builtin executes on the CPU. If inputs reside on the GPU (for example, after other accelerated operations), RunMat gathers them automatically so behaviour matches MATLAB.

Does startsWith preserve the input shape?

Yes. The output is a logical array whose shape reflects the MATLAB-style implicit expansion result. When that shape contains exactly one element, the builtin returns a logical scalar.

See also

contains, endsWith, regexp, regexpi

Source & Feedback