os::RegExp Class Reference
[Various utillity classes.]

Regular expression class. More...

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 Member Functions
	RegExp ()
	Default constructor.
	RegExp (const String &cExpression, bool bNoCase=false, bool bExtended=false)
	Constructor.
	~RegExp ()
	Destructor.
status_t	Compile (const String &cExpression, bool bNoCase=false, bool bExtended=false)
	Compile an regular expression.
int	GetSubExprCount () const
	Get the number of sub-expressions found in the previously compiled expression.
bool	IsValid () const
	Check if a valid expression has been compiled.
bool	Search (const String &cString)
	Search for the previously compiled regular expression.
bool	Search (const String &cString, int nStart, int nLen=-1)
	Search for the previously compiled regular expression.
bool	Match (const String &cString)
	Compare the regular expression to a string.
bool	Match (const String &cString, int nStart, int nLen=-1)
	Compare the regular expression to a string.
String	Expand (const String &cPattern) const
	Expand a string using substrings from the previous search.
int	GetStart () const
	Get the position of the first character that matched in the previous search.
int	GetEnd () const
	Get the position of the first character after the matched region in the previous search.
const String &	GetSubString (uint nIndex) const
	Get the result of a subexpression from the previous search.
bool	GetSubString (uint nIndex, int *pnStart, int *pnEnd) const
	Get the result of a subexpression from the previous search.
const std::vector< String > &	GetSubStrList () const
	Get a list of substrings from the previous search.
Classes
class	exception
class	Private

---

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 ([email protected])

---

Member Enumeration Documentation

anonymous enum

Enumerator:

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 ([email protected])

RegExp::RegExp	(	const 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 ([email protected])

RegExp::~RegExp

(

)

Description:

Destructor.

Note:

Author:

Kurt Skauen ([email protected])

---

Member Function Documentation

status_t RegExp::Compile	(	const 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 ([email protected])

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 ([email protected])

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 ([email protected])

bool RegExp::Search

(

const 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 String&,int,int), Match()

Author:

Kurt Skauen ([email protected])

bool RegExp::Search	(	const String &	cString,
		int	nStart,
		int	nLen = -1
	)

Description:

Same as Search(const 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 String&)

Author:

Kurt Skauen ([email protected])

bool RegExp::Match

(

const String &

cString

)

Description:

Same as Search(const 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 ([email protected])

bool RegExp::Match	(	const String &	cString,
		int	nStart,
		int	nLen = -1
	)

Description:

Same as Search(const 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 String&,int,int)

Author:

Kurt Skauen ([email protected])

String RegExp::Expand

(

const 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 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 ([email protected])

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 ([email protected])

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 ([email protected])

const 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 ([email protected])

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 ([email protected])

const std::vector< 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 ([email protected])

---