Qt Toolkit - QRegExp Class

| Classes - Annotated - Tree - Functions - Home - Structure

# QRegExp Class Reference

The QRegExp class provides pattern matching using regular expressions or wildcards. More...

`#include <qregexp.h>`

List of all member functions.

## Public Members

- QRegExp ()
- QRegExp ( const QString &, bool caseSensitive=TRUE, bool wildcard=FALSE )
- QRegExp ( const QRegExp & )
- ~QRegExp ()
- QRegExp& operator= ( const QRegExp & )
- QRegExp& operator= ( const QString & pattern ) (obsolete)
- bool operator== ( const QRegExp & ) const
- bool operator!= ( const QRegExp & r ) const
- bool isEmpty () const
- bool isValid () const
- bool caseSensitive () const
- void setCaseSensitive ( bool )
- bool wildcard () const
- void setWildcard ( bool )
- QString pattern () const
- void setPattern ( const QString & pattern )
- int match ( const QString & str, int index=0, int * len=0, bool indexIsStart = TRUE ) const
- int find ( const QString & str, int index )

## Protected Members

- void compile () (internal)
- const QChar* matchstr ( uint *, const QChar *, uint, const QChar * ) const (internal)

## Detailed Description

The QRegExp class provides pattern matching using regular expressions or wildcards.

QRegExp knows these regexp primitives:

- c matches the character 'c'
- . matches any character
- ^ matches start of input
- $ matches end of input
- [] matches a defined set of characters - see below.
- a* matches a sequence of zero or more a's
- a+ matches a sequence of one or more a's
- a? matches an optional a
- \c escape code for matching special characters such as \, [, *, +, . etc.
- \t matches the TAB character (9)
- \n matches newline (10)
- \r matches return (13)
- \s matches a white space (defined as any character for which QChar::isSpace() returns TRUE. This includes at least ASCII characters 9 (TAB), 10 (LF), 11 (VT), 12(FF), 13 (CR) and 32 (Space)).
- \d matches a digit (defined as any character for which QChar::isDigit() returns TRUE. This includes at least ASCII characters '0'-'9').
- \x1f6b matches the character with unicode point U1f6b (hexadecimal 1f6b). \x0012 will match the ASCII/Latin1 character 0x12 (18 decimal, 12 hexadecimal).
- \022 matches the ASCII/Latin1 character 022 (18 decimal, 22 octal).

In wildcard mode, it only knows four primitives:

- c matches the character 'c'
- ? matches any character
- * matches any sequence of characters
- [] matches a defined set of characters - see below.

QRegExp supports Unicode both in the pattern strings and in the strings to be matched.

When writing regular expressions in C++ code, remember that C++ processes \ characters. So in order to match e.g. a "." character, you must write "\\." in C++ source, not "\.".

A character set matches a defined set of characters. For example, [BSD] matches any of 'B', 'D' and 'S'. Within a character set, the special characters '.', '*', '?', '^', '$', '+' and '[' lose their special meanings. The following special characters apply:

- ^ When placed first in the list, changes the character set to match any character not in the list. To include the character '^' itself in the set, escape it or place it anywhere but first.
- - Defines a range of characters. To include the character '-' itself in the set, escape it or place it last.
- ] Ends the character set definition. To include the character ']' itself in the set, escape it or place it first (but after the negation operator '^', if present)

Thus, [a-zA-Z0-9.] matches upper and lower case ASCII letters, digits and dot; and [^\s] matches everything except white space.

\note In Qt 3.0, the language of regular expressions will contain five more special characters, namely '(', ')', '{', '|' and '}'. To ease porting, it's a good idea to escape these characters with a backslash in all the regular expressions you'll write from now on.

Bugs and limitations:

- Case insensitive matching is not supported for non-ASCII/Latin1 (non-8bit) characters. Any character with a non-zero QChar.row() is matched case sensitively even if the QRegExp is in case insensitive mode.

Examples: qmag/qmag.cpp

## Member Function Documentation

### QRegExp::QRegExp ()

Constructs an empty regular expression.

### QRegExp::QRegExp ( const QString & pattern, bool caseSensitive=TRUE, bool wildcard=FALSE )

Constructs a regular expression.

Arguments:

- pattern is the regular expression pattern string.
- caseSensitive specifies whether or not to use case sensitive matching.
- wildcard specifies whether the pattern string should be used for wildcard matching (also called globbing expression), normally used for matching file names.

See also setWildcard().

### QRegExp::QRegExp ( const QRegExp & r )

Constructs a regular expression which is a copy of r.

See also operator=(const and QRegExp&).

### QRegExp::~QRegExp ()

Destructs the regular expression and cleans up its internal data.

### bool QRegExp::caseSensitive () const

Returns TRUE if case sensitivity is enabled, otherwise FALSE. The default is TRUE.

See also setCaseSensitive().

### int QRegExp::find ( const QString & str, int index )

Attempts to match in str, starting from position index. Returns the position of the match, or -1 if there was no match.

See also match().

### bool QRegExp::isEmpty () const

Returns TRUE if the regexp is empty.

### bool QRegExp::isValid () const

Returns TRUE if the regexp is valid, or FALSE if it is invalid.

The pattern "[a-z" is an example of an invalid pattern, since it lacks a closing bracket.

### int QRegExp::match ( const QString & str, int index=0, int * len=0, bool indexIsStart = TRUE ) const

Attempts to match in str, starting from position index. Returns the position of the match, or -1 if there was no match.

If len is not a null pointer, the length of the match is stored in *len.

If indexIsStart is TRUE (the default), the position index in the string will match the start-of-input primitive (^) in the regexp, if present. Otherwise, position 0 in str will match.

Example:

        QRegExp r("[0-9]*\\.[0-9]+");               // matches floating point
        int len;
        r.match("pi = 3.1416", 0, &len);            // returns 5, len == 6

\note In Qt 3.0, this function will be replaced by find().

Examples: qmag/qmag.cpp

### bool QRegExp::operator!= ( const QRegExp & r ) const

Returns TRUE if this regexp is not equal to r.

See also operator==().

### QRegExp & QRegExp::operator= ( const QString & pattern )

This function is obsolete. It is provided to keep old source working, and will probably be removed in a future version of Qt. We strongly advise against using it in new code.

Consider using setPattern() instead of this method.

Sets the pattern string to pattern and returns a reference to this regexp. The case sensitivity or wildcard options do not change.

### QRegExp & QRegExp::operator= ( const QRegExp & r )

Copies the regexp r and returns a reference to this regexp. The case sensitivity and wildcard options are copied, as well.

### bool QRegExp::operator== ( const QRegExp & r ) const

Returns TRUE if this regexp is equal to r.

Two regexp objects are equal if they have equal pattern strings, case sensitivity options and wildcard options.

### QString QRegExp::pattern () const

Returns the pattern string of the regexp.

### void QRegExp::setCaseSensitive ( bool enable )

Enables or disables case sensitive matching.

In case sensitive mode, "a.e" matches "axe" but not "Axe".

See also: caseSensitive().

### void QRegExp::setPattern ( const QString & pattern )

Sets the pattern string to pattern and returns a reference to this regexp. The case sensitivity or wildcard options do not change.

### void QRegExp::setWildcard ( bool wildcard )

Sets the wildcard option for the regular expression. The default is FALSE.

Setting wildcard to TRUE makes it convenient to match filenames instead of plain text.

For example, "qr*.cpp" matches the string "qregexp.cpp" in wildcard mode, but not "qicpp" (which would be matched in normal mode).

See also wildcard().

### bool QRegExp::wildcard () const

Returns TRUE if wildcard mode is on, otherwise FALSE.

See also setWildcard().

### void QRegExp::compile () `[protected]`

For internal use only.

### const QChar * QRegExp::matchstr ( uint * rxd, const QChar * str, uint strlength, const QChar * bol ) const `[protected]`

For internal use only.

Search the documentation, FAQ, qt-interest archive and more (uses www.trolltech.com):

This file is part of the Qt toolkit, copyright © 1995-2001 Trolltech, all rights reserved.