PTLib  Version 2.10.4
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

List of all members.

Public Member Functions

Overrides from class PObject
virtual void PrintOn (ostream &strm) const
 Output the regular expression to the specified stream.
Compile & Execute functions
PBoolean Compile (const PString &pattern, int flags=IgnoreCase)
 Compiler pattern.
PBoolean Compile (const char *cpattern, int flags=IgnoreCase)
 Compiler pattern.
PBoolean Execute (const PString &str, PINDEX &start, int flags=0) const
 Execute regular expression.
PBoolean Execute (const PString &str, PINDEX &start, PINDEX &len, int flags=0) const
 Execute regular expression.
PBoolean Execute (const char *cstr, PINDEX &start, int flags=0) const
 Execute regular expression.
PBoolean Execute (const char *cstr, PINDEX &start, PINDEX &len, int flags=0) const
 Execute regular expression.
PBoolean Execute (const PString &str, PIntArray &starts, int flags=0) const
 Execute regular expression.
PBoolean Execute (const PString &str, PIntArray &starts, PIntArray &ends, int flags=0) const
 Execute regular expression.
PBoolean Execute (const char *cstr, PIntArray &starts, int flags=0) const
 Execute regular expression.
PBoolean Execute (const char *cstr, PIntArray &starts, PIntArray &ends, int flags=0) const
 Execute regular expression.
PBoolean Execute (const char *cstr, PStringArray &substring, int flags=0) const
 Execute regular expression.

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.

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.
 PRegularExpression (const PString &pattern, int flags=IgnoreCase)
 Create and compile a new regular expression pattern.
 PRegularExpression (const char *cpattern, int flags=IgnoreCase)
 Create and compile a new regular expression pattern.
 PRegularExpression (const PRegularExpression &)
 Copy a regular expression.
PRegularExpressionoperator= (const PRegularExpression &)
 Assign a regular expression.
 ~PRegularExpression ()
 Release storage for the compiled regular expression.

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.
PString GetErrorText () const
 Get the text description for the error of the last Compile() or Execute() operation.
const PStringGetPattern () const
 Return the string which represents the pattern matched by the regular expression.

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

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

Copy a regular expression.

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

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

Returns:
Error code.

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]

The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines