123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283 |
- [/
- Copyright 2006-2007 John Maddock.
- Distributed under the Boost Software License, Version 1.0.
- (See accompanying file LICENSE_1_0.txt or copy at
- http://www.boost.org/LICENSE_1_0.txt).
- ]
- [section:old_regex High Level Class RegEx (Deprecated)]
- The high level wrapper class RegEx is now deprecated and does not form
- part of the regular expression standardization proposal. This type still
- exists, and existing code will continue to compile, however the following
- documentation is unlikely to be further updated.
- #include <boost/cregex.hpp>
- The class RegEx provides a high level simplified interface to the regular
- expression library, this class only handles narrow character strings, and
- regular expressions always follow the "normal" syntax - that is the
- same as the perl / ECMAScript syntax.
- typedef bool (*GrepCallback)(const RegEx& expression);
- typedef bool (*GrepFileCallback)(const char* file, const RegEx& expression);
- typedef bool (*FindFilesCallback)(const char* file);
- class RegEx
- {
- public:
- RegEx();
- RegEx(const RegEx& o);
- ~RegEx();
- RegEx(const char* c, bool icase = false);
- explicit RegEx(const std::string& s, bool icase = false);
- RegEx& operator=(const RegEx& o);
- RegEx& operator=(const char* p);
- RegEx& operator=(const std::string& s);
- unsigned int SetExpression(const char* p, bool icase = false);
- unsigned int SetExpression(const std::string& s, bool icase = false);
- std::string Expression()const;
- //
- // now matching operators:
- //
- bool Match(const char* p, boost::match_flag_type flags = match_default);
- bool Match(const std::string& s, boost::match_flag_type flags = match_default);
- bool Search(const char* p, boost::match_flag_type flags = match_default);
- bool Search(const std::string& s, boost::match_flag_type flags = match_default);
- unsigned int Grep(GrepCallback cb, const char* p,
- boost::match_flag_type flags = match_default);
- unsigned int Grep(GrepCallback cb, const std::string& s,
- boost::match_flag_type flags = match_default);
- unsigned int Grep(std::vector<std::string>& v, const char* p,
- boost::match_flag_type flags = match_default);
- unsigned int Grep(std::vector<std::string>& v, const std::string& s,
- boost::match_flag_type flags = match_default);
- unsigned int Grep(std::vector<unsigned int>& v, const char* p,
- boost::match_flag_type flags = match_default);
- unsigned int Grep(std::vector<unsigned int>& v, const std::string& s,
- boost::match_flag_type flags = match_default);
- unsigned int GrepFiles(GrepFileCallback cb, const char* files, bool recurse = false,
- boost::match_flag_type flags = match_default);
- unsigned int GrepFiles(GrepFileCallback cb, const std::string& files,
- bool recurse = false,
- boost::match_flag_type flags = match_default);
- unsigned int FindFiles(FindFilesCallback cb, const char* files,
- bool recurse = false,
- boost::match_flag_type flags = match_default);
- unsigned int FindFiles(FindFilesCallback cb, const std::string& files,
- bool recurse = false,
- boost::match_flag_type flags = match_default);
- std::string Merge(const std::string& in, const std::string& fmt,
- bool copy = true, boost::match_flag_type flags = match_default);
- std::string Merge(const char* in, const char* fmt, bool copy = true,
- boost::match_flag_type flags = match_default);
- unsigned Split(std::vector<std::string>& v, std::string& s,
- boost::match_flag_type flags = match_default,
- unsigned max_count = ~0);
- //
- // now operators for returning what matched in more detail:
- //
- unsigned int Position(int i = 0)const;
- unsigned int Length(int i = 0)const;
- bool Matched(int i = 0)const;
- unsigned int Line()const;
- unsigned int Marks() const;
- std::string What(int i)const;
- std::string operator[](int i)const ;
- static const unsigned int npos;
- };
- Member functions for class RegEx are defined as follows:
-
- [table
- [[Member][Description]]
- [[`RegEx();`][Default constructor, constructs an instance of RegEx without any valid expression. ]]
- [[`RegEx(const RegEx& o);`][Copy constructor, all the properties of parameter /o/
- are copied. ]]
- [[`RegEx(const char* c, bool icase = false);`][Constructs an instance of RegEx,
- setting the expression to /c/, if /icase/ is true then matching is
- insensitive to case, otherwise it is sensitive to case. Throws
- [bad_expression] on failure. ]]
- [[`RegEx(const std::string& s, bool icase = false);`][Constructs an instance of
- RegEx, setting the expression to /s/, if /icase/ is true then matching
- is insensitive to case, otherwise it is sensitive to case. Throws
- [bad_expression] on failure. ]]
- [[`RegEx& operator=(const RegEx& o);`][Default assignment operator. ]]
- [[`RegEx& operator=(const char* p);`][Assignment operator, equivalent to calling
- `SetExpression(p, false)`. Throws [bad_expression] on failure. ]]
- [[`RegEx& operator=(const std::string& s);`][Assignment operator, equivalent to
- calling `SetExpression(s, false)`. Throws [bad_expression] on failure. ]]
- [[`unsigned int SetExpression(const char* p, bool icase = false);`][Sets the
- current expression to /p/, if /icase/ is true then matching is
- insensitive to case, otherwise it is sensitive to case.
- Throws [bad_expression] on failure. ]]
- [[`unsigned int SetExpression(const std::string& s, bool icase = false);`]
- [Sets the current expression to /s/, if /icase/ is true then matching is
- insensitive to case, otherwise it is sensitive to case. Throws
- [bad_expression] on failure. ]]
- [[`std::string Expression()const;`][Returns a copy of the current regular expression. ]]
- [[`bool Match(const char* p, boost::match_flag_type flags = match_default);`]
- [Attempts to match the current expression against the text /p/ using
- the match flags /flags/ - see [match_flag_type]. Returns /true/ if the
- expression matches the whole of the input string. ]]
- [[`bool Match(const std::string& s, boost::match_flag_type flags = match_default);`]
- [Attempts to match the current expression against the text /s/ using
- the [match_flag_type] /flags/. Returns /true/ if the expression matches
- the whole of the input string. ]]
- [[`bool Search(const char* p, boost::match_flag_type flags = match_default);`]
- [Attempts to find a match for the current expression somewhere in
- the text /p/ using the [match_flag_type] /flags/. Returns /true/
- if the match succeeds. ]]
- [[`bool Search(const std::string& s, boost::match_flag_type flags = match_default);`]
- [Attempts to find a match for the current expression somewhere in the
- text /s/ using the [match_flag_type] flags. Returns /true/ if the
- match succeeds. ]]
- [[`unsigned int Grep(GrepCallback cb, const char* p, boost::match_flag_type flags = match_default);`]
- [Finds all matches of the current expression in the text /p/ using the
- [match_flag_type] /flags/. For each match found calls the call-back
- function cb as: `cb(*this);`
- If at any stage the call-back function returns /false/ then the grep
- operation terminates, otherwise continues until no further matches
- are found. Returns the number of matches found.]]
- [[`unsigned int Grep(GrepCallback cb, const std::string& s, boost::match_flag_type flags = match_default);`]
- [Finds all matches of the current expression in the text /s/ using the
- [match_flag_type] flags. For each match found calls the call-back
- function cb as: `cb(*this);`
- If at any stage the call-back function returns false then the grep operation
- terminates, otherwise continues until no further matches are found.
- Returns the number of matches found.]]
- [[`unsigned int Grep(std::vector<std::string>& v, const char* p, boost::match_flag_type flags = match_default);`]
- [Finds all matches of the current expression in the text /p/ using the
- [match_flag_type] flags. For each match pushes a copy of what matched
- onto /v/. Returns the number of matches found. ]]
- [[`unsigned int Grep(std::vector<std::string>& v, const std::string& s, boost::match_flag_type flags = match_default);`]
- [Finds all matches of the current expression in the text /s/ using the
- [match_flag_type] /flags/. For each match pushes a copy of what
- matched onto /v/. Returns the number of matches found. ]]
- [[`unsigned int Grep(std::vector<unsigned int>& v, const char* p, boost::match_flag_type flags = match_default);`]
- [Finds all matches of the current expression in the text /p/ using the
- [match_flag_type] /flags/. For each match pushes the starting index of
- what matched onto /v/. Returns the number of matches found. ]]
- [[`unsigned int Grep(std::vector<unsigned int>& v, const std::string& s, boost::match_flag_type flags = match_default);`]
- [Finds all matches of the current expression in the text /s/ using the
- [match_flag_type] /flags/. For each match pushes the starting index of what
- matched onto /v/. Returns the number of matches found. ]]
- [[`unsigned int GrepFiles(GrepFileCallback cb, const char* files, bool recurse = false, boost::match_flag_type flags = match_default);`]
- [Finds all matches of the current expression in the files /files/ using
- the [match_flag_type] /flags/. For each match calls the call-back function cb.
- If the call-back returns false then the algorithm returns without
- considering further matches in the current file, or any further files.
-
- The parameter /files/ can include wild card characters '\*' and '\?', if
- the parameter recurse is true then searches sub-directories for matching
- file names.
- Returns the total number of matches found.
- May throw an exception derived from `std::runtime_error` if file io fails.]]
- [[`unsigned int GrepFiles(GrepFileCallback cb, const std::string& files, bool recurse = false, boost::match_flag_type flags = match_default);`]
- [Finds all matches of the current expression in the files /files/ using the
- [match_flag_type] /flags/. For each match calls the call-back function cb.
- If the call-back returns false then the algorithm returns without
- considering further matches in the current file, or any further files.
- The parameter /files/ can include wild card characters '\*' and '\?', if
- the parameter recurse is true then searches sub-directories for
- matching file names.
- Returns the total number of matches found.
- May throw an exception derived from `std::runtime_error` if file io fails.]]
-
- [[`unsigned int FindFiles(FindFilesCallback cb, const char* files, bool recurse = false, boost::match_flag_type flags = match_default);`]
- [Searches files to find all those which contain at least one match of
- the current expression using the [match_flag_type] /flags/. For each
- matching file calls the call-back function cb.
- If the call-back returns false then the algorithm returns without
- considering any further files.
- The parameter /files/ can include wild card characters '\*' and '\?', if
- the parameter /recurse/ is true then searches sub-directories for
- matching file names.
- Returns the total number of files found.
- May throw an exception derived from `std::runtime_error` if file io fails.]]
- [[`unsigned int FindFiles(FindFilesCallback cb, const std::string& files, bool recurse = false, boost::match_flag_type flags = match_default);`]
- [Searches files to find all those which contain at least one
- match of the current expression using the [match_flag_type] /flags/.
- For each matching file calls the call-back function cb.
- If the call-back returns false then the algorithm returns without
- considering any further files.
- The parameter /files/ can include wild card characters '\*' and '\?', if
- the parameter /recurse/ is true then searches sub-directories for
- matching file names.
- Returns the total number of files found.
- May throw an exception derived from `std::runtime_error` if file io fails.]]
-
- [[`std::string Merge(const std::string& in, const std::string& fmt, bool copy = true, boost::match_flag_type flags = match_default);`]
- [Performs a search and replace operation: searches through the
- string /in/ for all occurrences of the current expression, for each
- occurrence replaces the match with the format string /fmt/. Uses /flags/
- to determine what gets matched, and how the format string should be
- treated. If /copy/ is true then all unmatched sections of input are
- copied unchanged to output, if the flag /format_first_only/ is set then
- only the first occurrence of the pattern found is replaced.
- Returns the new string. See also
- [link boost_regex.format format string syntax], and [match_flag_type].]]
- [[`std::string Merge(const char* in, const char* fmt, bool copy = true, boost::match_flag_type flags = match_default);`]
- [Performs a search and replace operation: searches through the string /in/
- for all occurrences of the current expression, for each occurrence
- replaces the match with the format string /fmt/. Uses /flags/ to determine
- what gets matched, and how the format string should be treated.
- If /copy/ is true then all unmatched sections of input are copied
- unchanged to output, if the flag /format_first_only/ is set then only
- the first occurrence of the pattern found is replaced. Returns
- the new string. See also [link boost_regex.format format string syntax], and [match_flag_type].]]
- [[`unsigned Split(std::vector<std::string>& v, std::string& s, boost::match_flag_type flags = match_default, unsigned max_count = ~0);`]
- [Splits the input string and pushes each one onto the vector.
- If the expression contains no marked sub-expressions, then one
- string is outputted for each section of the input that does not
- match the expression. If the expression does contain marked
- sub-expressions, then outputs one string for each marked
- sub-expression each time a match occurs. Outputs no more than
- /max_count/ strings. Before returning, deletes from the input string
- /s/ all of the input that has been processed (all of the string if
- /max_count/ was not reached). Returns the number of strings pushed
- onto the vector. ]]
- [[`unsigned int Position(int i = 0)const;`]
- [Returns the position of what matched sub-expression /i/. If `i = 0`
- then returns the position of the whole match. Returns `RegEx::npos` if
- the supplied index is invalid, or if the specified sub-expression
- did not participate in the match. ]]
- [[`unsigned int Length(int i = 0)const;`]
- [Returns the length of what matched sub-expression i. If `i = 0` then
- returns the length of the whole match. Returns `RegEx::npos` if the
- supplied index is invalid, or if the specified sub-expression did not
- participate in the match. ]]
- [[`bool Matched(int i = 0)const;`]
- [Returns true if sub-expression /i/ was matched, false otherwise. ]]
- [[`unsigned int Line()const;`][Returns the line on which the match occurred,
- indexes start from 1 not zero, if no match occurred then returns `RegEx::npos`. ]]
- [[`unsigned int Marks() const;`][Returns the number of marked sub-expressions
- contained in the expression. Note that this includes the whole
- match (sub-expression zero), so the value returned is always >= 1. ]]
- [[`std::string What(int i)const;`]
- [Returns a copy of what matched sub-expression /i/. If `i = 0` then
- returns a copy of the whole match. Returns a null string if the
- index is invalid or if the specified sub-expression did not
- participate in a match. ]]
- [[`std::string operator[](int i)const ;`][Returns `what(i);`
- Can be used to simplify access to sub-expression matches, and make
- usage more perl-like.]]
- ]
- [endsect]
|