PTLib  Version 2.10.10
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
PRegularExpression Class Reference

A class representing a regular expression that may be used for locating patterns in strings. More...

#include <pstring.h>

Inheritance diagram for PRegularExpression:
PObject

Public Member Functions

Overrides from class PObject
virtual void PrintOn (ostream &strm) const
 Output the regular expression to the specified stream. More...
 
Compile & Execute functions
PBoolean Compile (const PString &pattern, int flags=IgnoreCase)
 Compiler pattern. More...
 
PBoolean Compile (const char *cpattern, int flags=IgnoreCase)
 Compiler pattern. More...
 
PBoolean Execute (const PString &str, PINDEX &start, int flags=0) const
 Execute regular expression. More...
 
PBoolean Execute (const PString &str, PINDEX &start, PINDEX &len, int flags=0) const
 Execute regular expression. More...
 
PBoolean Execute (const char *cstr, PINDEX &start, int flags=0) const
 Execute regular expression. More...
 
PBoolean Execute (const char *cstr, PINDEX &start, PINDEX &len, int flags=0) const
 Execute regular expression. More...
 
PBoolean Execute (const PString &str, PIntArray &starts, int flags=0) const
 Execute regular expression. More...
 
PBoolean Execute (const PString &str, PIntArray &starts, PIntArray &ends, int flags=0) const
 Execute regular expression. More...
 
PBoolean Execute (const char *cstr, PIntArray &starts, int flags=0) const
 Execute regular expression. More...
 
PBoolean Execute (const char *cstr, PIntArray &starts, PIntArray &ends, int flags=0) const
 Execute regular expression. More...
 
PBoolean Execute (const char *cstr, PStringArray &substring, int flags=0) const
 Execute regular expression. More...
 
- Public Member Functions inherited from PObject
virtual ~PObject ()
 
virtual PObjectClone () const
 Create a copy of the class on the heap. More...
 
virtual PINDEX HashFunction () const
 This function yields a hash value required by the PDictionary class. More...
 
virtual const char * GetClass (unsigned ancestor=0) const
 Get the current dynamic type of the object instance. More...
 
PBoolean IsClass (const char *cls) const
 
virtual PBoolean InternalIsDescendant (const char *clsName) const
 Determine if the dynamic type of the current instance is a descendent of the specified class. More...
 
virtual Comparison Compare (const PObject &obj) const
 Compare the two objects and return their relative rank. More...
 
virtual Comparison CompareObjectMemoryDirect (const PObject &obj) const
 Determine the byte wise comparison of two objects. More...
 
bool operator== (const PObject &obj) const
 Compare the two objects. More...
 
bool operator!= (const PObject &obj) const
 Compare the two objects. More...
 
bool operator< (const PObject &obj) const
 Compare the two objects. More...
 
bool operator> (const PObject &obj) const
 Compare the two objects. More...
 
bool operator<= (const PObject &obj) const
 Compare the two objects. More...
 
bool operator>= (const PObject &obj) const
 Compare the two objects. More...
 
virtual void ReadFrom (istream &strm)
 Input the contents of the object from the stream. More...
 

Static Public Member Functions

Miscellaneous functions
static PString EscapeString (const PString &str)
 Escape all characters in the str parameter that have a special meaning within a regular expression. More...
 
- Static Public Member Functions inherited from PObject
static const char * Class ()
 Get the name of the class as a C string. More...
 
static Comparison InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
 Internal function caled from CompareObjectMemoryDirect() More...
 

Protected Attributes

PString patternSaved
 
int flagsSaved
 
void * expression
 
ErrorCodes lastError
 

Constructors & destructors

enum  { Extended = 1, IgnoreCase = 2, AnchorNewLine = 4 }
 Flags for compiler options. More...
 
enum  { NotBeginningOfLine = 1, NotEndofLine = 2 }
 Flags for execution options. More...
 
 PRegularExpression ()
 Create a new, empty, regular expression. More...
 
 PRegularExpression (const PString &pattern, int flags=IgnoreCase)
 Create and compile a new regular expression pattern. More...
 
 PRegularExpression (const char *cpattern, int flags=IgnoreCase)
 Create and compile a new regular expression pattern. More...
 
 PRegularExpression (const PRegularExpression &)
 Copy a regular expression. More...
 
