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:

## 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 PObject * | Clone () 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...
PRegularExpression & | operator= (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 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...
Protected Member Functions inherited from PObject
| PObject ()
| Constructor for PObject, made protected so cannot ever create one on its own. More...

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

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,
|  | int | flags = `IgnoreCase`
| ) |  |

Create and compile a new regular expression pattern.

Parameters

  pattern | Pattern to compile
  flags | Pattern match options

PRegularExpression::PRegularExpression | ( | const char * | cpattern,
|  | int | flags = `IgnoreCase`
| ) |  |

Create and compile a new regular expression pattern.

Parameters

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

  pattern | Pattern to compile
  flags | Pattern 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

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

PBoolean PRegularExpression::Execute | ( | const PString & | str,
|  | PINDEX & | start,
|  | int | flags = `0`
| ) |  | const

Execute regular expression.

Parameters

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

PBoolean PRegularExpression::Execute | ( | const PString & | str,
|  | PINDEX & | start,
|  | PINDEX & | len,
|  | int | flags = `0`
| ) |  | const

Execute regular expression.

Parameters

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

PBoolean PRegularExpression::Execute | ( | const char * | cstr,
|  | PINDEX & | start,
|  | int | flags = `0`
| ) |  | const

Execute regular expression.

Parameters

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

PBoolean PRegularExpression::Execute | ( | const char * | cstr,
|  | PINDEX & | start,
|  | PINDEX & | len,
|  | int | flags = `0`
| ) |  | const

Execute regular expression.

Parameters

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

PBoolean PRegularExpression::Execute | ( | const PString & | str,
|  | PIntArray & | starts,
|  | int | flags = `0`
| ) |  | const

Execute regular expression.

Parameters

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

PBoolean PRegularExpression::Execute | ( | const PString & | str,
|  | PIntArray & | starts,
|  | PIntArray & | ends,
|  | int | flags = `0`
| ) |  | const

Execute regular expression.

Parameters

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

PBoolean PRegularExpression::Execute | ( | const char * | cstr,
|  | PIntArray & | starts,
|  | int | flags = `0`
| ) |  | const

Execute regular expression.

Parameters

  cstr | Source string to search
  starts | Array of match locations
  flags | Pattern 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

  cstr | Source string to search
  starts | Array of match locations
  ends | Array of match ends
  flags | Pattern 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

  cstr | Source string to search
  substring | Array of matched substrings
  flags | Pattern 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

  strm | I/O stream to output to.

Reimplemented from PObject.

## Member Data Documentation

void* PRegularExpression::expression

protected

int PRegularExpression::flagsSaved

protected

ErrorCodes PRegularExpression::lastError

mutable protected

PString PRegularExpression::patternSaved

protected

Referenced by GetPattern().

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

- pstring.h