Rogue Wave banner
Previous fileTop of documentContentsIndexNext file

RWCRegexp

Data Type and Member Function Indexes
(exclusive of constructors and destructors)

Synopsis

#include <rw/regexp.h>
RWCRegexp re(".*\\.doc");// Matches filename with suffix ".doc"

Description

Class RWCRegexp represents a regular expression. The constructor "compiles" the expression into a form that can be used more efficiently. The results can then be used for string searches using class RWCString.

The regular expression (RE) is constucted as follows:

The following rules determine one-character REs that match a single character:

1.1 Any character that is not a special character (to be defined) matches itself.
1.2 A backslash (\) followed by any special character matches the literal character itself. I.e., this "escapes" the special character.
1.3 The "special characters" are:

+ * ? . [ ] ^ $

1.4 The period (.) matches any character except the newline. E.g., ".umpty" matches either "Humpty" or "Dumpty."
1.5 A set of characters enclosed in brackets ([]) is a one-character RE that matches any of the characters in that set. E.g., "[akm]" matches either an "a", "k", or "m". A range of characters can be indicated with a dash. E.g., "[a-z]" matches any lower-case letter. However, if the first character of the set is the caret (^), then the RE matches any character except those in the set. It does not match the empty string. Example: [^akm] matches any character except "a", "k", or "m". The caret loses its special meaning if it is not the first character of the set.

The following rules can be used to build a multicharacter RE.

2.1 A one-character RE followed by an asterisk (*) matches zero or more occurrences of the RE. Hence, [a-z]* matches zero or more lower-case characters.
2.2 A one-character RE followed by a plus (+) matches one or more occurrences of the RE. Hence, [a-z]+ matches one or more lower-case characters.
2.3 A question mark (?) is an optional element. The preceeding RE can occur zero or once in the string -- no more. E.g. xy?z matches either xyz or xz.
2.4 The concatenation of REs is a RE that matches the corresponding concatenation of strings. E.g., [A-Z][a-z]* matches any capitalized word.

Finally, the entire regular expression can be anchored to match only the beginning or end of a line:

3.1 If the caret (^) is at the beginning of the RE, then the matched string must be at the beginning of a line.
3.2 If the dollar sign ($) is at the end of the RE, then the matched string must be at the end of the line.

The following escape codes can be used to match control characters:

\b backspace
\e ESC (escape)
\f formfeed
\n newline
\r carriage return
\t tab
\xddd the literal hex number 0xdd
\ddd the literal octal number ddd
\^C Control code. E.g. \^D is "control-D"

The most frequent problem with use of this class is in being able to specify a backslash character to be parsed. If you are attempting to parse a regular expression that contains backslashes, you must be aware that the C++ compiler and the regular expression constructor will both assume that any backslashes they see are intended to escape the following character. Thus, to specify a regular expression that exactly matches "a\a", you would have to create the regular expression using four backslashes as follows: the regular expression needs to see "a\\a", and for that to happen, the compiler would have to see "a\\\\a".

     RWCRegexp reg("a\\\\a");
                      ^|^|
                       1 2

The backslashes marked with a ^ are an escape for the compiler, and the ones marked with | will thus be seen by the regular expression parser. At that point, the backslash marked 1 is an escape, and the one marked 2 will actually be put into the regular expression.

Similarly, if you really need to escape a character, such as a ".", you will have to pass two backslashes to the compiler:

    RWCRegexp regDot("\\.")
                      ^|

Once again, the backslash marked ^ is an escape for the compiler, and the one marked with | will be seen by the regular expression constructor as an escape for the following ".".

Persistence

None

Example

#include <rw/regexp.h>
#include <rw/cstring.h>
#include <rw/rstream.h>

main(){
  RWCString aString("Hark! Hark! the lark");

  // A regular expression matching any lower-case word
  // starting with "l":
  RWCRegexp reg("l[a-z]*");

  cout << aString(reg) << endl;  // Prints "lark"
}

Public Constructors

RWCRegexp(const char* pat);
RWCRegexp(const RWCRegexp& r);

Public Destructor

~RWCRegexp();

Assignment Operators

RWCRegexp&
operator=(const RWCRegexp&);
RWCRegexp&
operator=(const char* pat);

Public Member Functions

size_t
index(const RWCString& str,size_t* len, size_t start=0) const;
statVal
status();
statVal
Meaning
RWCRegexp::OK
No errors
RWCRegexp::ILLEGAL
Pattern was illegal
RWCRegexp::TOOLONG
Pattern exceeded maximum length [3]


Previous fileTop of documentContentsIndexNext file
©Copyright 1999, Rogue Wave Software, Inc.
Send mail to report errors or comment on the documentation.