PRegularExpressionoperator= (const PRegularExpression &)
 Assign a regular expression. More...
 
 ~PRegularExpression ()
 Release storage for the compiled regular expression. More...
 

Status functions

enum  ErrorCodes {
  NoError = 0, NoMatch, BadPattern, CollateError,
  BadClassType, BadEscape, BadSubReg, UnmatchedBracket,
  UnmatchedParen, UnmatchedBrace, BadBR, RangeError,
  OutOfMemory, BadRepitition, PrematureEnd, TooBig,
  UnmatchedRParen, NotCompiled
}
 Error codes. More...
 
ErrorCodes GetErrorCode () const
 Get the error code for the last Compile() or Execute() operation. More...
 
PString GetErrorText () const
 Get the text description for the error of the last Compile() or Execute() operation. More...
 
const PStringGetPattern () const
 Return the string which represents the pattern matched by the regular expression. More...
 

Additional Inherited Members

- Public Types inherited from PObject
enum  Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
 Result of the comparison operation performed by the Compare() function. More...
 
- Protected Member Functions inherited from PObject
 PObject ()
 Constructor for PObject, made protected so cannot ever create one on its own. More...
 
- Friends inherited from PObject

Detailed Description

A class representing a regular expression that may be used for locating patterns in strings.

The regular expression string is "compiled" into a form that is more efficient during the matching. This compiled form exists for the lifetime of the PRegularExpression instance.

Member Enumeration Documentation

anonymous enum

Flags for compiler options.

Enumerator
Extended 

Use extended regular expressions.

IgnoreCase 

Ignore case in search.

AnchorNewLine 

If this bit is set, then anchors do not match at newline characters in the string.

If not set, then anchors do match at newlines.

anonymous enum

Flags for execution options.

Enumerator
NotBeginningOfLine 

If this bit is set, then the beginning-of-line operator doesn't match the beginning of the string (presumably because it's not the beginning of a line).

If not set, then the beginning-of-line operator does match the beginning of the string.

NotEndofLine 

Like NotBeginningOfLine, except for the end-of-line.

Error codes.

Enumerator
NoError 

Success.

NoMatch 

Didn't find a match (for regexec).

BadPattern 

Invalid pattern.

CollateError 

Not implemented.

BadClassType 

Invalid character class name.

BadEscape 

Trailing backslash.

BadSubReg 

Invalid back reference.

UnmatchedBracket 

Unmatched left bracket.

UnmatchedParen 

Parenthesis imbalance.

UnmatchedBrace 

Unmatched \.

BadBR 

Invalid contents of \.

RangeError 

Invalid range end.

OutOfMemory 

Ran out of memory.

BadRepitition 

No preceding re for repetition op.

PrematureEnd 

Premature end.

TooBig 

Compiled pattern bigger than 2^16 bytes.

UnmatchedRParen 

Unmatched ) or \); not returned from regcomp.

NotCompiled 

Miscellaneous error.

Constructor & Destructor Documentation

PRegularExpression::PRegularExpression ( )

Create a new, empty, regular expression.

PRegularExpression::PRegularExpression ( const PString pattern,
int  flags = IgnoreCase 
)

Create and compile a new regular expression pattern.

Parameters
patternPattern to compile
flagsPattern match options
PRegularExpression::PRegularExpression ( const char *  cpattern,
int  flags = IgnoreCase 
)

Create and compile a new regular expression pattern.

Parameters
cpatternPattern to compile
flagsPattern match options
PRegularExpression::PRegularExpression ( const PRegularExpression )

Copy a regular expression.

PRegularExpression::~PRegularExpression ( )

Release storage for the compiled regular expression.

Member Function Documentation

PBoolean PRegularExpression::Compile ( const PString pattern,
int  flags = IgnoreCase 
)

Compiler pattern.

Parameters
patternPattern to compile
flagsPattern match options
PBoolean PRegularExpression::Compile ( const char *  cpattern,
int  flags = IgnoreCase 
)

Compiler pattern.

The pattern is compiled into an internal format to speed subsequent execution of the pattern match algorithm.

Returns
true if successfully compiled.
Parameters
cpatternPattern to compile
flagsPattern match options
static PString PRegularExpression::EscapeString ( const PString str)
static

