Accelerating the pace of engineering and science

# Documentation Center

• Trial Software

## Regular Expressions

### What Is a Regular Expression?

A regular expression is a string of characters that defines a certain pattern. You normally use a regular expression to search text for a group of words that matches the pattern, for example, while parsing program input or while processing a block of text.

The string 'Joh?n\w*' is an example of a regular expression. It defines a pattern that starts with the letters Jo, is optionally followed by the letter h (indicated by 'h?'), is then followed by the letter n, and ends with any number of word characters, that is, characters that are alphabetic, numeric, or underscore (indicated by '\w*'). This pattern matches any of the following:

Jon, John, Jonathan, Johnny

Regular expressions provide a unique way to search a volume of text for a particular subset of characters within that text. Instead of looking for an exact character match as you would do with a function like strfind, regular expressions give you the ability to look for a particular pattern of characters.

For example, several ways of expressing a metric rate of speed are:

km/h
km/hr
km/hour
kilometers/hour
kilometers per hour

You could locate any of the above terms in your text by issuing five separate search commands:

strfind(text, 'km/h');
strfind(text, 'km/hour');
% etc.

To be more efficient, however, you can build a single phrase that applies to all of these search strings:

Translate this phrase it into a regular expression (to be explained later in this section) and you have:

pattern = 'k(ilo)?m(eters)?(/|\sper\s)h(r|our)?';

Now locate one or more of the strings using just a single command:

text = ['The high-speed train traveled at 250 ', ...
'kilometers per hour alongside the automobile ', ...
'travelling at 120 km/h.'];
regexp(text, pattern, 'match')
ans =
'kilometers per hour'    'km/h'

There are four MATLAB® functions that support searching and replacing characters using regular expressions. The first three are similar in the input values they accept and the output values they return. For details, click the links to the function reference pages.

FunctionDescription
regexp

Match regular expression.

regexpi

Match regular expression, ignoring case.

regexprep

Replace part of string using regular expression.

regexptranslate

Translate string into regular expression.

When calling any of the first three functions, pass the string to be parsed and the regular expression in the first two input arguments. When calling regexprep, pass an additional input that is an expression that specifies a pattern for the replacement string.

### Steps for Building Expressions

There are three steps involved in using regular expressions to search text for a particular string:

1. This entails breaking up the string you want to search for into groups of like character types. These character types could be a series of lowercase letters, a dollar sign followed by three numbers and then a decimal point, etc.

2. Use the metacharacters and operators described in this documentation to express each segment of your search string as a regular expression. Then combine these expression segments into the single expression to use in the search.

3. Call the appropriate search function

Pass the string you want to parse to one of the search functions, such as regexp or regexpi, or to the string replacement function, regexprep.

The example shown in this section searches a record containing contact information belonging to a group of five friends. This information includes each person's name, telephone number, place of residence, and email address. The goal is to extract specific information from one or more of the strings.

contacts = { ...
'Harry  287-625-7315  Columbus, OH  hparker@hmail.com'; ...
'Janice  529-882-1759  Fresno, CA  jan_stephens@horizon.net'; ...
'Mike  793-136-0975  Richmond, VA  sue_and_mike@hmail.net'; ...
'Jason  697-336-7728  Montrose, CO  jason_blake@mymail.com'};

The first part of the example builds a regular expression that represents the format of a standard email address. Using that expression, the example then searches the information for the email address of one of the group of friends. Contact information for Janice is in row 2 of the contacts cell array:

contacts{2}
ans =
Janice  529-882-1759  Fresno, CA  jan_stephens@horizon.net

#### Step 1 — Identify Unique Patterns in the String

A typical email address is made up of standard components: the user's account name, followed by an @ sign, the name of the user's internet service provider (ISP), a dot (period), and the domain to which the ISP belongs. The table below lists these components in the left column, and generalizes the format of each component in the right column.

Unique patterns of an email addressGeneral description of each pattern
jan_stephens  . . .
One or more lowercase letters and underscores
jan_stephens@  . . .
@ sign
jan_stephens@horizon  . . .
One or more lowercase letters, no underscores
jan_stephens@horizon.  . . .
Dot (period) character
Finish with the domain
jan_stephens@horizon.net
com or net

#### Step 2 — Express Each Pattern as a Regular Expression

In this step, you translate the general formats derived in Step 1 into segments of a regular expression. You then add these segments together to form the entire expression.

The table below shows the generalized format descriptions of each character pattern in the left-most column. (This was carried forward from the right column of the table in Step 1.) The second column shows the operators or metacharacters that represent the character pattern.

Description of each segmentPattern
One or more lowercase letters and underscores[a-z_]+
@ sign@
One or more lowercase letters, no underscores[a-z]+
Dot (period) character\.
com or net(com|net)

