regexprep

Replace text using regular expression

Syntax

newStr = regexprep(str,expression,replace)

newStr = regexprep(str,expression,replace,option1,...optionM)

Description

newStr = regexprep(str,expression,replace) replaces the text in str that matches expression with the text described by replace. The regexprep function returns the updated text in newStr.

• If str is a single piece of text (either a character vector or a string scalar), then newStr is also a single piece of text of the same type. newStr is a single piece of text even when expression or replace is a cell array of character vectors or a string array. When expression is a cell array or a string array, regexprep applies the first expression to str, and then applies each subsequent expression to the preceding result.

• If str is a cell array or a string array, then newStr is a cell array or string array with the same dimensions as str. For each element of str, the regexprep function applies each expression in sequence.

• If there are no matches to expression, then newStr is equivalent to str.

newStr = regexprep(str,expression,replace,option1,...optionM) modifies the search using the specified options. For example, specify 'ignorecase' to perform a case-insensitive match.

Examples

Update Text

Replace words that begin with M, end with y, and have at least one character between them.

str = 'My flowers may bloom in May';
expression = 'M(\w+)y';
replace = 'April';

newStr = regexprep(str,expression,replace)

newStr = 
'My flowers may bloom in April'

Include Tokens in Replacement Text

Replace variations of the phrase 'walk up' by capturing the letters that follow 'walk' in a token.

str = 'I walk up, they walked up, we are walking up.';
expression = 'walk(\w*) up';
replace = 'ascend$1';

newStr = regexprep(str,expression,replace)

newStr = 
'I ascend, they ascended, we are ascending.'

Include Dynamic Expression in Replacement Text

Replace lowercase letters at the beginning of sentences with their uppercase equivalents using the upper function.

str = 'here are two sentences. neither is capitalized.';
expression = '(^|\.)\s*.';
replace = '${upper($0)}';

newStr = regexprep(str,expression,replace)

newStr = 
'Here are two sentences. Neither is capitalized.'

The regular expression matches single characters (.) that follow the beginning of the character vector (^) or a period (\.) and any whitespace (\s*). The replace expression calls the upper function for the currently matching character ($0).

Update Multiple Pieces of Text

Replace each occurrence of a double letter in a set of character vectors with the symbols '--'.

str = {                                 ...
'Whose woods these are I think I know.' ; ...
'His house is in the village though;'   ; ...
'He will not see me stopping here'      ; ...
'To watch his woods fill up with snow.'};

expression = '(.)\1';
replace = '--';
newStr = regexprep(str,expression,replace)

newStr = 4x1 cell
    {'Whose w--ds these are I think I know.'}
    {'His house is in the vi--age though;'  }
    {'He wi-- not s-- me sto--ing here'     }
    {'To watch his w--ds fi-- up with snow.'}

Preserve Case in Original Text

Ignore letter case in the regular expression when finding matches, but mimic the letter case of the original text when updating.

str = 'My flowers may bloom in May';
expression = 'M(\w+)y';
replace = 'April';

newStr = regexprep(str,expression,replace,'preservecase')

newStr = 
'My flowers april bloom in April'

Replace Zero-Length Matches

Insert text at the beginning of a character vector using the '^' operator, which returns a zero-length match, and the 'emptymatch' keyword.

str = 'abc';
expression = '^';
replace = '__';

newStr = regexprep(str,expression,replace,'emptymatch')

newStr = 
'__abc'

Input Arguments

str — Text to update

character vector | cell array of character vectors | string array

Text to update, specified as a character vector, a cell array of character vectors, or a string array.

Data Types: char | cell | string

expression — Regular expression

character vector | cell array of character vectors | string array

Regular expression, specified as a character vector, a cell array of character vectors, or a string array. Each expression can contain characters, metacharacters, operators, tokens, and flags that specify patterns to match in str.

The following tables describe the elements of regular expressions.

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 square 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 square 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 comprised of any grouping of alphabetic, numeric, or underscore characters.
\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 term that is not a word comprised of any grouping of alphabetic, numeric, or underscore characters.
\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}	Character of hexadecimal value 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 pattern must occur in the matching text.

Quantifier	Number of Times Expression 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 text '<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 text'<tr><td><p>text</p></td>', the expression '</?t.*?>' ends each match at the first occurrence of the closing angle bracket (>): '<tr>' '<td>' '</td>'
exprq+	Possessive expression: match as much as possible, but do not rescan any portions of the text.	Given the text'<tr><td><p>text</p></td>', the expression '</?t.*+>' does not return any matches, because the closing angle 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 that contain, but do not end, with let or tel.