Escape all characters in the str parameter that have a special meaning within a regular expression.

Returns
String with additional escape ('\') characters.
Parameters
strString to add esacpes to.
PBoolean PRegularExpression::Execute ( const PString str,
PINDEX &  start,
int  flags = 0 
) const

Execute regular expression.

Parameters
strSource string to search
startFirst match location
flagsPattern match options
PBoolean PRegularExpression::Execute ( const PString str,
PINDEX &  start,
PINDEX &  len,
int  flags = 0 
) const

Execute regular expression.

Parameters
strSource string to search
startFirst match location
lenLength of match
flagsPattern match options
PBoolean PRegularExpression::Execute ( const char *  cstr,
PINDEX &  start,
int  flags = 0 
) const

Execute regular expression.

Parameters
cstrSource string to search
startFirst match location
flagsPattern match options
PBoolean PRegularExpression::Execute ( const char *  cstr,
PINDEX &  start,
PINDEX &  len,
int  flags = 0 
) const

Execute regular expression.

Parameters
cstrSource string to search
startFirst match location
lenLength of match
flagsPattern match options
PBoolean PRegularExpression::Execute ( const PString str,
PIntArray starts,
int  flags = 0 
) const

Execute regular expression.

Parameters
strSource string to search
startsArray of match locations
flagsPattern match options
PBoolean PRegularExpression::Execute ( const PString str,
PIntArray starts,
PIntArray ends,
int  flags = 0 
) const

Execute regular expression.

Parameters
strSource string to search
startsArray of match locations
endsArray of match ends
flagsPattern match options
PBoolean PRegularExpression::Execute ( const char *  cstr,
PIntArray starts,
int  flags = 0 
) const

Execute regular expression.

Parameters
cstrSource string to search
startsArray of match locations
flagsPattern match options
PBoolean PRegularExpression::Execute ( const char *  cstr,
PIntArray starts,
PIntArray ends,
int  flags = 0 
) const

Execute regular expression.

Execute the pattern match algorithm using the previously compiled pattern.

The starts and ends arrays indicate the start and end positions of the matched substrings in cstr. The 0th member is filled in to indicate what substring was matched by the entire regular expression. The remaining members report what substring was matched by parenthesized subexpressions within the regular expression.

The caller should set the size of the starts array before calling to indicated how many subexpressions are expected. If the starts array is empty, it will be set to one entry.

Returns
true if successfully compiled.
Parameters
cstrSource string to search
startsArray of match locations
endsArray of match ends
flagsPattern match options
PBoolean PRegularExpression::Execute ( const char *  cstr,
PStringArray substring,
int  flags = 0 
) const

Execute regular expression.

Execute the pattern match algorithm using the previously compiled pattern.

The substring arrays is filled with the matched substrings out of cstr. The 0th member is filled in to indicate what substring was matched by the entire regular expression. The remaining members report what substring was matched by parenthesized subexpressions within the regular expression.

The caller should set the size of the substring array before calling to indicated how many subexpressions are expected. If the substring array is empty, it will be set to one entry.

Returns
true if successfully compiled.
Parameters
cstrSource string to search
substringArray of matched substrings
flagsPattern match options
ErrorCodes PRegularExpression::GetErrorCode ( ) const

Get the error code for the last Compile() or Execute() operation.

Returns
Error code.
PString PRegularExpression::GetErrorText ( ) const

Get the text description for the error of the last Compile() or Execute() operation.

Returns
Error text string.
const PString& PRegularExpression::GetPattern ( ) const
inline

Return the string which represents the pattern matched by the regular expression.

References patternSaved.

PRegularExpression& PRegularExpression::operator= ( const PRegularExpression )

Assign a regular expression.

virtual void PRegularExpression::PrintOn ( ostream &  strm) const
virtual

Output the regular expression to the specified stream.

Parameters
strmI/O stream to output to.

Reimplemented from PObject.

Member Data Documentation

void* PRegularExpression::expression
protected
int PRegularExpression::flagsSaved
protected
ErrorCodes PRegularExpression::lastError
mutableprotected
PString PRegularExpression::patternSaved
protected

Referenced by GetPattern().


The documentation for this class was generated from the following file: