Main Page   Modules   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

os::RegExp Class Reference

Regular expression class. More...

#include <regexp.h>

List of all members.

Public Types

enum  {
  ERR_BADREPEAT = -2,
  ERR_BADBACKREF = -3,
  ERR_BADBRACE = -4,
  ERR_BADBRACK = -5,
  ERR_BADPARENTHESIS = -6,
  ERR_BADRANGE = -7,
  ERR_BADSUBREG = -8,
  ERR_BADCHARCLASS = -9,
  ERR_BADESCAPE = -10,
  ERR_BADPATTERN = -11,
  ERR_TOLARGE = -12,
  ERR_NOMEM = -13,
  ERR_GENERIC = -14
}

Public Methods

 RegExp ()
 Default constructor. More...

 RegExp (const std::string &cExpression, bool bNoCase=false, bool bExtended=false)
 Constructor. More...

 ~RegExp ()
 Destructor. More...

status_t Compile (const std::string &cExpression, bool bNoCase=false, bool bExtended=false)
 Compile an regular expression. More...

int GetSubExprCount () const
 Get the number of sub-expressions found in the previously compiled expression. More...

bool IsValid () const
 Check if a valid expression has been compiled. More...

bool Search (const std::string &cString)
 Search for the previously compiled regular expression. More...

bool Search (const std::string &cString, int nStart, int nLen=-1)
 Search for the previously compiled regular expression. More...

bool Match (const std::string &cString)
 Compare the regular expression to a string. More...

bool Match (const std::string &cString, int nStart, int nLen=-1)
 Compare the regular expression to a string. More...

std::string Expand (const std::string &cPattern) const
 Expand a string using substrings from the previous search. More...

int GetStart () const
 Get the position of the first character that matched in the previous search. More...

int GetEnd () const
 Get the position of the first character after the matched region in the previous search. More...

const std::string & GetSubString (uint nIndex) const
 Get the result of a subexpression from the previous search. More...

bool GetSubString (uint nIndex, int *pnStart, int *pnEnd) const
 Get the result of a subexpression from the previous search. More...

const std::vector< std::string > & GetSubStrList () const
 Get a list of substrings from the previous search. More...


Detailed Description

Description:
The os::RegExp class allow you to do regular expression searches on strings and to extract sub-strings from the searched string. The resulting sub-strings from a search can also be used to expand strings containing sub-expression references.
Since:
0.3.7
See also:
os::String
Author:
Kurt Skauen (kurt@atheos.cx)


Member Enumeration Documentation

anonymous enum
 

Enumeration values:
ERR_BADREPEAT  
ERR_BADBACKREF  
ERR_BADBRACE  
ERR_BADBRACK  
ERR_BADPARENTHESIS  
ERR_BADRANGE  
ERR_BADSUBREG  
ERR_BADCHARCLASS  
ERR_BADESCAPE  
ERR_BADPATTERN  
ERR_TOLARGE  
ERR_NOMEM  
ERR_GENERIC  


Constructor & Destructor Documentation

RegExp::RegExp
 

Author:
Kurt Skauen (kurt@atheos.cx)

RegExp::RegExp const std::string & cExpression,
bool bNoCase = false,
bool bExtended = false
 

Description:
Construct the os::RegExp object and compile the given pattern. See Compile() for a more detailed description of the pattern compilation mechanism.

If the regular expression is invalid an os::RegExp::exception exception will be thrown. The "error" member of the exception will be set to one of the os::RegExp::ERR_* error codes.

Parameters:
cExpression   The regular expression to compile.
bNoCase   Set to true if case should be ignored when doing subsequent searches.
bExtended   If true the POSIX Extended Regular Expression Syntax will be used. If false the POSIX Basic Regular Expression Syntax is used.
See also:
Compile()
Author:
Kurt Skauen (kurt@atheos.cx)

RegExp::~RegExp
 

Description:
Destructor.
Note:
Author:
Kurt Skauen (kurt@atheos.cx)


Member Function Documentation

status_t RegExp::Compile const std::string & cExpression,
bool bNoCase = false,
bool bExtended = false
 

Description:
Compile a regular expression into a form that is suitable for subsequent searches and matches.

The regular expression can be interpreted in two distinct ways If the bExtended argument is false (the default) the POSIX Basic Regular Expression Syntax is assumed, if it is true the the POSIX Extended Regular Expression Syntax is assumed.

