PTLib Version 2.12.9

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Protected Member Functions | Protected Attributes | List of all members
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:
[legend]
Collaboration diagram for PRegularExpression:
[legend]

## Public Member Functions
Constructors & destructors
| P_DECLARE_BITWISE_ENUM (CompileOptions, 3,(Simple, Extended, IgnoreCase, AnchorNewLine))
| Flags for compiler options. More...
| P_DECLARE_BITWISE_ENUM (ExecOptions, 2,(Normal, NotBeginningOfLine, NotEndofLine))
| Flags for execution options. More...
| PRegularExpression ()
| Create a new, empty, regular expression. More...
| PRegularExpression (const PString &pattern, CompileOptions options=IgnoreCase)
| Create and compile a new regular expression pattern. More...
| PRegularExpression (const char *cpattern, CompileOptions options=IgnoreCase)
| Create and compile a new regular expression pattern. More...
| PRegularExpression (const PRegularExpression &)
| Copy a regular expression. More...
PRegularExpression & | operator= (const PRegularExpression &)
| Assign a regular expression. More...
| ~PRegularExpression ()
| Release storage for the compiled regular expression. More...
Overrides from class PObject
virtual void | PrintOn (ostream &strm) const
| Output the regular expression to the specified stream. More...
Compile & Execute functions
bool | Compile (const PString &pattern, CompileOptions options=IgnoreCase)
| Compiler pattern. More...
bool | Compile (const char *cpattern, CompileOptions options=IgnoreCase)
| Compiler pattern. More...
bool | Execute (const PString &str, PINDEX &start, ExecOptions options=Normal) const
| Execute regular expression. More...
bool | Execute (const PString &str, PINDEX &start, PINDEX &len, ExecOptions options=Normal) const
| Execute regular expression. More...
bool | Execute (const char *cstr, PINDEX &start, ExecOptions options=Normal) const
| Execute regular expression. More...
bool | Execute (const char *cstr, PINDEX &start, PINDEX &len, ExecOptions options=Normal) const
| Execute regular expression. More...
bool | Execute (const PString &str, PIntArray &starts, ExecOptions options=Normal) const
| Execute regular expression. More...
bool | Execute (const PString &str, PIntArray &starts, PIntArray &ends, ExecOptions options=Normal) const
| Execute regular expression. More...
bool | Execute (const char *cstr, PIntArray &starts, ExecOptions options=Normal) const
| Execute regular expression. More...
bool | Execute (const char *cstr, PIntArray &starts, PIntArray &ends, ExecOptions options=Normal) const
| Execute regular expression. More...
bool | Execute (const char *cstr, PStringArray &substring, ExecOptions options=Normal) const
| Execute regular expression. More...
Public Member Functions inherited from PObject
unsigned | GetTraceContextIdentifier () const
| Get PTRACE context identifier. More...
void | SetTraceContextIdentifier (unsigned id)
void | GetTraceContextIdentifier (PObject &obj)
void | GetTraceContextIdentifier (PObject *obj)
void | SetTraceContextIdentifier (const PObject &obj)
void | SetTraceContextIdentifier (const PObject *obj)
virtual | ~PObject ()
virtual PObject * | Clone () const
| Create a copy of the class on the heap. More...
template<class CLS >
CLS * | CloneAs () const
| As for Clone() but converts to specified type. 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...
__inline const PObject * | PTraceObjectInstance () const
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 | PrintOn (ostream &strm) const
| Output the contents of the object to the stream. 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 __inline const PObject * | PTraceObjectInstance (const char *)
static __inline const PObject * | PTraceObjectInstance (const PObject *obj)
static Comparison | InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
| Internal function caled from CompareObjectMemoryDirect() More...

## Protected Member Functions
bool | InternalCompile ()
void | InternalClean ()
Protected Member Functions inherited from PObject
| PObject ()
| Constructor for PObject, made protected so cannot ever create one on its own. More...

## Protected Attributes
PString | m_pattern
CompileOptions | m_compileOptions
void * | m_compiledRegex
ErrorCodes | m_lastError
Protected Attributes inherited from PObject
unsigned | m_traceContextIdentifier

## 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 PString & | GetPattern () 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...
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

enum PRegularExpression::ErrorCodes

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,
|  | CompileOptions | options = `IgnoreCase`
| ) |  |

Create and compile a new regular expression pattern.

Parameters

  pattern | Pattern to compile
  options | Pattern match options

PRegularExpression::PRegularExpression | ( | const char * | cpattern,
|  | CompileOptions | options = `IgnoreCase`
| ) |  |

Create and compile a new regular expression pattern.

Parameters

  cpattern | Pattern to compile
  options | Pattern match options

PRegularExpression::PRegularExpression | ( | const PRegularExpression & |  | ) |

Copy a regular expression.

PRegularExpression::~PRegularExpression | ( |  | ) |

Release storage for the compiled regular expression.

## Member Function Documentation

bool PRegularExpression::Compile | ( | const PString & | pattern,
|  | CompileOptions | options = `IgnoreCase`
| ) |  |

Compiler pattern.

Parameters

  pattern | Pattern to compile
  options | Pattern match options

bool PRegularExpression::Compile | ( | const char * | cpattern,
|  | CompileOptions | options = `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

  cpattern | Pattern to compile
  options | Pattern 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

  str | String to add esacpes to.

bool PRegularExpression::Execute | ( | const PString & | str,
|  | PINDEX & | start,
|  | ExecOptions | options = `Normal`
| ) |  | const

Execute regular expression.

Parameters

  str | Source string to search
  start | First match location
  options | Pattern match options

bool PRegularExpression::Execute | ( | const PString & | str,
|  | PINDEX & | start,
|  | PINDEX & | len,
|  | ExecOptions | options = `Normal`
| ) |  | const

Execute regular expression.

Parameters

  str | Source string to search
  start | First match location
  len | Length of match
  options | Pattern match options

bool PRegularExpression::Execute | ( | const char * | cstr,
|  | PINDEX & | start,
|  | ExecOptions | options = `Normal`
| ) |  | const

Execute regular expression.

Parameters

  cstr | Source string to search
  start | First match location
  options | Pattern match options

bool PRegularExpression::Execute | ( | const char * | cstr,
|  | PINDEX & | start,
|  | PINDEX & | len,
|  | ExecOptions | options = `Normal`
| ) |  | const

Execute regular expression.

Parameters

  cstr | Source string to search
  start | First match location
  len | Length of match
  options | Pattern match options

bool PRegularExpression::Execute | ( | const PString & | str,
|  | PIntArray & | starts,
|  | ExecOptions | options = `Normal`
| ) |  | const

Execute regular expression.

Parameters

  str | Source string to search
  starts | Array of match locations
  options | Pattern match options

bool PRegularExpression::Execute | ( | const PString & | str,
|  | PIntArray & | starts,
|  | PIntArray & | ends,
|  | ExecOptions | options = `Normal`
| ) |  | const

Execute regular expression.

Parameters

  str | Source string to search
  starts | Array of match locations
  ends | Array of match ends
  options | Pattern match options

bool PRegularExpression::Execute | ( | const char * | cstr,
|  | PIntArray & | starts,
|  | ExecOptions | options = `Normal`
| ) |  | const

Execute regular expression.

Parameters

  cstr | Source string to search
  starts | Array of match locations
  options | Pattern match options

bool PRegularExpression::Execute | ( | const char * | cstr,
|  | PIntArray & | starts,
|  | PIntArray & | ends,
|  | ExecOptions | options = `Normal`
| ) |  | 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

  cstr | Source string to search
  starts | Array of match locations
  ends | Array of match ends
  options | Pattern match options

bool PRegularExpression::Execute | ( | const char * | cstr,
|  | PStringArray & | substring,
|  | ExecOptions | options = `Normal`
| ) |  | 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

  cstr | Source string to search
  substring | Array of matched substrings
  options | Pattern match options

ErrorCodes PRegularExpression::GetErrorCode | ( |  | ) | const
| inline

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

Returns
  Error code.

References m_lastError.

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

void PRegularExpression::InternalClean | ( |  | ) |
| protected

bool PRegularExpression::InternalCompile | ( |  | ) |
| protected

PRegularExpression& PRegularExpression::operator= | ( | const PRegularExpression & |  | ) |

Assign a regular expression.

PRegularExpression::P_DECLARE_BITWISE_ENUM | ( | CompileOptions | ,
|  | 3 | ,
|  | (Simple, Extended, IgnoreCase, AnchorNewLine) |
| ) |  |

Flags for compiler options.

PRegularExpression::P_DECLARE_BITWISE_ENUM | ( | ExecOptions | ,
|  | 2 | ,
|  | (Normal, NotBeginningOfLine, NotEndofLine) |
| ) |  |

Flags for execution options.

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

Output the regular expression to the specified stream.

Parameters

  strm | I/O stream to output to.

## Member Data Documentation

void* PRegularExpression::m_compiledRegex
| protected

CompileOptions PRegularExpression::m_compileOptions
| protected

ErrorCodes PRegularExpression::m_lastError
| mutable protected

Referenced by GetErrorCode().

PString PRegularExpression::m_pattern
| protected

Referenced by GetPattern().

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

- pstring.h