template<typename S>
class QRegularExpression< S >

A regular expression is a sequence of characters that define a search pattern and is often abbreviated as a regex or regexp. Regular expressions can be used for searching and extracting text from an existing string.

The following table shows various uses for regular expressions.

Category	Description	Sample Usage
Validation	test whether a substring meets a given set of criteria specified by a pattern	does the string contain an integer, does it contain any whitespaces
Searching	can match a more complex pattern than a generic substring match	does the string contain the word apple while ignoring the word pineapple
Search & Replace	replace a substring with a different substring	replace all occurrences of & with & except where the & is already followed by an amp;
String Splitting	identify where a string should be split apart	break a string on sentence boundaries

Several examples are provided which show the syntax for updating source code in your application which used the obsolete QRegExp class. Your code may need to be updated in order to use the CopperSpice QRegularExpression class. For more information refer to QRegularExpression Migration.

Theory of Regular Expressions

In order to use a regular expression a search pattern is required. The pattern consists of some combination of the following categories or grammar types.

Literal Characters

The simplest expression for a search pattern is a literal character. For example, X or 5.

Character Classes or Character Sets

A character class is a set of characters used to define the content of the search pattern. The syntax for declaring a character class uses square brackets. There are also predefined character classes which use a backslash followed by a single character.

Quantifiers

A quantifier specifies the number of occurrences or the length the search pattern should match. A quantifier will bind to the expression group to its immediate left. For information about groups refer to Grouping.

Assertions

Assertions do not match characters but rather a location in the string. Two examples of assertions are ^ and $. The caret is a notation for the beginning of the string while the dollar sign is a notation for the end of the string.

---

Character Class Example

The search pattern [ABCD] will match an A or a B or a C or a D. This same expression can be written using a range [A-D].

An expression to match any capital letter in the English alphabet is written as [A-Z].

Some of the character classes and quantifiers are so common they have been given special symbols to represent them. The expression \d is a shorthand notation for [0-9]. Refer to the Shorthand Character Classes table.

Quantifier Example

The search pattern x{1,1} means match one and only one x. If the search pattern was x{1,5}, this means match a sequence of x characters that contains at least one x but no more than five characters.

Assertion Example

If the search pattern was ^b the intent is to match the letter at the beginning of the search text. If the text string was bubble only the first b will match and nothing more. If the search pattern was changed to b$ to match at the end of the string, there is no match.

A word boundary is another very common type of assertion. A pair of word boundaries will match a full word and not a portion of a word. A single word boundary allows matching the beginning or end of a word.

Using the following search pattern and string, a match is found for apples but not for pineapples.

Using the following search pattern and string, a match is will be found for es three times in apples, oranges, and pineapples.

Refer to the Assertion Table below for additional expressions.

---

Grouping

Defining a group marks part of a regular expression as a single unit. It is denoted by using parentheses. There are several reasons to use a group in a regular expression.

• simplifies the regular expression pattern
• a quantifier can be applied to any group
• identifies a section of the regular expression which will be captured

Using the following search pattern and string, a match is found for the group an every time it occurs. The pattern will match bana, banana, bananana. The underline portion shows what the indicated group matches.

Another reason to group part of a regular expression is to create a captured group. If the regular expression match is successful the group matches are automatically numbered. The capturing group number #0 can be used to retrieve the substring matched by the entire pattern. Additional numeric capturing groups will exist for each subsequent match.

For additional information and examples refer to the section about extracting captured substrings.

Summary of Expressions

Non-Printable Characters

Expression	Description	ASCII
\a	Match bell	BEL, 0x07
\f	Match form feed	FF, 0x0C
\n	Match line feed	LF, 0x0A, Unix newline
\r	Match carriage return	CR, 0x0D
\t	Match horizontal tab	HT, 0x09
\v	Match vertical tab	VT, 0x0B

Special Characters

Expression	Description	Notes
\xhhhh	Match the character for the hexadecimal number hhhh	Value 0x0000 to 0xFFFF
\0ooo	Match the character for the octal number ooo	Value 0 to 0377
\n	Back reference number n	\1, \2, etc

Syntax for Character Classes

Expression	Description	Notes
-	Indicates a range of characters	[W-Z] matches 'W', 'X', 'Y', or 'Z'
^	Negates the character class when the caret is the first character	[^abc] match any character except 'a' or 'b' or 'c'

Character Classes

