class Poco::RegularExpression

Overview

A class for working with regular expressions. More…

#include <RegularExpression.h>

class RegularExpression
{
public:
    // typedefs

    typedef std::vector<Match> MatchVec;

    // enums

    enum Options;

    // structs

    struct Match;

    // construction

    RegularExpression(
        const std::string& pattern,
        int options = 0,
        bool study = true
        );

    // methods

    int
    match(
        const std::string& subject,
        Match& mtch,
        int options = 0
        ) const;

    int
    match(
        const std::string& subject,
        std::string::size_type offset,
        Match& mtch,
        int options = 0
        ) const;

    int
    match(
        const std::string& subject,
        std::string::size_type offset,
        MatchVec& matches,
        int options = 0
        ) const;

    bool
    match(
        const std::string& subject,
        std::string::size_type offset = 0
        ) const;

    bool
    match(
        const std::string& subject,
        std::string::size_type offset,
        int options
        ) const;

    bool
    operator==(const std::string& subject) const;

    bool
    operator!=(const std::string& subject) const;

    int
    extract(
        const std::string& subject,
        std::string& str,
        int options = 0
        ) const;

    int
    extract(
        const std::string& subject,
        std::string::size_type offset,
        std::string& str,
        int options = 0
        ) const;

    int
    split(
        const std::string& subject,
        std::vector<std::string>& strings,
        int options = 0
        ) const;

    int
    split(
        const std::string& subject,
        std::string::size_type offset,
        std::vector<std::string>& strings,
        int options = 0
        ) const;

    int
    subst(
        std::string& subject,
        const std::string& replacement,
        int options = 0
        ) const;

    int
    subst(
        std::string& subject,
        std::string::size_type offset,
        const std::string& replacement,
        int options = 0
        ) const;

    static
    bool
    match(
        const std::string& subject,
        const std::string& pattern,
        int options = 0
        );

protected:
    // methods

    std::string::size_type
    substOne(
        std::string& subject,
        std::string::size_type offset,
        const std::string& replacement,
        int options
        ) const;
};

Detailed Documentation

A class for working with regular expressions.

Implemented using PCRE, the Perl Compatible Regular Expressions library by Philip Hazel (see http://www.pcre.org).

Construction

RegularExpression(
    const std::string& pattern,
    int options = 0,
    bool study = true
    )

Creates a regular expression and parses the given pattern.

If study is true, the pattern is analyzed and optimized. This is mainly useful if the pattern is used more than once. For a description of the options, please see the PCRE documentation. Throws a RegularExpressionException if the patter cannot be compiled.

Methods

int
match(
    const std::string& subject,
    Match& mtch,
    int options = 0
    ) const

Matches the given subject string against the pattern.

Returns the position of the first captured substring in mtch. If no part of the subject matches the pattern, mtch.offset is std::string::npos and mtch.length is 0. Throws a RegularExpressionException in case of an error. Returns the number of matches.

int
match(
    const std::string& subject,
    std::string::size_type offset,
    Match& mtch,
    int options = 0
    ) const

Matches the given subject string, starting at offset, against the pattern.

Returns the position of the captured substring in mtch. If no part of the subject matches the pattern, mtch.offset is std::string::npos and mtch.length is 0. Throws a RegularExpressionException in case of an error. Returns the number of matches.

int
match(
    const std::string& subject,
    std::string::size_type offset,
    MatchVec& matches,
    int options = 0
    ) const

Matches the given subject string against the pattern.

The first entry in matches contains the position of the captured substring. The following entries identify matching subpatterns. See the PCRE documentation for a more detailed explanation. If no part of the subject matches the pattern, matches is empty. Throws a RegularExpressionException in case of an error. Returns the number of matches.

bool
match(
    const std::string& subject,
    std::string::size_type offset = 0
    ) const

Returns true if and only if the subject matches the regular expression.

Internally, this method sets the RE_ANCHORED and RE_NOTEMPTY options for matching, which means that the empty string will never match and the pattern is treated as if it starts with a ^.

bool
match(
    const std::string& subject,
    std::string::size_type offset,
    int options
    ) const

Returns true if and only if the subject matches the regular expression.

bool
operator==(const std::string& subject) const

Returns true if and only if the subject matches the regular expression.

Internally, this method sets the RE_ANCHORED and RE_NOTEMPTY options for matching, which means that the empty string will never match and the pattern is treated as if it starts with a ^.

bool
operator!=(const std::string& subject) const

Returns true if and only if the subject does not match the regular expression.

Internally, this method sets the RE_ANCHORED and RE_NOTEMPTY options for matching, which means that the empty string will never match and the pattern is treated as if it starts with a ^.

int
extract(
    const std::string& subject,
    std::string& str,
    int options = 0
    ) const

Matches the given subject string against the pattern.

Returns the captured string. Throws a RegularExpressionException in case of an error. Returns the number of matches.

int
extract(
    const std::string& subject,
    std::string::size_type offset,
    std::string& str,
    int options = 0
    ) const

Matches the given subject string, starting at offset, against the pattern.

Returns the captured string. Throws a RegularExpressionException in case of an error. Returns the number of matches.

int
split(
    const std::string& subject,
    std::vector<std::string>& strings,
    int options = 0
    ) const

Matches the given subject string against the pattern.

The first entry in captured is the captured substring. The following entries contain substrings matching subpatterns. See the PCRE documentation for a more detailed explanation. If no part of the subject matches the pattern, captured is empty. Throws a RegularExpressionException in case of an error. Returns the number of matches.

int
split(
    const std::string& subject,
    std::string::size_type offset,
    std::vector<std::string>& strings,
    int options = 0
    ) const

Matches the given subject string against the pattern.

The first entry in captured is the captured substring. The following entries contain substrings matching subpatterns. See the PCRE documentation for a more detailed explanation. If no part of the subject matches the pattern, captured is empty. Throws a RegularExpressionException in case of an error. Returns the number of matches.

int
subst(
    std::string& subject,
    const std::string& replacement,
    int options = 0
    ) const

Substitute in subject all matches of the pattern with replacement.

If RE_GLOBAL is specified as option, all matches are replaced. Otherwise, only the first match is replaced. Occurences of $<n> (for example, $1, $2, …) in replacement are replaced with the corresponding captured string. $0 is the original subject string. Returns the number of replaced occurences.

int
subst(
    std::string& subject,
    std::string::size_type offset,
    const std::string& replacement,
    int options = 0
    ) const

Substitute in subject all matches of the pattern with replacement, starting at offset.

If RE_GLOBAL is specified as option, all matches are replaced. Otherwise, only the first match is replaced. Unless RE_NO_VARS is specified, occurences of $<n> (for example, $0, $1, $2, … $9) in replacement are replaced with the corresponding captured string. $0 is the captured substring. $1 … $n are the substrings maching the subpatterns. Returns the number of replaced occurences.

static
bool
match(
    const std::string& subject,
    const std::string& pattern,
    int options = 0
    )

Matches the given subject string against the regular expression given in pattern, using the given options.