matches

R2026b

Determine if strings or category names match pattern

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

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"

Determine Category Names Match 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 match "earthquake". The matches function returns a logical array indicating which elements in the Cause categorical array have category names that match "earthquake".

TF = matches(T.Cause,"earthquake",IgnoreCase=true)

TF = 1468×1 logical array

   0
   0
   0
   0
   0
   0
   0
   0
   0
   0
   0
   0
   0
   0
   0
      ⋮

Display only the rows of the table where the cause matches "earthquake".

T(TF,:)

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

    {'West'     }    2005-09-26 06:32    258.18    1.3996e+05    2005-09-26 06:33    earthquake
    {'NorthEast'}    2012-12-04 17:12         0             0    2012-12-04 17:12    earthquake

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

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

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

Thread-Based Environment

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

The matches 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 matches function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2019b

R2026b: Support for categorical arrays

The matches 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 match a specified pattern.