Expression	Description	Notes
[:alnum:]	Alphanumeric character
[:alpha:]	Alpha character	QChar32::isLetter()
[:blank:]	Space or tab
[:cntrl:]	Control character
[:digit:]	Any Digit	QChar32::isDigit()
[:graph:]	Alphanumeric or punctuation
[:lower:]	Lower case character	QChar32::isLower()
[:print:]	Printable character	QChar32::isPrint()
[:punct:]	Punctuation character	QChar32::isPunct()
[:space:]	Whitespace character	QChar32::isSpace()
[:word:]	Letter, number, mark, or underscore	QChar32::isLetterOrNumber()   QChar32::isMark()
[:upper:]	Upper case character	QChar32::isUpper()
[:xdigit:]	Hex digit

Shorthand Character Classes

Expression	Description	Notes
. (dot)	Any character including a newline
\d	Any Digit	QChar32::isDigit()
\l	Lower case character	QChar32::isLower()
\D	Non-digit
\h	Space or tab
\s	Whitespace character	QChar32::isSpace()
\S	Non-whitespace character
\u	Upper case character	QChar32::isUpper()
\w	Letter, number, mark, or underscore	QChar32::isLetterOrNumber()   QChar32::isMark()
\W	Anything which is not matched by \w

Quantifiers Table

Expression	Description
*	Match zero or more times
+	Match one or more times
?	Match zero or one time
{n}	Match exactly n times
{n,}	Match at least n times
{n,m}	Match from n to m times

Assertion Table

Expression	Description
^	Match the beginning of the string
$	Match the end of the string
\b	Word boundary
\B	Not a word boundary
(?=EXP)	Positive lookahead, "EXP" can be any regular expression
(?!EXP)	Negative lookahead, "EXP" can be any regular expression

Operator Table

Operators	Description
|	OR operator
( )	Defines a group
[ ]	Defines a character class

Regular expression - Example 1

Problem: Define a regular expression which will match integers in the range 0 to 99.

At least one digit is required so we start with the expression [0-9]{1,1} which matches a single digit exactly once. This regular expression matches integers in the range 0 to 9. To match integers up to 99 increase the maximum number of occurrences to 2 so the regular expression becomes [0-9]{1,2}.

This regular expression satisfies the original requirement to match integers from 0 to 99 and it will also match integers which occur in the middle of strings. If we want the match integer to be the whole string then use the anchor assertions ^ and $.

The regular expression now becomes ^[0-9]{1,2}$.

Regular expression - Example 2

Problem: Optimize the search pattern ^[0-9]{1,2}$

The character class [0-9] can be replaced with the shortcut symbol \d. So the regular expression now becomes ^\d{1,2}$.

The quantifier part {1,2} can be rewritten as {0,1} by repeating the expression it quantifies. So the regular expression can now be represented by ^\d\d{0,1}$. This can be further enhanced by using a ? which is shorthand for the quantifier {0,1}.

The regular expression when it is optimized becomes ^\d\d?$.

• from the beginning of the string
• match one digit
• followed immediately by 0 or 1 more digits
• followed immediately by end of string

Regular expression - Example 3

Problem: Replace ampersand characters with the HTML entity &amp;.

The regular expression to match an ampersand is &.

However, this will also match any string that has already been converted. We want to replace only ampersands which are not already followed by amp;. The negative lookahead assertion can be used to peek ahead and check what follows the ampersand.

Adding the lookahead will change the regular expression to &(?!amp;)

Using QRegularExpression

A QRegularExpression is comprised of two parts.

• regular expression search pattern
• option flags to define how the search pattern should be parsed

A regular expression can be created from a pattern string by passing the search pattern to the QRegularExpression constructor.

The search pattern can also be passed directly to setPattern().

If the search pattern is a string literal all backslashes must be escaped with another backslash.

The pattern() method returns the search pattern from a QRegularExpression instance.

Pattern Options

The way the search pattern is processed can be configured by setting one or more pattern options. For example, case sensitivity can be turned off by using the class enum QPatternOption::CaseInsensitiveOption. The options can be passed to the QRegularExpression constructor as shown in the following example.

Alternatively, setPatternOptions() can be used to configure the options for an existing QRegularExpression. The following will match any line in the string which contains only digits (but at least one).

The pattern options currently set can be retrieved by using the method patternOptions().

Refer to QPatternOption for more information about the available pattern options.

Match Type and Match Options

The last two arguments for the methods match() and globalMatch() set the match type and the match options. The match type is a value of the QRegularExpression::MatchType enum. The "traditional" matching algorithm is chosen by using the NormalMatch match type (the default). It is also possible to set partial matching of the regular expression with a string. Refer to partial matching for more details.