Assembling these patterns into one string gives you the complete expression:

email = '[a-z_]+@[a-z]+\.(com|net)';

#### Step 3 — Call the Appropriate Search Function

In this step, you use the regular expression derived in Step 2 to match an email address for one of the friends in the group. Use the regexp function to perform the search.

Here is the list of contact information shown earlier in this section. Each person's record occupies a row of the contacts cell array:

contacts = { ...
'Harry  287-625-7315  Columbus, OH  hparker@hmail.com'; ...
'Janice  529-882-1759  Fresno, CA  jan_stephens@horizon.net'; ...
'Mike  793-136-0975  Richmond, VA  sue_and_mike@hmail.net'; ...
'Jason  697-336-7728  Montrose, CO  jason_blake@mymail.com'};

This is the regular expression that represents an email address, as derived in Step 2:

email = '[a-z_]+@[a-z]+\.(com|net)';

Call the regexp function, passing row 2 of the contacts cell array and the email regular expression. This returns the email address for Janice.

regexp(contacts{2}, email, 'match')
ans =
'jan_stephens@horizon.net'

MATLAB parses a string from left to right, "consuming" the string as it goes. If matching characters are found, regexp records the location and resumes parsing the string, starting just after the end of the most recent match.

Make the same call, but this time for the fifth person in the list:

regexp(contacts{5}, email, 'match')
ans =
'jason_blake@mymail.com'

You can also search for the email address of everyone in the list by using the entire cell array for the input string argument:

regexp(contacts, email, 'match');

### Operators and Characters

Regular expressions can contain characters, metacharacters, operators, tokens, and flags that specify patterns to match, as described in these sections:

#### Metacharacters

Metacharacters represent letters, letter ranges, digits, and space characters. Use them to construct a generalized pattern of characters.

Metacharacter

Description

Example

.

Any single character, including white space

'..ain' matches sequences of five consecutive characters that end with 'ain'.

[c1c2c3]

Any character contained within the brackets. The following characters are treated literally: \$ | . * + ? and - when not used to indicate a range.

'[rp.]ain' matches 'rain' or 'pain' or ‘.ain'.

[^c1c2c3]

Any character not contained within the brackets. The following characters are treated literally: \$ | . * + ? and - when not used to indicate a range.

'[^*rp]ain' matches all four-letter sequences that end in 'ain', except 'rain' and 'pain' and ‘*ain'. For example, it matches 'gain', 'lain', or 'vain'.

[c1-c2]

Any character in the range of c1 through c2

'[A-G]' matches a single character in the range of A through G.

\w

Any alphabetic, numeric, or underscore character. For English character sets, \w is equivalent to [a-zA-Z_0-9]

'\w*' identifies a word.

\W

Any character that is not alphabetic, numeric, or underscore. For English character sets, \W is equivalent to [^a-zA-Z_0-9]

'\W*' identifies a substring that is not a word.

\s

Any white-space character; equivalent to [ \f\n\r\t\v]

'\w*n\s' matches words that end with the letter n, followed by a white-space character.

\S

Any non-white-space character; equivalent to [^ \f\n\r\t\v]

'\d\S' matches a numeric digit followed by any non-white-space character.

\d

Any numeric digit; equivalent to [0-9]

'\d*' matches any number of consecutive digits.

\D

Any nondigit character; equivalent to [^0-9]

'\w*\D\>' matches words that do not end with a numeric digit.

\oN or \o{N}

Character of octal value N

'\o{40}' matches the space character, defined by octal 40.

\xN or \x{N}

'\x2C' matches the comma character, defined by hex 2C.

#### Character Representation

Operator

Description

\a

Alarm (beep)

\b

Backspace

\f

Form feed

\n

New line

\r

Carriage return

\t

Horizontal tab

\v

Vertical tab

\char

Any character with special meaning in regular expressions that you want to match literally (for example, use \\ to match a single backslash)

#### Quantifiers

Quantifiers specify the number of times a string pattern must occur in the matching string.

Quantifier

Matches the expression when it occurs...

Example

expr*

0 or more times consecutively.

'\w*' matches a word of any length.

expr?

0 times or 1 time.

'\w*(\.m)?' matches words that optionally end with the extension .m.

expr+

1 or more times consecutively.

'<img src="\w+\.gif">' matches an <img> HTML tag when the file name contains one or more characters.

expr{m,n}

At least m times, but no more than n times consecutively.

{0,1} is equivalent to ?.

'\S{4,8}' matches between four and eight non-white-space characters.

expr{m,}

At least m times consecutively.

{0,} and {1,} are equivalent to * and +, respectively.

'<a href="\w{1,}\.html">' matches an <a> HTML tag when the file name contains one or more characters.

