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

List of all members.

## 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.
PRegularExpression & | operator= (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 PString & | GetPattern () const
| Return the string which represents the pattern matched by the regular expression.

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

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

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

Compiler pattern.

Parameters:

  pattern | 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 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

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,
|  | 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 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 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 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 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 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 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

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.

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]`

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

- pstring.h