contains

R2026b

Determine if strings or category names contain pattern

Syntax

TF = contains(str,pat)

TF = contains(str,pat,IgnoreCase=true)

Description

TF = contains(str,pat) returns 1 (true) if str contains the specified pattern, and returns 0 (false) otherwise.

If pat is an array containing multiple patterns, then contains returns 1 if it finds any element of pat in str.

If str is a string array, cell array, or categorical array, then TF is a logical array that is the same size as str.

TF = contains(str,pat,IgnoreCase=true) ignores case when determining if str contains pat.

Examples

Find Text

Create a string array of names, where some names contain Paul.

You can create strings using double quotes.

str = ["Mary Ann Jones","Paul Jay Burns","John Paul Smith"]

str = 1×3 string
    "Mary Ann Jones"    "Paul Jay Burns"    "John Paul Smith"

Return a logical array where the position of each element equal to 1 corresponds to the position of a string in str that contains Paul.

pat = "Paul";
TF = contains(str,pat)

TF = 1×3 logical array

   0   1   1

Display the strings that contain Paul. Index back into str using TF.

str(TF)

ans = 1×2 string
    "Paul Jay Burns"    "John Paul Smith"

Search Using Patterns

Create a string array that contains addresses.

str = ["221B Baker St.","Tour Eiffel Champ de Mars","4059 Mt Lee Dr."]

str = 1×3 string
    "221B Baker St."    "Tour Eiffel Champ de Mars"    "4059 Mt Lee Dr."

To find addresses that contain numbers, create a pattern that matches an arbitrary number of digits by using the digitsPattern function.

pat = digitsPattern

pat = pattern
  Matching:

    digitsPattern

Return a logical array indicating which strings contain digits. Display the matching strings.

TF = contains(str,pat)

TF = 1×3 logical array

   1   0   1

str(TF)

ans = 1×2 string
    "221B Baker St."    "4059 Mt Lee Dr."

Search for strings that have a sequence of digits followed by one letter. You can build more complex patterns by combining simple patterns.

pat = digitsPattern + lettersPattern(1)

pat = pattern
  Matching:

    digitsPattern + lettersPattern(1)

TF = contains(str,pat);
str(TF)

ans = 
"221B Baker St."

For a list of functions that create pattern objects, see pattern.

Match Any Text in List

Create a string array of names, where some names contain either Ann or Paul.

str = ["Mary Ann Jones","Christopher Matthew Burns","John Paul Smith"]

str = 1×3 string
    "Mary Ann Jones"    "Christopher Matthew Burns"    "John Paul Smith"

Find the elements of str that contain either Ann or Paul.

pat = ["Ann","Paul"];
TF = contains(str,pat)

TF = 1×3 logical array

   1   0   1

Index back into str using TF.

str(TF)

ans = 1×2 string
    "Mary Ann Jones"    "John Paul Smith"

Ignore Case

Create a string array that contains names. Determine which names contain anne, ignoring case.

You can create strings using double quotes.

str = ["Anne","Elizabeth","Marianne","Tracy"]

str = 1×4 string
    "Anne"    "Elizabeth"    "Marianne"    "Tracy"

pat = "anne";
TF = contains(str,pat,IgnoreCase=true)

TF = 1×4 logical array

   1   0   1   0

Display the strings that contain anne. Index back into str using TF.

str(TF)

ans = 1×2 string
    "Anne"    "Marianne"

Determine If Character Vector Contains Substrings

Create a character vector that contains a list of foods. Determine if the names of different foods are in the character vector.

chr = 'peppers, onions, and mushrooms';
TF = contains(chr,'onion')

TF = logical
   1

TF = contains(chr,'pineapples')

TF = logical
   0

Determine If Category Names Contain String

Since R2026b

Load data on electric utility outages in the United States as a table. Convert the Cause variable to a categorical array.

T = readtable("outages.csv");
T.Cause = categorical(T.Cause);

Determine if the category names of Cause contain "storm". The contains function returns a logical array indicating which elements in the Cause categorical array have category names that contain "storm".

TF = contains(T.Cause,"storm",IgnoreCase=true)

TF = 1468×1 logical array

   1
   1
   1
   0
   1
   0
   0
   0
   0
   0
   0
   0
   1
   1
   1
      ⋮

Display only the rows of the table where the cause contains "storm".

T(TF,:)

ans = 684×6 table
       Region           OutageTime        Loss     Customers     RestorationTime        Cause    
    _____________    ________________    ______    __________    ________________    ____________

    {'SouthWest'}    2002-02-01 12:18    458.98    1.8202e+06    2002-02-07 16:50    winter storm
    {'SouthEast'}    2003-01-23 00:49    530.14    2.1204e+05                 NaT    winter storm
    {'SouthEast'}    2003-02-07 21:15     289.4    1.4294e+05    2003-02-17 08:14    winter storm
    {'MidWest'  }    2002-03-16 06:18    186.44    2.1275e+05    2002-03-18 23:23    severe storm
    {'SouthEast'}    2002-09-01 18:22    95.917         36759    2002-09-01 19:12    severe storm
    {'SouthEast'}    2003-09-27 07:32       NaN    3.5517e+05    2003-10-04 07:02    severe storm
    {'West'     }    2003-11-12 06:12    254.09    9.2429e+05    2003-11-17 02:04    winter storm
    {'NorthEast'}    2004-11-13 10:42       NaN    1.4227e+05    2004-11-19 02:31    winter storm
    {'SouthEast'}    2004-12-06 23:18       NaN         37136    2004-12-14 03:21    winter storm
    {'SouthEast'}    2002-12-12 18:08    46.918    1.0698e+05    2002-12-14 18:43    winter storm
    {'West'     }    2004-12-21 18:50    112.05     7.985e+05    2004-12-29 03:46    winter storm
    {'West'     }    2002-12-16 13:43    70.752    4.8193e+05    2002-12-19 09:38    winter storm
    {'NorthEast'}    2004-12-26 22:18    255.45    1.0444e+05    2004-12-27 14:11    winter storm
    {'NorthEast'}    2003-12-17 15:11       NaN         66692    2003-12-19 07:22    winter storm
    {'SouthEast'}    2005-03-08 16:37    1339.2    4.3003e+05    2005-03-10 20:42    winter storm
    {'MidWest'  }    2002-03-26 01:59    388.04    5.6422e+05    2002-03-28 19:55    winter storm
      ⋮

.

Input Arguments

str — Input array

string array | character vector | cell array of character vectors | categorical array

Input array, specified as a string array, character vector, cell array of character vectors, or categorical array (since R2026b).

pat — Search pattern

string array | character vector | cell array of character vectors | pattern array

Search pattern, specified as one of the following:

• String array

• Character vector

• Cell array of character vectors

• pattern array

Tips

• A string with no characters ("") or a character vector with no characters ('') is a substring of every string. Therefore, contains always finds such substrings within any input text. For more information, see Test for Empty Strings and Missing Values.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The contains function fully supports tall arrays. For more information, see Tall Arrays.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• str and pat must be a string scalar, character vector, or cell array containing not more than one character vector.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

The contains function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

The contains function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2016b

R2026b: Support for categorical arrays

The contains function now supports categorical arrays as the input array. You can use this function to determine whether elements in a categorical array have category names that contain a specified pattern.