If the bNoCase argument is false subsequent searches will be case insensitive.

If there is an syntactical error in the expression one of the ERR_* error codes will be returned:

Error CodeDescription
ERR_BADREPEAT An invalid repetition operator such as '*' or '?' appeared in a bad position (with no preceding subexpression to act on).
ERR_BADBACKREF There was an invalid backreference (\{...\}) construct in the expression. A valid backreference contain either a single numbed or two numbers in increasing order separated by a comma.
ERR_BADBRACE The expression had an unbalanced \{ \} construct.
ERR_BADBRACK The expression had an unbalanced \[ \] construct.
ERR_BADPARENTHESIS The expression had an unbalanced \( \) construct.
ERR_BADRANGE One of the endpoints in a range expression was invalid./td>
ERR_BADSUBREG There was an invalid number in a \digit construct.
ERR_BADCHARCLASS The expression referred to an invalid character class name.
ERR_BADESCAPE Invalid escape sequence (the expression ended with an '\').
ERR_BADPATTERN There was an syntax error in the regular expression.
ERR_TOLARGE The expression was to large. Compiled regular expression buffer requires a pattern buffer larger than 64Kb.
ERR_NOMEM Ran out of memory while compiling the expression.
ERR_GENERIC Unspecified error.

Parameters:
cExpression   The regular expression to compile.
bNoCase   Set to true if case should be ignored when doing subsequent searches.
bExtended   If true the POSIX Extended Regular Expression Syntax will be used. If false the POSIX Basic Regular Expression Syntax is used.
Returns:
On success 0 is returned. On failure one of the ERR_* values described above is returned. All the error codes have negative values.
See also:
Search(), Match()
Author:
Kurt Skauen (kurt@atheos.cx)

std::string RegExp::Expand const std::string & cPattern const
 

Description:
Expand a string using substrings from the previous search. Expand() will substitute "%n" and "%<nn>" constructs from cPattern with the string yielded by the referenced sub-expression and return the result in a new std::string object.

A substitution is initiated with a '%' followed by a single digit or a single/multi-digit number within a <> construct. Sub expressions are numbered starting with 1. To insert sub-expression number 3 into a string you can use "%3" or "%<3> in the pattern. To insert sub-sexpression number 12 you must use "%<12>". Two consecutive '%' characters will insert one literal '%' into the output.

Note:
In the current implementation a '%' not followed by a digit or a <nn> construct and substitutions that reference out-of-range sub expressions will be inserted unmodified into the output. You should avoid such constructs though and always use "%%" to insert a literal '%' into the output and keep the sub-expressions within range.
Parameters:
cPattern   The pattern that should be expanded.
Returns:
A copy of cPattern with all "%n" and "%<nn>" constructs expanded.
See also:
Compile(), Search()
Author:
Kurt Skauen (kurt@atheos.cx)

int RegExp::GetEnd const
 

Description:
Get the position of the first character after the matched region in the previous search. The rules for range-searces and failed/invalid searched that was described for GetStart() also apply for GetEnd().
Returns:
The index of the first character after the match in the searched string that matched the regular expression during the previous search or -1 if the previous search failed.
See also:
GetStart(), GetSubString(), Search(), Match()
Author:
Kurt Skauen (kurt@atheos.cx)

int RegExp::GetStart const
 

Description:
Get the position of the first character that matched in the previous search. This is the 0 based index of the first character from the searched string that matched the current regular expression. If the version of Search() that allow a range to be specified the start position will still be counted from the start of the string and not the start of the specified range.

If the last search was done with Match() the value will always be 0 or the start position of the sub-string to match if a range was specified.

If no previous search has been performed or if the previous search failed this function will return -1.

Returns:
The index of the first character in the searched string that matched the regular expression during the previous search or -1 if the previous search failed.
Error codes:
See also:
GetEnd(), GetSubString(), Search(), Match()
Author:
Kurt Skauen (kurt@atheos.cx)

int RegExp::GetSubExprCount const
 

Description:
Get the number of sub-expressions found in the previously compiled expression. If no expression have yet been compiled -1 is returned.
Returns:
The number of sub-extressions found in the previously compiled expression or -1 if no expression have yet been compiled.
See also:
Compile()
Author:
Kurt Skauen (kurt@atheos.cx)

const std::vector< std::string > & RegExp::GetSubStrList const
 

Description:
Get a list of substrings from the previous search. If the previous search failed or if no search have been performed yet an empty list will be returned.
Returns:
A STL vector with STL strings containing the sub-strings from the previous search.
See also:
GetSubString()
Author:
Kurt Skauen (kurt@atheos.cx)

bool RegExp::GetSubString uint nIndex,
int * pnStart,
int * pnEnd
const
 

Description:
This is the same as GetSubString(uint) except that it returns the range in the searched string instead of the actual sub-string itself.

If the specified sub-expression was not used or if nIndex is out of range pnStart and pnEnd will be set to -1.

Note:
If you specified a range for the previous search the positions will still be within the full searched string.
Parameters:
nIndex   A zero based index into the sub-expression list.
pnStart   Pointer to an integer that will receive the index of the first character that matched the specified sub-expression. If you are not interrested in the start-position NULL can be passed.
pnEnd   Pointer to an integer that will receive the index of the first character after the region that matched the specified sub-expression. If you are not interrested in the end-position NULL can be passed.
Returns:
Returns true if nIndex is within range and false if not.
See also:
GetSubString(uint), Search(), Match(), GetStart(), GetEnd()
Author:
Kurt Skauen (kurt@atheos.cx)

const std::string & RegExp::GetSubString uint nIndex const
 

Description:
Return the sub-string that matched sub-expression number nIndex. If the sub-expression was not used or if the index was out of range an empty string is returned.
Parameters:
nIndex   A zero based index into the sub-expression list.
Returns:
The result of the given sub-expression.
See also:
GetSubString(uint,int*,int*), Search(), Match(), GetStart(), GetEnd()
Author:
Kurt Skauen (kurt@atheos.cx)

bool RegExp::IsValid void const
 

Description:
Returns true if the os::RegExp object represent a valid regular expression (last call to Compile() was successfull). Returns false if the default constuctor was used and no calls to Compile() have yet been made or if the last call to Compile() failed.
See also:
Compile(), Search(), Match()
Author:
Kurt Skauen (kurt@atheos.cx)

bool RegExp::Match const std::string & cString,
int nStart,
int nLen = -1
 

Description:
Same as Search(const std::string&,int,int) except that the expression must match the entire sub-string to be successfull.
Parameters:
cString   The string that should be compared to the regular expression.
nStart   Where in cString to start the search.
nLen   How many characters from cString to search.
Returns:
Returns true if the pattern matched or false if no match was found or if the os::RegExp object don't contain a valid regular expression.
See also:
Match(const string&), Search(const std::string&,int,int)
Author:
Kurt Skauen (kurt@atheos.cx)

bool RegExp::Match const std::string & cString
 

Description:
Same as Search(const std::string&) except that the expression must match the entire string to be successfull.
Parameters:
cString   The string that should be compared to the regular expression.
Returns:
Returns true if the pattern matched or false if no match was found or if the os::RegExp object don't contain a valid regular expression.
Error codes:
See also:
Author:
Kurt Skauen (kurt@atheos.cx)

bool RegExp::Search const std::string & cString,
int nStart,
int nLen = -1
 

Description:
Same as Search(const std::string&) except that you can specify a range within the string that should be searched.
Parameters:
cString   The string to search.
nStart   Where in cString to start the search.
nLen   How many characters from cString to search.
Returns:
Returns true if the pattern was found or false if no match was found or if the os::RegExp object don't contain a valid regular expression.
See also:
Search(const std::string&)
Author:
Kurt Skauen (kurt@atheos.cx)

bool RegExp::Search const std::string & cString
 

Description:
Search() will search for the last compiled regular expression in cString. If the pattern was found true is returned and the start and end position of the expression within cString is recorded. If the regular expression contain subexpression the sub-strings will be extracted and made availabel through GetSubString() and GetSubStrList().
Parameters:
cString   The string to search.
Returns:
Returns true if the pattern was found or false if no match was found or if the os::RegExp object don't contain a valid regular expression.
See also:
Search(const std::string&,int,int), Match()
Author:
Kurt Skauen (kurt@atheos.cx)


Generated at Mon Oct 8 23:38:00 2001 for AtheOS higlevel API by doxygen1.2.9.1 written by Dimitri van Heesch, © 1997-2001