libcamgm
Public Types | Public Member Functions | Private Attributes | List of all members
ca_mgm::PosixRegEx Class Reference

#include <PosixRegEx.hpp>

Public Types

typedef regmatch_t match_t
 
typedef std::vector< match_tMatchArray
 

Public Member Functions

 PosixRegEx ()
 
 PosixRegEx (const std::string &regex, int cflags=1)
 
 PosixRegEx (const PosixRegEx &ref)
 
 ~PosixRegEx ()
 
PosixRegExoperator= (const PosixRegEx &ref)
 
bool compile (const std::string &regex, int cflags=1)
 
int errorCode ()
 
std::string errorString () const
 
std::string patternString () const
 
int compileFlags () const
 
bool isCompiled () const
 
bool execute (MatchArray &sub, const std::string &str, size_t index=0, size_t count=0, int eflags=0)
 
std::vector< std::string > capture (const std::string &str, size_t index=0, size_t count=0, int eflags=0)
 
std::string replace (const std::string &str, const std::string &rep, bool global=false, int eflags=0)
 
std::vector< std::string > split (const std::string &str, bool empty=false, int eflags=0)
 
std::vector< std::string > grep (const std::vector< std::string > &src, int eflags=0)
 
bool match (const std::string &str, size_t index=0, int eflags=0) const
 

Private Attributes

bool compiled
 
int m_flags
 
int m_ecode
 
std::string m_error
 
std::string m_rxstr
 
regex_t m_regex
 

Detailed Description

POSIX Regular Expression wrapper class and utility functions.

Depends on avaliability of a POSIX.2 / SUSv2 conforming regcomp(3) and regexec(3) function implementation.

Consult the regcomp(3), regexec(3) and regex(7) manual pages for informations about details of the posix regex usage.

Member Typedef Documentation

typedef regmatch_t ca_mgm::PosixRegEx::match_t

POSIX RegEx structure for captured substring offset pair. The regex match structure contains two member variables:

  • rm_so start offset of the regex match
  • rm_eo end offset of the regex match

Array of captured substring offsets.

Constructor & Destructor Documentation

ca_mgm::PosixRegEx::PosixRegEx ( )

Create a new PosixRegEx object without compilation.

ca_mgm::PosixRegEx::PosixRegEx ( const std::string &  regex,
int  cflags = 1 
)

Create a new PosixRegEx object and compile the regular expression.

See also compile() method.

Parameters
regexA regular expression pattern.
cflagsBitwise-or of compilation flags.
Exceptions
RegExCompileExceptionon compilation failure.
ca_mgm::PosixRegEx::PosixRegEx ( const PosixRegEx ref)

Create a new PosixRegEx as (deep) copy of the specified reference. If the reference is compiled, the new object will be compiled as well.

Parameters
refThe PosixRegEx object reference to copy.
Exceptions
RegExCompileExceptionon compilation failure.
ca_mgm::PosixRegEx::~PosixRegEx ( )

Destroy this PosixRegEx object.

Member Function Documentation

std::vector<std::string> ca_mgm::PosixRegEx::capture ( const std::string &  str,
size_t  index = 0,
size_t  count = 0,
int  eflags = 0 
)

Search in string and return an array of captured substrings.

Parameters
strstring to search in
indexmatch string starting at index
countexpected substring count
eflagsexecution flags, see execute() method
Returns
array of captured substrings
Exceptions
RegExCompileExceptionif regex is not compiled or the REG_NOSUB compilation flag was used.
RegExExecuteExceptionon execute failures.
OutOfBoundsExceptionif the index is greater than the string length.
Example:
std::string str("foo = bar trala hoho");
PosixRegEx reg("^([a-z]+)[ \t]*=[ \t]*(.*)$");
std::vector<std::string> out = reg.capture(str);
//
// out is { "foo = bar trala hoho",
// "foo",
// "bar trala hoho"
// }
bool ca_mgm::PosixRegEx::compile ( const std::string &  regex,
int  cflags = 1 
)

Compile the regular expression contained in the string.

Parameters
regexA regular expression pattern.
cflagsBitwise-or of compilation flags.
Returns
True on successful compilation, false on failure.

The cflags parameter can be set to one or a bitwise-or of the following flags. Consult the regcomp manual page for the complete (library specific) flag list and detailed description.

  • REG_EXTENDED Use Extended Regular Expressions syntax instead of Basic.
  • REG_ICASE Ignore character case in match.
  • REG_NOSUB Report match only, do not capture substrings.
  • REG_NEWLINE Match-any-character operators don't match a newline.
int ca_mgm::PosixRegEx::compileFlags ( ) const
Returns
The compilation flags used in compile() method.
int ca_mgm::PosixRegEx::errorCode ( )

Return the last error code generated by compile or one of the executing methods.

Returns
0 or the last error code
std::string ca_mgm::PosixRegEx::errorString ( ) const

Return the error message string for the last error code.

Returns
The error message or empty string if no expression was compiled.
bool ca_mgm::PosixRegEx::execute ( MatchArray sub,
const std::string &  str,
size_t  index = 0,
size_t  count = 0,
int  eflags = 0 
)

Execute regular expression matching against the string. The matching starts at the specified index and return true on match of false if no match found.

Note
In contrast to the (PCRE) PerlRegEx class, the index handling is not provided by posix regex. The PosixRegEx class is using simple str.c_str() + index construct and adjusts the resulting match offsets.

The expected number of substrings to match can be specified in count. If the default value of 0 is used, the count as detected by compile is used instead.

Note
If the specified count is greater 0 but smaller than the effectively number of found matches, the match array will contain only offsets for captured substring. This is a different than in PerlRegEx that reports failure. If the specified count is greater 0 and greater than the the effectively number of found matches, unused offsets at the end are filled with to -1.

