namedPattern

Designate named pattern

Since R2020b

Syntax

newpat = namedPattern(pat)

newpat = namedPattern(pat,name)

newpat = namedPattern(pat,name,description)

Description

newpat = namedPattern(pat) creates a named pattern that contains pat and is named using the input name of pat. You can use namedPattern to organize complicated pattern expressions by naming portions of the pattern. Named patterns can be nested inside named patterns.

newpat = namedPattern(pat,name) specifies a custom name for pat.

newpat = namedPattern(pat,name,description) additionally specifies a display description for pat.

Examples

Create Named Patterns to Organize Complicated Patterns

Use namedPattern to assign a pattern to a named pattern.

Build a pattern that matches simple arithmetic expressions composed of numbers and arithmetic operators.

mathSymbols = asManyOfPattern(digitsPattern | characterListPattern("+-*/="),1)

mathSymbols = pattern
  Matching:

    asManyOfPattern(digitsPattern | characterListPattern("+-*/="),1)

Build a pattern that matches arithmetic expressions with whitespaces between characters using the named pattern.

longExpressionPat = asManyOfPattern(mathSymbols + whitespacePattern) + mathSymbols

longExpressionPat = pattern
  Matching:

    asManyOfPattern(asManyOfPattern(digitsPattern | characterListPattern("+-*/="),1) + whitespacePattern) + asManyOfPattern(digitsPattern | characterListPattern("+-*/="),1)

This expression is long and hard to read. Use namedPattern to assign the pattern to the named pattern, mathSymbols.

mathSymbols = namedPattern(mathSymbols);
shortExpressionPat = asManyOfPattern(mathSymbols + whitespacePattern) + mathSymbols

shortExpressionPat = pattern
  Matching:

    asManyOfPattern(mathSymbols + whitespacePattern) + mathSymbols

  Using named patterns:

    mathSymbols: asManyOfPattern(digitsPattern | characterListPattern("+-*/="),1)

Create a string containing some arithmetic expressions, and then extract the pattern from the text.

txt = "What is the answer to 1 + 1? Oh, I know! 1 + 1 = 2!";
arithmetic = extract(txt,shortExpressionPat)

arithmetic = 2x1 string
    "1 + 1"
    "1 + 1 = 2"

Specify Names and Descriptions for Complicated Patterns

Create a pattern from two named patterns. Naming patterns adds context to the display of the pattern.

Build two patterns: one that matches words that begin and end with the letter D, and one that matches words that begin and end with the letter R.

dWordsPat = letterBoundary + caseInsensitivePattern("d" + lettersPattern + "d") + letterBoundary;
rWordsPat = letterBoundary + caseInsensitivePattern("r" + lettersPattern + "r") + letterBoundary;

Build a pattern using the named patterns that finds a word that starts and ends with D followed by a word that starts and ends with R.

dAndRWordsPat = dWordsPat + whitespacePattern + rWordsPat

dAndRWordsPat = pattern
  Matching:

    letterBoundary + caseInsensitivePattern("d" + lettersPattern + "d") + letterBoundary + whitespacePattern + letterBoundary + caseInsensitivePattern("r" + lettersPattern + "r") + letterBoundary

This pattern is hard to read and does not convey much information about its purpose. Use namedPattern to designate the patterns as named patterns that display specified names and descriptions in place of the pattern expressions.

dWordsPat = namedPattern(dWordsPat,"dWords", "Words that start and end with D");
rWordsPat = namedPattern(rWordsPat,"rWords", "Words that start and end with R");
dAndRWordsPat = dWordsPat + whitespacePattern + rWordsPat

dAndRWordsPat = pattern
  Matching:

    dWords + whitespacePattern + rWords

  Using named patterns:

    dWords: Words that start and end with D
    rWords: Words that start and end with R

  Use details to show more information

Create a string and extract the text that matches the pattern.

txt = "Dad, look at the divided river!";
words = extract(txt,dAndRWordsPat)

words = 
"divided river"

Match Email Addresses

Build an easy to read pattern to match email addresses.

Email addresses follow the structure [e-mail], where username and domain are made up of identifiers separated by periods. Build a pattern that matches identifiers composed of any combination of alphanumeric characters and "_" characters. Use maskedPattern to name this pattern identifier.

identifier = asManyOfPattern(alphanumericsPattern(1) | "_", 1);
identifier = maskedPattern(identifier);

Build patterns to match domains and subdomains comprised of identifiers. Create a pattern that matches TLDs from a specified list.

subdomain = asManyOfPattern(identifier + ".") + identifier;
domainName = namedPattern(identifier,"domainName");
tld = "com" | "org" | "gov" | "net" | "edu";

Build a pattern for matching the local part of an email, which matches one or more identifiers separated by periods. Build a pattern for matching the domain, TLD, and any potential subdomains by combining the previously defined patterns. Use namedPattern to assign each of these patterns to a named pattern.

username = asManyOfPattern(identifier + ".") + identifier;
domain = optionalPattern(namedPattern(subdomain) + ".") + ...
            domainName + "." + ...
            namedPattern(tld);

Combine all of the patterns into a single pattern expression. Use namedPattern to assign username, domain, and emailPattern to named patterns.

emailAddress = namedPattern(username) + "@" + namedPattern(domain);
emailPattern = namedPattern(emailAddress)

emailPattern = pattern
  Matching emailAddress:

    username + "@" + domain

  Using named patterns:

    emailAddress  : username + "@" + domain
      username    : asManyOfPattern(identifier + ".") + identifier
      domain      : optionalPattern(subdomain + ".") + domainName + "." + tld
        subdomain : asManyOfPattern(identifier + ".") + identifier
        domainName: identifier
        tld       : "com" | "org" | "gov" | "net" | "edu"

  Use details to show more information

Create a string that contains an email address, and then extract the pattern from the text.

txt = "You can reach me by email at [e-mail]";
extract(txt,emailPattern)

ans = 
"[e-mail]"

Named patterns allow dot-indexing in order to access named subpatterns. Use dot-indexing to assign a specific value to the named pattern domain.

emailPattern.emailAddress.domain = "mathworks.com"

emailPattern = pattern
  Matching emailAddress:

    username + "@" + domain

  Using named patterns:

    emailAddress: username + "@" + domain
      username  : asManyOfPattern(identifier + ".") + identifier
      domain    : "mathworks.com"

  Use details to show more information

Input Arguments

pat — Input pattern

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

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

Data Types: char | string | pattern | cell

name — Pattern name

string array | character vector | cell array of character vectors

Pattern name, specified as a string scalar, character vector, or cell array of character vectors.

Data Types: char | string | cell

description — Named pattern description

string array | character vector | cell array of character vectors

Named pattern description, specified as a string scalar, character vector, or cell array of character vectors. When a pattern expression is displayed, named patterns and their descriptions will be displayed separately from the full pattern expression.

Data Types: char | string | cell

Output Arguments

newpat — Output pattern

pattern (default) | array of pattern objects

Output pattern, returned as a pattern or an array of pattern objects.

Extended Capabilities

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

Version History

Introduced in R2020b