contains

Determine if pattern is in strings

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.

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 = 1x3 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 = 1x3 logical array

   0   1   1

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

str(TF)

ans = 1x2 string
    "Paul Jay Burns"    "John Paul Smith"

Search Using Patterns

Since R2020b

Create a string array that contains addresses.

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

str = 1x3 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 = 1x3 logical array

   1   0   1

str(TF)

ans = 1x2 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 = 1x3 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 = 1x3 logical array

   1   0   1

Index back into str using TF.

str(TF)

ans = 1x2 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 = 1x4 string
    "Anne"    "Elizabeth"    "Marianne"    "Tracy"

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

TF = 1x4 logical array

   1   0   1   0

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

str(TF)

ans = 1x2 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

Input Arguments

str — Input text

string array | character vector | cell array of character vectors

Input text, specified as a string array, character vector, or cell array of character vectors.

pat — Search pattern

string array | character vector | cell array of character vectors | pattern array (since R2020b)

Search pattern, specified as one of the following:

• String array

• Character vector

• Cell array of character vectors

• pattern array (since R2020b)

Extended Capabilities

Tall Arrays

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

Usage notes and limitations:

• Pattern objects are not supported.

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.

Thread-Based Environment

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

This 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™.

Usage notes and limitations:

• pat must be a string array, character vector, or a cell array of character vectors.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2016b