The match options are values from the QMatchOption enum. These options change the way a specific match of a regular expression with a string is done.

Normal Matching

In order to do a regular expression match pass a string to one of the match() methods. The result is a QRegularExpressionMatch instance which contains all the information about how the regular expression does or does not match.

If match is successful the capturing group number #0 can be used to retrieve the substring matched by the entire pattern. Refer to the section about extracting captured substrings.

It is also possible to start a match at an arbitrary offset inside the string by passing the offset as an argument of match(). In the following example "12 abc" is not matched because the match is started at offset 1.

Global Matching

If a match is found when calling one of the match() methods, a single QRegularExpressionMatch object is returned.

In contrast, for a global match a QRegularExpressionMatch is returned for every match found. All of the QRegularExpressionMatch objects are returned in a QList.

The following example will extract all of the words from a given string in one operation.

Extracting Captured Substrings

The QRegularExpressionMatch object contains information about the substrings captured by the capturing groups in the pattern string. QRegularExpressionMatch::captured() will return the string captured by a specific capturing group number.

Capturing groups in the pattern are numbered starting from 1. The capturing group #0 is used to capture the substring which matched the entire pattern.

It is also possible to retrieve the starting and the ending offsets inside the string of each captured substring by using QRegularExpressionMatch::capturedStart() and QRegularExpressionMatch::capturedEnd().

These methods have overloads which take a string as a parameter in order to extract named captured substrings.

Partial Matching

A partial match is obtained when the end of the string is reached and more characters are needed to successfully complete the match. A partial match is less efficient than a full match since some optimizations do not apply.

A partial match must be explicitly requested by specifying a match type of PartialPreferCompleteMatch or PartialPreferFirstMatch when calling QRegularExpression::match or QRegularExpression::globalMatch. If a partial match is found then calling QRegularExpressionMatch::hasMatch() on the QRegularExpressionMatch object returned by match() will return false, but QRegularExpressionMatch::hasPartialMatch() will return true.

When a partial match is found no captured substrings are returned, and the (implicit) capturing group 0 corresponding to the whole match captures the partially matched substring of the subject string.

Asking for a partial match can still lead to a complete match if one is found. In this case, QRegularExpressionMatch::hasMatch() will return true and QRegularExpressionMatch::hasPartialMatch() false. It never happens that a QRegularExpressionMatch reports both a partial and a complete match.

Partial matching is mainly useful in two scenarios: (1) validating user input in real time and (2) incremental / multi-segment matching.

Validating user input

Suppose we want input a date in a specific format like the following: "MMM dd, yyyy". We can check the input validity with a pattern as shown below:

This pattern is only intended to validate the month name.

As another example, say we want to validate input with a regular expression while the user is typing it. This can be advantageous, so we can report an error right away and let the user know they typed an invalid key. In order to do so we must distinguish between three cases:

• input cannot possibly match the regular expression
• input does match the regular expression
• input does not match the regular expression right now, but it will if more characters will be added to it

These three cases represent exactly the possible states of a QValidator.

In particular, in the last case we want the regular expression engine to report a partial match: we are successfully matching the pattern against the subject string but the matching cannot continue because the end of the subject is encountered. Notice, however, that the matching algorithm should continue and try all possibilities, and in case a complete (non-partial) match is found, then this one should be reported, and the input string accepted as fully valid.

This behavior is implemented by the PartialPreferCompleteMatch match type.

If matching the same regular expression against the subject string leads to a complete match it is reported as usual.

Another example with a different pattern, showing the behavior of preferring a complete match over a partial one.

In this case the subpattern abc\\w+X partially matches the subject string. However, the subpattern def matches the subject string completely and therefore a complete match is reported.

If multiple partial matches are found when matching (but no complete match), then the QRegularExpressionMatch object will report the first one that is found. For instance:

Incremental & Multi Segment Matching

Incremental matching is another use case of partial matching. Suppose that we want to find the occurrences of a regular expression inside a large text (that is, substrings matching the regular expression). In order to do so we would like to "feed" the large text to the regular expression engines in smaller chunks. The obvious problem is what happens if the substring that matches the regular expression spans across two or more chunks.

In this case, the regular expression engine should report a partial match, so that we can match again adding new data and (eventually) get a complete match. This implies that the regular expression engine may assume that there are other characters "beyond the end" of the subject string.

QRegularExpression implements this behavior when using the PartialPreferFirstMatch match type. This match type reports a partial match as soon as it is found, and other match alternatives are not tried (even if they could lead to a complete match). For instance:

