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 Code Description

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

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...