Anchors

Anchors in the expression match the beginning or end of the input text or word.

Anchor	Matches the...	Example
^expr	Beginning of the input text.	'^M\w*' matches a word starting with M at the beginning of the text.
expr$	End of the input text.	'\w*m$' matches words ending with m at the end of the text.
\<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 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 terms that are followed by ing, such as 'Fly' and 'fall' in the input text '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 terms that follow 're', such as 'new', 'use', and 'cycle' in the input text '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 pattern, if any, to match next. These operators support logical OR, and if or if/else conditions.

Conditions can be tokens, lookaround operators, 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 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 text that includes her when the text begins with Mrs, or that includes his when the text 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 text (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 text '<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 text that includes her when the text begins with Mrs, or that includes his when the text 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 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 text '<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 text that includes her when the text begins with Mrs, or that includes his when the text 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 Regular 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 term 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 match. 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 output 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 text.

Replacement Operator	Description
$& or $0	Portion of the input text that is currently a match
$`	Portion of the input text that precedes the current match
$'	Portion of the input text that follows the current match (use $'' to represent $')
$N	Nth token
$<name>	Named token
${cmd}	Output returned when MATLAB executes the command, cmd

Comments

Characters	Description	Example
(?#comment)	Insert a comment in the regular expression. The comment text is ignored when matching the input.	'(?# 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. An alternative to using a search flag within an expression is to pass an option input argument.

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 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 text (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.

Data Types: char | cell | string

replace — Replacement text

character vector | cell array of character vectors | string array

Replacement text, specified as a character vector, a cell array of character vectors, or a string array, as follows:

• If replace is a single character vector and expression is a cell array of character vectors, then regexprep uses the same replacement text for each expression.

• If replace is a cell array of N character vectors and expression is a single character vector, then regexprep attempts N matches and replacements.

• If both replace and expression are cell arrays of character vectors, then they must contain the same number of elements. regexprep pairs each replace element with its matching element in expression.

The replacement text can include regular characters, special characters (such as tabs or new lines), or replacement operators, as shown in the following tables.

Replacement Operator	Description
$& or $0	Portion of the input text that is currently a match
$`	Portion of the input text that precedes the current match
$'	Portion of the input text that follows the current match (use $'' to represent $')
$N	Nth token
$<name>	Named token
${cmd}	Output returned when MATLAB executes the command, cmd

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)

Data Types: char | cell | string

option — Search or replacement option

'once' | N | 'warnings' | 'ignorecase' | 'preservecase' | 'emptymatch' | 'dotexceptnewline' | 'lineanchors' | ...

Search or replacement option, specified as a character vector or an integer value, as shown in the following table.

Options come in sets: one option that corresponds to the default behavior, and one or two options that allow you to override the default. Specify only one option from a set. Options can appear in any order.

Default	Override	Description
'all'	'once'	Match and replace the expression as many times as possible (default), or only once.
	N	Replace only the Nth occurrence of the match, where N is an integer value.
'nowarnings'	'warnings'	Suppress warnings (default), or display them.
'matchcase'	'ignorecase'	Match letter case (default), or ignore case while matching and replacing.
	'preservecase'	Ignore case while matching, but preserve the case of corresponding characters in the original text while replacing if they match one of the following structures: If the original text is all lowercase, the replacement will be all lowercase. If the original text is all uppercase, the replacement will be all uppercase. If the original text has multiple words and the first letter of each word is capitalized, the replacement will have the same format. If the original text has multiple words and only the first letter of the first word is capitalized, the replacement will have the same format. If the original text does not match one of these structures then the replacement text will be all lowercase.
'noemptymatch'	'emptymatch'	Ignore zero length matches (default), or include them.
'dotall'	'dotexceptnewline'	Match dot with any character (default), or all except newline (\n).
'stringanchors'	'lineanchors'	Apply ^ and $ metacharacters to the beginning and end of a character vector (default), or to the beginning and end of a line. The newline character (\n) specifies the end of a line. The beginning of a line is specified as the first character, or any character that immediately follows a newline character.
'literalspacing'	'freespacing'	Include space characters and comments when matching (default), or ignore them. With freespacing, use '\ ' and '\#' to match space and # characters.

Data Types: char | string

Output Arguments

newStr — Updated text

character vector | cell array of character vectors | string array

Updated text, returned as a character vector, a cell array of character vectors, or a string array. The data type of newStr is the same as the data type of str.

Extended Capabilities

Tall Arrays

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

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

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.

Version History

Introduced before R2006a