matches

Determine if pattern matches strings

Syntax

TF = matches(str,pat)

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

Description

TF = matches(str,pat) returns 1 (true) if the specified pattern matches str, and returns 0 (false) otherwise. If str is an array, then TF is an array of the same size.

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

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

Examples

Match Text

Create a string array.

str = ["Mercury","Venus","Earth","Mars"]

str = 1×4 string
    "Mercury"    "Venus"    "Earth"    "Mars"

Find the strings that match "Earth". Return a logical array where the position of each element equal to 1 corresponds to the position of a matching string in str.

TF = matches(str,"Earth")

TF = 1×4 logical array

   0   0   1   0

Display the match by indexing back into str using TF.

str(TF)

ans = 
"Earth"

Match Hexadecimal Numbers Using Patterns

Since R2020b

Create a string array that represents numbers. Some of the numbers are hexadecimal numbers with the 0x prefix.

str = ["137","0xA7B","0x1248","72","0xG7"]

str = 1×5 string
    "137"    "0xA7B"    "0x1248"    "72"    "0xG7"

Create a pattern that matches the hexadecimal numbers. To match a single hexadecimal digit, specify a pattern that matches any digit, any capital letter A-F, or any lowercase letter a-f. Then, specify a pattern that begins with 0x and is followed by any number of hexadecimal digits.

pat = digitsPattern(1) | characterListPattern("A","F") | characterListPattern("a","f");
pat = "0x" + asManyOfPattern(pat)

pat = pattern
  Matching:

    "0x" + asManyOfPattern(digitsPattern(1) | characterListPattern("A","F") | characterListPattern("a","f"))

Find the elements of str that match. (The last element does not match because it contains an error: G is not a hexadecimal digit.)

TF = matches(str,pat)

TF = 1×5 logical array

   0   1   1   0   0

To display the matches, index into str using TF.

str(TF)

ans = 1×2 string
    "0xA7B"    "0x1248"

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

For more information on hexadecimal numbers, see Hexadecimal and Binary Values.

Match Multiple Strings

Create a string array.

str = ["Mercury","Venus","Earth","Mars"]

str = 1×4 string
    "Mercury"    "Venus"    "Earth"    "Mars"

Find elements of str that match either "Venus" or "Earth".

TF = matches(str,["Venus","Earth"])

TF = 1×4 logical array

   0   1   1   0

Display the matches by indexing into str using TF.

str(TF)

ans = 1×2 string
    "Venus"    "Earth"

Ignore Case

Create a string array.

str = ["Mercury","Venus","Earth","Mars"]

str = 1×4 string
    "Mercury"    "Venus"    "Earth"    "Mars"

Find the element of str that matches "earth", ignoring case.

TF = matches(str,"earth",IgnoreCase=true)

TF = 1×4 logical array

   0   0   1   0

Display the matching string.

str(TF)

ans = 
"Earth"

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.

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

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

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

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

Version History

Introduced in R2019b