This happens because when matching the first branch of the alternation operator a partial match is found, and therefore matching stops, without trying the second branch.

This shows what could seem a counterintuitive behavior of quantifiers: since ? is greedy, then the engine tries first to continue the match after having matched "abc" but then the matching reaches the end of the subject string, and therefore a partial match is reported. This is even more surprising in the following example.

It is easy to understand this behavior if we remember that the engine expects the subject string to be only a substring of the whole text we're looking for a match into (that is, how we said before, that the engine assumes that there are other characters beyond the end of the subject string).

Since the * quantifier is greedy, then reporting a complete match could be an error, because after the current subject "abc" there may be other occurrences of "abc". For instance, the complete text could have been "abcabcX", and therefore the right match to report (in the complete text) would have been "abcabc" by matching only against the leading "abc" we instead get a partial match.

Error Handling

It is possible for a QRegularExpression object to be invalid because of syntax errors in the pattern string. The isValid() function will return true if the regular expression is valid, or false otherwise:

You can get more information about the specific error by calling errorString().

If a match is attempted with an invalid QRegularExpression then the returned QRegularExpressionMatch object will be invalid as well. QRegularExpressionMatch::isValid() will return false. The same applies for calling globalMatch().

Exact Matching

When the regular expression pattern matches the entire search string this is referred to as an exact match. If you need an exact math use the QPatternOption::ExactMatchOption when constructing your regular expression.

Migrating to QRegularExpression

The following examples demonstrate how to update application code which used QRegExp and now uses QRegularExpression.

capturedTexts()

Pass the QPatternOption::ExactMatchOption when creating the regular expression.

QString buffer = "I have a dream";

// **

QRegExp regExp("(d)"); // QRegExp syntax

if (regExp.indexIn(buffer) == 0) {

QStringList list = regExp.capturedTexts();

}

// **

QRegularExpression regExp("(d)"); // QRegularExpression syntax

QRegularExpressionMatch match = rexExp.match(buffer);

if (match.capturedStart(0) == buffer.begin()) {

QStringList list = match.capturedTexts();

}

exactMatch()

Pass the QPatternOption::ExactMatchOption when creating the regular expression.

QString text = "www.copperspice.com";

QRegularExpression regExp("www.*com", QPatternOption::ExactMatchOption);

if (regExp.match(text).hasMatch()) {

// do something with the exact match

}

indexIn()

Replace with indexOfFast() to return an iterator indicating the location of the match.

// **

QRegExp regExpA("[0-9]+"); // QRegExp syntax

int pos = regExpA.indexIn(text);

if (pos == -1) {

// not found

} else {

text = text.mid(pos);

}

// **

QRegularExpression regExpB("[0-9]+"); // QRegularExpression syntax

auto iter = text.indexOfFast(regExpB);

if (iter == str.end()) {

// not found

} else {

text = QString(iter, text.end());

}

indexIn()

Another approach is to replace indexIn() with a QRegularExpressionMatch. Calling hasMatch() will return true if a match was found. If so, then it is safe to retrieve either a position or an iterator where the match was found.

// **

QRegExp regExpA("[0-9]+"); // QRegExp syntax

int pos = regExpA.indexIn(text);

if (pos == -1) {

// not found

} else {

text = text.mid(pos);

}

// **

QRegularExpression regExpB("[0-9]+"); // QRegularExpression syntax

QRegularExpressionMatch match = rexExpB.match(text);

if (match.hasMatch() {

// if you need the position ( not preferred )

int index = match.capturedStart() - text.begin();

text = text.mid(index);

// returns an iterator ( preferred )

auto iter = match.capturedStart();

text = QStringView(iter, text.constEnd());

}

matchedLength()

Replace with capturedLength()

QString text = "CopperSpice is a set of modern C++ libraries";

QRegularExpression regExp(".*?\\b");

QRegularExpressionMatch match = regExp.match(text);

if (match.hasMatch()) {

QString result = text.left( match.capturedLength(0) );

}

setMinimal()

Add a question mark after every quantifier like a * or a +

Multiple Line Matching

This example shows how to search a multiple line text string looking for comments. Each comment begins with a '#' sign and continues until the end of the line, which is denoted by '\n'. A use case for this regular expression might be to remove comments from a text file.

// **

QRegExp regExp("#.*\n"); // QRegExp syntax

// **

QRegularExpression regExp("#.*?\r?\n", QPatternOption::MultilineOption); // QRegularExpression syntax