expr{n}

Exactly n times consecutively.

Equivalent to {n,n}.

'\d{4}' matches four consecutive digits.

Quantifiers can appear in three modes, described in the following table. q represents any of the quantifiers in the previous table.

Mode

Description

Example

exprq

Greedy expression: match as many characters as possible.

Given the string '<tr><td><p>text</p></td>', the expression '</?t.*>' matches all characters between <tr and /td>:

'<tr><td><p>text</p></td>'

exprq?

Lazy expression: match as few characters as necessary.

Given the string '<tr><td><p>text</p></td>', the expression '</?t.*?>' ends each match at the first occurrence of the closing bracket (>):

'<tr>'   '<td>'   '</td>'

exprq+

Possessive expression: match as much as possible, but do not rescan any portions of the string.

Given the string '<tr><td><p>text</p></td>', the expression '</?t.*+>' does not return any matches, because the closing bracket is captured using .*, and is not rescanned.

#### Grouping Operators

Grouping operators allow you to capture tokens, apply one operator to multiple elements, or disable backtracking in a specific group.

Grouping Operator

Description

Example

(expr)

Group elements of the expression and capture tokens.

'Joh?n\s(\w*)' captures a token that contains the last name of any person with the first name John or Jon.

(?:expr)

Group, but do not capture tokens.

'(?:[aeiou][^aeiou]){2}' matches two consecutive patterns of a vowel followed by a nonvowel, such as 'anon'.

Without grouping, '[aeiou][^aeiou]{2}'matches a vowel followed by two nonvowels.

(?>expr)

Group atomically. Do not backtrack within the group to complete the match, and do not capture tokens.

'A(?>.*)Z' does not match 'AtoZ', although 'A(?:.*)Z' does. Using the atomic group, Z is captured using .* and is not rescanned.

(expr1|expr2)

Match expression expr1 or expression expr2.

If there is a match with expr1, then expr2 is ignored.

You can include ?: or ?> after the opening parenthesis to suppress tokens or group atomically.

'(let|tel)\w+' matches words in a string that start with let or tel.

#### Anchors

Anchors in the expression match the beginning or end of the string or word.

Anchor

Matches the...

Example

^expr

Beginning of the input string.

'^M\w*' matches a word starting with M at the beginning of the string.

expr\$

End of the input string.

'\w*m\$' matches words ending with m at the end of the string.

\<expr

Beginning of a word.

'\<n\w*' matches any words starting with n.

expr\>

End of a word.

'\w*e\>' matches any words ending with e.

#### Lookaround Assertions

Lookaround assertions look for string patterns that immediately precede or follow the intended match, but are not part of the match.

The pointer remains at the current location, and characters that correspond to the test expression are not captured or discarded. Therefore, lookahead assertions can match overlapping character groups.

Lookaround Assertion

Description

Example

expr(?=test)

Look ahead for characters that match test.

'\w*(?=ing)' matches strings that are followed by ing, such as 'Fly' and 'fall' in the input string 'Flying, not falling.'

expr(?!test)

Look ahead for characters that do not match test.

'i(?!ng)' matches instances of the letter i that are not followed by ng.

(?<=test)expr

Look behind for characters that match test..

'(?<=re)\w*' matches strings that follow 're', such as 'new', 'use', and 'cycle' in the input string 'renew, reuse, recycle'

(?<!test)expr

Look behind for characters that do not match test.

'(?<!\d)(\d)(?!\d)' matches single-digit numbers (digits that do not precede or follow other digits).

If you specify a lookahead assertion before an expression, the operation is equivalent to a logical AND.

Operation

Description

Example

(?=test)expr

Match both test and expr.

'(?=[a-z])[^aeiou]' matches consonants.

(?!test)expr

Match expr and do not match test.

'(?![aeiou])[a-z]' matches consonants.

#### Logical and Conditional Operators

Logical and conditional operators allow you to test the state of a given condition, and then use the outcome to determine which string, if any, to match next. These operators support logical OR and if or if/else conditions. (For AND conditions, see Lookaround Assertions.)

Conditions can be tokens, lookaround assertions, or dynamic expressions of the form (?@cmd). Dynamic expressions must return a logical or numeric value.

Conditional Operator

Description

Example

expr1|expr2

Match expression expr1 or expression expr2.

If there is a match with expr1, then expr2 is ignored.

'(let|tel)\w+' matches words in a string that start with let or tel.

(?(cond)expr)

If condition cond is true, then match expr.

'(?(?@ispc)[A-Z]:\\)' matches a drive name, such as C:\, when run on a Windows® system.

(?(cond)expr1|expr2)

If condition cond is true, then match expr1. Otherwise, match expr2.