If no match was found, the sub array will be empty and false is returned. If a match is found and the expression was compiled to capture substrings, the sub array will be filled with the captured substring offset (match_t structures). The first (index 0) offset pair points to the start of the first match and the end of the last match. Unused / optional capturing subpattern offsets will be set to -1.

Consult the regexec(3) and regex(7) manual pages for complete and detailed descriptions.

Parameters
subarray for substring offsets
strstring to match
indexmatch string starting at index
countnumber of expected substring matches
eflagsexecution flags described bellow
Returns
true on match or false
Exceptions
RegExCompileExceptionif regex is not compiled.
OutOfBoundsExceptionif the index is greater than the string length.

The eflags parameter can be set to 0, one or a bitwise-or of the following options:

  • REG_NOTBOL The circumflex character (^) will not match the beginning of string.
  • REG_NOTEOL The dollar sign ($) will not match the end of string.
Example:
std::string str("foo = bar trala hoho");
if( PosixRegEx("=").execute(sub, str) && !sub.empty())
{
//
// sub[0].rm_so is 4,
// sub[0].rm_eo is 5
//
}
std::vector<std::string> ca_mgm::PosixRegEx::grep ( const std::vector< std::string > &  src,
int  eflags = 0 
)

Match all strings in the array against regular expression. Returns an array of matching strings.

Parameters
srclist of strings to match
eflagsexecution flags, see execute() method
Exceptions
RegExCompileExceptionif regex is not compiled or the REG_NOSUB compilation flag was used.
RegExExecuteExceptionon execute failures.
OutOfBoundsExceptionif the index is greater than the string length.
Example:
std::vector<std::string> src;
src.push_back("\t");
src.push_back("one");
src.push_back("");
src.push_back("two");
src.push_back(" ");
std::vector<std::string> out = PosixRegEx("[^ \t]").grep(src);
//
// out is { "one", "two" }
//
bool ca_mgm::PosixRegEx::isCompiled ( ) const
Returns
true, if the current regex object is compiled.
bool ca_mgm::PosixRegEx::match ( const std::string &  str,
size_t  index = 0,
int  eflags = 0 
) const

Execute regular expression matching against the string. The matching starts at the specified index and return true on match of false if no match found.

See execute() method for description of the index and eflags parameters.

Parameters
strstring to match
indexmatch string starting at index
eflagsexecution flags, see execute() method
Returns
true on match or false
Exceptions
RegExCompileExceptionif regex is not compiled.
RegExExecuteExceptionon execute failures.
OutOfBoundsExceptionif the index is greater than the string length.
Example:
std::string str("foo = bar ");
if( PosixRegEx("^[a-z]+[ \t]*=[ \t]*.*$").match(str))
{
}
PosixRegEx& ca_mgm::PosixRegEx::operator= ( const PosixRegEx ref)

Assign the specified PosixRegEx reference. If the reference is compiled, the current object will be (re)compiled.

Parameters
refThe PosixRegEx object reference to assign from.
Exceptions
RegExCompileExceptionon compilation failure.
std::string ca_mgm::PosixRegEx::patternString ( ) const
Returns
The regular expression pattern string.
std::string ca_mgm::PosixRegEx::replace ( const std::string &  str,
const std::string &  rep,
bool  global = false,
int  eflags = 0 
)

Replace (substitute) the first or all matching substrings.

Substring(s) matching regular expression are replaced with the string provided in rep and a new, modified string is returned. If no matches are found, a copy of 'str' string is returned.

The rep string can contain capturing references "\\1" to "\\9" that will be substituted with the corresponding captured string. Prepended "\\" before the reference disables (switches to skip) the substitution. Note, the notation using double-slash followed by a digit character, not just "\1" like the "\n" escape sequence.

Parameters
strstring that should be matched
repreplacement substring with optional references
globalif to replace the first or all matches
eflagsexecution flags, see execute() method
Returns
new string with modification(s)
Exceptions
RegExCompileExceptionif regex is not compiled or the REG_NOSUB compilation flag was used.
RegExExecuteExceptionon execute failures.
OutOfBoundsExceptionif the index is greater than the string length.
Example:
std::string str("//foo/.//bar/hoho");
PosixRegEx reg("([/]+(\\.?[/]+)?)");
std::string out = reg.replace(str, "/", true);
//
// out is "/foo/bar/hoho"
//
std::vector<std::string> ca_mgm::PosixRegEx::split ( const std::string &  str,
bool  empty = false,
int  eflags = 0 
)

Split the specified string into an array of substrings. The regular expression is used to match the separators.

If the empty flag is true, empty substring are included in the resulting array.

If no separators were found, and the empty flag is true, the array will contain the input string as its only element. If the empty flag is false, a empty array is returned.

Parameters
strstring that should be splitted
emptywhether to capture empty substrings
eflagsexecution flags, see execute() method
Returns
array of resulting substrings or empty array on failure
Exceptions
RegExCompileExceptionif regex is not compiled or the REG_NOSUB compilation flag was used.
RegExExecuteExceptionon execute failures.
OutOfBoundsExceptionif the index is greater than the string length.
Example:
std::string str("1.23, .50 , , 71.00 , 6.00");
std::vector<std::string> out1 = PosixRegEx("([ \t]*,[ \t]*)").split(str);
//
// out1 is { "1.23", ".50", "71.00", "6.00" }
//

Member Data Documentation

bool ca_mgm::PosixRegEx::compiled
private
int ca_mgm::PosixRegEx::m_ecode
mutableprivate
std::string ca_mgm::PosixRegEx::m_error
mutableprivate
int ca_mgm::PosixRegEx::m_flags
private
regex_t ca_mgm::PosixRegEx::m_regex
private
std::string ca_mgm::PosixRegEx::m_rxstr
private

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