contains — Test whether text inputs contain patterns in MATLAB and RunMat.
contains(str, pattern) returns logical results indicating whether each element of str contains the corresponding text in pattern. It supports string arrays, character arrays, and cell text inputs with implicit expansion behavior matching MATLAB and RunMat.
Syntax
tf = contains(str, pat)
tf = contains(str, pat, ignoreCase)
tf = contains(str, pat, "IgnoreCase", value)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
str | Any | Yes | — | Text input (string/char/cell/string array). |
pat | Any | Yes | — | Pattern text (string/char/cell/string array). |
ignoreCase | Any | Yes | false | Logical flag controlling case-sensitive matching. |
name | StringScalar | Yes | "IgnoreCase" | Option name (`"IgnoreCase"`). |
value | Any | Yes | — | Option value for `"IgnoreCase"`. |
Returns
| Name | Type | Description |
|---|---|---|
tf | LogicalArray | Logical result indicating whether each text element contains the pattern. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:contains:InvalidInput | Text or pattern input is not a supported text container. | contains: text and pattern inputs must be text values |
RunMat:contains:InvalidOption | IgnoreCase option arguments are invalid or malformed. | contains: invalid option arguments |
RunMat:contains:ShapeMismatch | Text and pattern inputs are not broadcast-compatible. | contains: input sizes are not broadcast-compatible |
RunMat:contains:InternalError | Internal logical result assembly failed. | contains: internal error |
How contains works
- Accepts text inputs as string scalars/arrays, character scalars/arrays, or cell arrays of character vectors.
- Accepts patterns in the same formats. Either input may be scalar; when sizes differ MATLAB-style implicit expansion applies.
- Missing string scalars (
<missing>) never match any pattern. - Empty pattern values (
""or'') always match non-missing text elements. - The optional
'IgnoreCase', true|falsename-value pair controls case sensitivity (default is case-sensitive). - Returns a logical scalar when the broadcasted size is one element, otherwise returns a logical array with the broadcasted shape.
Does RunMat run contains on the GPU?
contains performs host-side text comparisons and registers no provider hook. Resident numeric inputs reject before provider access because they are not text values.
GPU memory and residency
contains executes on host text values. RunMat currently has no GPU-resident string representation, so a numeric gpuArray is rejected as nontext before any provider download.
Examples
Check if a string contains a substring
tf = contains("RunMat Accelerate", "Accelerate")Expected output:
tf = logical
1Perform a case-insensitive search
tf = contains("RunMat", "run", 'IgnoreCase', true)Expected output:
tf = logical
1Apply a scalar pattern to every element of a string array
labels = ["alpha" "beta" "gamma"];
tf = contains(labels, "a")Expected output:
tf = 1×3 logical array
1 1 1Match element-wise patterns with implicit expansion
names = ["hydrogen"; "helium"; "lithium"];
patterns = ["gen"; "ium"; "iron"];
tf = contains(names, patterns)Expected output:
tf = 3×1 logical array
1
1
0Search a cell array of character vectors
C = {'Mercury', 'Venus', 'Mars'};
tf = contains(C, 'us')Expected output:
tf = 1×3 logical array
0 1 0Provide multiple patterns as a column vector
tf = contains("saturn", ['s'; 'n'; 'x'])Expected output:
tf = 3×1 logical array
1
1
0Handle empty and missing text values
texts = ["", "<missing>"];
tf = contains(texts, "")Expected output:
tf = 1×2 logical array
1 0Using contains with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how contains changes the result.
Run a small contains example, explain the result, then change one input and compare the output.
FAQ
What types can I pass to contains?⌄
Use string scalars/arrays, character vectors/arrays, or cell arrays of character vectors for both the text and the pattern. Mixed combinations are accepted, and RunMat performs MATLAB-style implicit expansion when the array sizes differ.
How do I ignore letter case?⌄
Specify 'IgnoreCase', true after the pattern argument. The option name is case-insensitive and the default is false. Positional, numeric, and textual flag conveniences are available only in RunMat compatibility mode.
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 search for multiple patterns 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 separate missing values before calling contains.
Does contains run on the GPU?⌄
No. The builtin executes on the CPU, and RunMat has no GPU-resident text representation. Numeric gpuArray values reject as nontext before provider access.
Does contains preserve the input shape?⌄
Yes. The output is a logical array whose shape is the implicit-expansion result of the input shapes. When the broadcasted shape has exactly one element, the builtin returns a logical scalar.
Related Strings functions
Search
endsWith · matches · startsWith · strfind
Text Analytics
addDependencyDetails · addEntityDetails · addLemmaDetails · addPartOfSpeechDetails · addSentenceDetails · addTypeDetails · bagOfNgrams · bagOfWords · cosineSimilarity · doc2sequence · encode · extractFileText · extractHTMLText · fastTextWordEmbedding · findElement · getAttribute · htmlTree · ind2word · isVocabularyWord · normalizeWords · readWordEmbedding · removeLongWords · removeShortWords · removeStopWords · removeWords · stopWords · tokenDetails · tokenizedDocument · trainWordEmbedding · vaderSentimentScores · vec2word · word2ind · word2vec · wordEncoding · writeWordEmbedding
Transform
append · deblank · erase · eraseBetween · erasePunctuation · eraseURLs · extractAfter · extractBefore · extractBetween · insertAfter · insertBefore · join · lower · pad · replace · replaceBetween · reverse · split · splitlines · strcat · strip · strjoin · strjust · strrep · strsplit · strtrim · upper
Core
blanks · char · compose · convertCharsToStrings · convertContainedStringsToChars · convertStringsToChars · genvarname · int2str · isletter · isspace · isStringScalar · isstrprop · mat2str · native2unicode · newline · num2str · sprintf · sscanf · str2double · str2num · strcmp · strcmpi · string · string.empty · strings · strlength · strncmp · strncmpi · strtok · unicode2native
Pattern
digitsPattern · lettersPattern · pattern · regexpPattern · textBoundary · wildcardPattern
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how contains is executed, line by line, in Rust.
- View the source for contains 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.