'Mr(s?)\..*?(?(1)her|his) \w*' matches strings that include her when the string begins with Mrs, or that include his when the string begins with Mr.

#### Token Operators

Tokens are portions of the matched text that you define by enclosing part of the regular expression in parentheses. You can refer to a token by its sequence in the string (an ordinal token), or assign names to tokens for easier code maintenance and readable output.

Ordinal Token Operator

Description

Example

(expr)

Capture in a token the characters that match the enclosed expression.

'Joh?n\s(\w*)' captures a token that contains the last name of any person with the first name John or Jon.

\N

Match the Nth token.

'<(\w+).*>.*</\1>' captures tokens for HTML tags, such as 'title' from the string '<title>Some text</title>'.

(?(N)expr1|expr2)

If the Nth token is found, then match expr1. Otherwise, match expr2.

'Mr(s?)\..*?(?(1)her|his) \w*' matches strings that include her when the string begins with Mrs, or that include his when the string begins with Mr.

Named Token Operator

Description

Example

(?<name>expr)

Capture in a named token the characters that match the enclosed expression.

'(?<month>\d+)-(?<day>\d+)-(?<yr>\d+)' creates named tokens for the month, day, and year in an input date string of the form mm-dd-yy.

\k<name>

Match the token referred to by name.

'<(?<tag>\w+).*>.*</\k<tag>>' captures tokens for HTML tags, such as 'title' from the string '<title>Some text</title>'.

(?(name)expr1|expr2)

If the named token is found, then match expr1. Otherwise, match expr2.

'Mr(?<sex>s?)\..*?(?(sex)her|his) \w*' matches strings that include her when the string begins with Mrs, or that include his when the string begins with Mr.

 Note:   If an expression has nested parentheses, MATLAB captures tokens that correspond to the outermost set of parentheses. For example, given the search pattern '(and(y|rew))', MATLAB creates a token for 'andrew' but not for 'y' or 'rew'.

#### Dynamic Expressions

Dynamic expressions allow you to execute a MATLAB command or a regular expression to determine the text to match.

The parentheses that enclose dynamic expressions do not create a capturing group.

Operator

Description

Example

(??expr)

Parse expr and include the resulting string in the match expression.

When parsed, expr must correspond to a complete, valid regular expression. Dynamic expressions that use the backslash escape character (\) require two backslashes: one for the initial parsing of expr, and one for the complete match.

'^(\d+)((??\\w{\$1}))' determines how many characters to match by reading a digit at the beginning of the string. The dynamic expression is enclosed in a second set of parentheses so that the resulting match is captured in a token. For instance, matching '5XXXXX' captures tokens for '5' and 'XXXXX'.

(??@cmd)

Execute the MATLAB command represented by cmd, and include the string returned by the command in the match expression.

'(.{2,}).?(??@fliplr(\$1))' finds palindromes that are at least four characters long, such as 'abba'.

(?@cmd)

Execute the MATLAB command represented by cmd, but discard any output the command returns. (Helpful for diagnosing regular expressions.)

'\w*?(\w)(?@disp(\$1))\1\w*' matches words that include double letters (such as pp), and displays intermediate results.

Within dynamic expressions, use the following operators to define replacement strings.

Replacement String Operator

Description

\$& or \$0

Portion of the input string that is currently a match

\$`

Portion of the input string that precedes the current match

\$'

Portion of the input string that follows the current match (use \$'' to represent the string \$')

\$N

Nth token

\$<name>

Named token

\${cmd}

String returned when MATLAB executes the command, cmd

The comment operator enables you to insert comments into your code to make it more maintainable. The text of the comment is ignored by MATLAB when matching against the input string.

Characters

Description

Example

(?#comment)

Insert a comment in the regular expression. The comment text is ignored when matching the input string.

'(?# Initial digit)\<\d\w+' includes a comment, and matches words that begin with a number.

#### Search Flags

Search flags modify the behavior for matching expressions.

Flag

Description

(?-i)

Match letter case (default for regexp and regexprep).

(?i)

Do not match letter case (default for regexpi).

(?s)

Match dot (.) in the pattern string with any character (default).

(?-s)

Match dot in the pattern with any character that is not a newline character.

(?-m)

Match the ^ and \$ metacharacters at the beginning and end of a string (default).

(?m)

Match the ^ and \$ metacharacters at the beginning and end of a line.

(?-x)

Include space characters and comments when matching (default).

(?x)

Ignore space characters and comments when matching. Use '\ ' and '\#' to match space and # characters.

The expression that the flag modifies can appear either after the parentheses, such as

(?i)\w*

or inside the parentheses and separated from the flag with a colon (:), such as

(?i:\w*)

The latter syntax allows you to change the behavior for part of a larger expression.