regexpi
Match regular expression (case insensitive)
Syntax
Description
returns
the starting index of each substring of startIndex
= regexpi(str
,expression
)str
that
matches the character patterns specified by the regular expression,
without regard to letter case. If there are no matches, startIndex
is
an empty array.
[
returns
the starting and ending indices of all matches.startIndex
,endIndex
]
= regexpi(str
,expression
)
returns
the output specified by out
= regexpi(str
,expression
,outkey
)outkey
. For example,
if outkey
is 'match'
, then regexpi
returns
the substrings that match the expression rather than their starting
indices.
[
returns
the outputs specified by multiple output keywords, in the specified
order. For example, if you specify out
1,...,out
N]
= regexpi(str
,expression
,outkey
1,...,outkey
N)'match'
,'tokens'
,
then regexpi
returns substrings that match the
entire expression and tokens that
match parts of the expression.
___ = regexpi(___,'forceCellOutput')
returns
each output argument as a scalar cell. The cells contain the numeric
arrays or substrings that are described as the outputs of the previous
syntaxes. You can include any of the inputs and request any of the
outputs from previous syntaxes.
Examples
Pattern Matching
Find words that start with c
, end with t
, and contain one or more vowels between them.
str = 'bat cat can car COAT court cut ct CAT-scan'; expression = 'c[aeiou]+t'; startIndex = regexpi(str,expression)
startIndex = 1×4
5 17 28 35
Values in startIndex
indicate the index of the first character of each word that matches the regular expression.
The regular expression 'c[aeiou]+t'
specifies this pattern:
c
must be the first character.c
must be followed by one of the characters inside the brackets,[aeiou]
.The bracketed pattern must occur one or more times, as indicated by the
+
operator.t
must be the last character, with no characters between the bracketed pattern and thet
.
Case-Sensitive Match
Match letter case in all or part of an expression.
By default, regexpi
performs case-insensitive matching.
str = 'A character vector with UPPERCASE and lowercase text.'; expression = '\w*case'; matchStr = regexpi(str,expression,'match')
matchStr = 1x2 cell
{'UPPERCASE'} {'lowercase'}
Use the regexp
function with the same syntax as regexpi
to perform case-sensitive matching.
matchWithRegexp = regexp(str,expression,'match')
matchWithRegexp = 1x1 cell array
{'lowercase'}
To disable case-sensitive matching for regexp
, use the 'ignorecase'
option.
matchWithIgnorecase = regexp(str,expression,'match','ignorecase')
matchWithIgnorecase = 1x2 cell
{'UPPERCASE'} {'lowercase'}
For multiple expressions, enable and disable case-insensitive matching for selected expressions using the (?i)
and (?-i)
search flags.
expression = {'(?-i)\w*case';... '(?i)\w*case'}; matchStr = regexp(str,expression,'match'); celldisp(matchStr)
matchStr{1}{1} = lowercase matchStr{2}{1} = UPPERCASE matchStr{2}{2} = lowercase
Input Arguments
str
— Input text
character vector | cell array of character vectors | string array
Input text, specified as a character vector, a cell array of character vectors, or a string array. Each character vector in a cell array, or each string in a string array, can be of any length and contain any characters.
If str
and expression
are
string arrays or cell arrays, they must have the same dimensions.
Data Types: string
| char
| cell
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 |
|
| Any character contained within the square brackets. The following characters are treated
literally: |
|
| Any character not contained within the square brackets. The following characters are treated
literally: |
|
| Any character in the range of |
|
| Any alphabetic, numeric, or underscore character. For
English character sets, |
|
| Any character that is not alphabetic, numeric, or underscore.
For English character sets, |
|
| Any white-space character; equivalent to |
|
| Any non-white-space character; equivalent to |
|
| Any numeric digit; equivalent to |
|
| Any nondigit character; equivalent to |
|
| Character of octal value |
|
| Character of hexadecimal value |
|
Character Representation
Operator | Description |
---|---|
| Alarm (beep) |
| Backspace |
| Form feed |
| New line |
| Carriage return |
| Horizontal tab |
| Vertical tab |
| Any character with special meaning in regular expressions
that you want to match literally (for example, use |
Quantifiers
Quantifiers specify the number of times a pattern must occur in the matching text.
Quantifier | Number of Times Expression Occurs | Example |
---|---|---|
| 0 or more times consecutively. |
|
| 0 times or 1 time. |
|
| 1 or more times consecutively. |
|
| At least
|
|
| At least
|
|
| Exactly Equivalent
to |
|
Quantifiers can appear in three modes, described in the following table. q represents any of the quantifiers in the previous table.
Mode | Description | Example |
---|---|---|
| Greedy expression: match as many characters as possible. | Given the text
|
| Lazy expression: match as few characters as necessary. | Given the text
|
| Possessive expression: match as much as possible, but do not rescan any portions of the text. | Given the text |
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 |
---|---|---|
| Group elements of the expression and capture tokens. |
|
| Group, but do not capture tokens. |
Without
grouping, |
| Group atomically. Do not backtrack within the group to complete the match, and do not capture tokens. |
|
| Match expression If
there is a match with You can include |
|
Anchors
Anchors in the expression match the beginning or end of the input text or word.
Anchor | Matches the... | Example |
---|---|---|
| Beginning of the input text. |
|
| End of the input text. |
|
| Beginning of a word. |
|
| End of a word. |
|
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 |
---|---|---|
| Look ahead for characters that match |
|
| Look ahead for characters that do not match |
|
| Look behind for characters that match |
|
| Look behind for characters that do not match |
|
If you specify a lookahead assertion before an
expression, the operation is equivalent to a logical AND
.
Operation | Description | Example |
---|---|---|
| Match both |
|
| Match |
|
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 |
---|---|---|
| Match expression If
there is a match with |
|
| If condition |
|
| If condition |
|
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 |
---|---|---|
| Capture in a token the characters that match the enclosed expression. |
|
| Match the |
|
| If the |
|
Named Token Operator | Description | Example |
---|---|---|
| Capture in a named token the characters that match the enclosed expression. |
|
| Match the token referred to by |
|
| If the named token is found, then match |
|
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 |
---|---|---|
| Parse When parsed, |
|
| Execute the MATLAB command represented by |
|
| Execute the MATLAB command represented by |
|
Within dynamic expressions, use the following operators to define replacement text.
Replacement Operator | Description |
---|---|
| 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 |
|
|
| Named token |
| Output returned when MATLAB executes the command, |
Comments
Characters | Description | Example |
---|---|---|
(?#comment) | Insert a comment in the regular expression. The comment text is ignored when matching the input. |
|
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 |
(?i) | Do not match letter case (default for |
(?s) | Match dot ( |
(?-s) | Match dot in the pattern with any character that is not a newline character. |
(?-m) | Match the |
(?m) | Match the |
(?-x) | Include space characters and comments when matching (default). |
(?x) | Ignore space characters and comments when matching. Use |
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
outkey
— Keyword that indicates which outputs to return
'start'
(default) | 'end'
| 'tokenExtents'
| 'match'
| 'tokens'
| 'names'
| 'split'
Keyword that indicates which outputs to return, specified as one of the following character vectors.
Output Keyword | Returns |
---|---|
| Starting indices of all matches, |
| Ending indices of all matches, |
| Starting and ending indices of all tokens |
| Text of each substring that matches the pattern in |
| Text of each captured token in |
| Name and text of each named token |
| Text of nonmatching substrings of |
Data Types: char
| string
option
— Search option
'once'
| 'warnings'
| 'matchcase'
| 'emptymatch'
| 'dotexceptnewline'
| 'lineanchors'
| ...
Search option, specified as a character vector. Options come in pairs: one option that corresponds to the default behavior, and one option that allows you to override the default. Specify only one option from a pair. Options can appear in any order.
Default |
Override |
Description |
---|---|---|
|
|
Match the expression as many times as possible (default), or only once. |
|
|
Suppress warnings (default), or display them. |
|
|
Ignore letter case (default), or match case. |
|
|
Ignore zero length matches (default), or include them. |
|
|
Match dot with any character (default), or all
except newline ( |
|
| Apply |
|
|
Include space characters and comments when
matching (default), or ignore them. With
|
Data Types: char
Output Arguments
startIndex
— Starting index of each match
row vector | cell array of row vectors
Starting indices of each match, returned as a row vector or cell array, as follows:
If
str
andexpression
are both character vectors or string scalars, the output is a row vector (or, if there are no matches, an empty array).If either
str
orexpression
is a cell array of character vectors or a string array, and the other is a character vector or a string scalar, the output is a cell array of row vectors. The output cell array has the same dimensions as the input array.If
str
andexpression
are both cell arrays or string arrays, they must have the same dimensions. The output is a cell array with the same dimensions.
endIndex
— Ending index of each match
row vector | cell array of row vectors
Ending index of each match, returned as a row vector or cell array, as follows:
If
str
andexpression
are both character vectors or string scalars, the output is a row vector (or, if there are no matches, an empty array).If either
str
orexpression
is a cell array of character vectors or a string array, and the other is a character vector or a string scalar, the output is a cell array of row vectors. The output cell array has the same dimensions as the input array.If
str
andexpression
are both cell arrays or string arrays, they must have the same dimensions. The output is a cell array with the same dimensions.
out
— Information about matches
numeric array | cell array | string array | structure array
Information about matches, returned as a numeric, cell, string,
or structure array. The information in the output depends upon the
value you specify for outkey
, as follows.
Output Keyword | Output Description | Output Type and Dimensions |
---|---|---|
| Starting indices of matches | For both
|
| Ending indices of matches | |
| Starting and ending indices of all tokens | By default, when returning all matches:
When you specify the If
a token is expected at a particular index |
| Text of each substring that matches the pattern in | By default, when returning all matches:
When you specify the |
| Text of each captured token in | By default, when returning all matches:
When you specify the If
a token is expected at a particular index, but is not found, then MATLAB returns
an empty value for the token, |
| Name and text of each named token | For all matches:
|
| Text of nonmatching substrings of | For all matches:
|
More About
Tokens
Tokens are portions of the matched text that correspond to portions of the regular expression. To create tokens, enclose part of the regular expression in parentheses.
For example, this expression finds a date of the form dd-mmm-yyyy
,
including tokens for the day, month, and year.
str = 'Here is a date: 01-Apr-2020'; expression = '(\d+)-(\w+)-(\d+)'; mydate = regexp(str,expression,'tokens'); mydate{:}
ans = 1×3 cell array {'01'} {'Apr'} {'2020'}
You can associate names with tokens so that they are more easily identifiable:
str = 'Here is a date: 01-Apr-2020'; expression = '(?<day>\d+)-(?<month>\w+)-(?<year>\d+)'; mydate = regexp(str,expression,'names')
mydate = struct with fields: day: '01' month: 'Apr' year: '2020'
For more information, see Tokens in Regular Expressions.
Extended Capabilities
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
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)