The class bad_expression defines the type of objects thrown as
- exceptions to report errors during the conversion from a string representing a
- regular expression to a finite state machine.
Footnotes: the class bad_pattern forms the base class for all
- pattern-matching exceptions, of which bad_expression is one. The choice
- of std::runtime_error as the base class for bad_pattern is moot;
- depending upon how the library is used exceptions may be either logic errors
- (programmer supplied expressions) or run time errors (user supplied
- expressions).
The template class basic_regex encapsulates regular expression parsing
- and compilation. The class takes three template parameters:
-
charT: determines the character type, i.e. either char or
- wchar_t.
-
traits: determines the behavior of the character type, for
- example which character class names are recognized. A default traits class is
- provided: regex_traits<charT>.
-
Allocator: the allocator class used to allocate memory by the
- class.
-
For ease of use there are two typedefs that define the two standard basic_regex
- instances, unless you want to use custom traits classes or allocators, you
- won't need to use anything other than these:
The definition of basic_regex follows: it is based very closely on class
- basic_string, and fulfils the requirements for a constant-container of charT.
The static constant members are provided as synonyms for the constants declared
- in namespace boost::regex_constants; for each constant of type
- syntax_option_type declared in namespace boost::regex_constants
- then a constant with the same name, type and value is declared within the scope
- of basic_regex.
-
basic_regex constructors
-
In all basic_regex constructors, a copy of the Allocator
- argument is used for any memory allocation performed by the constructor or
- member functions during the lifetime of the object.
-
-basic_regex(const Allocator& a = Allocator());
-
-
Effects: Constructs an object of class basic_regex. The
- postconditions of this function are indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
true
-
-
-
-
-
size()
-
-
-
0
-
-
-
-
-
str()
-
-
-
basic_string<charT>()
-
-
-
-
-
-
-
basic_regex(const charT* p, flag_type f = regex_constants::normal, const Allocator& a = Allocator());
-
-
-
Requires:p shall not be a null pointer.
-
Throws:bad_expression if p is not a valid regular
- expression.
-
Effects: Constructs an object of class basic_regex; the
- object's internal finite state machine is constructed from the regular
- expression contained in the null-terminated string p, and interpreted
- according to the option flags specified
- in f. The postconditions of this function are indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
false
-
-
-
-
-
size()
-
-
-
char_traits<charT>::length(p)
-
-
-
-
-
str()
-
-
-
basic_string<charT>(p)
-
-
-
-
-
flags()
-
-
-
f
-
-
-
-
-
mark_count()
-
-
-
The number of marked sub-expressions within the expression.
-
-
-
-
-
-
-
-
-
-
basic_regex(const charT* p1, const charT* p2, flag_type f = regex_constants::normal, const Allocator& a = Allocator());
-
Requires:p1 and p2 are not null pointers, p1 < p2.
-
Throws:bad_expression if [p1,p2) is not a valid regular
- expression.
-
Effects: Constructs an object of class basic_regex; the
- object's internal finite state machine is constructed from the regular
- expression contained in the sequence of characters [p1,p2), and interpreted
- according the option flags specified in f.
- The postconditions of this function are indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
false
-
-
-
-
-
size()
-
-
-
std::distance(p1,p2)
-
-
-
-
-
str()
-
-
-
basic_string<charT>(p1,p2)
-
-
-
-
-
flags()
-
-
-
f
-
-
-
-
-
mark_count()
-
-
-
The number of marked sub-expressions within the expression.
Requires:p shall not be a null pointer, len < max_size().
-
Throws:bad_expression if p is not a valid regular
- expression.
-
Effects: Constructs an object of class basic_regex; the
- object's internal finite state machine is constructed from the regular
- expression contained in the sequence of characters [p, p+len), and interpreted
- according the option flags specified in f.
- The postconditions of this function are indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
false
-
-
-
-
-
size()
-
-
-
len
-
-
-
-
-
str()
-
-
-
basic_string<charT>(p, len)
-
-
-
-
-
flags()
-
-
-
f
-
-
-
-
-
mark_count()
-
-
-
The number of marked sub-expressions within the expression.
-
-
-
-
-
-
-
-
-
-
-basic_regex(const basic_regex& e);
-
-
Effects: Constructs an object of class basic_regex as a
- copy of the object e. The postconditions of this function are indicated
- in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
e.empty()
-
-
-
-
-
size()
-
-
-
e.size()
-
-
-
-
-
str()
-
-
-
e.str()
-
-
-
-
-
flags()
-
-
-
e.flags()
-
-
-
-
-
mark_count()
-
-
-
e.mark_count()
-
-
-
-
-
-
-
-
-
-
-template <class ST, class SA>
-
-basic_regex(const basic_string<charT, ST, SA>& s,
- flag_type f = regex_constants::normal, const Allocator& a = Allocator());
-
-
Throws:bad_expression if s is not a valid regular
- expression.
-
Effects: Constructs an object of class basic_regex; the
- object's internal finite state machine is constructed from the regular
- expression contained in the string s, and interpreted according to the
- option flags specified in f. The postconditions of this function
- are indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
false
-
-
-
-
-
size()
-
-
-
s.size()
-
-
-
-
-
str()
-
-
-
s
-
-
-
-
-
flags()
-
-
-
f
-
-
-
-
-
mark_count()
-
-
-
The number of marked sub-expressions within the expression.
-
-
-
-
-
-
-
-
-
-
-template <class ForwardIterator>
-
-basic_regex(ForwardIterator first, ForwardIterator last,
- flag_type f = regex_constants::normal, const Allocator& a = Allocator());
-
-
Throws:bad_expression if the sequence [first, last)
- is not a valid regular expression.
-
Effects: Constructs an object of class basic_regex; the
- object's internal finite state machine is constructed from the regular
- expression contained in the sequence of characters [first, last), and
- interpreted according to the option flags
- specified in f. The postconditions of this function are indicated in the
- table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
false
-
-
-
-
-
size()
-
-
-
distance(first,last)
-
-
-
-
-
str()
-
-
-
basic_string<charT>(first,last)
-
-
-
-
-
flags()
-
-
-
f
-
-
-
-
-
mark_count()
-
-
-
The number of marked sub-expressions within the expression.
-
-
-
-
-
-
-
-
-
-
-basic_regex& operator=(const basic_regex& e);
-
-
Effects: Returns the result of assign(e.str(), e.flags()).
template <class string_traits, class A>
-basic_regex& assign(const basic_string<charT, string_traits, A>& s,
- flag_type f = regex_constants::normal);
-
-
Throws:bad_expression if s is not a valid regular
- expression.
-
Returns:*this.
-
Effects: Assigns the regular expression contained in the string s,
- interpreted according the option flags specified
- in f. The postconditions of this function are indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
false
-
-
-
-
-
size()
-
-
-
s.size()
-
-
-
-
-
str()
-
-
-
s
-
-
-
-
-
flags()
-
-
-
f
-
-
-
-
-
mark_count()
-
-
-
The number of marked sub-expressions within the expression.
-
-
-
-
-
-
-
-
-
-
template <class InputIterator>
-basic_regex& assign(InputIterator first, InputIterator last,
- flag_type f = regex_constants::normal);
-
-
Requires: The type InputIterator corresponds to the Input Iterator
- requirements (24.1.1).
Effects: Returns a copy of the Allocator that was passed to the object's
- constructor.
-
flag_type flags() const;
-
-
Effects: Returns a copy of the regular expression syntax flags that were
- passed to the object's constructor, or the last call to assign.
-
basic_string<charT> str() const;
-
-
Effects: Returns a copy of the character sequence passed to the object's
- constructor, or the last call to assign.
-
int compare(basic_regex& e)const;
-
-
Effects: If flags() == e.flags() then returns str().compare(e.str()),
- otherwise returns flags() - e.flags().
-
basic_regex locale
-
locale_type imbue(locale_type l);
-
-
Effects: Returns the result of traits_inst.imbue(l) where
- traits_inst is a (default initialized) instance of the template
- parameter traits stored within the object. Calls to imbue
- invalidate any currently contained regular expression.
-
Postcondition:empty() == true.
-
-locale_type getloc() const;
-
-
Effects: Returns the result of traits_inst.getloc() where
- traits_inst is a (default initialized) instance of the template
- parameter traits stored within the object.
-
basic_regex swap
-
-void swap(basic_regex& e) throw();
-
-
Effects: Swaps the contents of the two regular expressions.
-
Postcondition:*this contains the characters that were in e,
- e contains the regular expression that was in *this.
-
Complexity: constant time.
-
basic_regex non-member functions
-
basic_regex non-member comparison operators
-
Comparisons between basic_regex objects are provided on an experimental basis:
- please note that these are likely to be removed from the standard library
- proposal, so use with care if you are writing portable code.
Captures are the iterator ranges that are "captured" by marked sub-expressions
- as a regular expression gets matched. Each marked sub-expression can
- result in more than one capture, if it is matched more than once. This
- document explains how captures and marked sub-expressions in Boost.Regex are
- represented and accessed.
-
Marked sub-expressions
-
Every time a Perl regular expression contains a parenthesis group (), it spits
- out an extra field, known as a marked sub-expression, for example the
- expression:
-
(\w+)\W+(\w+)
-
- Has two marked sub-expressions (known as $1 and $2 respectively), in addition
- the complete match is known as $&, everything before the first match as $`,
- and everything after the match as $'. So if the above expression is
- searched for within "@abc def--", then we obtain:
The Perl and Boost.Regex equivalents are as follows:
-
-
-
-
-
Perl
-
Boost.Regex
-
-
-
$`
-
m.prefix()
-
-
-
$&
-
m[0]
-
-
-
$n
-
m[n]
-
-
-
$'
-
m.suffix()
-
-
-
-
-
-
In Boost.Regex each sub-expression match is represented by a
- sub_match object, this is basically just a pair of iterators denoting
- the start and end possition of the sub-expression match, but there are some
- additional operators provided so that objects of type sub_match behave a lot
- like a std::basic_string: for example they are implicitly
- convertible to a basic_string, they can be compared
- to a string, added to a string, or
- streamed out to an output stream.
-
Unmatched Sub-Expressions
-
When a regular expression match is found there is no need for all of the marked
- sub-expressions to have participated in the match, for example the expression:
-
(abc)|(def)
-
can match either $1 or $2, but never both at the same time. In
- Boost.Regex you can determine which sub-expressions matched by accessing the
- sub_match::matched data member.
-
Repeated Captures
-
When a marked sub-expression is repeated, then the sub-expression gets
- "captured" multiple times, however normally only the final capture is
- available, for example if
-
(?:(\w+)\W+)+
-
is matched against
-
one fine day
-
Then $1 will contain the string "day", and all the previous captures will have
- been forgotten.
-
However, Boost.Regex has an experimental feature that allows all the capture
- information to be retained - this is accessed either via the
- match_results::captures member function or the sub_match::captures
- member function. These functions return a container that contains a
- sequence of all the captures obtained during the regular expression
- matching. The following example program shows how this information may be
- used:
-
#include <boost/regex.hpp>
-#include <iostream>
-
-
-void print_captures(const std::string& regx, const std::string& text)
-{
- boost::regex e(regx);
- boost::smatch what;
- std::cout << "Expression: \"" << regx << "\"\n";
- std::cout << "Text: \"" << text << "\"\n";
- if(boost::regex_match(text, what, e, boost::match_extra))
- {
- unsigned i, j;
- std::cout << "** Match found **\n Sub-Expressions:\n";
- for(i = 0; i < what.size(); ++i)
- std::cout << " $" << i << " = \"" << what[i] << "\"\n";
- std::cout << " Captures:\n";
- for(i = 0; i < what.size(); ++i)
- {
- std::cout << " $" << i << " = {";
- for(j = 0; j < what.captures(i).size(); ++j)
- {
- if(j)
- std::cout << ", ";
- else
- std::cout << " ";
- std::cout << "\"" << what.captures(i)[j] << "\"";
- }
- std::cout << " }\n";
- }
- }
- else
- {
- std::cout << "** No Match found **\n";
- }
-}
-
-int main(int , char* [])
-{
- print_captures("(([[:lower:]]+)|([[:upper:]]+))+", "aBBcccDDDDDeeeeeeee");
- print_captures("(.*)bar|(.*)bah", "abcbar");
- print_captures("(.*)bar|(.*)bah", "abcbah");
- print_captures("^(?:(\\w+)|(?>\\W+))*$", "now is the time for all good men to come to the aid of the party");
- return 0;
-}
-
Which produces the following output:
-
Expression: "(([[:lower:]]+)|([[:upper:]]+))+"
-Text: "aBBcccDDDDDeeeeeeee"
-** Match found **
- Sub-Expressions:
- $0 = "aBBcccDDDDDeeeeeeee"
- $1 = "eeeeeeee"
- $2 = "eeeeeeee"
- $3 = "DDDDD"
- Captures:
- $0 = { "aBBcccDDDDDeeeeeeee" }
- $1 = { "a", "BB", "ccc", "DDDDD", "eeeeeeee" }
- $2 = { "a", "ccc", "eeeeeeee" }
- $3 = { "BB", "DDDDD" }
-Expression: "(.*)bar|(.*)bah"
-Text: "abcbar"
-** Match found **
- Sub-Expressions:
- $0 = "abcbar"
- $1 = "abc"
- $2 = ""
- Captures:
- $0 = { "abcbar" }
- $1 = { "abc" }
- $2 = { }
-Expression: "(.*)bar|(.*)bah"
-Text: "abcbah"
-** Match found **
- Sub-Expressions:
- $0 = "abcbah"
- $1 = ""
- $2 = "abc"
- Captures:
- $0 = { "abcbah" }
- $1 = { }
- $2 = { "abc" }
-Expression: "^(?:(\w+)|(?>\W+))*$"
-Text: "now is the time for all good men to come to the aid of the party"
-** Match found **
- Sub-Expressions:
- $0 = "now is the time for all good men to come to the aid of the party"
- $1 = "party"
- Captures:
- $0 = { "now is the time for all good men to come to the aid of the party" }
- $1 = { "now", "is", "the", "time", "for", "all", "good", "men", "to", "come", "to", "the", "aid", "of", "the", "party" }
-
-
Unfortunately enabling this feature has an impact on performance (even if you
- don't use it), and a much bigger impact if you do use it, therefore to use this
- feature you need to:
-
-
- Define BOOST_REGEX_MATCH_EXTRA for all translation units including the library
- source (the best way to do this is to uncomment this define in
- boost/regex/user.hpp
- and then rebuild everything.
-
You shouldn't need to do anything special to configure
-boost.regex for use with your compiler - the boost.config subsystem should already
-take care of it, if you do have problems (or you are using a
-particularly obscure compiler or platform) then boost.config has a configure script.
-
-
Locale and traits class selection.
-
-
The following macros (see user.hpp) control how
-boost.regex interacts with the user's locale:
-
-
-
-
BOOST_REGEX_USE_C_LOCALE
-
Forces boost.regex to use the global C locale in its traits
-class support: this is the default behavior on non-windows
-platforms, but MS Windows platforms normally use the Win32 API for
-locale support.
-
-
-
-
BOOST_REGEX_USE_CPP_LOCALE
-
Forces boost.regex to use std::locale in it's default traits
-class, regular expressions can then be imbued with an
-instance specific locale.
-
-
-
-
BOOST_REGEX_NO_W32
-
Tells boost.regex not to use any Win32 API's even when
-available (implies BOOST_REGEX_USE_C_LOCALE unless
-BOOST_REGEX_USE_CPP_LOCALE is set).
-
-
-
-
-
-
-
-
Linkage Options
-
-
-
-
BOOST_REGEX_DYN_LINK
-
For Microsoft and Borland C++ builds, this tells boost.regex
-that it should link to the dll build of the boost.regex. By
-default boost.regex will link to its static library build, even if
-the dynamic C runtime library is in use.
-
-
-
-
BOOST_REGEX_NO_LIB
-
For Microsoft and Borland C++ builds, this tells boost.regex
-that it should not automatically select the library to link
-to.
-
-
-
-
-
-
-
-
Algorithm Selection
-
-
-
-
BOOST_REGEX_V3
-
Tells boost.regex to use the boost-1.30.0 matching algorithm,
-define only if you need maximum compatibility with previous
-behavior.
-
-
-
-
BOOST_REGEX_RECURSIVE
-
Tells boost.regex to use a stack-recursive matching
-algorithm. This is generally the fastest option (although
-there is very little in it), but can cause stack overflow in
-extreme cases, on Win32 this can be handled safely, but this is not
-the case on other platforms.
-
-
-
-
BOOST_REGEX_NON_RECURSIVE
-
Tells boost.regex to use a non-stack recursive matching
-algorithm, this can be slightly slower than the alternative, but is
-always safe no matter how pathological the regular
-expression. This is the default on non-Win32 platforms.
-
-
-
-
-
-
-
-
Algorithm Tuning
-
-
The following option applies only if BOOST_REGEX_RECURSIVE is
-set.
-
-
-
-
BOOST_REGEX_HAS_MS_STACK_GUARD
-
Tells boost.regex that Microsoft style __try - __except blocks
-are supported, and can be used to safely trap stack overflow.
-
-
-
-
-
-
-
-
The following options apply only if BOOST_REGEX_NON_RECURSIVE is
-set.
-
-
-
-
BOOST_REGEX_BLOCKSIZE
-
In non-recursive mode, boost.regex uses largish blocks of
-memory to act as a stack for the state machine, the larger the
-block size then the fewer allocations that will take place.
-This defaults to 4096 bytes, which is large enough to match the
-vast majority of regular expressions without further
-allocations, however, you can choose smaller or larger values
-depending upon your platforms characteristics.
-
-
-
-
BOOST_REGEX_MAX_BLOCKS
-
Tells boost.regex how many blocks of size BOOST_REGEX_BLOCKSIZE
-it is permitted to use. If this value is exceeded then
-boost.regex will stop trying to find a match and throw a
-std::runtime_error. Defaults to 1024, don't forget to tweek
-this value if you alter BOOST_REGEX_BLOCKSIZE by much.
-
-
-
-
BOOST_REGEX_MAX_CACHE_BLOCKS
-
Tells boost.regex how many memory blocks to store in it's
-internal cache - memory blocks are taken from this cache rather
-than by calling ::operator new. Generally speeking this can
-be an order of magnitude faster than calling ::opertator new each
-time a memory block is required, but has the downside that
-boost.regex can end up caching a large chunk of memory (by default
-up to 16 blocks each of BOOST_REGEX_BLOCKSIZE size). If
-memory is tight then try defining this to 0 (disables all caching),
-or if that is too slow, then a value of 1 or 2, may be
-sufficient. On the other hand, on large multi-processor,
-multi-threaded systems, you may find that a higher value is in
-order.
The author can be contacted at john@johnmaddock.co.uk; the home page for
- this library is at www.boost.org.
-
I am indebted to Robert Sedgewick's
- "Algorithms in C++" for forcing me to think about algorithms and their
- performance, and to the folks at boost for
- forcing me to think, period.
Pete Becker, of Dinkumware Ltd, has
- helped enormously with the standardisation proposal language.
-
The following people have all contributed useful comments or fixes: Dave
- Abrahams, Mike Allison, Edan Ayal, Jayashree Balasubramanian, Jan Bölsche,
- Beman Dawes, Paul Baxter, David Bergman, David Dennerline, Edward Diener, Peter
- Dimov, Robert Dunn, Fabio Forno, Tobias Gabrielsson, Rob Gillen, Marc Gregoire,
- Chris Hecker, Nick Hodapp, Jesse Jones, Martin Jost, Boris Krasnovskiy, Jan
- Hermelink, Max Leung, Wei-hao Lin, Jens Maurer, Richard Peters, Heiko Schmidt,
- Jason Shirk, Gerald Slacik, Scobie Smith, Mike Smyth, Alexander Sokolovsky,
- Hervé Poirier, Michael Raykh, Marc Recht, Scott VanCamp, Bruno Voigt, Alexey
- Voinov, Jerry Waldorf, Rob Ward, Lealon Watts, John Wismar, Thomas Witt and
- Yuval Yosef. I am also grateful to the manuals supplied with the Henry Spencer,
- Perl and GNU regular expression libraries - wherever possible I have tried to
- maintain compatibility with these libraries and with the POSIX standard - the
- code however is entirely my own, including any bugs! I can absolutely guarantee
- that I will not fix any bugs I don't know about, so if you have any comments or
- spot any bugs, please get in touch.
-
Useful further information can be found at:
-
Short tutorials on regular expressions can be
- found here and here.
There are three demo applications that ship with this library, they all come
- with makefiles for Borland, Microsoft and gcc compilers, otherwise you will
- have to create your own makefiles.
-
regress.exe:
-
A regression test application that gives the matching/searching algorithms a
- full workout. The presence of this program is your guarantee that the library
- will behave as claimed - at least as far as those items tested are concerned -
- if anyone spots anything that isn't being tested I'd be glad to hear about it.
A simple grep implementation, run with no command line options to find out its
- usage. Look at fileiter.cpp/fileiter.hpp and
- the mapfile class to see an example of a "smart" bidirectional iterator that
- can be used with boost.regex or any other STL algorithm.
A simple interactive expression matching application, the results of all
- matches are timed, allowing the programmer to optimize their regular
- expressions where performance is critical.
Q. Why can't I
- use the "convenience" versions of regex_match / regex_search / regex_grep /
- regex_format / regex_merge?
-
A. These versions may or may not be available depending upon the capabilities
- of your compiler, the rules determining the format of these functions are quite
- complex - and only the versions visible to a standard compliant compiler are
- given in the help. To find out what your compiler supports, run
- <boost/regex.hpp> through your C++ pre-processor, and search the output
- file for the function that you are interested in.
-
Q. I can't get regex++ to work with
- escape characters, what's going on?
-
A. If you embed regular expressions in C++ code, then remember that escape
- characters are processed twice: once by the C++ compiler, and once by the
- regex++ expression compiler, so to pass the regular expression \d+ to regex++,
- you need to embed "\\d+" in your code. Likewise to match a literal backslash
- you will need to embed "\\\\" in your code.
-
-
Q. Why does using parenthesis in a POSIX regular expression
- change the result of a match?
-
For POSIX (extended and basic) regular expressions, but not for perl regexes,
- parentheses don't only mark; they determine what the best match is as well.
- When the expression is compiled as a POSIX basic or extended regex then
- Boost.regex follows the POSIX standard leftmost longest rule for determining
- what matched. So if there is more than one possible match after considering the
- whole expression, it looks next at the first sub-expression and then the second
- sub-expression and so on. So...
-
-"(0*)([0-9]*)" against "00123" would produce
-$1 = "00"
-$2 = "123"
-
-
where as
-
-"0*([0-9])*" against "00123" would produce
-$1 = "00123"
-
-
If you think about it, had $1 only matched the "123", this would be "less good"
- than the match "00123" which is both further to the left and longer. If you
- want $1 to match only the "123" part, then you need to use something like:
-
-"0*([1-9][0-9]*)"
-
-
as the expression.
-
Q. Why don't character ranges work properly (POSIX mode
- only)?
- A. The POSIX standard specifies that character range expressions are locale
- sensitive - so for example the expression [A-Z] will match any collating
- element that collates between 'A' and 'Z'. That means that for most locales
- other than "C" or "POSIX", [A-Z] would match the single character 't' for
- example, which is not what most people expect - or at least not what most
- people have come to expect from regular expression engines. For this reason,
- the default behaviour of boost.regex (perl mode) is to turn locale sensitive
- collation off by not setting the regex_constants::collate compile time flag.
- However if you set a non-default compile time flag - for example
- regex_constants::extended or regex_constants::basic, then locale dependent
- collation will be enabled, this also applies to the POSIX API functions which
- use either regex_constants::extended or regex_constants::basic internally. [Note
- - when regex_constants::nocollate in effect, the library behaves "as if" the
- LC_COLLATE locale category were always "C", regardless of what its actually set
- to - end note].
-
Q. Why are there no throw specifications on any of the
- functions? What exceptions can the library throw?
-
A. Not all compilers support (or honor) throw specifications, others support
- them but with reduced efficiency. Throw specifications may be added at a later
- date as compilers begin to handle this better. The library should throw only
- three types of exception: boost::bad_expression can be thrown by basic_regex
- when compiling a regular expression, std::runtime_error can be thrown when a
- call to basic_regex::imbue tries to open a message catalogue that doesn't
- exist, or when a call to regex_search or regex_match results in an
- "everlasting" search, or when a call to RegEx::GrepFiles or
- RegEx::FindFiles tries to open a file that cannot be opened, finally
- std::bad_alloc can be thrown by just about any of the functions in this
- library.
Format strings are used by the algorithm regex_replace and by match_results::format, and are used
-to transform one string into another.
-
-
There are three kind of format string: sed, Perl and extended,
-the extended syntax is a superset of the others so this is covered
-first.
-
-
Extended format syntax
-
-
In format strings, all characters are treated as literals
-except: ()$\?:
-
-
To use any of these as literals you must prefix them with the
-escape character \
-
-
The following special sequences are recognized:
-
- Grouping:
-
-
Use the parenthesis characters ( and ) to group sub-expressions
-within the format string, use \( and \) to represent literal '('
-and ')'.
-
- Sub-expression expansions:
-
-
The following Perl like expressions expand to a particular
-matched sub-expression:
-
-
-
-
-
-
-
-
$`
-
Expands to all the text from the end
-of the previous match to the start of the current match, if there
-was no previous match in the current operation, then everything
-from the start of the input string to the start of the match.
-
-
-
-
-
-
$'
-
Expands to all the text from the end
-of the match to the end of the input string.
-
-
-
-
-
-
$&
-
Expands to all of the current
-match.
-
-
-
-
-
-
$0
-
Expands to all of the current
-match.
-
-
-
-
-
-
$N
-
Expands to the text that matched
-sub-expression N.
-
-
-
-
-
-
-
-
-
Conditional expressions:
-
-
Conditional expressions allow two different format strings to be
-selected dependent upon whether a sub-expression participated in
-the match or not:
-
-
?Ntrue_expression:false_expression
-
-
Executes true_expression if sub-expression N participated
-in the match, otherwise executes false_expression.
-
-
Example: suppose we search for "(while)|(for)" then the format
-string "?1WHILE:FOR" would output what matched, but in upper
-case.
-
- Escape sequences:
-
-
The following escape sequences are also allowed:
-
-
-
-
-
-
-
-
\a
-
The bell character.
-
-
-
-
-
-
\f
-
The form feed character.
-
-
-
-
-
-
\n
-
The newline character.
-
-
-
-
-
-
\r
-
The carriage return character.
-
-
-
-
-
-
\t
-
The tab character.
-
-
-
-
-
-
\v
-
A vertical tab character.
-
-
-
-
-
-
\x
-
A hexadecimal character - for example
-\x0D.
-
-
-
-
-
-
\x{}
-
A possible Unicode hexadecimal
-character - for example \x{1A0}
-
-
-
-
-
-
\cx
-
The ASCII escape character x, for
-example \c@ is equivalent to escape-@.
-
-
-
-
-
-
\e
-
The ASCII escape character.
-
-
-
-
-
-
\dd
-
An octal character constant, for
-example \10.
-
-
-
-
-
-
-
-
-
Perl format strings
-
-
Perl format strings are the same as the default syntax except
-that the characters ()?: have no special meaning.
-
-
Sed format strings
-
-
Sed format strings use only the characters \ and & as
-special characters.
-
-
\n where n is a digit, is expanded to the nth
-sub-expression.
-
-
& is expanded to the whole of the match (equivalent to
-\0).
-
-
Other escape sequences are expanded as per the default
-syntax.
There are two main headers used by this library: <boost/regex.hpp>
- provides full access to the entire library, while <boost/cregex.hpp>
- provides access to just the high level class RegEx, and the POSIX API
- functions.
-
-
There is also a header containing only forward declarations
- <boost/regex_fwd.hpp> for use when an interface is dependent upon
- boost::basic_regex, but otherwise does not need the full definitions.
- Added support for Perl style independent sub-expressions.
-
- Added non-member operators to the sub_match class,
- so that you can compare sub_match's with strings, or add them to a string to
- produce a new string.
-
- Changed the match flags so that they are a distinct type (not an integer), if
- you try to pass the match flags as an integer rather than
- match_flag_type to the regex algorithms then you will now get a compiler
- error.
When you extract the library from its zip file, you must preserve its internal
- directory structure (for example by using the -d option when extracting). If
- you didn't do that when extracting, then you'd better stop reading this, delete
- the files you just extracted, and try again!
-
-
This library should not need configuring before use; most popular
- compilers/standard libraries/platforms are already supported "as is". If you do
- experience configuration problems, or just want to test the configuration with
- your compiler, then the process is the same as for all of boost; see the
- configuration library documentation.
-
The library will encase all code inside namespace boost.
-
-
Unlike some other template libraries, this library consists of a mixture of
- template code (in the headers) and static code and data (in cpp files).
- Consequently it is necessary to build the library's support code into a library
- or archive file before you can use it, instructions for specific platforms are
- as follows:
-
-
Borland C++ Builder:
-
-
-
- Open up a console window and change to the <boost>\libs\regex\build
- directory.
-
- Select the appropriate makefile (bcb4.mak for C++ Builder 4, bcb5.mak for C++
- Builder 5, and bcb6.mak for C++ Builder 6).
-
- Invoke the makefile (pass the full path to your version of make if you have
- more than one version installed, the makefile relies on the path to make to
- obtain your C++ Builder installation directory and tools) for example:
-
-
-
make -fbcb5.mak
-
The build process will build a variety of .lib and .dll files (the exact number
- depends upon the version of Borland's tools you are using) the .lib and dll
- files will be in a sub-directory called bcb4 or bcb5 depending upon the
- makefile used. To install the libraries into your development system use:
-
make -fbcb5.mak install
-
library files will be copied to <BCROOT>/lib and the dll's to
- <BCROOT>/bin, where <BCROOT> corresponds to the install path of
- your Borland C++ tools.
-
-
You may also remove temporary files created during the build process (excluding
- lib and dll files) by using:
-
make -fbcb5.mak clean
-
Finally when you use regex++ it is only necessary for you to add the
- <boost> root director to your list of include directories for that
- project. It is not necessary for you to manually add a .lib file to the
- project; the headers will automatically select the correct .lib file for your
- build mode and tell the linker to include it. There is one caveat however: the
- library can not tell the difference between VCL and non-VCL enabled builds when
- building a GUI application from the command line, if you build from the command
- line with the 5.5 command line tools then you must define the pre-processor
- symbol _NO_VCL in order to ensure that the correct link libraries are selected:
- the C++ Builder IDE normally sets this automatically. Hint, users of the 5.5
- command line tools may want to add a -D_NO_VCL to bcc32.cfg in order to set
- this option permanently.
-
-
If you would prefer to do a dynamic link to the regex libraries when using the
- dll runtime then define BOOST_REGEX_DYN_LINK (you must do this if you want to
- use boost.regex in multiple dll's), otherwise Boost.regex will be staically
- linked by default.
-
If you want to suppress automatic linking altogether (and supply your own
- custom build of the lib) then define BOOST_REGEX_NO_LIB.
-
If you are building with C++ Builder 6, you will find that
- <boost/regex.hpp> can not be used in a pre-compiled header (the actual
- problem is in <locale> which gets included by <boost/regex.hpp>),
- if this causes problems for you, then try defining BOOST_NO_STD_LOCALE when
- building, this will disable some features throughout boost, but may save you a
- lot in compile times!
-
Microsoft Visual C++ 6 and 7
-
You need version 6 of MSVC to build this library. If you are using VC5 then you
- may want to look at one of the previous releases of this
- library
-
-
Open up a command prompt, which has the necessary MSVC environment variables
- defined (for example by using the batch file Vcvars32.bat installed by the
- Visual Studio installation), and change to the <boost>\libs\regex\build
- directory.
-
-
Select the correct makefile - vc6.mak for "vanilla" Visual C++ 6 or
- vc6-stlport.mak if you are using STLPort.
-
Invoke the makefile like this:
-
nmake -fvc6.mak
-
You will now have a collection of lib and dll files in a "vc6" subdirectory, to
- install these into your development system use:
-
nmake -fvc6.mak install
-
The lib files will be copied to your <VC6>\lib directory and the dll
- files to <VC6>\bin, where <VC6> is the root of your Visual C++ 6
- installation.
-
You can delete all the temporary files created during the build (excluding lib
- and dll files) using:
-
nmake -fvc6.mak clean
-
Finally when you use regex++ it is only necessary for you to add the
- <boost> root directory to your list of include directories for that
- project. It is not necessary for you to manually add a .lib file to the
- project; the headers will automatically select the correct .lib file for your
- build mode and tell the linker to include it.
-
-
- Note that if you want to dynamically link to the regex library when using the
- dynamic C++ runtime, define BOOST_REGEX_DYN_LINK when building your project.
-
If you want to add the source directly to your project then define
- BOOST_REGEX_NO_LIB to disable automatic library selection.
-
There are several important caveats to remember when using boost.regex with
- Microsoft's Compiler:
-
-
- There have been some reports of compiler-optimization bugs affecting this
- library, (particularly with VC6 versions prior to service patch 5) the
- workaround is to build the library using /Oityb1 rather than /O2. That is to
- use all optimization settings except /Oa. This problem is reported to affect
- some standard library code as well (in fact I'm not sure if the problem is with
- the regex code or the underlying standard library), so it's probably worthwhile
- applying this workaround in normal practice in any case.
-
- If you have replaced the C++ standard library that comes with VC6, then when
- you build the library you must ensure that the environment variables "INCLUDE"
- and "LIB" have been updated to reflect the include and library paths for the
- new library - see vcvars32.bat (part of your Visual Studio installation) for
- more details.
-
-
- If you are building with the full STLPort v4.x, then use the vc6-stlport.mak
- file provided and set the environment variable STLPORT_PATH to point to the
- location of your STLPort installation (Note that the full STLPort libraries
- appear not to support single-thread static builds).
-
- If you are building your application with /Zc:wchar_t then you will need to
- modify the makefile to add /Zc:wchar_t before building the library.
-
-
-
GCC(2.95 and 3.x)
-
-
You can build with gcc using the normal boost Jamfile in
- <boost>/libs/regex/build, alternatively there is a conservative makefile
- for the g++ compiler. From the command prompt change to the
- <boost>/libs/regex/build directory and type:
-
-
make -fgcc.mak
-
At the end of the build process you should have a gcc sub-directory containing
- release and debug versions of the library (libboost_regex.a and
- libboost_regex_debug.a). When you build projects that use regex++, you will
- need to add the boost install directory to your list of include paths and add
- <boost>/libs/regex/build/gcc/libboost_regex.a to your list of library
- files.
-
-
There is also a makefile to build the library as a shared library:
-
make -fgcc-shared.mak
-
which will build libboost_regex.so and libboost_regex_debug.so.
-
Both of the these makefiles support the following environment variables:
-
CXXFLAGS: extra compiler options - note that this applies to both the debug and
- release builds.
There is a makefile for the sun (6.1) compiler (C++ version 3.12). From the
- command prompt change to the <boost>/libs/regex/build directory and type:
-
-
dmake -f sunpro.mak
-
At the end of the build process you should have a sunpro sub-directory
- containing single and multithread versions of the library (libboost_regex.a,
- libboost_regex.so, libboost_regex_mt.a and libboost_regex_mt.so). When you
- build projects that use regex++, you will need to add the boost install
- directory to your list of include paths and add
- <boost>/libs/regex/build/sunpro/ to your library search path.
-
-
Both of the these makefiles support the following environment variables:
-
CXXFLAGS: extra compiler options - note that this applies to both the single
- and multithreaded builds.
-
INCLUDES: additional include directories.
-
LDFLAGS: additional linker options.
-
LIBS: additional library files.
-
LIBSUFFIX: a suffix to mangle the library name with (defaults to nothing).
-
This makefile does not set any architecture specific options like -xarch=v9,
- you can set these by defining the appropriate macros, for example:
will build v9 variants of the regex library named libboost_regex_v9.a etc.
-
Other compilers:
-
-
There is a generic makefile (generic.mak
- ) provided in <boost-root>/libs/regex/build - see that makefile for
- details of environment variables that need to be set before use.
-
- Alternatively you can using the Jam based
- build system: cd into <boost>/libs/regex/build and run:
Regular expressions are a form of pattern-matching that are often used in text
- processing; many users will be familiar with the Unix utilities grep, sed
- and awk, and the programming language Perl, each of which make
- extensive use of regular expressions. Traditionally C++ users have been limited
- to the POSIX C API's for manipulating regular expressions, and while regex++
- does provide these API's, they do not represent the best way to use the
- library. For example regex++ can cope with wide character strings, or search
- and replace operations (in a manner analogous to either sed or Perl), something
- that traditional C libraries can not do.
-
The class boost::basic_regex is the key class in
- this library; it represents a "machine readable" regular expression, and is
- very closely modeled on std::basic_string, think of it as a string plus the
- actual state-machine required by the regular expression algorithms. Like
- std::basic_string there are two typedefs that are almost always the means by
- which this class is referenced:
To see how this library can be used, imagine that we are writing a credit card
- processing application. Credit card numbers generally come as a string of
- 16-digits, separated into groups of 4-digits, and separated by either a space
- or a hyphen. Before storing a credit card number in a database (not necessarily
- something your customers will appreciate!), we may want to verify that the
- number is in the correct format. To match any digit we could use the regular
- expression [0-9], however ranges of characters like this are actually locale
- dependent. Instead we should use the POSIX standard form [[:digit:]], or the
- regex++ and Perl shorthand for this \d (note that many older libraries tended
- to be hard-coded to the C-locale, consequently this was not an issue for them).
- That leaves us with the following regular expression to validate credit card
- number formats:
-
(\d{4}[- ]){3}\d{4}
-
Here the parenthesis act to group (and mark for future reference)
- sub-expressions, and the {4} means "repeat exactly 4 times". This is an example
- of the extended regular expression syntax used by Perl, awk and egrep. Regex++
- also supports the older "basic" syntax used by sed and grep, but this is
- generally less useful, unless you already have some basic regular expressions
- that you need to reuse.
-
Now let's take that expression and place it in some C++ code to validate the
- format of a credit card number:
Note how we had to add some extra escapes to the expression: remember that the
- escape is seen once by the C++ compiler, before it gets to be seen by the
- regular expression engine, consequently escapes in regular expressions have to
- be doubled up when embedding them in C/C++ code. Also note that all the
- examples assume that your compiler supports Koenig lookup, if yours doesn't
- (for example VC6), then you will have to add some boost:: prefixes to some of
- the function calls in the examples.
-
Those of you who are familiar with credit card processing, will have realized
- that while the format used above is suitable for human readable card numbers,
- it does not represent the format required by online credit card systems; these
- require the number as a string of 16 (or possibly 15) digits, without any
- intervening spaces. What we need is a means to convert easily between the two
- formats, and this is where search and replace comes in. Those who are familiar
- with the utilities sed and Perl will already be ahead here; we
- need two strings - one a regular expression - the other a "format
- string" that provides a description of the text to replace the match
- with. In regex++ this search and replace operation is performed with the
- algorithm regex_replace, for our credit card
- example we can write two algorithms like this to provide the format
- conversions:
-
// match any format with the regular expression:
-const boost::regex e("\\A(\\d{3,4})[- ]?(\\d{4})[- ]?(\\d{4})[- ]?(\\d{4})\\z");
-const std::string machine_format("\\1\\2\\3\\4");
-const std::string human_format("\\1-\\2-\\3-\\4");
-
-std::string machine_readable_card_number(const std::string s)
-{
- returnregex_replace(s, e, machine_format, boost::match_default | boost::format_sed);
-}
-
-std::string human_readable_card_number(const std::string s)
-{
- returnregex_replace(s, e, human_format, boost::match_default | boost::format_sed);
-}
-
Here we've used marked sub-expressions in the regular expression to split out
- the four parts of the card number as separate fields, the format string then
- uses the sed-like syntax to replace the matched text with the reformatted
- version.
-
In the examples above, we haven't directly manipulated the results of a regular
- expression match, however in general the result of a match contains a number of
- sub-expression matches in addition to the overall match. When the library needs
- to report a regular expression match it does so using an instance of the class
- match_results, as before there are typedefs of this class for the most
- common cases:
-
The algorithms regex_search and regex_match
- make use of match_results to report what matched; the difference between these
- algorithms is that regex_match will only find
- matches that consume all of the input text, where as
- regex_search will search for a match anywhere within the text
- being matched.
-
Note that these algorithms are not restricted to searching regular C-strings,
- any bidirectional iterator type can be searched, allowing for the possibility
- of seamlessly searching almost any kind of data.
-
-
For search and replace operations, in addition to the algorithm
- regex_replace that we have already seen, the match_results
- class has a format member that takes the result of a match and a format string,
- and produces a new string by merging the two.
-
For iterating through all occurences of an expression within a text, there are
- two iterator types: regex_iterator will
- enumerate over the match_results objects
- found, while regex_token_iterator will
- enumerate a series of strings (similar to perl style split operations).
-
For those that dislike templates, there is a high level wrapper class RegEx
- that is an encapsulation of the lower level template code - it provides a
- simplified interface for those that don't need the full power of the library,
- and supports only narrow characters, and the "extended" regular expression
- syntax. This class is now deprecated as it does not form part of the regular
- expressions C++ standard library proposal.
-
-
The POSIX API functions: regcomp, regexec, regfree
- and regerror, are available in both narrow character and Unicode versions, and
- are provided for those who need compatibility with these API's.
-
-
Finally, note that the library now has run-time localization
- support, and recognizes the full POSIX regular expression syntax - including
- advanced features like multi-character collating elements and equivalence
- classes - as well as providing compatibility with other regular expression
- libraries including GNU and BSD4 regex packages, and to a more limited extent
- Perl 5.
-
Boost.regex provides extensive support for run-time
-localization, the localization model used can be split into two
-parts: front-end and back-end.
-
-
Front-end localization deals with everything which the user sees
-- error messages, and the regular expression syntax itself. For
-example a French application could change [[:word:]] to [[:mot:]]
-and \w to \m. Modifying the front end locale requires active
-support from the developer, by providing the library with a message
-catalogue to load, containing the localized strings. Front-end
-locale is affected by the LC_MESSAGES category only.
-
-
Back-end localization deals with everything that occurs after
-the expression has been parsed - in other words everything that the
-user does not see or interact with directly. It deals with case
-conversion, collation, and character class membership. The back-end
-locale does not require any intervention from the developer - the
-library will acquire all the information it requires for the
-current locale from the underlying operating system / run time
-library. This means that if the program user does not interact with
-regular expressions directly - for example if the expressions are
-embedded in your C++ code - then no explicit localization is
-required, as the library will take care of everything for you. For
-example embedding the expression [[:word:]]+ in your code will
-always match a whole word, if the program is run on a machine with,
-for example, a Greek locale, then it will still match a whole word,
-but in Greek characters rather than Latin ones. The back-end locale
-is affected by the LC_TYPE and LC_COLLATE categories.
-
-
There are three separate localization mechanisms supported by
-boost.regex:
-
-
Win32 localization model.
-
-
This is the default model when the library is compiled under
-Win32, and is encapsulated by the traits class w32_regex_traits.
-When this model is in effect there is a single global locale as
-defined by the user's control panel settings, and returned by
-GetUserDefaultLCID. All the settings used by boost.regex are
-acquired directly from the operating system bypassing the C run
-time library. Front-end localization requires a resource dll,
-containing a string table with the user-defined strings. The traits
-class exports the function:
which needs to be called with a string identifying the name of
-the resource dll, before your code compiles any regular
-expressions (but not necessarily before you construct any
-basic_regex instances):
Note that this API sets the dll name for both the narrow
-and wide character specializations of w32_regex_traits.
-
-
This model does not currently support thread specific locales
-(via SetThreadLocale under Windows NT), the library provides full
-Unicode support under NT, under Windows 9x the library degrades
-gracefully - characters 0 to 255 are supported, the remainder are
-treated as "unknown" graphic characters.
-
-
C localization model.
-
-
This is the default model when the library is compiled under an
-operating system other than Win32, and is encapsulated by the
-traits class c_regex_traits, Win32 users can force this
-model to take effect by defining the pre-processor symbol
-BOOST_REGEX_USE_C_LOCALE. When this model is in effect there is a
-single global locale, as set by setlocale. All settings are
-acquired from your run time library, consequently Unicode support
-is dependent upon your run time library implementation. Front end
-localization requires a POSIX message catalogue. The traits class
-exports the function:
which needs to be called with a string identifying the name of
-the message catalogue, before your code compiles any regular
-expressions (but not necessarily before you construct any
-basic_regex instances):
Note that this API sets the dll name for both the narrow
-and wide character specializations of c_regex_traits. If your run
-time library does not support POSIX message catalogues, then you
-can either provide your own implementation of <nl_types.h> or
-define BOOST_RE_NO_CAT to disable front-end localization via
-message catalogues.
-
-
Note that calling setlocale invalidates all compiled
-regular expressions, calling setlocale(LC_ALL, "C") will
-make this library behave equivalent to most traditional regular
-expression libraries including version 1 of this library.
-
-
C++ localization model.
-
-
This model is only in effect if the library is built with the
-pre-processor symbol BOOST_REGEX_USE_CPP_LOCALE defined. When this
-model is in effect each instance of basic_regex<> has its own
-instance of std::locale, class basic_regex<> also has a
-member function imbue which allows the locale for the
-expression to be set on a per-instance basis. Front end
-localization requires a POSIX message catalogue, which will be
-loaded via the std::messages facet of the expression's locale, the
-traits class exports the symbol:
which needs to be called with a string identifying the name of
-the message catalogue, before your code compiles any regular
-expressions (but not necessarily before you construct any
-basic_regex instances):
Note that calling basic_regex<>::imbue will invalidate any
-expression currently compiled in that instance of
-basic_regex<>. This model is the one which closest fits the
-ethos of the C++ standard library, however it is the model which
-will produce the slowest code, and which is the least well
-supported by current standard library implementations, for example
-I have yet to find an implementation of std::locale which supports
-either message catalogues, or locales other than "C" or
-"POSIX".
-
-
Finally note that if you build the library with a non-default
-localization model, then the appropriate pre-processor symbol
-(BOOST_REGEX_USE_C_LOCALE or BOOST_REGEX_USE_CPP_LOCALE) must be
-defined both when you build the support library, and when you
-include <boost/regex.hpp> or <boost/cregex.hpp> in your
-code. The best way to ensure this is to add the #define to
-<boost/regex/user.hpp>.
-
-
Providing a message catalogue:
-
-
In order to localize the front end of the library, you need to
-provide the library with the appropriate message strings contained
-either in a resource dll's string table (Win32 model), or a POSIX
-message catalogue (C or C++ models). In the latter case the
-messages must appear in message set zero of the catalogue. The
-messages and their id's are as follows:
-
-
-
-
-
-
-
-
Message id
-
Meaning
-
Default value
-
-
-
-
-
-
101
-
The character used to start a
-sub-expression.
-
"("
-
-
-
-
-
-
102
-
The character used to end a
-sub-expression declaration.
-
")"
-
-
-
-
-
-
103
-
The character used to denote an end of
-line assertion.
-
"$"
-
-
-
-
-
-
104
-
The character used to denote the start
-of line assertion.
-
"^"
-
-
-
-
-
-
105
-
The character used to denote the
-"match any character expression".
-
"."
-
-
-
-
-
-
106
-
The match zero or more times
-repetition operator.
-
"*"
-
-
-
-
-
-
107
-
The match one or more repetition
-operator.
-
"+"
-
-
-
-
-
-
108
-
The match zero or one repetition
-operator.
-
"?"
-
-
-
-
-
-
109
-
The character set opening
-character.
-
"["
-
-
-
-
-
-
110
-
The character set closing
-character.
-
"]"
-
-
-
-
-
-
111
-
The alternation operator.
-
"|"
-
-
-
-
-
-
112
-
The escape character.
-
"\\"
-
-
-
-
-
-
113
-
The hash character (not currently
-used).
-
"#"
-
-
-
-
-
-
114
-
The range operator.
-
"-"
-
-
-
-
-
-
115
-
The repetition operator opening
-character.
-
"{"
-
-
-
-
-
-
116
-
The repetition operator closing
-character.
-
"}"
-
-
-
-
-
-
117
-
The digit characters.
-
"0123456789"
-
-
-
-
-
-
118
-
The character which when preceded by
-an escape character represents the word boundary assertion.
-
"b"
-
-
-
-
-
-
119
-
The character which when preceded by
-an escape character represents the non-word boundary
-assertion.
-
"B"
-
-
-
-
-
-
120
-
The character which when preceded by
-an escape character represents the word-start boundary
-assertion.
-
"<"
-
-
-
-
-
-
121
-
The character which when preceded by
-an escape character represents the word-end boundary
-assertion.
-
">"
-
-
-
-
-
-
122
-
The character which when preceded by
-an escape character represents any word character.
-
"w"
-
-
-
-
-
-
123
-
The character which when preceded by
-an escape character represents a non-word character.
-
"W"
-
-
-
-
-
-
124
-
The character which when preceded by
-an escape character represents a start of buffer assertion.
-
"`A"
-
-
-
-
-
-
125
-
The character which when preceded by
-an escape character represents an end of buffer assertion.
-
"'z"
-
-
-
-
-
-
126
-
The newline character.
-
"\n"
-
-
-
-
-
-
127
-
The comma separator.
-
","
-
-
-
-
-
-
128
-
The character which when preceded by
-an escape character represents the bell character.
-
"a"
-
-
-
-
-
-
129
-
The character which when preceded by
-an escape character represents the form feed character.
-
"f"
-
-
-
-
-
-
130
-
The character which when preceded by
-an escape character represents the newline character.
-
"n"
-
-
-
-
-
-
131
-
The character which when preceded by
-an escape character represents the carriage return character.
-
"r"
-
-
-
-
-
-
132
-
The character which when preceded by
-an escape character represents the tab character.
-
"t"
-
-
-
-
-
-
133
-
The character which when preceded by
-an escape character represents the vertical tab character.
-
"v"
-
-
-
-
-
-
134
-
The character which when preceded by
-an escape character represents the start of a hexadecimal character
-constant.
-
"x"
-
-
-
-
-
-
135
-
The character which when preceded by
-an escape character represents the start of an ASCII escape
-character.
-
"c"
-
-
-
-
-
-
136
-
The colon character.
-
":"
-
-
-
-
-
-
137
-
The equals character.
-
"="
-
-
-
-
-
-
138
-
The character which when preceded by
-an escape character represents the ASCII escape character.
-
"e"
-
-
-
-
-
-
139
-
The character which when preceded by
-an escape character represents any lower case character.
-
"l"
-
-
-
-
-
-
140
-
The character which when preceded by
-an escape character represents any non-lower case character.
-
"L"
-
-
-
-
-
-
141
-
The character which when preceded by
-an escape character represents any upper case character.
-
"u"
-
-
-
-
-
-
142
-
The character which when preceded by
-an escape character represents any non-upper case character.
-
"U"
-
-
-
-
-
-
143
-
The character which when preceded by
-an escape character represents any space character.
-
"s"
-
-
-
-
-
-
144
-
The character which when preceded by
-an escape character represents any non-space character.
-
"S"
-
-
-
-
-
-
145
-
The character which when preceded by
-an escape character represents any digit character.
-
"d"
-
-
-
-
-
-
146
-
The character which when preceded by
-an escape character represents any non-digit character.
-
"D"
-
-
-
-
-
-
147
-
The character which when preceded by
-an escape character represents the end quote operator.
-
"E"
-
-
-
-
-
-
148
-
The character which when preceded by
-an escape character represents the start quote operator.
-
"Q"
-
-
-
-
-
-
149
-
The character which when preceded by
-an escape character represents a Unicode combining character
-sequence.
-
"X"
-
-
-
-
-
-
150
-
The character which when preceded by
-an escape character represents any single character.
-
"C"
-
-
-
-
-
-
151
-
The character which when preceded by
-an escape character represents end of buffer operator.
-
"Z"
-
-
-
-
-
-
152
-
The character which when preceded by
-an escape character represents the continuation assertion.
-
"G"
-
-
-
-
-
-
153
-
The character which when preceeded by (? indicates a zero width
-negated forward lookahead assert.
-
!
-
-
-
-
-
-
-
-
-
Custom error messages are loaded as follows:
-
-
-
-
-
-
-
Message ID
-
Error message ID
-
Default string
-
-
-
-
-
-
201
-
REG_NOMATCH
-
"No match"
-
-
-
-
-
-
202
-
REG_BADPAT
-
"Invalid regular expression"
-
-
-
-
-
-
203
-
REG_ECOLLATE
-
"Invalid collation character"
-
-
-
-
-
-
204
-
REG_ECTYPE
-
"Invalid character class name"
-
-
-
-
-
-
205
-
REG_EESCAPE
-
"Trailing backslash"
-
-
-
-
-
-
206
-
REG_ESUBREG
-
"Invalid back reference"
-
-
-
-
-
-
207
-
REG_EBRACK
-
"Unmatched [ or [^"
-
-
-
-
-
-
208
-
REG_EPAREN
-
"Unmatched ( or \\("
-
-
-
-
-
-
209
-
REG_EBRACE
-
"Unmatched \\{"
-
-
-
-
-
-
210
-
REG_BADBR
-
"Invalid content of \\{\\}"
-
-
-
-
-
-
211
-
REG_ERANGE
-
"Invalid range end"
-
-
-
-
-
-
212
-
REG_ESPACE
-
"Memory exhausted"
-
-
-
-
-
-
213
-
REG_BADRPT
-
"Invalid preceding regular
-expression"
-
-
-
-
-
-
214
-
REG_EEND
-
"Premature end of regular
-expression"
-
-
-
-
-
-
215
-
REG_ESIZE
-
"Regular expression too big"
-
-
-
-
-
-
216
-
REG_ERPAREN
-
"Unmatched ) or \\)"
-
-
-
-
-
-
217
-
REG_EMPTY
-
"Empty expression"
-
-
-
-
-
-
218
-
REG_E_UNKNOWN
-
"Unknown error"
-
-
-
-
-
-
-
-
-
Custom character class names are loaded as followed:
-
-
-
-
-
-
-
Message ID
-
Description
-
Equivalent default class name
-
-
-
-
-
-
300
-
The character class name for
-alphanumeric characters.
-
"alnum"
-
-
-
-
-
-
301
-
The character class name for
-alphabetic characters.
-
"alpha"
-
-
-
-
-
-
302
-
The character class name for control
-characters.
-
"cntrl"
-
-
-
-
-
-
303
-
The character class name for digit
-characters.
-
"digit"
-
-
-
-
-
-
304
-
The character class name for graphics
-characters.
-
"graph"
-
-
-
-
-
-
305
-
The character class name for lower
-case characters.
-
"lower"
-
-
-
-
-
-
306
-
The character class name for printable
-characters.
-
"print"
-
-
-
-
-
-
307
-
The character class name for
-punctuation characters.
-
"punct"
-
-
-
-
-
-
308
-
The character class name for space
-characters.
-
"space"
-
-
-
-
-
-
309
-
The character class name for upper
-case characters.
-
"upper"
-
-
-
-
-
-
310
-
The character class name for
-hexadecimal characters.
-
"xdigit"
-
-
-
-
-
-
311
-
The character class name for blank
-characters.
-
"blank"
-
-
-
-
-
-
312
-
The character class name for word
-characters.
-
"word"
-
-
-
-
-
-
313
-
The character class name for Unicode
-characters.
-
"unicode"
-
-
-
-
-
-
-
-
-
Finally, custom collating element names are loaded starting from
-message id 400, and terminating when the first load thereafter
-fails. Each message looks something like: "tagname string" where
-tagname is the name used inside [[.tagname.]] and
-string is the actual text of the collating element. Note that
-the value of collating element [[.zero.]] is used for the
-conversion of strings to numbers - if you replace this with another
-value then that will be used for string parsing - for example use
-the Unicode character 0x0660 for [[.zero.]] if you want to use
-Unicode Arabic-Indic digits in your regular expressions in place of
-Latin digits.
-
-
Note that the POSIX defined names for character classes and
-collating elements are always available - even if custom names are
-defined, in contrast, custom error messages, and custom syntax
-messages replace the default ones.
The type match_flag_type is an implementation specific bitmask
- type (17.3.2.1.2) that controls how a regular expression is matched against a
- character sequence. The behavior of the format flags is descibed in more
- detail in the format syntax guide.
The type match_flag_type is an implementation specific bitmask
- type (17.3.2.1.2). When matching a regular expression against a sequence of
- characters [first, last) then setting its elements has the effects listed in
- the table below:
-
-
-
-
-
Element
-
-
-
Effect if set
-
-
-
-
-
match_default
-
-
-
Specifies that matching of regular expressions proceeds without any
- modification of the normal rules used in ECMA-262, ECMAScript Language
- Specification, Chapter 15 part 10, RegExp (Regular Expression) Objects (FWD.1)
-
-
-
-
match_not_bob
-
Specifies that the expression "\A" should not match
- against the sub-sequence [first,first).
-
-
-
match_not_eob
-
Specifies that the expressions "\z" and
- "\Z" should not match against the sub-sequence [last,last).
-
-
-
-
match_not_bol
-
-
-
Specifies that the expression "^" should not be matched against the
- sub-sequence [first,first).
-
-
-
-
-
match_not_eol
-
-
-
Specifies that the expression "$" should not be matched against the
- sub-sequence [last,last).
-
-
-
-
-
match_not_bow
-
-
-
Specifies that the expression "\b" should not be matched against the
- sub-sequence [first,first).
-
-
-
-
-
match_not_eow
-
-
-
Specifies that the expression "\b" should not be matched against the
- sub-sequence [last,last).
-
-
-
-
-
match_any
-
-
-
Specifies that if more than one match is possible then any match is an
- acceptable result.
-
-
-
-
-
match_not_null
-
-
-
Specifies that the expression can not be matched against an empty sequence.
-
-
-
-
-
match_continuous
-
-
-
Specifies that the expression must match a sub-sequence that begins at first.
-
-
-
-
-
match_partial
-
-
-
Specifies that if no match can be found, then it is acceptable to return a
- match [from, last) where from!=last, if there exists some sequence of
- characters [from,to) of which [from,last) is a prefix, and which would result
- in a full match.
Equivalent to Perl's s/ modifier; prevents ^ from
- matching after an embedded newline character (so that it only matches at the
- start of the text being matched), and $ from matching before an embedded
- newline (so that it only matches at the end of the text being matched).
-
-
-
-
match_prev_avail
-
-
-
Specifies that --first is a valid iterator position, when this
- flag is set then the flags match_not_bol and match_not_bow
- are ignored by the regular expression algorithms (RE.7) and iterators (RE.8).
-
-
-
-
match_not_dot_newline
-
Specifies that the expression "." does not match a
- newline character.
-
-
-
match_not_dot_null
-
Specified that the expression "." does not match a
- character null '\0'.
-
-
-
-
format_default
-
-
-
Specifies that when a regular expression match is to be replaced by a new
- string, that the new string is constructed using the rules used by the
- ECMAScript replace function in ECMA-262, ECMAScript Language Specification,
- Chapter 15 part 5.4.11 String.prototype.replace. (FWD.1). In addition during
- search and replace operations then all non-overlapping occurrences of the
- regular expression are located and replaced, and sections of the input that did
- not match the expression, are copied unchanged to the output string.
-
-
-
-
-
format_sed
-
-
-
Specifies that when a regular expression match is to be replaced by a new
- string, that the new string is constructed using the rules used by the Unix sed
- utility in IEEE Std 1003.1-2001, Portable Operating SystemInterface (POSIX ),
- Shells and Utilities..
-
-
-
-
-
format_perl
-
-
-
- Specifies that when a regular expression match is to be replaced by a new
- string, that the new string is constructed using the same rules as Perl 5.
-
-
-
-
format_all
-
Specifies that all syntax extensions are
- enabled, including conditional (?ddexpression1:expression2) replacements: see
- the format string guide for more details.
-
-
-
-
format_no_copy
-
-
-
When specified during a search and replace operation, then sections of the
- character container sequence being searched that do match the regular
- expression, are not copied to the output string.
-
-
-
-
-
format_first_only
-
-
-
When specified during a search and replace operation, then only the first
- occurrence of the regular expression is replaced.
Regular expressions are different from many simple pattern-matching algorithms
- in that as well as finding an overall match they can also produce
- sub-expression matches: each sub-expression being delimited in the pattern by a
- pair of parenthesis (...). There has to be some method for reporting
- sub-expression matches back to the user: this is achieved this by defining a
- class match_results that acts as an indexed collection of sub-expression
- matches, each sub-expression match being contained in an object of type
- sub_match .
-
Template class match_results denotes a collection of character sequences
- representing the result of a regular expression match. Objects of type
- match_results are passed to the algorithms regex_match
- and regex_search, and are returned by the
- iterator regex_iterator . Storage for
- the collection is allocated and freed as necessary by the member functions of
- class match_results.
-
The template class match_results conforms to the requirements of a Sequence, as
- specified in (lib.sequence.reqmts), except that only operations defined for
- const-qualified Sequences are supported.
-
Class template match_results is most commonly used as one of the typedefs
- cmatch, wcmatch, smatch, or wsmatch:
In all match_results constructors, a copy of the Allocator
- argument is used for any memory allocation performed by the constructor or
- member functions during the lifetime of the object.
-
-match_results(const Allocator& a = Allocator());
-
-
-
Effects: Constructs an object of class match_results. The postconditions
- of this function are indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
true
-
-
-
-
-
size()
-
-
-
0
-
-
-
-
-
str()
-
-
-
basic_string<charT>()
-
-
-
-
-
-
-match_results(const match_results& m);
-
-
-
Effects: Constructs an object of class match_results, as a copy of m.
Effects: Assigns m to *this. The postconditions of this function are
- indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
m.empty().
-
-
-
-
-
size()
-
-
-
m.size().
-
-
-
-
-
str(n)
-
-
-
m.str(n) for all integers n < m.size().
-
-
-
-
-
prefix()
-
-
-
m.prefix().
-
-
-
-
-
suffix()
-
-
-
m.suffix().
-
-
-
-
-
(*this)[n]
-
-
-
m[n] for all integers n < m.size().
-
-
-
-
-
length(n)
-
-
-
m.length(n) for all integers n < m.size().
-
-
-
-
-
position(n)
-
-
-
m.position(n) for all integers n < m.size().
-
-
-
-
-
match_results size
-
-size_type size()const;
-
-
-
Effects: Returns the number of sub_match elements stored in *this; that
- is the number of marked sub-expressions in the regular expression that was
- matched plus one.
-
-size_type max_size()const;
-
-
-
Effects: Returns the maximum number of sub_match elements that can be
- stored in *this.
-
-bool empty()const;
-
-
-
Effects: Returns size() == 0.
-
match_results element access
-
-difference_type length(int sub = 0)const;
-
-
-
Effects: Returns the length of sub-expression sub, that is to
- say: (*this)[sub].length().
-
-difference_type position(unsigned int sub = 0)const;
-
-
-
Effects: Returns the starting location of sub-expression sub,
- or -1 if sub was not matched .
-
-string_type str(int sub = 0)const;
-
-
-
Effects: Returns sub-expression sub as a string: string_type((*this)[sub]).
-
-const_reference operator[](int n) const;
-
-
-
Effects: Returns a reference to the sub_match object
- representing the character sequence that matched marked sub-expression n.
- If n == 0 then returns a reference to a sub_match object
- representing the character sequence that matched the whole regular
- expression. If n is out of range, or if n is an
- unmatched sub-expression, then returns a sub_match object whose matched
- member is false.
-
-const_reference prefix()const;
-
-
-
Effects: Returns a reference to the sub_match object
- representing the character sequence from the start of the string being
- matched/searched, to the start of the match found.
-
-const_reference suffix()const;
-
-
-
Effects: Returns a reference to the sub_match object
- representing the character sequence from the end of the match found to the end
- of the string being matched/searched.
-
-const_iterator begin()const;
-
-
-
Effects: Returns a starting iterator that enumerates over all the marked
- sub-expression matches stored in *this.
-
-const_iterator end()const;
-
-
-
Effects: Returns a terminating iterator that enumerates over all the
- marked sub-expression matches stored in *this.
Requires: The type OutputIterator conforms to the Output Iterator
- requirements (24.1.2).
-
-
Effects: Copies the character sequence [fmt.begin(), fmt.end()) to
- OutputIterator out. For each format specifier or escape sequence in fmt,
- replace that sequence with either the character(s) it represents, or the
- sequence of characters within *this to which it refers. The bitmasks specified
- in flags determines what
- format specifiers or escape sequences are recognized, by default this is
- the format used by ECMA-262, ECMAScript Language Specification, Chapter 15 part
- 5.4.11 String.prototype.replace.
Effects: Returns a copy of the string fmt. For each format
- specifier or escape sequence in fmt, replace that sequence with either
- the character(s) it represents, or the sequence of characters within *this to
- which it refers. The bitmasks specified in flags
- determines what format specifiers or escape sequences
- are recognized, by default this is the format used by ECMA-262,
- ECMAScript Language Specification, Chapter 15 part 5.4.11
- String.prototype.replace.
-
Allocator access
-
allocator_type get_allocator()const;
-
-
-
Effects: Returns a copy of the Allocator that was passed to the object's
- constructor.
-
Swap
-
void swap(match_results& that);
-
-
-
Effects: Swaps the contents of the two sequences.
-
-
Postcondition:*this contains the sequence of matched
- sub-expressions that were in that, that contains the
- sequence of matched sub-expressions that were in *this.
Defines an implementation-specific type that satisfies the requirements of
- a standard library Sequence (21.1.1 including the optional Table 68
- operations), whose value_type is a sub_match<BidirectionalIterator>. This
- type happens to be std::vector<sub_match<BidirectionalIterator> >,
- but you shouldn't actually rely on that.
Effects: returns a sequence containing all the captures
- obtained for sub-expression i.
-
Returns:(*this)[i].captures();
-
Preconditions: the library must be built and used with
- BOOST_REGEX_MATCH_EXTRA defined, and you must pass the flag
- match_extra to the regex matching functions (regex_match,
- regex_search, regex_iterator
- or regex_token_iterator) in order for
- this member function to be defined and return useful information.
-
Rationale: Enabling this feature has several consequences:
-
-
-
- sub_match occupies more memory resulting in complex expressions running out of
- memory or stack space more quickly during matching.
-
- The matching algorithms are less efficient at handling some features
- (independent sub-expressions for example), even when match_extra is not used.
-
- The matching algorithms are much less efficient (i.e. slower), when match_extra
- is used. Mostly this is down to the extra memory allocations that have to
- take place.
The match-flagmatch_partial can
- be passed to the following algorithms: regex_match,
- regex_search, and regex_grep.
- When used it indicates that partial as well as full matches should be found. A
- partial match is one that matched one or more characters at the end of the text
- input, but did not match all of the regular expression (although it may have
- done so had more input been available). Partial matches are typically used when
- either validating data input (checking each character as it is entered on the
- keyboard), or when searching texts that are either too long to load into memory
- (or even into a memory mapped file), or are of indeterminate length (for
- example the source may be a socket or similar). Partial and full matches can be
- differentiated as shown in the following table (the variable M represents an
- instance of match_results<> as filled in
- by regex_match, regex_search or regex_grep):
-
-
-
-
-
-
Result
-
M[0].matched
-
M[0].first
-
M[0].second
-
-
-
No match
-
False
-
Undefined
-
Undefined
-
Undefined
-
-
-
Partial match
-
True
-
False
-
Start of partial match.
-
End of partial match (end of text).
-
-
-
Full match
-
True
-
True
-
Start of full match.
-
End of full match.
-
-
-
-
The following example
- tests to see whether the text could be a valid credit card number, as the user
- presses a key, the character entered would be added to the string being built
- up, and passed to is_possible_card_number. If this returns true
- then the text could be a valid card number, so the user interface's OK button
- would be enabled. If it returns false, then this is not yet a valid card
- number, but could be with more input, so the user interface would disable the
- OK button. Finally, if the procedure throws an exception the input could never
- become a valid number, and the inputted character must be discarded, and a
- suitable error indication displayed to the user.
-
#include <string>
-#include <iostream>
-#include <boost/regex.hpp>
-
-boost::regex e("(\\d{3,4})[- ]?(\\d{4})[- ]?(\\d{4})[- ]?(\\d{4})");
-
-bool is_possible_card_number(const std::string& input)
-{
- //
- // return false for partial match, true for full match, or throw for
- // impossible match based on what we have so far...
- boost::match_results<std::string::const_iterator> what;
- if(0 == boost::regex_match(input, what, e, boost::match_default | boost::match_partial))
- {
- // the input so far could not possibly be valid so reject it:
- throw std::runtime_error("Invalid data entered - this could not possibly be a valid card number");
- }
- // OK so far so good, but have we finished?
- if(what[0].matched)
- {
- // excellent, we have a result:
- return true;
- }
- // what we have so far is only a partial match...
- return false;
-}
-
In the following example,
- text input is taken from a stream containing an unknown amount of text; this
- example simply counts the number of html tags encountered in the stream. The
- text is loaded into a buffer and searched a part at a time, if a partial match
- was encountered, then the partial match gets searched a second time as the
- start of the next batch of text:
-
#include <iostream>
-#include <fstream>
-#include <sstream>
-#include <string>
-#include <boost/regex.hpp>
-
-// match some kind of html tag:
-boost::regex e("<[^>]*>");
-// count how many:
-unsigned int tags = 0;
-// saved position of partial match:
-char* next_pos = 0;
-
-bool grep_callback(const boost::match_results<char*>& m)
-{
- if(m[0].matched == false)
- {
- // save position and return:
- next_pos = m[0].first;
- }
- else
- ++tags;
- return true;
-}
-
-void search(std::istream& is)
-{
- char buf[4096];
- next_pos = buf + sizeof(buf);
- bool have_more = true;
- while(have_more)
- {
- // how much do we copy forward from last try:
- unsigned leftover = (buf + sizeof(buf)) - next_pos;
- // and how much is left to fill:
- unsigned size = next_pos - buf;
- // copy forward whatever we have left:
- memcpy(buf, next_pos, leftover);
- // fill the rest from the stream:
- unsigned read = is.readsome(buf + leftover, size);
- // check to see if we've run out of text:
- have_more = read == size;
- // reset next_pos:
- next_pos = buf + sizeof(buf);
- // and then grep:
- boost::regex_grep(grep_callback,
- buf,
- buf + read + leftover,
- e,
- boost::match_default | boost::match_partial);
- }
-}
The performance of Boost.regex in both recursive and non-recursive modes should
- be broadly comparable to other regular expression libraries: recursive mode is
- slightly faster (especially where memory allocation requires thread
- synchronisation), but not by much. The following pages compare
- Boost.regex with various other regular expression libraries for the following
- compilers:
The following functions are available for users who need a POSIX compatible C
- library, they are available in both Unicode and narrow character versions, the
- standard POSIX API names are macros that expand to one version or the other
- depending upon whether UNICODE is defined or not.
-
-
Important: Note that all the symbols defined here are enclosed inside
- namespace boost when used in C++ programs, unless you use #include
- <boost/regex.h> instead - in which case the symbols are still defined in
- namespace boost, but are made available in the global namespace as well.
All the functions operate on structure regex_t, which exposes two public
- members:
-
-
unsigned int re_nsub this is filled in by regcomp and indicates
- the number of sub-expressions contained in the regular expression.
-
-
const TCHAR* re_endp points to the end of the expression to compile when
- the flag REG_PEND is set.
-
-
Footnote: regex_t is actually a #define - it is either regex_tA or regex_tW
- depending upon whether UNICODE is defined or not, TCHAR is either char or
- wchar_t again depending upon the macro UNICODE.
-
-
regcomp
-
regcomp takes a pointer to a regex_t, a pointer to the expression
- to compile and a flags parameter which can be a combination of:
-
-
-
-
-
-
-
-
REG_EXTENDED
-
Compiles modern regular expressions. Equivalent to
- regbase::char_classes | regbase::intervals | regbase::bk_refs.
All characters are ordinary, the expression is a
- literal string.
-
-
-
-
-
REG_ICASE
-
Compiles for matching that ignores character case.
-
-
-
-
-
REG_NOSUB
-
Has no effect in this library.
-
-
-
-
-
REG_NEWLINE
-
When this flag is set a dot does not match the
- newline character.
-
-
-
-
-
REG_PEND
-
When this flag is set the re_endp parameter of the
- regex_t structure must point to the end of the regular expression to compile.
-
-
-
-
-
REG_NOCOLLATE
-
When this flag is set then locale dependent collation
- for character ranges is turned off.
-
-
-
-
-
REG_ESCAPE_IN_LISTS
- , , ,
-
-
When this flag is set, then escape sequences are
- permitted in bracket expressions (character sets).
-
-
-
-
-
REG_NEWLINE_ALT
-
When this flag is set then the newline character is
- equivalent to the alternation operator |.
-
-
-
-
-
REG_PERL
-
Compiles Perl like regular expressions.
-
-
-
-
-
REG_AWK
-
A shortcut for awk-like behavior: REG_EXTENDED |
- REG_ESCAPE_IN_LISTS
-
-
-
-
-
REG_GREP
-
A shortcut for grep like behavior: REG_BASIC |
- REG_NEWLINE_ALT
-
-
-
-
-
REG_EGREP
-
A shortcut for egrep like behavior:
- REG_EXTENDED | REG_NEWLINE_ALT
-
-
-
-
-
regerror
-
regerror takes the following parameters, it maps an error code to a human
- readable string:
-
-
-
-
-
-
-
int code
-
The error code.
-
-
-
-
-
const regex_t* e
-
The regular expression (can be null).
-
-
-
-
-
char* buf
-
The buffer to fill in with the error message.
-
-
-
-
-
unsigned int buf_size
-
The length of buf.
-
-
-
-
-
If the error code is OR'ed with REG_ITOA then the message that results is the
- printable name of the code rather than a message, for example "REG_BADPAT". If
- the code is REG_ATIO then e must not be null and e->re_pend must
- point to the printable name of an error code, the return value is then the
- value of the error code. For any other value of code, the return value
- is the number of characters in the error message, if the return value is
- greater than or equal to buf_size then regerror will have to be
- called again with a larger buffer.
-
regexec
-
regexec finds the first occurrence of expression e within string buf.
- If len is non-zero then *m is filled in with what matched the
- regular expression, m[0] contains what matched the whole string, m[1]
- the first sub-expression etc, see regmatch_t in the header file
- declaration for more details. The eflags parameter can be a combination
- of:
-
-
-
-
-
-
-
-
REG_NOTBOL
-
Parameter buf does not represent the start of
- a line.
-
-
-
-
-
REG_NOTEOL
-
Parameter buf does not terminate at the end of
- a line.
-
-
-
-
-
REG_STARTEND
-
The string searched starts at buf + pmatch[0].rm_so
- and ends at buf + pmatch[0].rm_eo.
-
-
-
-
-
regfree
-
Finally regfree frees all the memory that was allocated by regcomp.
-
-
Footnote: this is an abridged reference to the POSIX API functions, it is
- provided for compatibility with other libraries, rather than an API to be used
- in new code (unless you need access from a language other than C++). This
- version of these functions should also happily coexist with other versions, as
- the names used are macros that expand to the actual function names.
-
If you are using Microsoft or Borland C++ and link to a dll version of the run
- time library, then you can choose to also link to a dll version of boost.regex
- by defining the symbol BOOST_REGEX_DYN_LINK when you compile your code. While
- these dll's are redistributable, there are no "standard" versions, so when
- installing on the users PC, you should place these in a directory private to
- your application, and not in the PC's directory path. Note that if you link to
- a static version of your run time library, then you will also link to a static
- version of boost.regex and no dll's will need to be distributed. The possible
- boost.regex dll and library names are computed according to the following
- formula:
-
-
-
BOOST_LIB_PREFIX
- + "boost_regex_"
- + BOOST_LIB_TOOLSET
- + "_"
- + BOOST_LIB_THREAD_OPT
- + BOOST_LIB_RT_OPT
- + BOOST_LIB_DEBUG_OPT
-
- These are defined as:
-
BOOST_LIB_PREFIX: Either "lib" if this is a static link library,
- or nothing for dynamic / shared libraries.
-
- BOOST_LIB_TOOLSET: The compiler toolset name (vc6, vc7, bcb5 etc).
-
- BOOST_LIB_THREAD_OPT: "s" for single thread builds,
- "m" for multithread builds.
-
- BOOST_LIB_RT_OPT: "s" for static runtime,
- "d" for dynamic runtime.
-
- BOOST_LIB_LINK_OPT: "s" for static link,
- "i" for dynamic link.
-
- BOOST_LIB_DEBUG_OPT: nothing for release builds,
- "d" for debug builds,
- "dd" for debug-diagnostic builds (_STLP_DEBUG).
-
- Note: you can disable automatic library selection by defining the symbol
- BOOST_REGEX_NO_LIB when compiling, this is useful if you want to statically
- link even though you're using the dll version of your run time library, or if
- you need to debug boost.regex.
-
Use of the type boost::regbase is now deprecated,
-and the type does not form a part of the
-regular expression standardization proposal. This type
-still exists as a base class of boost::basic_regex,
-and you can still refer to
-boost::regbase::constant_name in your code, however for
-maximum portability to other std regex implementations you should
-instead use either:
The high level wrapper class RegEx is now deprecated and does not form a 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 synatx.
Member functions for class RegEx are defined as follows:
-
-
-
-
-
-
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(constchar* 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.
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=(constchar*
- 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.
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.
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.
Attempts to match the current expression against the
- text p using the match flags flags - see
- match flags. Returns true if the expression matches the whole of
- the input string.
Attempts to match the current expression against the
- text s using the match flags flags - see
- match flags. Returns true if the expression matches the whole of
- the input string.
Attempts to find a match for the current expression
- somewhere in the text p using the match flags flags - see
- match flags. Returns true if the match succeeds.
Attempts to find a match for the current expression
- somewhere in the text s using the match flags flags - see
- match flags. Returns true if the match succeeds.
Finds all matches of the current expression in the
- text p using the match flags flags - see
- match 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.
Finds all matches of the current expression in the
- text s using the match flags flags - see
- match 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.
Finds all matches of the current expression in the
- text p using the match flags flags - see
- match flags. For each match pushes a copy of what matched onto v.
- Returns the number of matches found.
Finds all matches of the current expression in the
- text s using the match flags flags - see
- match flags. For each match pushes a copy of what matched onto v.
- Returns the number of matches found.
Finds all matches of the current expression in the
- text p using the match flags flags - see
- match flags. For each match pushes the starting index of what matched
- onto v. Returns the number of matches found.
Finds all matches of the current expression in the
- text s using the match flags flags - see
- match flags. For each match pushes the starting index of what matched
- onto v. Returns the number of matches found.
Finds all matches of the current expression in the
- files files using the match flags flags - see
- match 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.
Finds all matches of the current expression in the
- files files using the match flags flags - see
- match 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.
Searches files to find all those which contain
- at least one match of the current expression using the match flags flags
- - see match 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.
Searches files to find all those which contain
- at least one match of the current expression using the match flags flags
- - see match 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.
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
- occurance of the pattern found is replaced. Returns the new string. See
- also format string syntax, match flags
- and format flags.
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
- occurance of the pattern found is replaced. Returns the new string. See
- also format string syntax, match flags
- and format flags.
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.
-
-
-
-
-
unsignedint 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.
-
-
-
-
-
unsignedint 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.
-
-
-
-
-
unsignedint 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.
The algorithm regex_format is deprecated; new code should use
-match_results::format instead. Existing code will continue to
-compile, the following documentation is taken from the previous
-version of boost.regex and will not be further updated:
The algorithm regex_format takes the results of a match and
-creates a new string based upon a
-format string, regex_format can be used for search and replace
-operations:
-
-
-template <class OutputIterator, class iterator, class Allocator, class charT>
-OutputIterator regex_format(OutputIterator out,
- const match_results<iterator, Allocator>& m,
- const charT* fmt,
- match_flag_type flags = 0);
-template <class OutputIterator, class iterator, class Allocator, class charT>
-OutputIterator regex_format(OutputIterator out,
- const match_results<iterator, Allocator>& m,
- const std::basic_string<charT>& fmt,
- match_flag_type flags = 0);
-
-
-
The library also defines the following convenience variation of
-regex_format, which returns the result directly as a string, rather
-than outputting to an iterator [note - this version may not be
-available, or may be available in a more limited form, depending
-upon your compilers capabilities]:
-
-
-template <class iterator, class Allocator, class charT>
-std::basic_string<charT> regex_format
- (const match_results<iterator, Allocator>& m,
- const charT* fmt,
- match_flag_type flags = 0);
-
-template <class iterator, class Allocator, class charT>
-std::basic_string<charT> regex_format
- (const match_results<iterator, Allocator>& m,
- const std::basic_string<charT>& fmt,
- match_flag_type flags = 0);
-
-
-
Parameters to the main version of the function are passed as
-follows:
-
-
-
-
-
-
-
OutputIterator out
-
An output iterator type, the output
-string is sent to this iterator. Typically this would be a
-std::ostream_iterator.
-
-
-
-
-
-
const
-match_results<iterator, Allocator>& m
-
An instance of match_results<>
-obtained from one of the matching algorithms above, and denoting
-what matched.
-
-
-
-
-
-
const charT* fmt
-
A format string that determines how
-the match is transformed into the new string.
-
-
-
-
-
-
unsigned flags
-
Optional flags which describe how the
-format string is to be interpreted.
-
-
-
-
-
-
-
-
-
Format flags are defined as
-follows:
-
-
-
-
-
-
-
format_all
-
Enables all syntax options (perl-like
-plus extentions).
-
-
-
-
-
-
format_sed
-
Allows only a sed-like syntax.
-
-
-
-
-
-
format_perl
-
Allows only a perl-like syntax.
-
-
-
-
-
-
format_no_copy
-
Disables copying of unmatched sections
-to the output string during
-regex_merge operations.
-
-
-
-
-
-
format_first_only
-
When this flag is set only the first occurance will be replaced
-(applies to regex_merge only).
-
-
-
-
-
-
-
-
-
The format string syntax (and available options) is described
-more fully under format strings
-.
regex_grep allows you to search through a bidirectional-iterator range and
- locate all the (non-overlapping) matches with a given regular expression. The
- function is declared as:
-
-template <class Predicate, class iterator, class charT, class traits, class Allocator>
-unsignedint regex_grep(Predicate foo,
- iterator first,
- iterator last,
- const basic_regex<charT, traits, Allocator>& e,
- boost::match_flag_type flags = match_default)
-
-
The library also defines the following convenience versions, which take either
- a const charT*, or a const std::basic_string<>& in place of a pair of
- iterators [note - these versions may not be available, or may be available in a
- more limited form, depending upon your compilers capabilities]:
-
-template <class Predicate, class charT, class Allocator, class traits>
-unsignedint regex_grep(Predicate foo,
- const charT* str,
- const basic_regex<charT, traits, Allocator>& e,
- boost::match_flag_type flags = match_default);
-
-template <class Predicate, class ST, class SA, class Allocator, class charT, class traits>
-unsignedint regex_grep(Predicate foo,
- const std::basic_string<charT, ST, SA>& s,
- const basic_regex<charT, traits, Allocator>& e,
- boost::match_flag_type flags = match_default);
-
-
The parameters for the primary version of regex_grep have the following
- meanings:
-
-
-
-
-
foo
-
A predicate function object or function pointer, see
- below for more information.
-
-
-
-
-
first
-
The start of the range to search.
-
-
-
-
-
last
-
The end of the range to search.
-
-
-
-
-
e
-
The regular expression to search for.
-
-
-
-
-
flags
-
The flags that determine how matching is carried out,
- one of the match_flags enumerators.
-
-
-
-
-
-
The algorithm finds all of the non-overlapping matches of the expression e, for
- each match it fills a match_results<iterator,
- Allocator> structure, which contains information on what matched, and calls
- the predicate foo, passing the match_results<iterator, Allocator> as a
- single argument. If the predicate returns true, then the grep operation
- continues, otherwise it terminates without searching for further matches. The
- function returns the number of matches found.
Note that in almost every case the allocator parameter can be omitted, when
- specifying the match_results type,
- alternatively one of the typedefs cmatch, wcmatch, smatch or wsmatch can be
- used.
-
For example the regular expression "a*b" would find one match in the string
- "aaaaab" and two in the string "aaabb".
-
Remember this algorithm can be used for a lot more than implementing a version
- of grep, the predicate can be and do anything that you want, grep utilities
- would output the results to the screen, another program could index a file
- based on a regular expression and store a set of bookmarks in a list, or a text
- file conversion utility would output to file. The results of one regex_grep can
- even be chained into another regex_grep to create recursive parsers.
-
The algorithm may throw std::runtime_error if the complexity
- of matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
Example: convert
- the example from regex_search to use regex_grep instead:
-
-#include <string>
-#include <map>
-#include <boost/regex.hpp>
-
-// IndexClasses:
-// takes the contents of a file in the form of a string
-// and searches for all the C++ class definitions, storing
-// their locations in a map of strings/int's
-typedef std::map<std::string, int, std::less<std::string> > map_type;
-
-const char* re =
- // possibly leading whitespace:
- "^[[:space:]]*"
- // possible template declaration:
- "(template[[:space:]]*<[^;:{]+>[[:space:]]*)?"
- // class or struct:
- "(class|struct)[[:space:]]*"
- // leading declspec macros etc:
- "("
- "\\<\\w+\\>"
- "("
- "[[:blank:]]*\\([^)]*\\)"
- ")?"
- "[[:space:]]*"
- ")*"
- // the class name
- "(\\<\\w*\\>)[[:space:]]*"
- // template specialisation parameters
- "(<[^;:{]+>)?[[:space:]]*"
- // terminate in { or :
- "(\\{|:[^;\\{()]*\\{)";
-
-boost::regex expression(re);
-class IndexClassesPred
-{
- map_type& m;
- std::string::const_iterator base;
-public:
- IndexClassesPred(map_type& a, std::string::const_iterator b) : m(a), base(b) {}
- booloperator()(const smatch& what)
- {
- // what[0] contains the whole string
-// what[5] contains the class name.
-// what[6] contains the template specialisation if any.
-// add class name and position to map:
- m[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] =
- what[5].first - base;
- returntrue;
- }
-};
-void IndexClasses(map_type& m, const std::string& file)
-{
- std::string::const_iterator start, end;
- start = file.begin();
- end = file.end();
- regex_grep(IndexClassesPred(m, start), start, end, expression);
-}
-
-
Example: Use
- regex_grep to call a global callback function:
-
-#include <string>
-#include <map>
-#include <boost/regex.hpp>
-
-// purpose:
-// takes the contents of a file in the form of a string
-// and searches for all the C++ class definitions, storing
-// their locations in a map of strings/int's
-typedef std::map<std::string, int, std::less<std::string> > map_type;
-
-const char* re =
- // possibly leading whitespace:
- "^[[:space:]]*"
- // possible template declaration:
- "(template[[:space:]]*<[^;:{]+>[[:space:]]*)?"
- // class or struct:
- "(class|struct)[[:space:]]*"
- // leading declspec macros etc:
- "("
- "\\<\\w+\\>"
- "("
- "[[:blank:]]*\\([^)]*\\)"
- ")?"
- "[[:space:]]*"
- ")*"
- // the class name
- "(\\<\\w*\\>)[[:space:]]*"
- // template specialisation parameters
- "(<[^;:{]+>)?[[:space:]]*"
- // terminate in { or :
- "(\\{|:[^;\\{()]*\\{)";
-
-boost::regex expression(re);
-map_type class_index;
-std::string::const_iterator base;
-
-bool grep_callback(const boost::smatch& what)
-{
- // what[0] contains the whole string
-// what[5] contains the class name.
-// what[6] contains the template specialisation if any.
-// add class name and position to map:
- class_index[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] =
- what[5].first - base;
- returntrue;
-}
-void IndexClasses(const std::string& file)
-{
- std::string::const_iterator start, end;
- start = file.begin();
- end = file.end();
- base = start;
- regex_grep(grep_callback, start, end, expression, match_default);
-}
-
-
-
Example: use
- regex_grep to call a class member function, use the standard library adapters std::mem_fun
- and std::bind1st to convert the member function into a predicate:
-
-#include <string>
-#include <map>
-#include <boost/regex.hpp>
-#include <functional>
-// purpose:
-// takes the contents of a file in the form of a string
-// and searches for all the C++ class definitions, storing
-// their locations in a map of strings/int's
-
-typedef std::map<std::string, int, std::less<std::string> > map_type;
-class class_index
-{
- boost::regex expression;
- map_type index;
- std::string::const_iterator base;
- bool grep_callback(boost::smatch what);
-public:
- void IndexClasses(const std::string& file);
- class_index()
- : index(),
- expression("^(template[[:space:]]*<[^;:{]+>[[:space:]]*)?"
- "(class|struct)[[:space:]]*(\\<\\w+\\>([[:blank:]]*\\([^)]*\\))?"
- "[[:space:]]*)*(\\<\\w*\\>)[[:space:]]*(<[^;:{]+>[[:space:]]*)?"
- "(\\{|:[^;\\{()]*\\{)"
- ){}
-};
-bool class_index::grep_callback(boost::smatch what)
-{
- // what[0] contains the whole string
-// what[5] contains the class name.
-// what[6] contains the template specialisation if any.
-// add class name and position to map:
- index[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] =
- what[5].first - base;
- returntrue;
-}
-
-void class_index::IndexClasses(const std::string& file)
-{
- std::string::const_iterator start, end;
- start = file.begin();
- end = file.end();
- base = start;
- regex_grep(std::bind1st(std::mem_fun(&class_index::grep_callback), this),
- start,
- end,
- expression);
-}
-
-
-
Finally, C++
- Builder users can use C++ Builder's closure type as a callback argument:
-
-#include <string>
-#include <map>
-#include <boost/regex.hpp>
-#include <functional>
-// purpose:
-// takes the contents of a file in the form of a string
-// and searches for all the C++ class definitions, storing
-// their locations in a map of strings/int's
-
-typedef std::map<std::string, int, std::less<std::string> > map_type;
-class class_index
-{
- boost::regex expression;
- map_type index;
- std::string::const_iterator base;
- typedef boost::smatch arg_type;
- bool grep_callback(const arg_type& what);
-public:
- typedefbool (__closure* grep_callback_type)(const arg_type&);
- void IndexClasses(const std::string& file);
- class_index()
- : index(),
- expression("^(template[[:space:]]*<[^;:{]+>[[:space:]]*)?"
- "(class|struct)[[:space:]]*(\\<\\w+\\>([[:blank:]]*\\([^)]*\\))?"
- "[[:space:]]*)*(\\<\\w*\\>)[[:space:]]*(<[^;:{]+>[[:space:]]*)?"
- "(\\{|:[^;\\{()]*\\{)"
- ){}
-};
-
-bool class_index::grep_callback(const arg_type& what)
-{
- // what[0] contains the whole string
-// what[5] contains the class name.
-// what[6] contains the template specialisation if any.
-// add class name and position to map:
-index[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] =
- what[5].first - base;
- returntrue;
-}
-
-void class_index::IndexClasses(const std::string& file)
-{
- std::string::const_iterator start, end;
- start = file.begin();
- end = file.end();
- base = start;
- class_index::grep_callback_type cl = &(this->grep_callback);
- regex_grep(cl,
- start,
- end,
- expression);
-}
-
The iterator type regex_iterator will enumerate all of the regular expression
- matches found in some sequence: dereferencing a regex_iterator yields a
- reference to a match_results object.
A regex_iterator is constructed from a pair of iterators, and enumerates all
- occurrences of a regular expression within that iterator range.
-
-regex_iterator();
-
-
-
Effects: constructs an end of sequence regex_iterator.
-
regex_iterator(BidirectionalIterator a, BidirectionalIterator b,
- const regex_type& re,
- match_flag_type m = match_default);
-
-
-
Effects: constructs a regex_iterator that will enumerate all occurrences
- of the expression re, within the sequence [a,b), and found
- using match flags m. The object re must exist for the
- lifetime of the regex_iterator.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
Effects: dereferencing a regex_iterator object it yields a
- const reference to a match_results object,
- whose members are set as follows:
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
(*it).size()
-
-
-
re.mark_count()
-
-
-
-
-
(*it).empty()
-
-
-
false
-
-
-
-
-
(*it).prefix().first
-
-
-
The end of the last match found, or the start of the underlying sequence if
- this is the first match enumerated
-
-
-
-
-
(*it).prefix().last
-
-
-
The same as the start of the match found:
- (*it)[0].first
-
-
-
-
-
(*it).prefix().matched
-
-
-
True if the prefix did not match an empty string:
- (*it).prefix().first != (*it).prefix().second
-
-
-
-
-
(*it).suffix().first
-
-
-
The same as the end of the match found:
- (*it)[0].second
-
-
-
-
-
(*it).suffix().last
-
-
-
The end of the underlying sequence.
-
-
-
-
-
(*it).suffix().matched
-
-
-
True if the suffix did not match an empty string:
- (*it).suffix().first != (*it).suffix().second
-
-
-
-
-
(*it)[0].first
-
-
-
The start of the sequence of characters that matched the regular expression
-
-
-
-
-
(*it)[0].second
-
-
-
The end of the sequence of characters that matched the regular expression
-
-
-
-
-
(*it)[0].matched
-
-
-
true if a full match was found, and false if it was a
- partial match (found as a result of the match_partial flag being
- set).
-
-
-
-
-
(*it)[n].first
-
-
-
For all integers n < (*it).size(), the start of the sequence that matched
- sub-expression n. Alternatively, if sub-expression n did not participate
- in the match, then last.
-
-
-
-
-
(*it)[n].second
-
-
-
For all integers n < (*it).size(), the end of the sequence that matched
- sub-expression n. Alternatively, if sub-expression n did not participate
- in the match, then last.
-
-
-
-
-
(*it)[n].matched
-
-
-
For all integers n < (*it).size(), true if sub-expression n participated
- in the match, false otherwise.
-
-
-
-
(*it).position(n)
-
For all integers n < (*it).size(), then the
- distance from the start of the underlying sequence to the start of
- sub-expression match n.
-
-
-
-
-
-
-const value_type* operator->()const;
-
-
-
Effects: returns &(*this).
-
-regex_iterator& operator++();
-
-
Effects: moves the iterator to the next match in the
- underlying sequence, or the end of sequence iterator if none if found.
- When the last match found matched a zero length string, then the
- regex_iterator will find the next match as follows: if there exists a non-zero
- length match that starts at the same location as the last one, then returns it,
- otherwise starts looking for the next (possibly zero length) match from one
- position to the right of the last match.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
-
Returns:*this.
-
-regex_iterator operator++(int);
-
-
-
Effects: constructs a copy result of *this,
- then calls ++(*this).
-
-
Returns:result.
-
Examples
-
The following example
- takes a C++ source file and builds up an index of class names, and the location
- of that class in the file.
-
-#include <string>
-#include <map>
-#include <fstream>
-#include <iostream>
-#include <boost/regex.hpp>
-
-usingnamespace std;
-
-// purpose:
-// takes the contents of a file in the form of a string
-// and searches for all the C++ class definitions, storing
-// their locations in a map of strings/int's
-
-typedef std::map<std::string, std::string::difference_type, std::less<std::string> > map_type;
-
-constchar* re =
- // possibly leading whitespace:
- "^[[:space:]]*"
- // possible template declaration:
- "(template[[:space:]]*<[^;:{]+>[[:space:]]*)?"
- // class or struct:
- "(class|struct)[[:space:]]*"
- // leading declspec macros etc:
- "("
- "\\<\\w+\\>"
- "("
- "[[:blank:]]*\\([^)]*\\)"
- ")?"
- "[[:space:]]*"
- ")*"
- // the class name
- "(\\<\\w*\\>)[[:space:]]*"
- // template specialisation parameters
- "(<[^;:{]+>)?[[:space:]]*"
- // terminate in { or :
- "(\\{|:[^;\\{()]*\\{)";
-
-
-boost::regex expression(re);
-map_type class_index;
-
-bool regex_callback(const boost::match_results<std::string::const_iterator>& what)
-{
- // what[0] contains the whole string
- // what[5] contains the class name.
- // what[6] contains the template specialisation if any.
- // add class name and position to map:
- class_index[what[5].str() + what[6].str()] = what.position(5);
- returntrue;
-}
-
-void load_file(std::string& s, std::istream& is)
-{
- s.erase();
- s.reserve(is.rdbuf()->in_avail());
- char c;
- while(is.get(c))
- {
- if(s.capacity() == s.size())
- s.reserve(s.capacity() * 3);
- s.append(1, c);
- }
-}
-
-int main(int argc, constchar** argv)
-{
- std::string text;
- for(int i = 1; i < argc; ++i)
- {
- cout << "Processing file " << argv[i] << endl;
- std::ifstream fs(argv[i]);
- load_file(text, fs);
- // construct our iterators:
- boost::sregex_iterator m1(text.begin(), text.end(), expression);
- boost::sregex_iterator m2;
- std::for_each(m1, m2, ®ex_callback);
- // copy results:
- cout << class_index.size() << " matches found" << endl;
- map_type::iterator c, d;
- c = class_index.begin();
- d = class_index.end();
- while(c != d)
- {
- cout << "class \"" << (*c).first << "\" found at index: " << (*c).second << endl;
- ++c;
- }
- class_index.erase(class_index.begin(), class_index.end());
- }
- return 0;
-}
-
- The algorithm regex _match determines whether a given regular expression
- matches all of a given character sequence denoted by a pair of
- bidirectional-iterators, the algorithm is defined as follows, the main use of
- this function is data input validation.
-
Note that the result is true only if the expression matches the whole of
- the input sequence. If you want to search for an expression
- somewhere within the sequence then use regex_search.
- If you want to match a prefix of the character string then use
- regex_search with the flag match_continuous
- set.
-
template <class BidirectionalIterator, class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
- match_results<BidirectionalIterator, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template <class BidirectionalIterator, class charT, class traits, class Allocator2>
-bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template <class charT, class Allocator, class traits, class Allocator2>
-bool regex_match(const charT* str, match_results<const charT*, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template <class ST, class SA, class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_match(const basic_string<charT, ST, SA>& s,
- match_results<typename basic_string<charT, ST, SA>::const_iterator, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template <class charT, class traits, class Allocator2>
-bool regex_match(const charT* str,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template <class ST, class SA, class charT, class traits, class Allocator2>
-bool regex_match(const basic_string<charT, ST, SA>& s,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-
Description
-
template <class BidirectionalIterator, class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
- match_results<BidirectionalIterator, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Requires: Type BidirectionalIterator meets the requirements of a
- Bidirectional Iterator (24.1.4).
-
Effects: Determines whether there is an exact match between the regular
- expression e, and all of the character sequence [first, last), parameter
- flags is used to control how the expression
- is matched against the character sequence. Returns true if such a match
- exists, false otherwise.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
Postconditions: If the function returns false, then the effect on
- parameter m is undefined, otherwise the effects on parameter m are
- given in the table:
-
-
-
-
-
-
-
Element
-
-
-
-
Value
-
-
-
-
-
-
m.size()
-
-
-
e.mark_count()
-
-
-
-
-
m.empty()
-
-
-
false
-
-
-
-
-
m.prefix().first
-
-
-
first
-
-
-
-
-
m.prefix().last
-
-
-
first
-
-
-
-
-
m.prefix().matched
-
-
-
false
-
-
-
-
-
m.suffix().first
-
-
-
last
-
-
-
-
-
m.suffix().last
-
-
-
last
-
-
-
-
-
m.suffix().matched
-
-
-
false
-
-
-
-
-
m[0].first
-
-
-
first
-
-
-
-
-
m[0].second
-
-
-
last
-
-
-
-
-
m[0].matched
-
-
-
true if a full match was found, and false if it was
- a partial match (found as a result of the match_partial flag being
- set).
-
-
-
-
-
m[n].first
-
-
-
For all integers n < m.size(), the start of the sequence that matched
- sub-expression n. Alternatively, if sub-expression n did not participate
- in the match, then last.
-
-
-
-
-
m[n].second
-
-
-
For all integers n < m.size(), the end of the sequence that matched
- sub-expression n. Alternatively, if sub-expression n did not participate
- in the match, then last.
-
-
-
-
-
m[n].matched
-
-
-
For all integers n < m.size(), true if sub-expression n participated
- in the match, false otherwise.
-
-
-
-
-
-
-
-
template <class BidirectionalIterator, class charT, class traits, class Allocator2>
-bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Effects: Behaves "as if" by constructing an instance of
- match_results<BidirectionalIterator> what,
- and then returning the result of regex_match(first, last, what, e, flags).
-
template <class charT, class Allocator, class traits, class Allocator2>
-bool regex_match(const charT* str, match_results<const charT*, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_match(str, str +
- char_traits<charT>::length(str), m, e, flags).
-
template <class ST, class SA, class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_match(const basic_string<charT, ST, SA>& s,
- match_results<typename basic_string<charT, ST, SA>::const_iterator, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_match(s.begin(), s.end(), m, e,
- flags).
-
template <class charT, class traits, class Allocator2>
-bool regex_match(const charT* str,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_match(str, str +
- char_traits<charT>::length(str), e, flags).
-
template <class ST, class SA, class charT, class traits, class Allocator2>
-bool regex_match(const basic_string<charT, ST, SA>& s,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_match(s.begin(), s.end(), e,
- flags).
-
Examples
-
The following example
- processes an ftp response:
-
-
#include <stdlib.h>
-#include <boost/regex.hpp>
-#include <string>
-#include <iostream>
-
-using namespace boost;
-
-regex expression("([0-9]+)(\\-| |$)(.*)");
-
-// process_ftp:
-// on success returns the ftp response code, and fills
-// msg with the ftp response message.
-int process_ftp(constchar* response, std::string* msg)
-{
- cmatch what;
- if(regex_match(response, what, expression))
- {
- // what[0] contains the whole string
-// what[1] contains the response code
-// what[2] contains the separator character
-// what[3] contains the text message.
-if(msg)
- msg->assign(what[3].first, what[3].second);
- return std::atoi(what[1].first);
- }
- // failure did not match
-if(msg)
- msg->erase();
- return -1;
-}
-
The algorithm regex_replace searches through a string finding
- all the matches to the regular expression: for each match it then calls
- match_results::format to format the string and sends the result to the
- output iterator. Sections of text that do not match are copied to the output
- unchanged only if the flags parameter does not have the flag
- format_no_copy set. If the flag format_first_only
- is set then only the first occurrence is replaced rather than all
- occurrences.
template <class OutputIterator, class BidirectionalIterator, class traits,
- class Allocator, class charT>
-OutputIterator regex_replace(OutputIterator out,
- BidirectionalIterator first,
- BidirectionalIterator last,
- const basic_regex<charT, traits, Allocator>& e,
- const basic_string<charT>& fmt,
- match_flag_type flags = match_default);
-
-template <class traits, class Allocator, class charT>
-basic_string<charT> regex_replace(const basic_string<charT>& s,
- const basic_regex<charT, traits, Allocator>& e,
- const basic_string<charT>& fmt,
- match_flag_type flags = match_default);
-
-
-
Description
-
template <class OutputIterator, class BidirectionalIterator, class traits,
- class Allocator, class charT>
-OutputIterator regex_replace(OutputIterator out,
- BidirectionalIterator first,
- BidirectionalIterator last,
- const basic_regex<charT, traits, Allocator>& e,
- const basic_string<charT>& fmt,
- match_flag_type flags = match_default);
-
Enumerates all the occurences of expression e in the sequence [first,
- last), replacing each occurence with the string that results by merging the
- match found with the format string fmt, and copies the resulting
- string to out.
-
If the flag format_no_copy is set in flags then unmatched sections of
- text are not copied to output.
-
-
If the flag format_first_only is set in flags then only the first
- occurence of e is replaced.
-
-
The manner in which the format string fmt is interpretted, along with
- the rules used for finding matches, are determined by the
- flags set in flags
-
Effects: Constructs an
- regex_iterator
- object:
-
-
regex_iterator<BidirectionalIterator, charT, traits, Allocator> i(first, last, e, flags),
-
and uses
-
- i
- to enumerate through all of the matches m of type
-
- match_results
- <BidirectionalIterator> that
- occur within the sequence [first, last).
-
where
-
- last_m
-
- is a copy of the last match found.
-
-
If
- flags &
-format_first_only
- is non-zero then only the first match found is replaced.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
Returns:out.
-
-
template <class traits, class Allocator, class charT>
-basic_string<charT> regex_replace(const basic_string<charT>& s,
- const basic_regex<charT, traits, Allocator>& e,
- const basic_string<charT>& fmt,
- match_flag_type flags = match_default);
-
Effects: Constructs an object basic_string<charT> result,
- calls regex_replace(back_inserter(result), s.begin(), s.end(), e, fmt,
- flags), and then returns result.
-
Examples
-
The following example
- takes C/C++ source code as input, and outputs syntax highlighted HTML code.
The algorithm regex_search will search a range denoted by a pair of
- bidirectional-iterators for a given regular expression. The algorithm uses
- various heuristics to reduce the search time by only checking for a match if a
- match could conceivably start at that position. The algorithm is defined as
- follows:
-
template <class BidirectionalIterator,
- class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_search(BidirectionalIterator first, BidirectionalIterator last,
- match_results<BidirectionalIterator, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template <class ST, class SA,
- class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_search(const basic_string<charT, ST, SA>& s,
- match_results<
- typename basic_string<charT, ST,SA>::const_iterator,
- Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template<class charT, class Allocator, class traits,
- class Allocator2>
-bool regex_search(const charT* str,
- match_results<const charT*, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template <class BidirectionalIterator, class Allocator,
- class charT, class traits>
-bool regex_search(BidirectionalIterator first, BidirectionalIterator last,
- const basic_regex<charT, traits, Allocator>& e,
- match_flag_type flags = match_default);
-
-template <class charT, class Allocator,
- class traits>
-bool regex_search(const charT* str,
- const basic_regex<charT, traits, Allocator>& e,
- match_flag_type flags = match_default);
-
-template<class ST, class SA,
- class Allocator, class charT,
- class traits>
-bool regex_search(const basic_string<charT, ST, SA>& s,
- const basic_regex<charT, traits, Allocator>& e,
- match_flag_type flags = match_default);
-
-
Description
-
template <class BidirectionalIterator, class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_search(BidirectionalIterator first, BidirectionalIterator last,
- match_results<BidirectionalIterator, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Requires: Type BidirectionalIterator meets the requirements of a
- Bidirectional Iterator (24.1.4).
-
Effects: Determines whether there is some sub-sequence within
- [first,last) that matches the regular expression e, parameter flags
- is used to control how the expression is matched against the character
- sequence. Returns true if such a sequence exists, false otherwise.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
Postconditions: If the function returns false, then the effect on
- parameter m is undefined, otherwise the effects on parameter m are
- given in the table:
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
-
m.size()
-
-
-
e.mark_count()
-
-
-
-
-
m.empty()
-
-
-
false
-
-
-
-
-
m.prefix().first
-
-
-
first
-
-
-
-
-
m.prefix().last
-
-
-
m[0].first
-
-
-
-
-
m.prefix().matched
-
-
-
m.prefix().first != m.prefix().second
-
-
-
-
-
m.suffix().first
-
-
-
m[0].second
-
-
-
-
-
m.suffix().last
-
-
-
last
-
-
-
-
-
m.suffix().matched
-
-
-
m.suffix().first != m.suffix().second
-
-
-
-
-
m[0].first
-
-
-
The start of the sequence of characters that matched the regular expression
-
-
-
-
-
m[0].second
-
-
-
The end of the sequence of characters that matched the regular expression
-
-
-
-
-
m[0].matched
-
-
-
true if a full match was found, and false if it was
- a partial match (found as a result of the match_partial flag being
- set).
-
-
-
-
-
m[n].first
-
-
-
For all integers n < m.size(), the start of the sequence that matched
- sub-expression n. Alternatively, if sub-expression n did not participate
- in the match, then last.
-
-
-
-
-
m[n].second
-
-
-
For all integers n < m.size(), the end of the sequence that matched
- sub-expression n. Alternatively, if sub-expression n did not participate
- in the match, then last.
-
-
-
-
-
m[n].matched
-
-
-
For all integers n < m.size(), true if sub-expression n participated
- in the match, false otherwise.
-
-
-
-
-
-
template <class charT, class Allocator, class traits, class Allocator2>
-bool regex_search(const charT* str, match_results<const charT*, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_search(str, str +
- char_traits<charT>::length(str), m, e, flags).
-
template <class ST, class SA, class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_search(const basic_string<charT, ST, SA>& s,
- match_results<typename basic_string<charT, ST, SA>::const_iterator, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_search(s.begin(), s.end(), m,
- e, flags).
-
template <class iterator, class Allocator, class charT,
- class traits>
-bool regex_search(iterator first, iterator last,
- const basic_regex<charT, traits, Allocator>& e,
- match_flag_type flags = match_default);
-
Effects: Behaves "as if" by constructing an instance of
- match_results<BidirectionalIterator> what,
- and then returning the result of regex_search(first, last, what, e, flags).
-
template <class charT, class Allocator, class traits>
-bool regex_search(const charT* str
- const basic_regex<charT, traits, Allocator>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_search(str, str +
- char_traits<charT>::length(str), e, flags).
-
template <class ST, class SA, class Allocator, class charT,
- class traits>
-bool regex_search(const basic_string<charT, ST, SA>& s,
- const basic_regex<charT, traits, Allocator>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_search(s.begin(), s.end(), e,
- flags).
-
Examples
-
The following example,
- takes the contents of a file in the form of a string, and searches for all the
- C++ class declarations in the file. The code will work regardless of the way
- that std::string is implemented, for example it could easily be modified to
- work with the SGI rope class, which uses a non-contiguous storage strategy.
-
-
#include <string>
-#include <map>
-#include <boost/regex.hpp>
-
-// purpose:
-// takes the contents of a file in the form of a string
-// and searches for all the C++ class definitions, storing
-// their locations in a map of strings/int's
-typedef std::map<std::string, int, std::less<std::string> > map_type;
-
-boost::regex expression("^(template[[:space:]]*<[^;:{]+>[[:space:]]*)?(class|struct)[[:space:]]*(\\<\\w+\\>([[:blank:]]*\\([^)]*\\))?[[:space:]]*)*(\\<\\w*\\>)[[:space:]]*(<[^;:{]+>[[:space:]]*)?(\\{|:[^;\\{()]*\\{)");
-
-void IndexClasses(map_type& m, const std::string& file)
-{
- std::string::const_iterator start, end;
- start = file.begin();
- end = file.end();
- boost::match_results<std::string::const_iterator> what;
- boost::match_flag_type flags = boost::match_default;
- while(regex_search(start, end, what, expression, flags))
- {
- // what[0] contains the whole string
-// what[5] contains the class name.
-// what[6] contains the template specialisation if any.
-// add class name and position to map:
- m[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] =
- what[5].first - file.begin();
- // update search position:
- start = what[0].second;
- // update flags:
- flags |= boost::match_prev_avail;
- flags |= boost::match_not_bob;
- }
-}
-
The algorithm regex_split has been deprecated in favor of the iterator
- regex_token_iterator which has a more flexible and powerful interface,
- as well as following the more usual standard library "pull" rather than "push"
- semantics.
-
Code which uses regex_split will continue to compile, the following
- documentation is taken from the previous boost.regex version:
Algorithm regex_split performs a similar operation to the perl split operation,
- and comes in three overloaded forms:
-
-
template <class OutputIterator, class charT, class Traits1, class Alloc1, class Traits2, class Alloc2>
-std::size_t regex_split(OutputIterator out,
- std::basic_string<charT, Traits1, Alloc1>& s,
- const basic_regex<charT, Traits2, Alloc2>& e,
- boost::match_flag_type flags,
- std::size_t max_split);
-
-template <class OutputIterator, class charT, class Traits1, class Alloc1, class Traits2, class Alloc2>
-std::size_t regex_split(OutputIterator out,
- std::basic_string<charT, Traits1, Alloc1>& s,
- const basic_regex<charT, Traits2, Alloc2>& e,
- boost::match_flag_type flags = match_default);
-
-template <class OutputIterator, class charT, class Traits1, class Alloc1>
-std::size_t regex_split(OutputIterator out,
- std::basic_string<charT, Traits1, Alloc1>& s);
-
Effects: Each version of the algorithm takes an
- output-iterator for output, and a string for input. If the expression contains
- no marked sub-expressions, then the algorithm writes one string onto the
- output-iterator for each section of input that does not match the expression.
- If the expression does contain marked sub-expressions, then each time a match
- is found, one string for each marked sub-expression will be written to the
- output-iterator. No more than max_split strings will be written to the
- output-iterator. Before returning, all the input processed will be deleted from
- the string s (if max_split is not reached then all of s will
- be deleted). Returns the number of strings written to the output-iterator. If
- the parameter max_split is not specified then it defaults to UINT_MAX.
- If no expression is specified, then it defaults to "\s+", and splitting occurs
- on whitespace.
-
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
Example: the
- following function will split the input string into a series of tokens, and
- remove each token from the string s:
-
The template class regex_token_iterator is an iterator adapter;
- that is to say it represents a new view of an existing iterator sequence, by
- enumerating all the occurrences of a regular expression within that sequence,
- and presenting one or more character sequence for each match found. Each
- position enumerated by the iterator is a sub_match
- object that represents what matched a particular sub-expression within the
- regular expression. When class regex_token_iterator is used to
- enumerate a single sub-expression with index -1, then the iterator performs
- field splitting: that is to say it enumerates one character sequence for each
- section of the character container sequence that does not match the regular
- expression specified.
regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b, const regex_type& re,
- int submatch = 0, match_flag_type m = match_default);
-
Preconditions: !re.empty(). Object re shall exist
- for the lifetime of the iterator constructed from it.
-
Effects: constructs a regex_token_iterator that will enumerate one
- string for each regular expression match of the expression re found
- within the sequence [a,b), using match flags m. The
- string enumerated is the sub-expression submatch for each match
- found; if submatch is -1, then enumerates all the text sequences that
- did not match the expression re (that is to performs field splitting).
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b, const regex_type& re,
- const std::vector<int>& submatches, match_flag_type m = match_default);
-
Preconditions:submatches.size() && !re.empty().
- Object re shall exist for the lifetime of the iterator constructed from it.
-
Effects: constructs a regex_token_iterator that will enumerate submatches.size()
- strings for each regular expression match of the expression re found
- within the sequence [a,b), using match flags m. For
- each match found one string will be enumerated for each sub-expression
- index contained within submatches vector; if submatches[0]
- is -1, then the first string enumerated for each match will be all of the text
- from end of the last match to the start of the current match, in addition there
- will be one extra string enumerated when no more matches can be found: from the
- end of the last match found, to the end of the underlying sequence.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
template <std::size_t N>
-regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b, const regex_type& re,
- const int (&submatches)[R], match_flag_type m = match_default);
-
Preconditions: !re.empty(). Object re shall exist
- for the lifetime of the iterator constructed from it.
-
Effects: constructs a regex_token_iterator that will
- enumerate R strings for each regular expression match of the
- expression re found within the sequence [a,b), using match
- flags m. For each match found one string will be
- enumerated for each sub-expression index contained within the submatches
- array; if submatches[0] is -1, then the first string enumerated
- for each match will be all of the text from end of the last match to the start
- of the current match, in addition there will be one extra string enumerated
- when no more matches can be found: from the end of the last match found, to the
- end of the underlying sequence.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
- Effects: returns the current character sequence being enumerated.
-
const value_type* operator->()const;
-
- Effects: returns &(*this).
-
regex_token_iterator& operator++();
-
- Effects: Moves on to the next character sequence to be enumerated.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
-
- Returns: *this.
regex_token_iterator& operator++(int);
-
Effects: constructs a copy result of *this,
- then calls ++(*this).
-
Returns:result.
-
Examples
-
The following example
- takes a string and splits it into a series of tokens:
Boost.regex is intended to conform to the
- regular expression standardization proposal, which will appear in a
- future C++ standard technical report (and hopefully in a future version of the
- standard). Currently there are some differences in how the regular
- expression traits classes are defined, these will be fixed in a future release.
-
ECMAScript / JavaScript
-
All of the ECMAScript regular expression syntax features are supported, except
- that:
-
Negated class escapes (\S, \D and \W) are not permitted inside character class
- definitions ( [...] ).
-
The escape sequence \u matches any upper case character (the same as
- [[:upper:]]) rather than a Unicode escape sequence; use \x{DDDD} for
- Unicode escape sequences.
-
Perl
-
Almost all Perl features are supported, except for:
-
\N{name} Use [[:name:]] instead.
-
\pP and \PP
-
(?imsx-imsx)
-
(?<=pattern)
-
(?<!pattern)
-
(?{code})
-
(??{code})
-
(?(condition)yes-pattern) and (?(condition)yes-pattern|no-pattern)
-
These embarrassments / limitations will be removed in due course, mainly
- dependent upon user demand.
-
POSIX
-
All the POSIX basic and extended regular expression features are supported,
- except that:
-
No character collating names are recognized except those specified in the POSIX
- standard for the C locale, unless they are explicitly registered with the
- traits class.
-
Character equivalence classes ( [[=a=]] etc) are probably buggy except on
- Win32. Implementing this feature requires knowledge of the format of the
- string sort keys produced by the system; if you need this, and the default
- implementation doesn't work on your platform, then you will need to supply a
- custom traits class.
Regular expressions are different from many simple pattern-matching algorithms
- in that as well as finding an overall match they can also produce
- sub-expression matches: each sub-expression being delimited in the pattern by a
- pair of parenthesis (...). There has to be some method for reporting
- sub-expression matches back to the user: this is achieved this by defining a
- class match_results that acts as an
- indexed collection of sub-expression matches, each sub-expression match being
- contained in an object of type sub_match
- .
-
Objects of type sub_match may only obtained by subscripting an object
- of type match_results
- .
-
Objects of type sub_match may be compared to objects of type std::basic_string,
- or const charT* or const charT
- .
-
Objects of type sub_match may be added to objects of type std::basic_string,
- or const charT* or const charT, to produce a new std::basic_string
-
- object.
-
When the marked sub-expression denoted by an object of type sub_match<>
- participated in a regular expression match then member matched evaluates
- to true, and members first and second denote the
- range of characters [first,second) which formed that match.
- Otherwise matched is false, and members first and second
- contained undefined values.
-
When the marked sub-expression denoted by an object of type sub_match<>
- was repeated, then the sub_match object represents the match obtained by the
- last repeat. The complete set of all the captures obtained for all the
- repeats, may be accessed via the captures() member function (Note: this has
- serious performance implications, you have to explicitly enable this feature).
-
If an object of type sub_match<> represents sub-expression 0
- - that is to say the whole match - then member matched is always
- true, unless a partial match was obtained as a result of the flag match_partial
- being passed to a regular expression algorithm, in which case member matched
- is false, and members first and second represent the
- character range that formed the partial match.
Defines an implementation-specific type that satisfies the requirements of
- a standard library Sequence (21.1.1 including the optional Table 68
- operations), whose value_type is a sub_match<BidirectionalIterator>. This
- type happens to be std::vector<sub_match<BidirectionalIterator> >,
- but you shouldn't actually rely on that.
Effects: returns a sequence containing all the captures
- obtained for this sub-expression.
-
Preconditions: the library must be built and used with
- BOOST_REGEX_MATCH_EXTRA defined, and you must pass the flag
- match_extra to the regex matching functions (regex_match,
- regex_search, regex_iterator
- or regex_token_iterator) in order for
- this member function to be defined and return useful information.
-
Rationale: Enabling this feature has several consequences:
-
-
-
- sub_match occupies more memory resulting in complex expressions running out of
- memory or stack space more quickly during matching.
-
- The matching algorithms are less efficient at handling some features
- (independent sub-expressions for example), even when match_extra is not used.
-
- The matching algorithms are much less efficient (i.e. slower), when match_extra
- is used. Mostly this is down to the extra memory allocations that have to
- take place.
The addition operators for sub_match allow you to add a sub_match to any type
- to which you can add a std::string and obtain a new string as the result.
This section covers the regular expression syntax used by this library, this is
- a programmers guide, the actual syntax presented to your program's users will
- depend upon the flags used during expression compilation.
-
-
Literals
-
-
All characters are literals except: ".", "|", "*", "?", "+", "(", ")", "{",
- "}", "[", "]", "^", "$" and "\". These characters are literals when preceded by
- a "\". A literal is a character that matches itself, or matches the result of
- traits_type::translate(), where traits_type is the traits template parameter to
- class basic_regex.
-
Wildcard
-
-
The dot character "." matches any single character except : when match_not_dot_null
- is passed to the matching algorithms, the dot does not match a null character;
- when match_not_dot_newline is passed to the matching algorithms, then
- the dot does not match a newline character.
-
-
Repeats
-
-
A repeat is an expression that is repeated an arbitrary number of times. An
- expression followed by "*" can be repeated any number of times including zero.
- An expression followed by "+" can be repeated any number of times, but at least
- once, if the expression is compiled with the flag regex_constants::bk_plus_qm
- then "+" is an ordinary character and "\+" represents a repeat of once or more.
- An expression followed by "?" may be repeated zero or one times only, if the
- expression is compiled with the flag regex_constants::bk_plus_qm then "?" is an
- ordinary character and "\?" represents the repeat zero or once operator. When
- it is necessary to specify the minimum and maximum number of repeats
- explicitly, the bounds operator "{}" may be used, thus "a{2}" is the letter "a"
- repeated exactly twice, "a{2,4}" represents the letter "a" repeated between 2
- and 4 times, and "a{2,}" represents the letter "a" repeated at least twice with
- no upper limit. Note that there must be no white-space inside the {}, and there
- is no upper limit on the values of the lower and upper bounds. When the
- expression is compiled with the flag regex_constants::bk_braces then "{" and
- "}" are ordinary characters and "\{" and "\}" are used to delimit bounds
- instead. All repeat expressions refer to the shortest possible previous
- sub-expression: a single character; a character set, or a sub-expression
- grouped with "()" for example.
-
-
Examples:
-
-
"ba*" will match all of "b", "ba", "baaa" etc.
-
-
"ba+" will match "ba" or "baaaa" for example but not "b".
-
-
"ba?" will match "b" or "ba".
-
-
"ba{2,4}" will match "baa", "baaa" and "baaaa".
-
-
Non-greedy repeats
-
-
Whenever the "extended" regular expression syntax is in use (the default) then
- non-greedy repeats are possible by appending a '?' after the repeat; a
- non-greedy repeat is one which will match the shortest possible string.
-
-
For example to match html tag pairs one could use something like:
-
-
"<\s*tagname[^>]*>(.*?)<\s*/tagname\s*>"
-
-
In this case $1 will contain the text between the tag pairs, and will be the
- shortest possible matching string.
-
-
Parenthesis
-
-
Parentheses serve two purposes, to group items together into a sub-expression,
- and to mark what generated the match. For example the expression "(ab)*" would
- match all of the string "ababab". The matching algorithms
- regex_match and regex_search each take
- an instance of match_results that reports what
- caused the match, on exit from these functions the match_results
- contains information both on what the whole expression matched and on what each
- sub-expression matched. In the example above match_results[1] would contain a
- pair of iterators denoting the final "ab" of the matching string. It is
- permissible for sub-expressions to match null strings. If a sub-expression
- takes no part in a match - for example if it is part of an alternative that is
- not taken - then both of the iterators that are returned for that
- sub-expression point to the end of the input string, and the matched parameter
- for that sub-expression is false. Sub-expressions are indexed from left
- to right starting from 1, sub-expression 0 is the whole expression.
-
-
Non-Marking Parenthesis
-
-
Sometimes you need to group sub-expressions with parenthesis, but don't want
- the parenthesis to spit out another marked sub-expression, in this case a
- non-marking parenthesis (?:expression) can be used. For example the following
- expression creates no sub-expressions:
-
-
"(?:abc)*"
-
Forward Lookahead Asserts
-
-
There are two forms of these; one for positive forward lookahead asserts, and
- one for negative lookahead asserts:
-
"(?=abc)" matches zero characters only if they are followed by the expression
- "abc".
-
"(?!abc)" matches zero characters only if they are not followed by the
- expression "abc".
-
Independent sub-expressions
-
"(?>expression)" matches "expression" as an independent atom (the algorithm
- will not backtrack into it if a failure occurs later in the expression).
-
Alternatives
-
-
Alternatives occur when the expression can match either one sub-expression or
- another, each alternative is separated by a "|", or a "\|" if the flag
- regex_constants::bk_vbar is set, or by a newline character if the flag
- regex_constants::newline_alt is set. Each alternative is the largest possible
- previous sub-expression; this is the opposite behavior from repetition
- operators.
-
-
Examples:
-
-
"a(b|c)" could match "ab" or "ac".
-
-
"abc|def" could match "abc" or "def".
-
-
Sets
-
-
A set is a set of characters that can match any single character that is a
- member of the set. Sets are delimited by "[" and "]" and can contain literals,
- character ranges, character classes, collating elements and equivalence
- classes. Set declarations that start with "^" contain the complement of the
- elements that follow.
-
-
Examples:
-
-
Character literals:
-
-
"[abc]" will match either of "a", "b", or "c".
-
-
"[^abc] will match any character other than "a", "b", or "c".
-
-
Character ranges:
-
-
"[a-z]" will match any character in the range "a" to "z".
-
-
"[^A-Z]" will match any character other than those in the range "A" to "Z".
-
-
Note that character ranges are highly locale dependent if the flag
- regex_constants::collate is set: they match any character that collates between
- the endpoints of the range, ranges will only behave according to ASCII rules
- when the default "C" locale is in effect. For example if the library is
- compiled with the Win32 localization model, then [a-z] will match the ASCII
- characters a-z, and also 'A', 'B' etc, but not 'Z' which collates just after
- 'z'. This locale specific behavior is disabled by default (in perl mode), and
- forces ranges to collate according to ASCII character code.
-
-
Character classes are denoted using the syntax "[:classname:]" within a set
- declaration, for example "[[:space:]]" is the set of all whitespace characters.
- Character classes are only available if the flag regex_constants::char_classes
- is set. The available character classes are:
-
-
-
-
-
-
-
-
alnum
-
Any alpha numeric character.
-
-
-
-
-
alpha
-
Any alphabetical character a-z and A-Z. Other
- characters may also be included depending upon the locale.
-
-
-
-
-
blank
-
Any blank character, either a space or a tab.
-
-
-
-
-
cntrl
-
Any control character.
-
-
-
-
-
digit
-
Any digit 0-9.
-
-
-
-
-
graph
-
Any graphical character.
-
-
-
-
-
lower
-
Any lower case character a-z. Other characters may
- also be included depending upon the locale.
-
-
-
-
-
print
-
Any printable character.
-
-
-
-
-
punct
-
Any punctuation character.
-
-
-
-
-
space
-
Any whitespace character.
-
-
-
-
-
upper
-
Any upper case character A-Z. Other characters may
- also be included depending upon the locale.
-
-
-
-
-
xdigit
-
Any hexadecimal digit character, 0-9, a-f and A-F.
-
-
-
-
-
word
-
Any word character - all alphanumeric characters plus
- the underscore.
-
-
-
-
-
Unicode
-
Any character whose code is greater than 255, this
- applies to the wide character traits classes only.
-
-
-
-
-
There are some shortcuts that can be used in place of the character classes,
- provided the flag regex_constants::escape_in_lists is set then you can use:
-
-
\w in place of [:word:]
-
-
\s in place of [:space:]
-
-
\d in place of [:digit:]
-
-
\l in place of [:lower:]
-
-
\u in place of [:upper:]
-
-
Collating elements take the general form [.tagname.] inside a set declaration,
- where tagname is either a single character, or a name of a collating
- element, for example [[.a.]] is equivalent to [a], and [[.comma.]] is
- equivalent to [,]. The library supports all the standard POSIX collating
- element names, and in addition the following digraphs: "ae", "ch", "ll", "ss",
- "nj", "dz", "lj", each in lower, upper and title case variations.
- Multi-character collating elements can result in the set matching more than one
- character, for example [[.ae.]] would match two characters, but note that
- [^[.ae.]] would only match one character.
-
-
- Equivalence classes take the generalform[=tagname=] inside a set declaration,
- where tagname is either a single character, or a name of a collating
- element, and matches any character that is a member of the same primary
- equivalence class as the collating element [.tagname.]. An equivalence class is
- a set of characters that collate the same, a primary equivalence class is a set
- of characters whose primary sort key are all the same (for example strings are
- typically collated by character, then by accent, and then by case; the primary
- sort key then relates to the character, the secondary to the accentation, and
- the tertiary to the case). If there is no equivalence class corresponding to tagname
- ,then[=tagname=] is exactly the same as [.tagname.]. Unfortunately there is no
- locale independent method of obtaining the primary sort key for a character,
- except under Win32. For other operating systems the library will "guess" the
- primary sort key from the full sort key (obtained from strxfrm), so
- equivalence classes are probably best considered broken under any operating
- system other than Win32.
-
-
To include a literal "-" in a set declaration then: make it the first character
- after the opening "[" or "[^", the endpoint of a range, a collating element, or
- if the flag regex_constants::escape_in_lists is set then precede with an escape
- character as in "[\-]". To include a literal "[" or "]" or "^" in a set then
- make them the endpoint of a range, a collating element, or precede with an
- escape character if the flag regex_constants::escape_in_lists is set.
-
-
Line anchors
-
-
An anchor is something that matches the null string at the start or end of a
- line: "^" matches the null string at the start of a line, "$" matches the null
- string at the end of a line.
-
-
Back references
-
-
A back reference is a reference to a previous sub-expression that has already
- been matched, the reference is to what the sub-expression matched, not to the
- expression itself. A back reference consists of the escape character "\"
- followed by a digit "1" to "9", "\1" refers to the first sub-expression, "\2"
- to the second etc. For example the expression "(.*)\1" matches any string that
- is repeated about its mid-point for example "abcabc" or "xyzxyz". A back
- reference to a sub-expression that did not participate in any match, matches
- the null string: NB this is different to some other regular expression
- matchers. Back references are only available if the expression is compiled with
- the flag regex_constants::bk_refs set.
-
-
Characters by code
-
-
This is an extension to the algorithm that is not available in other libraries,
- it consists of the escape character followed by the digit "0" followed by the
- octal character code. For example "\023" represents the character whose octal
- code is 23. Where ambiguity could occur use parentheses to break the expression
- up: "\0103" represents the character whose code is 103, "(\010)3 represents the
- character 10 followed by "3". To match characters by their hexadecimal code,
- use \x followed by a string of hexadecimal digits, optionally enclosed inside
- {}, for example \xf0 or \x{aff}, notice the latter example is a Unicode
- character.
-
Word operators
-
-
The following operators are provided for compatibility with the GNU regular
- expression library.
-
-
"\w" matches any single character that is a member of the "word" character
- class, this is identical to the expression "[[:word:]]".
-
-
"\W" matches any single character that is not a member of the "word" character
- class, this is identical to the expression "[^[:word:]]".
-
-
"\<" matches the null string at the start of a word.
-
-
"\>" matches the null string at the end of the word.
-
-
"\b" matches the null string at either the start or the end of a word.
-
-
"\B" matches a null string within a word.
-
-
The start of the sequence passed to the matching algorithms is considered to be
- a potential start of a word unless the flag match_not_bow is set. The end of
- the sequence passed to the matching algorithms is considered to be a potential
- end of a word unless the flag match_not_eow is set.
-
-
Buffer operators
-
-
The following operators are provided for compatibility with the GNU regular
- expression library, and Perl regular expressions:
-
-
"\`" matches the start of a buffer.
-
-
"\A" matches the start of the buffer.
-
-
"\'" matches the end of a buffer.
-
-
"\z" matches the end of a buffer.
-
-
"\Z" matches the end of a buffer, or possibly one or more new line characters
- followed by the end of the buffer.
-
-
A buffer is considered to consist of the whole sequence passed to the matching
- algorithms, unless the flags match_not_bob or match_not_eob are set.
-
-
Escape operator
-
-
The escape character "\" has several meanings.
-
-
Inside a set declaration the escape character is a normal character unless the
- flag regex_constants::escape_in_lists is set in which case whatever follows the
- escape is a literal character regardless of its normal meaning.
-
-
The escape operator may introduce an operator for example: back references, or
- a word operator.
-
-
The escape operator may make the following character normal, for example "\*"
- represents a literal "*" rather than the repeat operator.
-
-
Single character escape sequences
-
-
The following escape sequences are aliases for single characters:
-
-
-
-
-
-
-
-
Escape sequence
-
-
Character code
-
-
Meaning
-
-
-
-
-
-
\a
-
-
0x07
-
-
Bell character.
-
-
-
-
-
-
\f
-
-
0x0C
-
-
Form feed.
-
-
-
-
-
-
\n
-
-
0x0A
-
-
Newline character.
-
-
-
-
-
-
\r
-
-
0x0D
-
-
Carriage return.
-
-
-
-
-
-
\t
-
-
0x09
-
-
Tab character.
-
-
-
-
-
-
\v
-
-
0x0B
-
-
Vertical tab.
-
-
-
-
-
-
\e
-
-
0x1B
-
-
ASCII Escape character.
-
-
-
-
-
-
\0dd
-
-
0dd
-
-
An octal character code, where dd is one or
- more octal digits.
-
-
-
-
-
-
\xXX
-
-
0xXX
-
-
A hexadecimal character code, where XX is one or more
- hexadecimal digits.
-
-
-
-
-
-
\x{XX}
-
-
0xXX
-
-
A hexadecimal character code, where XX is one or more
- hexadecimal digits, optionally a Unicode character.
-
-
-
-
-
-
\cZ
-
-
z-@
-
-
An ASCII escape sequence control-Z, where Z is any
- ASCII character greater than or equal to the character code for '@'.
-
-
-
-
-
-
Miscellaneous escape sequences:
-
-
The following are provided mostly for perl compatibility, but note that there
- are some differences in the meanings of \l \L \u and \U:
-
-
-
-
-
-
-
-
\w
-
-
Equivalent to [[:word:]].
-
-
-
-
-
-
\W
-
-
Equivalent to [^[:word:]].
-
-
-
-
-
-
\s
-
-
Equivalent to [[:space:]].
-
-
-
-
-
-
\S
-
-
Equivalent to [^[:space:]].
-
-
-
-
-
-
\d
-
-
Equivalent to [[:digit:]].
-
-
-
-
-
-
\D
-
-
Equivalent to [^[:digit:]].
-
-
-
-
-
-
\l
-
-
Equivalent to [[:lower:]].
-
-
-
-
-
-
\L
-
-
Equivalent to [^[:lower:]].
-
-
-
-
-
-
\u
-
-
Equivalent to [[:upper:]].
-
-
-
-
-
-
\U
-
-
Equivalent to [^[:upper:]].
-
-
-
-
-
-
\C
-
-
Any single character, equivalent to '.'.
-
-
-
-
-
-
\X
-
-
Match any Unicode combining character sequence, for
- example "a\x 0301" (a letter a with an acute).
-
-
-
-
-
-
\Q
-
-
The begin quote operator, everything that follows is
- treated as a literal character until a \E end quote operator is found.
-
-
-
-
-
-
\E
-
-
The end quote operator, terminates a sequence begun
- with \Q.
-
-
-
-
-
-
What gets matched?
-
-
- When the expression is compiled as a Perl-compatible regex then the matching
- algorithms will perform a depth first search on the state machine and report
- the first match found.
-
- When the expression is compiled as a POSIX-compatible regex then the matching
- algorithms will match the first possible matching string, if more than one
- string starting at a given location can match then it matches the longest
- possible string, unless the flag match_any is set, in which case the first
- match encountered is returned. Use of the match_any option can reduce the time
- taken to find the match - but is only useful if the user is less concerned
- about what matched - for example it would not be suitable for search and
- replace operations. In cases where their are multiple possible matches all
- starting at the same location, and all of the same length, then the match
- chosen is the one with the longest first sub-expression, if that is the same
- for two or more matches, then the second sub-expression will be examined and so
- on.
-
-
- The following table examples illustrate the main differences between Perl and
- POSIX regular expression matching rules:
-
-
-
-
-
-
-
Expression
-
-
-
Text
-
-
-
POSIX leftmost longest match
-
-
-
ECMAScript depth first search match
-
-
-
-
-
a|ab
-
-
-
xaby
-
-
-
-
"ab"
-
-
-
"a"
-
-
-
-
-
.*([[:alnum:]]+).*
-
-
-
" abc def xyz "
-
-
-
$0 = " abc def xyz "
- $1 = "abc"
-
-
-
$0 = " abc def xyz "
- $1 = "z"
-
-
-
-
-
.*(a|xayy)
-
-
-
zzxayyzz
-
-
-
"zzxayy"
-
-
-
"zzxa"
-
-
-
-
These differences between Perl matching rules, and POSIX matching rules, mean
- that these two regular expression syntaxes differ not only in the features
- offered, but also in the form that the state machine takes and/or the
- algorithms used to traverse the state machine.
Type syntax_option type is an implementation specific bitmask type that
- controls how a regular expression string is to be interpreted. For
- convenience note that all the constants listed here, are also duplicated within
- the scope of class template basic_regex.
The type syntax_option_type is an implementation specific bitmask
- type (17.3.2.1.2). Setting its elements has the effects listed in the table
- below, a valid value of type syntax_option_type will always have
- exactly one of the elements normal, basic, extended, awk, grep, egrep, sed
- or perl set.
-
Note that for convenience all the constants listed here are duplicated within
- the scope of class template basic_regex, so you can use any of:
-
boost::regex_constants::constant_name
-
or
-
boost::regex::constant_name
-
or
-
boost::wregex::constant_name
-
in an interchangeable manner.
-
-
-
-
-
Element
-
-
-
Effect if set
-
-
-
-
-
normal
-
-
-
Specifies that the grammar recognized by the regular expression engine uses its
- normal semantics: that is the same as that given in the ECMA-262, ECMAScript
- Language Specification, Chapter 15 part 10, RegExp (Regular Expression) Objects
- (FWD.1).
-
boost.regex also recognizes most perl-compatible extensions in this mode.
-
-
-
-
-
icase
-
-
-
Specifies that matching of regular expressions against a character container
- sequence shall be performed without regard to case.
-
-
-
-
-
nosubs
-
-
-
Specifies that when a regular expression is matched against a character
- container sequence, then no sub-expression matches are to be stored in the
- supplied match_results structure.
-
-
-
-
-
optimize
-
-
-
Specifies that the regular expression engine should pay more attention to the
- speed with which regular expressions are matched, and less to the speed with
- which regular expression objects are constructed. Otherwise it has no
- detectable effect on the program output. This currently has no effect for
- boost.regex.
-
-
-
-
-
collate
-
-
-
Specifies that character ranges of the form "[a-b]" should be locale sensitive.
-
-
-
-
-
ECMAScript
-
-
-
The same as normal.
-
-
-
-
-
JavaScript
-
-
-
The same as normal.
-
-
-
-
-
JScript
-
-
-
The same as normal.
-
-
-
-
-
basic
-
-
-
Specifies that the grammar recognized by the regular expression engine is the
- same as that used by POSIX basic regular expressions in IEEE Std 1003.1-2001,
- Portable Operating System Interface (POSIX ), Base Definitions and Headers,
- Section 9, Regular Expressions (FWD.1).
-
-
-
-
-
-
extended
-
-
-
Specifies that the grammar recognized by the regular expression engine is the
- same as that used by POSIX extended regular expressions in IEEE Std
- 1003.1-2001, Portable Operating System Interface (POSIX ), Base Definitions and
- Headers, Section 9, Regular Expressions (FWD.1).
-
-
-
-
-
awk
-
-
-
Specifies that the grammar recognized by the regular expression engine is the
- same as that used by POSIX utility awk in IEEE Std 1003.1-2001, Portable
- Operating System Interface (POSIX ), Shells and Utilities, Section 4, awk
- (FWD.1).
-
That is to say: the same as POSIX extended syntax, but with escape sequences in
- character classes permitted.
-
-
-
-
-
grep
-
-
-
Specifies that the grammar recognized by the regular expression engine is the
- same as that used by POSIX utility grep in IEEE Std 1003.1-2001, Portable
- Operating System Interface (POSIX ), Shells and Utilities, Section 4,
- Utilities, grep (FWD.1).
-
That is to say, the same as POSIX basic syntax, but with the newline character
- acting as an alternation character in addition to "|".
-
-
-
-
-
egrep
-
-
-
Specifies that the grammar recognized by the regular expression engine is the
- same as that used by POSIX utility grep when given the -E option in IEEE Std
- 1003.1-2001, Portable Operating System Interface (POSIX ), Shells and
- Utilities, Section 4, Utilities, grep (FWD.1).
-
That is to say, the same as POSIX extended syntax, but with the newline
- character acting as an alternation character in addition to "|".
Allows the use of the escape "\" character in sets of
- characters, for example [\]] represents the set of characters containing only
- "]". If this flag is not set then "\" is an ordinary character inside sets.
-
-
-
regbase::char_classes
-
When this bit is set, character classes [:classname:]
- are allowed inside character set declarations, for example "[[:word:]]"
- represents the set of all characters that belong to the character class "word".
-
-
-
regbase:: intervals
-
When this bit is set, repetition intervals are
- allowed, for example "a{2,4}" represents a repeat of between 2 and 4 letter
- a's.
-
-
-
regbase:: limited_ops
-
When this bit is set all of "+", "?" and "|" are
- ordinary characters in all situations.
-
-
-
regbase:: newline_alt
-
When this bit is set, then the newline character "\n"
- has the same effect as the alternation operator "|".
-
-
-
regbase:: bk_plus_qm
-
When this bit is set then "\+" represents the one or
- more repetition operator and "\?" represents the zero or one repetition
- operator. When this bit is not set then "+" and "?" are used instead.
-
-
-
regbase:: bk_braces
-
When this bit is set then "\{" and "\}" are used for
- bounded repetitions and "{" and "}" are normal characters. This is the opposite
- of default behavior.
-
-
-
regbase:: bk_parens
-
When this bit is set then "\(" and "\)" are used to
- group sub-expressions and "(" and ")" are ordinary characters, this is the
- opposite of default behavior.
-
-
-
regbase:: bk_refs
-
When this bit is set then back references are
- allowed.
-
-
-
regbase:: bk_vbar
-
When this bit is set then "\|" represents the
- alternation operator and "|" is an ordinary character. This is the opposite of
- default behavior.
-
-
-
regbase:: use_except
-
When this bit is set then a bad_expression
- exception will be thrown on error. Use of this flag is deprecated -
- basic_regex will always throw on error.
-
-
-
regbase:: failbit
-
This bit is set on error, if regbase::use_except is
- not set, then this bit should be checked to see if a regular expression is
- valid before usage.
-
-
-
regbase::literal
-
All characters in the string are treated as literals,
- there are no special characters or escape sequences.
-
-
-
regbase::emacs
-
Provides compatability with the emacs
- editor, eqivalent to: bk_braces | bk_parens | bk_refs | bk_vbar.
The regex library is thread safe when Boost is: you can verify that Boost is in
- thread safe mode by checking to see if BOOST_HAS_THREADS is defined: this macro
- is set automatically by the config system when threading support is turned on
- in your compiler.
-
-
Class basic_regex<> and its typedefs regex
- and wregex are thread safe, in that compiled regular expressions can safely be
- shared between threads. The matching algorithms regex_match,
- regex_search, regex_grep,
- regex_format and regex_merge
- are all re-entrant and thread safe. Class match_results
- is now thread safe, in that the results of a match can be safely copied from
- one thread to another (for example one thread may find matches and push
- match_results instances onto a queue, while another thread pops them off the
- other end), otherwise use a separate instance of match_results
- per thread.
-
-
The POSIX API functions are all re-entrant and
- thread safe, regular expressions compiled with regcomp can also be
- shared between threads.
-
-
The class RegEx is only thread safe if each thread
- gets its own RegEx instance (apartment threading) - this is a consequence of
- RegEx handling both compiling and matching regular expressions.
-
-
Finally note that changing the global locale invalidates all compiled regular
- expressions, therefore calling set_locale from one thread while another
- uses regular expressions will produce unpredictable results.
-
-
- There is also a requirement that there is only one thread executing prior to
- the start of main().
The class bad_expression defines the type of objects thrown as
- exceptions to report errors during the conversion from a string representing a
- regular expression to a finite state machine.
Footnotes: the class bad_pattern forms the base class for all
- pattern-matching exceptions, of which bad_expression is one. The choice
- of std::runtime_error as the base class for bad_pattern is moot;
- depending upon how the library is used exceptions may be either logic errors
- (programmer supplied expressions) or run time errors (user supplied
- expressions).
The template class basic_regex encapsulates regular expression parsing
- and compilation. The class takes three template parameters:
-
charT: determines the character type, i.e. either char or
- wchar_t.
-
traits: determines the behavior of the character type, for
- example which character class names are recognized. A default traits class is
- provided: regex_traits<charT>.
-
Allocator: the allocator class used to allocate memory by the
- class.
-
For ease of use there are two typedefs that define the two standard basic_regex
- instances, unless you want to use custom traits classes or allocators, you
- won't need to use anything other than these:
The definition of basic_regex follows: it is based very closely on class
- basic_string, and fulfils the requirements for a constant-container of charT.
The static constant members are provided as synonyms for the constants declared
- in namespace boost::regex_constants; for each constant of type
- syntax_option_type declared in namespace boost::regex_constants
- then a constant with the same name, type and value is declared within the scope
- of basic_regex.
-
basic_regex constructors
-
In all basic_regex constructors, a copy of the Allocator
- argument is used for any memory allocation performed by the constructor or
- member functions during the lifetime of the object.
-
-basic_regex(const Allocator& a = Allocator());
-
-
Effects: Constructs an object of class basic_regex. The
- postconditions of this function are indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
true
-
-
-
-
-
size()
-
-
-
0
-
-
-
-
-
str()
-
-
-
basic_string<charT>()
-
-
-
-
-
-
-
basic_regex(const charT* p, flag_type f = regex_constants::normal, const Allocator& a = Allocator());
-
-
-
Requires:p shall not be a null pointer.
-
Throws:bad_expression if p is not a valid regular
- expression.
-
Effects: Constructs an object of class basic_regex; the
- object's internal finite state machine is constructed from the regular
- expression contained in the null-terminated string p, and interpreted
- according to the option flags specified
- in f. The postconditions of this function are indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
false
-
-
-
-
-
size()
-
-
-
char_traits<charT>::length(p)
-
-
-
-
-
str()
-
-
-
basic_string<charT>(p)
-
-
-
-
-
flags()
-
-
-
f
-
-
-
-
-
mark_count()
-
-
-
The number of marked sub-expressions within the expression.
-
-
-
-
-
-
-
-
-
-
basic_regex(const charT* p1, const charT* p2, flag_type f = regex_constants::normal, const Allocator& a = Allocator());
-
Requires:p1 and p2 are not null pointers, p1 < p2.
-
Throws:bad_expression if [p1,p2) is not a valid regular
- expression.
-
Effects: Constructs an object of class basic_regex; the
- object's internal finite state machine is constructed from the regular
- expression contained in the sequence of characters [p1,p2), and interpreted
- according the option flags specified in f.
- The postconditions of this function are indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
false
-
-
-
-
-
size()
-
-
-
std::distance(p1,p2)
-
-
-
-
-
str()
-
-
-
basic_string<charT>(p1,p2)
-
-
-
-
-
flags()
-
-
-
f
-
-
-
-
-
mark_count()
-
-
-
The number of marked sub-expressions within the expression.
Requires:p shall not be a null pointer, len < max_size().
-
Throws:bad_expression if p is not a valid regular
- expression.
-
Effects: Constructs an object of class basic_regex; the
- object's internal finite state machine is constructed from the regular
- expression contained in the sequence of characters [p, p+len), and interpreted
- according the option flags specified in f.
- The postconditions of this function are indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
false
-
-
-
-
-
size()
-
-
-
len
-
-
-
-
-
str()
-
-
-
basic_string<charT>(p, len)
-
-
-
-
-
flags()
-
-
-
f
-
-
-
-
-
mark_count()
-
-
-
The number of marked sub-expressions within the expression.
-
-
-
-
-
-
-
-
-
-
-basic_regex(const basic_regex& e);
-
-
Effects: Constructs an object of class basic_regex as a
- copy of the object e. The postconditions of this function are indicated
- in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
e.empty()
-
-
-
-
-
size()
-
-
-
e.size()
-
-
-
-
-
str()
-
-
-
e.str()
-
-
-
-
-
flags()
-
-
-
e.flags()
-
-
-
-
-
mark_count()
-
-
-
e.mark_count()
-
-
-
-
-
-
-
-
-
-
-template <class ST, class SA>
-
-basic_regex(const basic_string<charT, ST, SA>& s,
- flag_type f = regex_constants::normal, const Allocator& a = Allocator());
-
-
Throws:bad_expression if s is not a valid regular
- expression.
-
Effects: Constructs an object of class basic_regex; the
- object's internal finite state machine is constructed from the regular
- expression contained in the string s, and interpreted according to the
- option flags specified in f. The postconditions of this function
- are indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
false
-
-
-
-
-
size()
-
-
-
s.size()
-
-
-
-
-
str()
-
-
-
s
-
-
-
-
-
flags()
-
-
-
f
-
-
-
-
-
mark_count()
-
-
-
The number of marked sub-expressions within the expression.
-
-
-
-
-
-
-
-
-
-
-template <class ForwardIterator>
-
-basic_regex(ForwardIterator first, ForwardIterator last,
- flag_type f = regex_constants::normal, const Allocator& a = Allocator());
-
-
Throws:bad_expression if the sequence [first, last)
- is not a valid regular expression.
-
Effects: Constructs an object of class basic_regex; the
- object's internal finite state machine is constructed from the regular
- expression contained in the sequence of characters [first, last), and
- interpreted according to the option flags
- specified in f. The postconditions of this function are indicated in the
- table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
false
-
-
-
-
-
size()
-
-
-
distance(first,last)
-
-
-
-
-
str()
-
-
-
basic_string<charT>(first,last)
-
-
-
-
-
flags()
-
-
-
f
-
-
-
-
-
mark_count()
-
-
-
The number of marked sub-expressions within the expression.
-
-
-
-
-
-
-
-
-
-
-basic_regex& operator=(const basic_regex& e);
-
-
Effects: Returns the result of assign(e.str(), e.flags()).
template <class string_traits, class A>
-basic_regex& assign(const basic_string<charT, string_traits, A>& s,
- flag_type f = regex_constants::normal);
-
-
Throws:bad_expression if s is not a valid regular
- expression.
-
Returns:*this.
-
Effects: Assigns the regular expression contained in the string s,
- interpreted according the option flags specified
- in f. The postconditions of this function are indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
false
-
-
-
-
-
size()
-
-
-
s.size()
-
-
-
-
-
str()
-
-
-
s
-
-
-
-
-
flags()
-
-
-
f
-
-
-
-
-
mark_count()
-
-
-
The number of marked sub-expressions within the expression.
-
-
-
-
-
-
-
-
-
-
template <class InputIterator>
-basic_regex& assign(InputIterator first, InputIterator last,
- flag_type f = regex_constants::normal);
-
-
Requires: The type InputIterator corresponds to the Input Iterator
- requirements (24.1.1).
Effects: Returns a copy of the Allocator that was passed to the object's
- constructor.
-
flag_type flags() const;
-
-
Effects: Returns a copy of the regular expression syntax flags that were
- passed to the object's constructor, or the last call to assign.
-
basic_string<charT> str() const;
-
-
Effects: Returns a copy of the character sequence passed to the object's
- constructor, or the last call to assign.
-
int compare(basic_regex& e)const;
-
-
Effects: If flags() == e.flags() then returns str().compare(e.str()),
- otherwise returns flags() - e.flags().
-
basic_regex locale
-
locale_type imbue(locale_type l);
-
-
Effects: Returns the result of traits_inst.imbue(l) where
- traits_inst is a (default initialized) instance of the template
- parameter traits stored within the object. Calls to imbue
- invalidate any currently contained regular expression.
-
Postcondition:empty() == true.
-
-locale_type getloc() const;
-
-
Effects: Returns the result of traits_inst.getloc() where
- traits_inst is a (default initialized) instance of the template
- parameter traits stored within the object.
-
basic_regex swap
-
-void swap(basic_regex& e) throw();
-
-
Effects: Swaps the contents of the two regular expressions.
-
Postcondition:*this contains the characters that were in e,
- e contains the regular expression that was in *this.
-
Complexity: constant time.
-
basic_regex non-member functions
-
basic_regex non-member comparison operators
-
Comparisons between basic_regex objects are provided on an experimental basis:
- please note that these are likely to be removed from the standard library
- proposal, so use with care if you are writing portable code.
Captures are the iterator ranges that are "captured" by marked sub-expressions
- as a regular expression gets matched. Each marked sub-expression can
- result in more than one capture, if it is matched more than once. This
- document explains how captures and marked sub-expressions in Boost.Regex are
- represented and accessed.
-
Marked sub-expressions
-
Every time a Perl regular expression contains a parenthesis group (), it spits
- out an extra field, known as a marked sub-expression, for example the
- expression:
-
(\w+)\W+(\w+)
-
- Has two marked sub-expressions (known as $1 and $2 respectively), in addition
- the complete match is known as $&, everything before the first match as $`,
- and everything after the match as $'. So if the above expression is
- searched for within "@abc def--", then we obtain:
The Perl and Boost.Regex equivalents are as follows:
-
-
-
-
-
Perl
-
Boost.Regex
-
-
-
$`
-
m.prefix()
-
-
-
$&
-
m[0]
-
-
-
$n
-
m[n]
-
-
-
$'
-
m.suffix()
-
-
-
-
-
-
In Boost.Regex each sub-expression match is represented by a
- sub_match object, this is basically just a pair of iterators denoting
- the start and end possition of the sub-expression match, but there are some
- additional operators provided so that objects of type sub_match behave a lot
- like a std::basic_string: for example they are implicitly
- convertible to a basic_string, they can be compared
- to a string, added to a string, or
- streamed out to an output stream.
-
Unmatched Sub-Expressions
-
When a regular expression match is found there is no need for all of the marked
- sub-expressions to have participated in the match, for example the expression:
-
(abc)|(def)
-
can match either $1 or $2, but never both at the same time. In
- Boost.Regex you can determine which sub-expressions matched by accessing the
- sub_match::matched data member.
-
Repeated Captures
-
When a marked sub-expression is repeated, then the sub-expression gets
- "captured" multiple times, however normally only the final capture is
- available, for example if
-
(?:(\w+)\W+)+
-
is matched against
-
one fine day
-
Then $1 will contain the string "day", and all the previous captures will have
- been forgotten.
-
However, Boost.Regex has an experimental feature that allows all the capture
- information to be retained - this is accessed either via the
- match_results::captures member function or the sub_match::captures
- member function. These functions return a container that contains a
- sequence of all the captures obtained during the regular expression
- matching. The following example program shows how this information may be
- used:
-
#include <boost/regex.hpp>
-#include <iostream>
-
-
-void print_captures(const std::string& regx, const std::string& text)
-{
- boost::regex e(regx);
- boost::smatch what;
- std::cout << "Expression: \"" << regx << "\"\n";
- std::cout << "Text: \"" << text << "\"\n";
- if(boost::regex_match(text, what, e, boost::match_extra))
- {
- unsigned i, j;
- std::cout << "** Match found **\n Sub-Expressions:\n";
- for(i = 0; i < what.size(); ++i)
- std::cout << " $" << i << " = \"" << what[i] << "\"\n";
- std::cout << " Captures:\n";
- for(i = 0; i < what.size(); ++i)
- {
- std::cout << " $" << i << " = {";
- for(j = 0; j < what.captures(i).size(); ++j)
- {
- if(j)
- std::cout << ", ";
- else
- std::cout << " ";
- std::cout << "\"" << what.captures(i)[j] << "\"";
- }
- std::cout << " }\n";
- }
- }
- else
- {
- std::cout << "** No Match found **\n";
- }
-}
-
-int main(int , char* [])
-{
- print_captures("(([[:lower:]]+)|([[:upper:]]+))+", "aBBcccDDDDDeeeeeeee");
- print_captures("(.*)bar|(.*)bah", "abcbar");
- print_captures("(.*)bar|(.*)bah", "abcbah");
- print_captures("^(?:(\\w+)|(?>\\W+))*$", "now is the time for all good men to come to the aid of the party");
- return 0;
-}
-
Which produces the following output:
-
Expression: "(([[:lower:]]+)|([[:upper:]]+))+"
-Text: "aBBcccDDDDDeeeeeeee"
-** Match found **
- Sub-Expressions:
- $0 = "aBBcccDDDDDeeeeeeee"
- $1 = "eeeeeeee"
- $2 = "eeeeeeee"
- $3 = "DDDDD"
- Captures:
- $0 = { "aBBcccDDDDDeeeeeeee" }
- $1 = { "a", "BB", "ccc", "DDDDD", "eeeeeeee" }
- $2 = { "a", "ccc", "eeeeeeee" }
- $3 = { "BB", "DDDDD" }
-Expression: "(.*)bar|(.*)bah"
-Text: "abcbar"
-** Match found **
- Sub-Expressions:
- $0 = "abcbar"
- $1 = "abc"
- $2 = ""
- Captures:
- $0 = { "abcbar" }
- $1 = { "abc" }
- $2 = { }
-Expression: "(.*)bar|(.*)bah"
-Text: "abcbah"
-** Match found **
- Sub-Expressions:
- $0 = "abcbah"
- $1 = ""
- $2 = "abc"
- Captures:
- $0 = { "abcbah" }
- $1 = { }
- $2 = { "abc" }
-Expression: "^(?:(\w+)|(?>\W+))*$"
-Text: "now is the time for all good men to come to the aid of the party"
-** Match found **
- Sub-Expressions:
- $0 = "now is the time for all good men to come to the aid of the party"
- $1 = "party"
- Captures:
- $0 = { "now is the time for all good men to come to the aid of the party" }
- $1 = { "now", "is", "the", "time", "for", "all", "good", "men", "to", "come", "to", "the", "aid", "of", "the", "party" }
-
-
Unfortunately enabling this feature has an impact on performance (even if you
- don't use it), and a much bigger impact if you do use it, therefore to use this
- feature you need to:
-
-
- Define BOOST_REGEX_MATCH_EXTRA for all translation units including the library
- source (the best way to do this is to uncomment this define in
- boost/regex/user.hpp
- and then rebuild everything.
-
You shouldn't need to do anything special to configure
-boost.regex for use with your compiler - the boost.config subsystem should already
-take care of it, if you do have problems (or you are using a
-particularly obscure compiler or platform) then boost.config has a configure script.
-
-
Locale and traits class selection.
-
-
The following macros (see user.hpp) control how
-boost.regex interacts with the user's locale:
-
-
-
-
BOOST_REGEX_USE_C_LOCALE
-
Forces boost.regex to use the global C locale in its traits
-class support: this is the default behavior on non-windows
-platforms, but MS Windows platforms normally use the Win32 API for
-locale support.
-
-
-
-
BOOST_REGEX_USE_CPP_LOCALE
-
Forces boost.regex to use std::locale in it's default traits
-class, regular expressions can then be imbued with an
-instance specific locale.
-
-
-
-
BOOST_REGEX_NO_W32
-
Tells boost.regex not to use any Win32 API's even when
-available (implies BOOST_REGEX_USE_C_LOCALE unless
-BOOST_REGEX_USE_CPP_LOCALE is set).
-
-
-
-
-
-
-
-
Linkage Options
-
-
-
-
BOOST_REGEX_DYN_LINK
-
For Microsoft and Borland C++ builds, this tells boost.regex
-that it should link to the dll build of the boost.regex. By
-default boost.regex will link to its static library build, even if
-the dynamic C runtime library is in use.
-
-
-
-
BOOST_REGEX_NO_LIB
-
For Microsoft and Borland C++ builds, this tells boost.regex
-that it should not automatically select the library to link
-to.
-
-
-
-
-
-
-
-
Algorithm Selection
-
-
-
-
BOOST_REGEX_V3
-
Tells boost.regex to use the boost-1.30.0 matching algorithm,
-define only if you need maximum compatibility with previous
-behavior.
-
-
-
-
BOOST_REGEX_RECURSIVE
-
Tells boost.regex to use a stack-recursive matching
-algorithm. This is generally the fastest option (although
-there is very little in it), but can cause stack overflow in
-extreme cases, on Win32 this can be handled safely, but this is not
-the case on other platforms.
-
-
-
-
BOOST_REGEX_NON_RECURSIVE
-
Tells boost.regex to use a non-stack recursive matching
-algorithm, this can be slightly slower than the alternative, but is
-always safe no matter how pathological the regular
-expression. This is the default on non-Win32 platforms.
-
-
-
-
-
-
-
-
Algorithm Tuning
-
-
The following option applies only if BOOST_REGEX_RECURSIVE is
-set.
-
-
-
-
BOOST_REGEX_HAS_MS_STACK_GUARD
-
Tells boost.regex that Microsoft style __try - __except blocks
-are supported, and can be used to safely trap stack overflow.
-
-
-
-
-
-
-
-
The following options apply only if BOOST_REGEX_NON_RECURSIVE is
-set.
-
-
-
-
BOOST_REGEX_BLOCKSIZE
-
In non-recursive mode, boost.regex uses largish blocks of
-memory to act as a stack for the state machine, the larger the
-block size then the fewer allocations that will take place.
-This defaults to 4096 bytes, which is large enough to match the
-vast majority of regular expressions without further
-allocations, however, you can choose smaller or larger values
-depending upon your platforms characteristics.
-
-
-
-
BOOST_REGEX_MAX_BLOCKS
-
Tells boost.regex how many blocks of size BOOST_REGEX_BLOCKSIZE
-it is permitted to use. If this value is exceeded then
-boost.regex will stop trying to find a match and throw a
-std::runtime_error. Defaults to 1024, don't forget to tweek
-this value if you alter BOOST_REGEX_BLOCKSIZE by much.
-
-
-
-
BOOST_REGEX_MAX_CACHE_BLOCKS
-
Tells boost.regex how many memory blocks to store in it's
-internal cache - memory blocks are taken from this cache rather
-than by calling ::operator new. Generally speeking this can
-be an order of magnitude faster than calling ::opertator new each
-time a memory block is required, but has the downside that
-boost.regex can end up caching a large chunk of memory (by default
-up to 16 blocks each of BOOST_REGEX_BLOCKSIZE size). If
-memory is tight then try defining this to 0 (disables all caching),
-or if that is too slow, then a value of 1 or 2, may be
-sufficient. On the other hand, on large multi-processor,
-multi-threaded systems, you may find that a higher value is in
-order.
The author can be contacted at john@johnmaddock.co.uk; the home page for
- this library is at www.boost.org.
-
I am indebted to Robert Sedgewick's
- "Algorithms in C++" for forcing me to think about algorithms and their
- performance, and to the folks at boost for
- forcing me to think, period.
Pete Becker, of Dinkumware Ltd, has
- helped enormously with the standardisation proposal language.
-
The following people have all contributed useful comments or fixes: Dave
- Abrahams, Mike Allison, Edan Ayal, Jayashree Balasubramanian, Jan Bölsche,
- Beman Dawes, Paul Baxter, David Bergman, David Dennerline, Edward Diener, Peter
- Dimov, Robert Dunn, Fabio Forno, Tobias Gabrielsson, Rob Gillen, Marc Gregoire,
- Chris Hecker, Nick Hodapp, Jesse Jones, Martin Jost, Boris Krasnovskiy, Jan
- Hermelink, Max Leung, Wei-hao Lin, Jens Maurer, Richard Peters, Heiko Schmidt,
- Jason Shirk, Gerald Slacik, Scobie Smith, Mike Smyth, Alexander Sokolovsky,
- Hervé Poirier, Michael Raykh, Marc Recht, Scott VanCamp, Bruno Voigt, Alexey
- Voinov, Jerry Waldorf, Rob Ward, Lealon Watts, John Wismar, Thomas Witt and
- Yuval Yosef. I am also grateful to the manuals supplied with the Henry Spencer,
- Perl and GNU regular expression libraries - wherever possible I have tried to
- maintain compatibility with these libraries and with the POSIX standard - the
- code however is entirely my own, including any bugs! I can absolutely guarantee
- that I will not fix any bugs I don't know about, so if you have any comments or
- spot any bugs, please get in touch.
-
Useful further information can be found at:
-
Short tutorials on regular expressions can be
- found here and here.
There are three demo applications that ship with this library, they all come
- with makefiles for Borland, Microsoft and gcc compilers, otherwise you will
- have to create your own makefiles.
-
regress.exe:
-
A regression test application that gives the matching/searching algorithms a
- full workout. The presence of this program is your guarantee that the library
- will behave as claimed - at least as far as those items tested are concerned -
- if anyone spots anything that isn't being tested I'd be glad to hear about it.
A simple grep implementation, run with no command line options to find out its
- usage. Look at fileiter.cpp/fileiter.hpp and
- the mapfile class to see an example of a "smart" bidirectional iterator that
- can be used with boost.regex or any other STL algorithm.
A simple interactive expression matching application, the results of all
- matches are timed, allowing the programmer to optimize their regular
- expressions where performance is critical.
Q. Why can't I
- use the "convenience" versions of regex_match / regex_search / regex_grep /
- regex_format / regex_merge?
-
A. These versions may or may not be available depending upon the capabilities
- of your compiler, the rules determining the format of these functions are quite
- complex - and only the versions visible to a standard compliant compiler are
- given in the help. To find out what your compiler supports, run
- <boost/regex.hpp> through your C++ pre-processor, and search the output
- file for the function that you are interested in.
-
Q. I can't get regex++ to work with
- escape characters, what's going on?
-
A. If you embed regular expressions in C++ code, then remember that escape
- characters are processed twice: once by the C++ compiler, and once by the
- regex++ expression compiler, so to pass the regular expression \d+ to regex++,
- you need to embed "\\d+" in your code. Likewise to match a literal backslash
- you will need to embed "\\\\" in your code.
-
-
Q. Why does using parenthesis in a POSIX regular expression
- change the result of a match?
-
For POSIX (extended and basic) regular expressions, but not for perl regexes,
- parentheses don't only mark; they determine what the best match is as well.
- When the expression is compiled as a POSIX basic or extended regex then
- Boost.regex follows the POSIX standard leftmost longest rule for determining
- what matched. So if there is more than one possible match after considering the
- whole expression, it looks next at the first sub-expression and then the second
- sub-expression and so on. So...
-
-"(0*)([0-9]*)" against "00123" would produce
-$1 = "00"
-$2 = "123"
-
-
where as
-
-"0*([0-9])*" against "00123" would produce
-$1 = "00123"
-
-
If you think about it, had $1 only matched the "123", this would be "less good"
- than the match "00123" which is both further to the left and longer. If you
- want $1 to match only the "123" part, then you need to use something like:
-
-"0*([1-9][0-9]*)"
-
-
as the expression.
-
Q. Why don't character ranges work properly (POSIX mode
- only)?
- A. The POSIX standard specifies that character range expressions are locale
- sensitive - so for example the expression [A-Z] will match any collating
- element that collates between 'A' and 'Z'. That means that for most locales
- other than "C" or "POSIX", [A-Z] would match the single character 't' for
- example, which is not what most people expect - or at least not what most
- people have come to expect from regular expression engines. For this reason,
- the default behaviour of boost.regex (perl mode) is to turn locale sensitive
- collation off by not setting the regex_constants::collate compile time flag.
- However if you set a non-default compile time flag - for example
- regex_constants::extended or regex_constants::basic, then locale dependent
- collation will be enabled, this also applies to the POSIX API functions which
- use either regex_constants::extended or regex_constants::basic internally. [Note
- - when regex_constants::nocollate in effect, the library behaves "as if" the
- LC_COLLATE locale category were always "C", regardless of what its actually set
- to - end note].
-
Q. Why are there no throw specifications on any of the
- functions? What exceptions can the library throw?
-
A. Not all compilers support (or honor) throw specifications, others support
- them but with reduced efficiency. Throw specifications may be added at a later
- date as compilers begin to handle this better. The library should throw only
- three types of exception: boost::bad_expression can be thrown by basic_regex
- when compiling a regular expression, std::runtime_error can be thrown when a
- call to basic_regex::imbue tries to open a message catalogue that doesn't
- exist, or when a call to regex_search or regex_match results in an
- "everlasting" search, or when a call to RegEx::GrepFiles or
- RegEx::FindFiles tries to open a file that cannot be opened, finally
- std::bad_alloc can be thrown by just about any of the functions in this
- library.
Format strings are used by the algorithm regex_replace and by match_results::format, and are used
-to transform one string into another.
-
-
There are three kind of format string: sed, Perl and extended,
-the extended syntax is a superset of the others so this is covered
-first.
-
-
Extended format syntax
-
-
In format strings, all characters are treated as literals
-except: ()$\?:
-
-
To use any of these as literals you must prefix them with the
-escape character \
-
-
The following special sequences are recognized:
-
- Grouping:
-
-
Use the parenthesis characters ( and ) to group sub-expressions
-within the format string, use \( and \) to represent literal '('
-and ')'.
-
- Sub-expression expansions:
-
-
The following Perl like expressions expand to a particular
-matched sub-expression:
-
-
-
-
-
-
-
-
$`
-
Expands to all the text from the end
-of the previous match to the start of the current match, if there
-was no previous match in the current operation, then everything
-from the start of the input string to the start of the match.
-
-
-
-
-
-
$'
-
Expands to all the text from the end
-of the match to the end of the input string.
-
-
-
-
-
-
$&
-
Expands to all of the current
-match.
-
-
-
-
-
-
$0
-
Expands to all of the current
-match.
-
-
-
-
-
-
$N
-
Expands to the text that matched
-sub-expression N.
-
-
-
-
-
-
-
-
-
Conditional expressions:
-
-
Conditional expressions allow two different format strings to be
-selected dependent upon whether a sub-expression participated in
-the match or not:
-
-
?Ntrue_expression:false_expression
-
-
Executes true_expression if sub-expression N participated
-in the match, otherwise executes false_expression.
-
-
Example: suppose we search for "(while)|(for)" then the format
-string "?1WHILE:FOR" would output what matched, but in upper
-case.
-
- Escape sequences:
-
-
The following escape sequences are also allowed:
-
-
-
-
-
-
-
-
\a
-
The bell character.
-
-
-
-
-
-
\f
-
The form feed character.
-
-
-
-
-
-
\n
-
The newline character.
-
-
-
-
-
-
\r
-
The carriage return character.
-
-
-
-
-
-
\t
-
The tab character.
-
-
-
-
-
-
\v
-
A vertical tab character.
-
-
-
-
-
-
\x
-
A hexadecimal character - for example
-\x0D.
-
-
-
-
-
-
\x{}
-
A possible Unicode hexadecimal
-character - for example \x{1A0}
-
-
-
-
-
-
\cx
-
The ASCII escape character x, for
-example \c@ is equivalent to escape-@.
-
-
-
-
-
-
\e
-
The ASCII escape character.
-
-
-
-
-
-
\dd
-
An octal character constant, for
-example \10.
-
-
-
-
-
-
-
-
-
Perl format strings
-
-
Perl format strings are the same as the default syntax except
-that the characters ()?: have no special meaning.
-
-
Sed format strings
-
-
Sed format strings use only the characters \ and & as
-special characters.
-
-
\n where n is a digit, is expanded to the nth
-sub-expression.
-
-
& is expanded to the whole of the match (equivalent to
-\0).
-
-
Other escape sequences are expanded as per the default
-syntax.
Compiler: GNU C++ version 3.2 20020927 (prerelease).
-
C++ Standard Library: GNU libstdc++ version 20020927.
-
OS: Cygwin.
-
Boost version: 1.31.0.
-
PCRE version: 4.1.
-
As ever care should be taken in interpreting the results, only sensible regular
- expressions (rather than pathological cases) are given, most are taken from the
- Boost regex examples, or from the Library of
- Regular Expressions. In addition, some variation in the relative
- performance of these libraries can be expected on other machines - as memory
- access and processor caching effects can be quite large for most finite state
- machine algorithms. In each case the first figure given is the relative time
- taken (so a value of 1.0 is as good as it gets), while the second figure is the
- actual time taken.
-
Averages
-
The following are the average relative scores for all the tests: the perfect
- regular expression library would score 1, in practice anything less than 2
- is pretty good.
-
-
-
Boost
-
Boost + C++ locale
-
POSIX
-
PCRE
-
-
-
1.4503
-
1.49124
-
108.372
-
1.56255
-
-
-
-
-
Comparison 1: Long Search
-
For each of the following regular expressions the time taken to find all
- occurrences of the expression within a long English language text was measured
- (mtent12.txt
- from Project Gutenberg, 19Mb).
For each of the following regular expressions the time taken to find all
- occurrences of the expression within a medium sized English language text was
- measured (the first 50K from mtent12.txt).
For each of the following regular expressions the time taken to find all
- occurrences of the expression within the C++ source file
- boost/crc.hpp was measured.
For each of the following regular expressions the time taken to find all
- occurrences of the expression within the html file libs/libraries.htm
- was measured.
There are two main headers used by this library: <boost/regex.hpp>
- provides full access to the entire library, while <boost/cregex.hpp>
- provides access to just the high level class RegEx, and the POSIX API
- functions.
-
-
There is also a header containing only forward declarations
- <boost/regex_fwd.hpp> for use when an interface is dependent upon
- boost::basic_regex, but otherwise does not need the full definitions.
- Added support for Perl style independent sub-expressions.
-
- Added non-member operators to the sub_match class,
- so that you can compare sub_match's with strings, or add them to a string to
- produce a new string.
-
- Changed the match flags so that they are a distinct type (not an integer), if
- you try to pass the match flags as an integer rather than
- match_flag_type to the regex algorithms then you will now get a compiler
- error.
When you extract the library from its zip file, you must preserve its internal
- directory structure (for example by using the -d option when extracting). If
- you didn't do that when extracting, then you'd better stop reading this, delete
- the files you just extracted, and try again!
-
-
This library should not need configuring before use; most popular
- compilers/standard libraries/platforms are already supported "as is". If you do
- experience configuration problems, or just want to test the configuration with
- your compiler, then the process is the same as for all of boost; see the
- configuration library documentation.
-
The library will encase all code inside namespace boost.
-
-
Unlike some other template libraries, this library consists of a mixture of
- template code (in the headers) and static code and data (in cpp files).
- Consequently it is necessary to build the library's support code into a library
- or archive file before you can use it, instructions for specific platforms are
- as follows:
-
-
Borland C++ Builder:
-
-
-
- Open up a console window and change to the <boost>\libs\regex\build
- directory.
-
- Select the appropriate makefile (bcb4.mak for C++ Builder 4, bcb5.mak for C++
- Builder 5, and bcb6.mak for C++ Builder 6).
-
- Invoke the makefile (pass the full path to your version of make if you have
- more than one version installed, the makefile relies on the path to make to
- obtain your C++ Builder installation directory and tools) for example:
-
-
-
make -fbcb5.mak
-
The build process will build a variety of .lib and .dll files (the exact number
- depends upon the version of Borland's tools you are using) the .lib and dll
- files will be in a sub-directory called bcb4 or bcb5 depending upon the
- makefile used. To install the libraries into your development system use:
-
make -fbcb5.mak install
-
library files will be copied to <BCROOT>/lib and the dll's to
- <BCROOT>/bin, where <BCROOT> corresponds to the install path of
- your Borland C++ tools.
-
-
You may also remove temporary files created during the build process (excluding
- lib and dll files) by using:
-
make -fbcb5.mak clean
-
Finally when you use regex++ it is only necessary for you to add the
- <boost> root director to your list of include directories for that
- project. It is not necessary for you to manually add a .lib file to the
- project; the headers will automatically select the correct .lib file for your
- build mode and tell the linker to include it. There is one caveat however: the
- library can not tell the difference between VCL and non-VCL enabled builds when
- building a GUI application from the command line, if you build from the command
- line with the 5.5 command line tools then you must define the pre-processor
- symbol _NO_VCL in order to ensure that the correct link libraries are selected:
- the C++ Builder IDE normally sets this automatically. Hint, users of the 5.5
- command line tools may want to add a -D_NO_VCL to bcc32.cfg in order to set
- this option permanently.
-
-
If you would prefer to do a dynamic link to the regex libraries when using the
- dll runtime then define BOOST_REGEX_DYN_LINK (you must do this if you want to
- use boost.regex in multiple dll's), otherwise Boost.regex will be staically
- linked by default.
-
If you want to suppress automatic linking altogether (and supply your own
- custom build of the lib) then define BOOST_REGEX_NO_LIB.
-
If you are building with C++ Builder 6, you will find that
- <boost/regex.hpp> can not be used in a pre-compiled header (the actual
- problem is in <locale> which gets included by <boost/regex.hpp>),
- if this causes problems for you, then try defining BOOST_NO_STD_LOCALE when
- building, this will disable some features throughout boost, but may save you a
- lot in compile times!
-
Microsoft Visual C++ 6 and 7
-
You need version 6 of MSVC to build this library. If you are using VC5 then you
- may want to look at one of the previous releases of this
- library
-
-
Open up a command prompt, which has the necessary MSVC environment variables
- defined (for example by using the batch file Vcvars32.bat installed by the
- Visual Studio installation), and change to the <boost>\libs\regex\build
- directory.
-
-
Select the correct makefile - vc6.mak for "vanilla" Visual C++ 6 or
- vc6-stlport.mak if you are using STLPort.
-
Invoke the makefile like this:
-
nmake -fvc6.mak
-
You will now have a collection of lib and dll files in a "vc6" subdirectory, to
- install these into your development system use:
-
nmake -fvc6.mak install
-
The lib files will be copied to your <VC6>\lib directory and the dll
- files to <VC6>\bin, where <VC6> is the root of your Visual C++ 6
- installation.
-
You can delete all the temporary files created during the build (excluding lib
- and dll files) using:
-
nmake -fvc6.mak clean
-
Finally when you use regex++ it is only necessary for you to add the
- <boost> root directory to your list of include directories for that
- project. It is not necessary for you to manually add a .lib file to the
- project; the headers will automatically select the correct .lib file for your
- build mode and tell the linker to include it.
-
-
- Note that if you want to dynamically link to the regex library when using the
- dynamic C++ runtime, define BOOST_REGEX_DYN_LINK when building your project.
-
If you want to add the source directly to your project then define
- BOOST_REGEX_NO_LIB to disable automatic library selection.
-
There are several important caveats to remember when using boost.regex with
- Microsoft's Compiler:
-
-
- There have been some reports of compiler-optimization bugs affecting this
- library, (particularly with VC6 versions prior to service patch 5) the
- workaround is to build the library using /Oityb1 rather than /O2. That is to
- use all optimization settings except /Oa. This problem is reported to affect
- some standard library code as well (in fact I'm not sure if the problem is with
- the regex code or the underlying standard library), so it's probably worthwhile
- applying this workaround in normal practice in any case.
-
- If you have replaced the C++ standard library that comes with VC6, then when
- you build the library you must ensure that the environment variables "INCLUDE"
- and "LIB" have been updated to reflect the include and library paths for the
- new library - see vcvars32.bat (part of your Visual Studio installation) for
- more details.
-
-
- If you are building with the full STLPort v4.x, then use the vc6-stlport.mak
- file provided and set the environment variable STLPORT_PATH to point to the
- location of your STLPort installation (Note that the full STLPort libraries
- appear not to support single-thread static builds).
-
- If you are building your application with /Zc:wchar_t then you will need to
- modify the makefile to add /Zc:wchar_t before building the library.
-
-
-
GCC(2.95 and 3.x)
-
-
You can build with gcc using the normal boost Jamfile in
- <boost>/libs/regex/build, alternatively there is a conservative makefile
- for the g++ compiler. From the command prompt change to the
- <boost>/libs/regex/build directory and type:
-
-
make -fgcc.mak
-
At the end of the build process you should have a gcc sub-directory containing
- release and debug versions of the library (libboost_regex.a and
- libboost_regex_debug.a). When you build projects that use regex++, you will
- need to add the boost install directory to your list of include paths and add
- <boost>/libs/regex/build/gcc/libboost_regex.a to your list of library
- files.
-
-
There is also a makefile to build the library as a shared library:
-
make -fgcc-shared.mak
-
which will build libboost_regex.so and libboost_regex_debug.so.
-
Both of the these makefiles support the following environment variables:
-
CXXFLAGS: extra compiler options - note that this applies to both the debug and
- release builds.
There is a makefile for the sun (6.1) compiler (C++ version 3.12). From the
- command prompt change to the <boost>/libs/regex/build directory and type:
-
-
dmake -f sunpro.mak
-
At the end of the build process you should have a sunpro sub-directory
- containing single and multithread versions of the library (libboost_regex.a,
- libboost_regex.so, libboost_regex_mt.a and libboost_regex_mt.so). When you
- build projects that use regex++, you will need to add the boost install
- directory to your list of include paths and add
- <boost>/libs/regex/build/sunpro/ to your library search path.
-
-
Both of the these makefiles support the following environment variables:
-
CXXFLAGS: extra compiler options - note that this applies to both the single
- and multithreaded builds.
-
INCLUDES: additional include directories.
-
LDFLAGS: additional linker options.
-
LIBS: additional library files.
-
LIBSUFFIX: a suffix to mangle the library name with (defaults to nothing).
-
This makefile does not set any architecture specific options like -xarch=v9,
- you can set these by defining the appropriate macros, for example:
will build v9 variants of the regex library named libboost_regex_v9.a etc.
-
Other compilers:
-
-
There is a generic makefile (generic.mak
- ) provided in <boost-root>/libs/regex/build - see that makefile for
- details of environment variables that need to be set before use.
-
- Alternatively you can using the Jam based
- build system: cd into <boost>/libs/regex/build and run:
Regular expressions are a form of pattern-matching that are often used in text
- processing; many users will be familiar with the Unix utilities grep, sed
- and awk, and the programming language Perl, each of which make
- extensive use of regular expressions. Traditionally C++ users have been limited
- to the POSIX C API's for manipulating regular expressions, and while regex++
- does provide these API's, they do not represent the best way to use the
- library. For example regex++ can cope with wide character strings, or search
- and replace operations (in a manner analogous to either sed or Perl), something
- that traditional C libraries can not do.
-
The class boost::basic_regex is the key class in
- this library; it represents a "machine readable" regular expression, and is
- very closely modeled on std::basic_string, think of it as a string plus the
- actual state-machine required by the regular expression algorithms. Like
- std::basic_string there are two typedefs that are almost always the means by
- which this class is referenced:
To see how this library can be used, imagine that we are writing a credit card
- processing application. Credit card numbers generally come as a string of
- 16-digits, separated into groups of 4-digits, and separated by either a space
- or a hyphen. Before storing a credit card number in a database (not necessarily
- something your customers will appreciate!), we may want to verify that the
- number is in the correct format. To match any digit we could use the regular
- expression [0-9], however ranges of characters like this are actually locale
- dependent. Instead we should use the POSIX standard form [[:digit:]], or the
- regex++ and Perl shorthand for this \d (note that many older libraries tended
- to be hard-coded to the C-locale, consequently this was not an issue for them).
- That leaves us with the following regular expression to validate credit card
- number formats:
-
(\d{4}[- ]){3}\d{4}
-
Here the parenthesis act to group (and mark for future reference)
- sub-expressions, and the {4} means "repeat exactly 4 times". This is an example
- of the extended regular expression syntax used by Perl, awk and egrep. Regex++
- also supports the older "basic" syntax used by sed and grep, but this is
- generally less useful, unless you already have some basic regular expressions
- that you need to reuse.
-
Now let's take that expression and place it in some C++ code to validate the
- format of a credit card number:
Note how we had to add some extra escapes to the expression: remember that the
- escape is seen once by the C++ compiler, before it gets to be seen by the
- regular expression engine, consequently escapes in regular expressions have to
- be doubled up when embedding them in C/C++ code. Also note that all the
- examples assume that your compiler supports Koenig lookup, if yours doesn't
- (for example VC6), then you will have to add some boost:: prefixes to some of
- the function calls in the examples.
-
Those of you who are familiar with credit card processing, will have realized
- that while the format used above is suitable for human readable card numbers,
- it does not represent the format required by online credit card systems; these
- require the number as a string of 16 (or possibly 15) digits, without any
- intervening spaces. What we need is a means to convert easily between the two
- formats, and this is where search and replace comes in. Those who are familiar
- with the utilities sed and Perl will already be ahead here; we
- need two strings - one a regular expression - the other a "format
- string" that provides a description of the text to replace the match
- with. In regex++ this search and replace operation is performed with the
- algorithm regex_replace, for our credit card
- example we can write two algorithms like this to provide the format
- conversions:
-
// match any format with the regular expression:
-const boost::regex e("\\A(\\d{3,4})[- ]?(\\d{4})[- ]?(\\d{4})[- ]?(\\d{4})\\z");
-const std::string machine_format("\\1\\2\\3\\4");
-const std::string human_format("\\1-\\2-\\3-\\4");
-
-std::string machine_readable_card_number(const std::string s)
-{
- returnregex_replace(s, e, machine_format, boost::match_default | boost::format_sed);
-}
-
-std::string human_readable_card_number(const std::string s)
-{
- returnregex_replace(s, e, human_format, boost::match_default | boost::format_sed);
-}
-
Here we've used marked sub-expressions in the regular expression to split out
- the four parts of the card number as separate fields, the format string then
- uses the sed-like syntax to replace the matched text with the reformatted
- version.
-
In the examples above, we haven't directly manipulated the results of a regular
- expression match, however in general the result of a match contains a number of
- sub-expression matches in addition to the overall match. When the library needs
- to report a regular expression match it does so using an instance of the class
- match_results, as before there are typedefs of this class for the most
- common cases:
-
The algorithms regex_search and regex_match
- make use of match_results to report what matched; the difference between these
- algorithms is that regex_match will only find
- matches that consume all of the input text, where as
- regex_search will search for a match anywhere within the text
- being matched.
-
Note that these algorithms are not restricted to searching regular C-strings,
- any bidirectional iterator type can be searched, allowing for the possibility
- of seamlessly searching almost any kind of data.
-
-
For search and replace operations, in addition to the algorithm
- regex_replace that we have already seen, the match_results
- class has a format member that takes the result of a match and a format string,
- and produces a new string by merging the two.
-
For iterating through all occurences of an expression within a text, there are
- two iterator types: regex_iterator will
- enumerate over the match_results objects
- found, while regex_token_iterator will
- enumerate a series of strings (similar to perl style split operations).
-
For those that dislike templates, there is a high level wrapper class RegEx
- that is an encapsulation of the lower level template code - it provides a
- simplified interface for those that don't need the full power of the library,
- and supports only narrow characters, and the "extended" regular expression
- syntax. This class is now deprecated as it does not form part of the regular
- expressions C++ standard library proposal.
-
-
The POSIX API functions: regcomp, regexec, regfree
- and regerror, are available in both narrow character and Unicode versions, and
- are provided for those who need compatibility with these API's.
-
-
Finally, note that the library now has run-time localization
- support, and recognizes the full POSIX regular expression syntax - including
- advanced features like multi-character collating elements and equivalence
- classes - as well as providing compatibility with other regular expression
- libraries including GNU and BSD4 regex packages, and to a more limited extent
- Perl 5.
-
Boost.regex provides extensive support for run-time
-localization, the localization model used can be split into two
-parts: front-end and back-end.
-
-
Front-end localization deals with everything which the user sees
-- error messages, and the regular expression syntax itself. For
-example a French application could change [[:word:]] to [[:mot:]]
-and \w to \m. Modifying the front end locale requires active
-support from the developer, by providing the library with a message
-catalogue to load, containing the localized strings. Front-end
-locale is affected by the LC_MESSAGES category only.
-
-
Back-end localization deals with everything that occurs after
-the expression has been parsed - in other words everything that the
-user does not see or interact with directly. It deals with case
-conversion, collation, and character class membership. The back-end
-locale does not require any intervention from the developer - the
-library will acquire all the information it requires for the
-current locale from the underlying operating system / run time
-library. This means that if the program user does not interact with
-regular expressions directly - for example if the expressions are
-embedded in your C++ code - then no explicit localization is
-required, as the library will take care of everything for you. For
-example embedding the expression [[:word:]]+ in your code will
-always match a whole word, if the program is run on a machine with,
-for example, a Greek locale, then it will still match a whole word,
-but in Greek characters rather than Latin ones. The back-end locale
-is affected by the LC_TYPE and LC_COLLATE categories.
-
-
There are three separate localization mechanisms supported by
-boost.regex:
-
-
Win32 localization model.
-
-
This is the default model when the library is compiled under
-Win32, and is encapsulated by the traits class w32_regex_traits.
-When this model is in effect there is a single global locale as
-defined by the user's control panel settings, and returned by
-GetUserDefaultLCID. All the settings used by boost.regex are
-acquired directly from the operating system bypassing the C run
-time library. Front-end localization requires a resource dll,
-containing a string table with the user-defined strings. The traits
-class exports the function:
which needs to be called with a string identifying the name of
-the resource dll, before your code compiles any regular
-expressions (but not necessarily before you construct any
-basic_regex instances):
Note that this API sets the dll name for both the narrow
-and wide character specializations of w32_regex_traits.
-
-
This model does not currently support thread specific locales
-(via SetThreadLocale under Windows NT), the library provides full
-Unicode support under NT, under Windows 9x the library degrades
-gracefully - characters 0 to 255 are supported, the remainder are
-treated as "unknown" graphic characters.
-
-
C localization model.
-
-
This is the default model when the library is compiled under an
-operating system other than Win32, and is encapsulated by the
-traits class c_regex_traits, Win32 users can force this
-model to take effect by defining the pre-processor symbol
-BOOST_REGEX_USE_C_LOCALE. When this model is in effect there is a
-single global locale, as set by setlocale. All settings are
-acquired from your run time library, consequently Unicode support
-is dependent upon your run time library implementation. Front end
-localization requires a POSIX message catalogue. The traits class
-exports the function:
which needs to be called with a string identifying the name of
-the message catalogue, before your code compiles any regular
-expressions (but not necessarily before you construct any
-basic_regex instances):
Note that this API sets the dll name for both the narrow
-and wide character specializations of c_regex_traits. If your run
-time library does not support POSIX message catalogues, then you
-can either provide your own implementation of <nl_types.h> or
-define BOOST_RE_NO_CAT to disable front-end localization via
-message catalogues.
-
-
Note that calling setlocale invalidates all compiled
-regular expressions, calling setlocale(LC_ALL, "C") will
-make this library behave equivalent to most traditional regular
-expression libraries including version 1 of this library.
-
-
C++ localization model.
-
-
This model is only in effect if the library is built with the
-pre-processor symbol BOOST_REGEX_USE_CPP_LOCALE defined. When this
-model is in effect each instance of basic_regex<> has its own
-instance of std::locale, class basic_regex<> also has a
-member function imbue which allows the locale for the
-expression to be set on a per-instance basis. Front end
-localization requires a POSIX message catalogue, which will be
-loaded via the std::messages facet of the expression's locale, the
-traits class exports the symbol:
which needs to be called with a string identifying the name of
-the message catalogue, before your code compiles any regular
-expressions (but not necessarily before you construct any
-basic_regex instances):
Note that calling basic_regex<>::imbue will invalidate any
-expression currently compiled in that instance of
-basic_regex<>. This model is the one which closest fits the
-ethos of the C++ standard library, however it is the model which
-will produce the slowest code, and which is the least well
-supported by current standard library implementations, for example
-I have yet to find an implementation of std::locale which supports
-either message catalogues, or locales other than "C" or
-"POSIX".
-
-
Finally note that if you build the library with a non-default
-localization model, then the appropriate pre-processor symbol
-(BOOST_REGEX_USE_C_LOCALE or BOOST_REGEX_USE_CPP_LOCALE) must be
-defined both when you build the support library, and when you
-include <boost/regex.hpp> or <boost/cregex.hpp> in your
-code. The best way to ensure this is to add the #define to
-<boost/regex/user.hpp>.
-
-
Providing a message catalogue:
-
-
In order to localize the front end of the library, you need to
-provide the library with the appropriate message strings contained
-either in a resource dll's string table (Win32 model), or a POSIX
-message catalogue (C or C++ models). In the latter case the
-messages must appear in message set zero of the catalogue. The
-messages and their id's are as follows:
-
-
-
-
-
-
-
-
Message id
-
Meaning
-
Default value
-
-
-
-
-
-
101
-
The character used to start a
-sub-expression.
-
"("
-
-
-
-
-
-
102
-
The character used to end a
-sub-expression declaration.
-
")"
-
-
-
-
-
-
103
-
The character used to denote an end of
-line assertion.
-
"$"
-
-
-
-
-
-
104
-
The character used to denote the start
-of line assertion.
-
"^"
-
-
-
-
-
-
105
-
The character used to denote the
-"match any character expression".
-
"."
-
-
-
-
-
-
106
-
The match zero or more times
-repetition operator.
-
"*"
-
-
-
-
-
-
107
-
The match one or more repetition
-operator.
-
"+"
-
-
-
-
-
-
108
-
The match zero or one repetition
-operator.
-
"?"
-
-
-
-
-
-
109
-
The character set opening
-character.
-
"["
-
-
-
-
-
-
110
-
The character set closing
-character.
-
"]"
-
-
-
-
-
-
111
-
The alternation operator.
-
"|"
-
-
-
-
-
-
112
-
The escape character.
-
"\\"
-
-
-
-
-
-
113
-
The hash character (not currently
-used).
-
"#"
-
-
-
-
-
-
114
-
The range operator.
-
"-"
-
-
-
-
-
-
115
-
The repetition operator opening
-character.
-
"{"
-
-
-
-
-
-
116
-
The repetition operator closing
-character.
-
"}"
-
-
-
-
-
-
117
-
The digit characters.
-
"0123456789"
-
-
-
-
-
-
118
-
The character which when preceded by
-an escape character represents the word boundary assertion.
-
"b"
-
-
-
-
-
-
119
-
The character which when preceded by
-an escape character represents the non-word boundary
-assertion.
-
"B"
-
-
-
-
-
-
120
-
The character which when preceded by
-an escape character represents the word-start boundary
-assertion.
-
"<"
-
-
-
-
-
-
121
-
The character which when preceded by
-an escape character represents the word-end boundary
-assertion.
-
">"
-
-
-
-
-
-
122
-
The character which when preceded by
-an escape character represents any word character.
-
"w"
-
-
-
-
-
-
123
-
The character which when preceded by
-an escape character represents a non-word character.
-
"W"
-
-
-
-
-
-
124
-
The character which when preceded by
-an escape character represents a start of buffer assertion.
-
"`A"
-
-
-
-
-
-
125
-
The character which when preceded by
-an escape character represents an end of buffer assertion.
-
"'z"
-
-
-
-
-
-
126
-
The newline character.
-
"\n"
-
-
-
-
-
-
127
-
The comma separator.
-
","
-
-
-
-
-
-
128
-
The character which when preceded by
-an escape character represents the bell character.
-
"a"
-
-
-
-
-
-
129
-
The character which when preceded by
-an escape character represents the form feed character.
-
"f"
-
-
-
-
-
-
130
-
The character which when preceded by
-an escape character represents the newline character.
-
"n"
-
-
-
-
-
-
131
-
The character which when preceded by
-an escape character represents the carriage return character.
-
"r"
-
-
-
-
-
-
132
-
The character which when preceded by
-an escape character represents the tab character.
-
"t"
-
-
-
-
-
-
133
-
The character which when preceded by
-an escape character represents the vertical tab character.
-
"v"
-
-
-
-
-
-
134
-
The character which when preceded by
-an escape character represents the start of a hexadecimal character
-constant.
-
"x"
-
-
-
-
-
-
135
-
The character which when preceded by
-an escape character represents the start of an ASCII escape
-character.
-
"c"
-
-
-
-
-
-
136
-
The colon character.
-
":"
-
-
-
-
-
-
137
-
The equals character.
-
"="
-
-
-
-
-
-
138
-
The character which when preceded by
-an escape character represents the ASCII escape character.
-
"e"
-
-
-
-
-
-
139
-
The character which when preceded by
-an escape character represents any lower case character.
-
"l"
-
-
-
-
-
-
140
-
The character which when preceded by
-an escape character represents any non-lower case character.
-
"L"
-
-
-
-
-
-
141
-
The character which when preceded by
-an escape character represents any upper case character.
-
"u"
-
-
-
-
-
-
142
-
The character which when preceded by
-an escape character represents any non-upper case character.
-
"U"
-
-
-
-
-
-
143
-
The character which when preceded by
-an escape character represents any space character.
-
"s"
-
-
-
-
-
-
144
-
The character which when preceded by
-an escape character represents any non-space character.
-
"S"
-
-
-
-
-
-
145
-
The character which when preceded by
-an escape character represents any digit character.
-
"d"
-
-
-
-
-
-
146
-
The character which when preceded by
-an escape character represents any non-digit character.
-
"D"
-
-
-
-
-
-
147
-
The character which when preceded by
-an escape character represents the end quote operator.
-
"E"
-
-
-
-
-
-
148
-
The character which when preceded by
-an escape character represents the start quote operator.
-
"Q"
-
-
-
-
-
-
149
-
The character which when preceded by
-an escape character represents a Unicode combining character
-sequence.
-
"X"
-
-
-
-
-
-
150
-
The character which when preceded by
-an escape character represents any single character.
-
"C"
-
-
-
-
-
-
151
-
The character which when preceded by
-an escape character represents end of buffer operator.
-
"Z"
-
-
-
-
-
-
152
-
The character which when preceded by
-an escape character represents the continuation assertion.
-
"G"
-
-
-
-
-
-
153
-
The character which when preceeded by (? indicates a zero width
-negated forward lookahead assert.
-
!
-
-
-
-
-
-
-
-
-
Custom error messages are loaded as follows:
-
-
-
-
-
-
-
Message ID
-
Error message ID
-
Default string
-
-
-
-
-
-
201
-
REG_NOMATCH
-
"No match"
-
-
-
-
-
-
202
-
REG_BADPAT
-
"Invalid regular expression"
-
-
-
-
-
-
203
-
REG_ECOLLATE
-
"Invalid collation character"
-
-
-
-
-
-
204
-
REG_ECTYPE
-
"Invalid character class name"
-
-
-
-
-
-
205
-
REG_EESCAPE
-
"Trailing backslash"
-
-
-
-
-
-
206
-
REG_ESUBREG
-
"Invalid back reference"
-
-
-
-
-
-
207
-
REG_EBRACK
-
"Unmatched [ or [^"
-
-
-
-
-
-
208
-
REG_EPAREN
-
"Unmatched ( or \\("
-
-
-
-
-
-
209
-
REG_EBRACE
-
"Unmatched \\{"
-
-
-
-
-
-
210
-
REG_BADBR
-
"Invalid content of \\{\\}"
-
-
-
-
-
-
211
-
REG_ERANGE
-
"Invalid range end"
-
-
-
-
-
-
212
-
REG_ESPACE
-
"Memory exhausted"
-
-
-
-
-
-
213
-
REG_BADRPT
-
"Invalid preceding regular
-expression"
-
-
-
-
-
-
214
-
REG_EEND
-
"Premature end of regular
-expression"
-
-
-
-
-
-
215
-
REG_ESIZE
-
"Regular expression too big"
-
-
-
-
-
-
216
-
REG_ERPAREN
-
"Unmatched ) or \\)"
-
-
-
-
-
-
217
-
REG_EMPTY
-
"Empty expression"
-
-
-
-
-
-
218
-
REG_E_UNKNOWN
-
"Unknown error"
-
-
-
-
-
-
-
-
-
Custom character class names are loaded as followed:
-
-
-
-
-
-
-
Message ID
-
Description
-
Equivalent default class name
-
-
-
-
-
-
300
-
The character class name for
-alphanumeric characters.
-
"alnum"
-
-
-
-
-
-
301
-
The character class name for
-alphabetic characters.
-
"alpha"
-
-
-
-
-
-
302
-
The character class name for control
-characters.
-
"cntrl"
-
-
-
-
-
-
303
-
The character class name for digit
-characters.
-
"digit"
-
-
-
-
-
-
304
-
The character class name for graphics
-characters.
-
"graph"
-
-
-
-
-
-
305
-
The character class name for lower
-case characters.
-
"lower"
-
-
-
-
-
-
306
-
The character class name for printable
-characters.
-
"print"
-
-
-
-
-
-
307
-
The character class name for
-punctuation characters.
-
"punct"
-
-
-
-
-
-
308
-
The character class name for space
-characters.
-
"space"
-
-
-
-
-
-
309
-
The character class name for upper
-case characters.
-
"upper"
-
-
-
-
-
-
310
-
The character class name for
-hexadecimal characters.
-
"xdigit"
-
-
-
-
-
-
311
-
The character class name for blank
-characters.
-
"blank"
-
-
-
-
-
-
312
-
The character class name for word
-characters.
-
"word"
-
-
-
-
-
-
313
-
The character class name for Unicode
-characters.
-
"unicode"
-
-
-
-
-
-
-
-
-
Finally, custom collating element names are loaded starting from
-message id 400, and terminating when the first load thereafter
-fails. Each message looks something like: "tagname string" where
-tagname is the name used inside [[.tagname.]] and
-string is the actual text of the collating element. Note that
-the value of collating element [[.zero.]] is used for the
-conversion of strings to numbers - if you replace this with another
-value then that will be used for string parsing - for example use
-the Unicode character 0x0660 for [[.zero.]] if you want to use
-Unicode Arabic-Indic digits in your regular expressions in place of
-Latin digits.
-
-
Note that the POSIX defined names for character classes and
-collating elements are always available - even if custom names are
-defined, in contrast, custom error messages, and custom syntax
-messages replace the default ones.
The type match_flag_type is an implementation specific bitmask
- type (17.3.2.1.2) that controls how a regular expression is matched against a
- character sequence. The behavior of the format flags is descibed in more
- detail in the format syntax guide.
The type match_flag_type is an implementation specific bitmask
- type (17.3.2.1.2). When matching a regular expression against a sequence of
- characters [first, last) then setting its elements has the effects listed in
- the table below:
-
-
-
-
-
Element
-
-
-
Effect if set
-
-
-
-
-
match_default
-
-
-
Specifies that matching of regular expressions proceeds without any
- modification of the normal rules used in ECMA-262, ECMAScript Language
- Specification, Chapter 15 part 10, RegExp (Regular Expression) Objects (FWD.1)
-
-
-
-
match_not_bob
-
Specifies that the expression "\A" should not match
- against the sub-sequence [first,first).
-
-
-
match_not_eob
-
Specifies that the expressions "\z" and
- "\Z" should not match against the sub-sequence [last,last).
-
-
-
-
match_not_bol
-
-
-
Specifies that the expression "^" should not be matched against the
- sub-sequence [first,first).
-
-
-
-
-
match_not_eol
-
-
-
Specifies that the expression "$" should not be matched against the
- sub-sequence [last,last).
-
-
-
-
-
match_not_bow
-
-
-
Specifies that the expression "\b" should not be matched against the
- sub-sequence [first,first).
-
-
-
-
-
match_not_eow
-
-
-
Specifies that the expression "\b" should not be matched against the
- sub-sequence [last,last).
-
-
-
-
-
match_any
-
-
-
Specifies that if more than one match is possible then any match is an
- acceptable result.
-
-
-
-
-
match_not_null
-
-
-
Specifies that the expression can not be matched against an empty sequence.
-
-
-
-
-
match_continuous
-
-
-
Specifies that the expression must match a sub-sequence that begins at first.
-
-
-
-
-
match_partial
-
-
-
Specifies that if no match can be found, then it is acceptable to return a
- match [from, last) where from!=last, if there exists some sequence of
- characters [from,to) of which [from,last) is a prefix, and which would result
- in a full match.
Equivalent to Perl's s/ modifier; prevents ^ from
- matching after an embedded newline character (so that it only matches at the
- start of the text being matched), and $ from matching before an embedded
- newline (so that it only matches at the end of the text being matched).
-
-
-
-
match_prev_avail
-
-
-
Specifies that --first is a valid iterator position, when this
- flag is set then the flags match_not_bol and match_not_bow
- are ignored by the regular expression algorithms (RE.7) and iterators (RE.8).
-
-
-
-
match_not_dot_newline
-
Specifies that the expression "." does not match a
- newline character.
-
-
-
match_not_dot_null
-
Specified that the expression "." does not match a
- character null '\0'.
-
-
-
-
format_default
-
-
-
Specifies that when a regular expression match is to be replaced by a new
- string, that the new string is constructed using the rules used by the
- ECMAScript replace function in ECMA-262, ECMAScript Language Specification,
- Chapter 15 part 5.4.11 String.prototype.replace. (FWD.1). In addition during
- search and replace operations then all non-overlapping occurrences of the
- regular expression are located and replaced, and sections of the input that did
- not match the expression, are copied unchanged to the output string.
-
-
-
-
-
format_sed
-
-
-
Specifies that when a regular expression match is to be replaced by a new
- string, that the new string is constructed using the rules used by the Unix sed
- utility in IEEE Std 1003.1-2001, Portable Operating SystemInterface (POSIX ),
- Shells and Utilities..
-
-
-
-
-
format_perl
-
-
-
- Specifies that when a regular expression match is to be replaced by a new
- string, that the new string is constructed using the same rules as Perl 5.
-
-
-
-
format_all
-
Specifies that all syntax extensions are
- enabled, including conditional (?ddexpression1:expression2) replacements: see
- the format string guide for more details.
-
-
-
-
format_no_copy
-
-
-
When specified during a search and replace operation, then sections of the
- character container sequence being searched that do match the regular
- expression, are not copied to the output string.
-
-
-
-
-
format_first_only
-
-
-
When specified during a search and replace operation, then only the first
- occurrence of the regular expression is replaced.
Regular expressions are different from many simple pattern-matching algorithms
- in that as well as finding an overall match they can also produce
- sub-expression matches: each sub-expression being delimited in the pattern by a
- pair of parenthesis (...). There has to be some method for reporting
- sub-expression matches back to the user: this is achieved this by defining a
- class match_results that acts as an indexed collection of sub-expression
- matches, each sub-expression match being contained in an object of type
- sub_match .
-
Template class match_results denotes a collection of character sequences
- representing the result of a regular expression match. Objects of type
- match_results are passed to the algorithms regex_match
- and regex_search, and are returned by the
- iterator regex_iterator . Storage for
- the collection is allocated and freed as necessary by the member functions of
- class match_results.
-
The template class match_results conforms to the requirements of a Sequence, as
- specified in (lib.sequence.reqmts), except that only operations defined for
- const-qualified Sequences are supported.
-
Class template match_results is most commonly used as one of the typedefs
- cmatch, wcmatch, smatch, or wsmatch:
In all match_results constructors, a copy of the Allocator
- argument is used for any memory allocation performed by the constructor or
- member functions during the lifetime of the object.
-
-match_results(const Allocator& a = Allocator());
-
-
-
Effects: Constructs an object of class match_results. The postconditions
- of this function are indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
true
-
-
-
-
-
size()
-
-
-
0
-
-
-
-
-
str()
-
-
-
basic_string<charT>()
-
-
-
-
-
-
-match_results(const match_results& m);
-
-
-
Effects: Constructs an object of class match_results, as a copy of m.
Effects: Assigns m to *this. The postconditions of this function are
- indicated in the table:
-
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
empty()
-
-
-
m.empty().
-
-
-
-
-
size()
-
-
-
m.size().
-
-
-
-
-
str(n)
-
-
-
m.str(n) for all integers n < m.size().
-
-
-
-
-
prefix()
-
-
-
m.prefix().
-
-
-
-
-
suffix()
-
-
-
m.suffix().
-
-
-
-
-
(*this)[n]
-
-
-
m[n] for all integers n < m.size().
-
-
-
-
-
length(n)
-
-
-
m.length(n) for all integers n < m.size().
-
-
-
-
-
position(n)
-
-
-
m.position(n) for all integers n < m.size().
-
-
-
-
-
match_results size
-
-size_type size()const;
-
-
-
Effects: Returns the number of sub_match elements stored in *this; that
- is the number of marked sub-expressions in the regular expression that was
- matched plus one.
-
-size_type max_size()const;
-
-
-
Effects: Returns the maximum number of sub_match elements that can be
- stored in *this.
-
-bool empty()const;
-
-
-
Effects: Returns size() == 0.
-
match_results element access
-
-difference_type length(int sub = 0)const;
-
-
-
Effects: Returns the length of sub-expression sub, that is to
- say: (*this)[sub].length().
-
-difference_type position(unsigned int sub = 0)const;
-
-
-
Effects: Returns the starting location of sub-expression sub,
- or -1 if sub was not matched .
-
-string_type str(int sub = 0)const;
-
-
-
Effects: Returns sub-expression sub as a string: string_type((*this)[sub]).
-
-const_reference operator[](int n) const;
-
-
-
Effects: Returns a reference to the sub_match object
- representing the character sequence that matched marked sub-expression n.
- If n == 0 then returns a reference to a sub_match object
- representing the character sequence that matched the whole regular
- expression. If n is out of range, or if n is an
- unmatched sub-expression, then returns a sub_match object whose matched
- member is false.
-
-const_reference prefix()const;
-
-
-
Effects: Returns a reference to the sub_match object
- representing the character sequence from the start of the string being
- matched/searched, to the start of the match found.
-
-const_reference suffix()const;
-
-
-
Effects: Returns a reference to the sub_match object
- representing the character sequence from the end of the match found to the end
- of the string being matched/searched.
-
-const_iterator begin()const;
-
-
-
Effects: Returns a starting iterator that enumerates over all the marked
- sub-expression matches stored in *this.
-
-const_iterator end()const;
-
-
-
Effects: Returns a terminating iterator that enumerates over all the
- marked sub-expression matches stored in *this.
Requires: The type OutputIterator conforms to the Output Iterator
- requirements (24.1.2).
-
-
Effects: Copies the character sequence [fmt.begin(), fmt.end()) to
- OutputIterator out. For each format specifier or escape sequence in fmt,
- replace that sequence with either the character(s) it represents, or the
- sequence of characters within *this to which it refers. The bitmasks specified
- in flags determines what
- format specifiers or escape sequences are recognized, by default this is
- the format used by ECMA-262, ECMAScript Language Specification, Chapter 15 part
- 5.4.11 String.prototype.replace.
Effects: Returns a copy of the string fmt. For each format
- specifier or escape sequence in fmt, replace that sequence with either
- the character(s) it represents, or the sequence of characters within *this to
- which it refers. The bitmasks specified in flags
- determines what format specifiers or escape sequences
- are recognized, by default this is the format used by ECMA-262,
- ECMAScript Language Specification, Chapter 15 part 5.4.11
- String.prototype.replace.
-
Allocator access
-
allocator_type get_allocator()const;
-
-
-
Effects: Returns a copy of the Allocator that was passed to the object's
- constructor.
-
Swap
-
void swap(match_results& that);
-
-
-
Effects: Swaps the contents of the two sequences.
-
-
Postcondition:*this contains the sequence of matched
- sub-expressions that were in that, that contains the
- sequence of matched sub-expressions that were in *this.
Defines an implementation-specific type that satisfies the requirements of
- a standard library Sequence (21.1.1 including the optional Table 68
- operations), whose value_type is a sub_match<BidirectionalIterator>. This
- type happens to be std::vector<sub_match<BidirectionalIterator> >,
- but you shouldn't actually rely on that.
Effects: returns a sequence containing all the captures
- obtained for sub-expression i.
-
Returns:(*this)[i].captures();
-
Preconditions: the library must be built and used with
- BOOST_REGEX_MATCH_EXTRA defined, and you must pass the flag
- match_extra to the regex matching functions (regex_match,
- regex_search, regex_iterator
- or regex_token_iterator) in order for
- this member function to be defined and return useful information.
-
Rationale: Enabling this feature has several consequences:
-
-
-
- sub_match occupies more memory resulting in complex expressions running out of
- memory or stack space more quickly during matching.
-
- The matching algorithms are less efficient at handling some features
- (independent sub-expressions for example), even when match_extra is not used.
-
- The matching algorithms are much less efficient (i.e. slower), when match_extra
- is used. Mostly this is down to the extra memory allocations that have to
- take place.
The match-flagmatch_partial can
- be passed to the following algorithms: regex_match,
- regex_search, and regex_grep.
- When used it indicates that partial as well as full matches should be found. A
- partial match is one that matched one or more characters at the end of the text
- input, but did not match all of the regular expression (although it may have
- done so had more input been available). Partial matches are typically used when
- either validating data input (checking each character as it is entered on the
- keyboard), or when searching texts that are either too long to load into memory
- (or even into a memory mapped file), or are of indeterminate length (for
- example the source may be a socket or similar). Partial and full matches can be
- differentiated as shown in the following table (the variable M represents an
- instance of match_results<> as filled in
- by regex_match, regex_search or regex_grep):
-
-
-
-
-
-
Result
-
M[0].matched
-
M[0].first
-
M[0].second
-
-
-
No match
-
False
-
Undefined
-
Undefined
-
Undefined
-
-
-
Partial match
-
True
-
False
-
Start of partial match.
-
End of partial match (end of text).
-
-
-
Full match
-
True
-
True
-
Start of full match.
-
End of full match.
-
-
-
-
The following example
- tests to see whether the text could be a valid credit card number, as the user
- presses a key, the character entered would be added to the string being built
- up, and passed to is_possible_card_number. If this returns true
- then the text could be a valid card number, so the user interface's OK button
- would be enabled. If it returns false, then this is not yet a valid card
- number, but could be with more input, so the user interface would disable the
- OK button. Finally, if the procedure throws an exception the input could never
- become a valid number, and the inputted character must be discarded, and a
- suitable error indication displayed to the user.
-
#include <string>
-#include <iostream>
-#include <boost/regex.hpp>
-
-boost::regex e("(\\d{3,4})[- ]?(\\d{4})[- ]?(\\d{4})[- ]?(\\d{4})");
-
-bool is_possible_card_number(const std::string& input)
-{
- //
- // return false for partial match, true for full match, or throw for
- // impossible match based on what we have so far...
- boost::match_results<std::string::const_iterator> what;
- if(0 == boost::regex_match(input, what, e, boost::match_default | boost::match_partial))
- {
- // the input so far could not possibly be valid so reject it:
- throw std::runtime_error("Invalid data entered - this could not possibly be a valid card number");
- }
- // OK so far so good, but have we finished?
- if(what[0].matched)
- {
- // excellent, we have a result:
- return true;
- }
- // what we have so far is only a partial match...
- return false;
-}
-
In the following example,
- text input is taken from a stream containing an unknown amount of text; this
- example simply counts the number of html tags encountered in the stream. The
- text is loaded into a buffer and searched a part at a time, if a partial match
- was encountered, then the partial match gets searched a second time as the
- start of the next batch of text:
-
#include <iostream>
-#include <fstream>
-#include <sstream>
-#include <string>
-#include <boost/regex.hpp>
-
-// match some kind of html tag:
-boost::regex e("<[^>]*>");
-// count how many:
-unsigned int tags = 0;
-// saved position of partial match:
-char* next_pos = 0;
-
-bool grep_callback(const boost::match_results<char*>& m)
-{
- if(m[0].matched == false)
- {
- // save position and return:
- next_pos = m[0].first;
- }
- else
- ++tags;
- return true;
-}
-
-void search(std::istream& is)
-{
- char buf[4096];
- next_pos = buf + sizeof(buf);
- bool have_more = true;
- while(have_more)
- {
- // how much do we copy forward from last try:
- unsigned leftover = (buf + sizeof(buf)) - next_pos;
- // and how much is left to fill:
- unsigned size = next_pos - buf;
- // copy forward whatever we have left:
- memcpy(buf, next_pos, leftover);
- // fill the rest from the stream:
- unsigned read = is.readsome(buf + leftover, size);
- // check to see if we've run out of text:
- have_more = read == size;
- // reset next_pos:
- next_pos = buf + sizeof(buf);
- // and then grep:
- boost::regex_grep(grep_callback,
- buf,
- buf + read + leftover,
- e,
- boost::match_default | boost::match_partial);
- }
-}
The performance of Boost.regex in both recursive and non-recursive modes should
- be broadly comparable to other regular expression libraries: recursive mode is
- slightly faster (especially where memory allocation requires thread
- synchronisation), but not by much. The following pages compare
- Boost.regex with various other regular expression libraries for the following
- compilers:
The following functions are available for users who need a POSIX compatible C
- library, they are available in both Unicode and narrow character versions, the
- standard POSIX API names are macros that expand to one version or the other
- depending upon whether UNICODE is defined or not.
-
-
Important: Note that all the symbols defined here are enclosed inside
- namespace boost when used in C++ programs, unless you use #include
- <boost/regex.h> instead - in which case the symbols are still defined in
- namespace boost, but are made available in the global namespace as well.
All the functions operate on structure regex_t, which exposes two public
- members:
-
-
unsigned int re_nsub this is filled in by regcomp and indicates
- the number of sub-expressions contained in the regular expression.
-
-
const TCHAR* re_endp points to the end of the expression to compile when
- the flag REG_PEND is set.
-
-
Footnote: regex_t is actually a #define - it is either regex_tA or regex_tW
- depending upon whether UNICODE is defined or not, TCHAR is either char or
- wchar_t again depending upon the macro UNICODE.
-
-
regcomp
-
regcomp takes a pointer to a regex_t, a pointer to the expression
- to compile and a flags parameter which can be a combination of:
-
-
-
-
-
-
-
-
REG_EXTENDED
-
Compiles modern regular expressions. Equivalent to
- regbase::char_classes | regbase::intervals | regbase::bk_refs.
All characters are ordinary, the expression is a
- literal string.
-
-
-
-
-
REG_ICASE
-
Compiles for matching that ignores character case.
-
-
-
-
-
REG_NOSUB
-
Has no effect in this library.
-
-
-
-
-
REG_NEWLINE
-
When this flag is set a dot does not match the
- newline character.
-
-
-
-
-
REG_PEND
-
When this flag is set the re_endp parameter of the
- regex_t structure must point to the end of the regular expression to compile.
-
-
-
-
-
REG_NOCOLLATE
-
When this flag is set then locale dependent collation
- for character ranges is turned off.
-
-
-
-
-
REG_ESCAPE_IN_LISTS
- , , ,
-
-
When this flag is set, then escape sequences are
- permitted in bracket expressions (character sets).
-
-
-
-
-
REG_NEWLINE_ALT
-
When this flag is set then the newline character is
- equivalent to the alternation operator |.
-
-
-
-
-
REG_PERL
-
Compiles Perl like regular expressions.
-
-
-
-
-
REG_AWK
-
A shortcut for awk-like behavior: REG_EXTENDED |
- REG_ESCAPE_IN_LISTS
-
-
-
-
-
REG_GREP
-
A shortcut for grep like behavior: REG_BASIC |
- REG_NEWLINE_ALT
-
-
-
-
-
REG_EGREP
-
A shortcut for egrep like behavior:
- REG_EXTENDED | REG_NEWLINE_ALT
-
-
-
-
-
regerror
-
regerror takes the following parameters, it maps an error code to a human
- readable string:
-
-
-
-
-
-
-
int code
-
The error code.
-
-
-
-
-
const regex_t* e
-
The regular expression (can be null).
-
-
-
-
-
char* buf
-
The buffer to fill in with the error message.
-
-
-
-
-
unsigned int buf_size
-
The length of buf.
-
-
-
-
-
If the error code is OR'ed with REG_ITOA then the message that results is the
- printable name of the code rather than a message, for example "REG_BADPAT". If
- the code is REG_ATIO then e must not be null and e->re_pend must
- point to the printable name of an error code, the return value is then the
- value of the error code. For any other value of code, the return value
- is the number of characters in the error message, if the return value is
- greater than or equal to buf_size then regerror will have to be
- called again with a larger buffer.
-
regexec
-
regexec finds the first occurrence of expression e within string buf.
- If len is non-zero then *m is filled in with what matched the
- regular expression, m[0] contains what matched the whole string, m[1]
- the first sub-expression etc, see regmatch_t in the header file
- declaration for more details. The eflags parameter can be a combination
- of:
-
-
-
-
-
-
-
-
REG_NOTBOL
-
Parameter buf does not represent the start of
- a line.
-
-
-
-
-
REG_NOTEOL
-
Parameter buf does not terminate at the end of
- a line.
-
-
-
-
-
REG_STARTEND
-
The string searched starts at buf + pmatch[0].rm_so
- and ends at buf + pmatch[0].rm_eo.
-
-
-
-
-
regfree
-
Finally regfree frees all the memory that was allocated by regcomp.
-
-
Footnote: this is an abridged reference to the POSIX API functions, it is
- provided for compatibility with other libraries, rather than an API to be used
- in new code (unless you need access from a language other than C++). This
- version of these functions should also happily coexist with other versions, as
- the names used are macros that expand to the actual function names.
-
If you are using Microsoft or Borland C++ and link to a dll version of the run
- time library, then you can choose to also link to a dll version of boost.regex
- by defining the symbol BOOST_REGEX_DYN_LINK when you compile your code. While
- these dll's are redistributable, there are no "standard" versions, so when
- installing on the users PC, you should place these in a directory private to
- your application, and not in the PC's directory path. Note that if you link to
- a static version of your run time library, then you will also link to a static
- version of boost.regex and no dll's will need to be distributed. The possible
- boost.regex dll and library names are computed according to the following
- formula:
-
-
-
BOOST_LIB_PREFIX
- + "boost_regex_"
- + BOOST_LIB_TOOLSET
- + "_"
- + BOOST_LIB_THREAD_OPT
- + BOOST_LIB_RT_OPT
- + BOOST_LIB_DEBUG_OPT
-
- These are defined as:
-
BOOST_LIB_PREFIX: Either "lib" if this is a static link library,
- or nothing for dynamic / shared libraries.
-
- BOOST_LIB_TOOLSET: The compiler toolset name (vc6, vc7, bcb5 etc).
-
- BOOST_LIB_THREAD_OPT: "s" for single thread builds,
- "m" for multithread builds.
-
- BOOST_LIB_RT_OPT: "s" for static runtime,
- "d" for dynamic runtime.
-
- BOOST_LIB_LINK_OPT: "s" for static link,
- "i" for dynamic link.
-
- BOOST_LIB_DEBUG_OPT: nothing for release builds,
- "d" for debug builds,
- "dd" for debug-diagnostic builds (_STLP_DEBUG).
-
- Note: you can disable automatic library selection by defining the symbol
- BOOST_REGEX_NO_LIB when compiling, this is useful if you want to statically
- link even though you're using the dll version of your run time library, or if
- you need to debug boost.regex.
-
Use of the type boost::regbase is now deprecated,
-and the type does not form a part of the
-regular expression standardization proposal. This type
-still exists as a base class of boost::basic_regex,
-and you can still refer to
-boost::regbase::constant_name in your code, however for
-maximum portability to other std regex implementations you should
-instead use either:
The high level wrapper class RegEx is now deprecated and does not form a 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 synatx.
Member functions for class RegEx are defined as follows:
-
-
-
-
-
-
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(constchar* 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.
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=(constchar*
- 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.
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.
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.
Attempts to match the current expression against the
- text p using the match flags flags - see
- match flags. Returns true if the expression matches the whole of
- the input string.
Attempts to match the current expression against the
- text s using the match flags flags - see
- match flags. Returns true if the expression matches the whole of
- the input string.
Attempts to find a match for the current expression
- somewhere in the text p using the match flags flags - see
- match flags. Returns true if the match succeeds.
Attempts to find a match for the current expression
- somewhere in the text s using the match flags flags - see
- match flags. Returns true if the match succeeds.
Finds all matches of the current expression in the
- text p using the match flags flags - see
- match 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.
Finds all matches of the current expression in the
- text s using the match flags flags - see
- match 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.
Finds all matches of the current expression in the
- text p using the match flags flags - see
- match flags. For each match pushes a copy of what matched onto v.
- Returns the number of matches found.
Finds all matches of the current expression in the
- text s using the match flags flags - see
- match flags. For each match pushes a copy of what matched onto v.
- Returns the number of matches found.
Finds all matches of the current expression in the
- text p using the match flags flags - see
- match flags. For each match pushes the starting index of what matched
- onto v. Returns the number of matches found.
Finds all matches of the current expression in the
- text s using the match flags flags - see
- match flags. For each match pushes the starting index of what matched
- onto v. Returns the number of matches found.
Finds all matches of the current expression in the
- files files using the match flags flags - see
- match 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.
Finds all matches of the current expression in the
- files files using the match flags flags - see
- match 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.
Searches files to find all those which contain
- at least one match of the current expression using the match flags flags
- - see match 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.
Searches files to find all those which contain
- at least one match of the current expression using the match flags flags
- - see match 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.
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
- occurance of the pattern found is replaced. Returns the new string. See
- also format string syntax, match flags
- and format flags.
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
- occurance of the pattern found is replaced. Returns the new string. See
- also format string syntax, match flags
- and format flags.
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.
-
-
-
-
-
unsignedint 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.
-
-
-
-
-
unsignedint 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.
-
-
-
-
-
unsignedint 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.
The algorithm regex_format is deprecated; new code should use
-match_results::format instead. Existing code will continue to
-compile, the following documentation is taken from the previous
-version of boost.regex and will not be further updated:
The algorithm regex_format takes the results of a match and
-creates a new string based upon a
-format string, regex_format can be used for search and replace
-operations:
-
-
-template <class OutputIterator, class iterator, class Allocator, class charT>
-OutputIterator regex_format(OutputIterator out,
- const match_results<iterator, Allocator>& m,
- const charT* fmt,
- match_flag_type flags = 0);
-template <class OutputIterator, class iterator, class Allocator, class charT>
-OutputIterator regex_format(OutputIterator out,
- const match_results<iterator, Allocator>& m,
- const std::basic_string<charT>& fmt,
- match_flag_type flags = 0);
-
-
-
The library also defines the following convenience variation of
-regex_format, which returns the result directly as a string, rather
-than outputting to an iterator [note - this version may not be
-available, or may be available in a more limited form, depending
-upon your compilers capabilities]:
-
-
-template <class iterator, class Allocator, class charT>
-std::basic_string<charT> regex_format
- (const match_results<iterator, Allocator>& m,
- const charT* fmt,
- match_flag_type flags = 0);
-
-template <class iterator, class Allocator, class charT>
-std::basic_string<charT> regex_format
- (const match_results<iterator, Allocator>& m,
- const std::basic_string<charT>& fmt,
- match_flag_type flags = 0);
-
-
-
Parameters to the main version of the function are passed as
-follows:
-
-
-
-
-
-
-
OutputIterator out
-
An output iterator type, the output
-string is sent to this iterator. Typically this would be a
-std::ostream_iterator.
-
-
-
-
-
-
const
-match_results<iterator, Allocator>& m
-
An instance of match_results<>
-obtained from one of the matching algorithms above, and denoting
-what matched.
-
-
-
-
-
-
const charT* fmt
-
A format string that determines how
-the match is transformed into the new string.
-
-
-
-
-
-
unsigned flags
-
Optional flags which describe how the
-format string is to be interpreted.
-
-
-
-
-
-
-
-
-
Format flags are defined as
-follows:
-
-
-
-
-
-
-
format_all
-
Enables all syntax options (perl-like
-plus extentions).
-
-
-
-
-
-
format_sed
-
Allows only a sed-like syntax.
-
-
-
-
-
-
format_perl
-
Allows only a perl-like syntax.
-
-
-
-
-
-
format_no_copy
-
Disables copying of unmatched sections
-to the output string during
-regex_merge operations.
-
-
-
-
-
-
format_first_only
-
When this flag is set only the first occurance will be replaced
-(applies to regex_merge only).
-
-
-
-
-
-
-
-
-
The format string syntax (and available options) is described
-more fully under format strings
-.
regex_grep allows you to search through a bidirectional-iterator range and
- locate all the (non-overlapping) matches with a given regular expression. The
- function is declared as:
-
-template <class Predicate, class iterator, class charT, class traits, class Allocator>
-unsignedint regex_grep(Predicate foo,
- iterator first,
- iterator last,
- const basic_regex<charT, traits, Allocator>& e,
- boost::match_flag_type flags = match_default)
-
-
The library also defines the following convenience versions, which take either
- a const charT*, or a const std::basic_string<>& in place of a pair of
- iterators [note - these versions may not be available, or may be available in a
- more limited form, depending upon your compilers capabilities]:
-
-template <class Predicate, class charT, class Allocator, class traits>
-unsignedint regex_grep(Predicate foo,
- const charT* str,
- const basic_regex<charT, traits, Allocator>& e,
- boost::match_flag_type flags = match_default);
-
-template <class Predicate, class ST, class SA, class Allocator, class charT, class traits>
-unsignedint regex_grep(Predicate foo,
- const std::basic_string<charT, ST, SA>& s,
- const basic_regex<charT, traits, Allocator>& e,
- boost::match_flag_type flags = match_default);
-
-
The parameters for the primary version of regex_grep have the following
- meanings:
-
-
-
-
-
foo
-
A predicate function object or function pointer, see
- below for more information.
-
-
-
-
-
first
-
The start of the range to search.
-
-
-
-
-
last
-
The end of the range to search.
-
-
-
-
-
e
-
The regular expression to search for.
-
-
-
-
-
flags
-
The flags that determine how matching is carried out,
- one of the match_flags enumerators.
-
-
-
-
-
-
The algorithm finds all of the non-overlapping matches of the expression e, for
- each match it fills a match_results<iterator,
- Allocator> structure, which contains information on what matched, and calls
- the predicate foo, passing the match_results<iterator, Allocator> as a
- single argument. If the predicate returns true, then the grep operation
- continues, otherwise it terminates without searching for further matches. The
- function returns the number of matches found.
Note that in almost every case the allocator parameter can be omitted, when
- specifying the match_results type,
- alternatively one of the typedefs cmatch, wcmatch, smatch or wsmatch can be
- used.
-
For example the regular expression "a*b" would find one match in the string
- "aaaaab" and two in the string "aaabb".
-
Remember this algorithm can be used for a lot more than implementing a version
- of grep, the predicate can be and do anything that you want, grep utilities
- would output the results to the screen, another program could index a file
- based on a regular expression and store a set of bookmarks in a list, or a text
- file conversion utility would output to file. The results of one regex_grep can
- even be chained into another regex_grep to create recursive parsers.
-
The algorithm may throw std::runtime_error if the complexity
- of matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
Example: convert
- the example from regex_search to use regex_grep instead:
-
-#include <string>
-#include <map>
-#include <boost/regex.hpp>
-
-// IndexClasses:
-// takes the contents of a file in the form of a string
-// and searches for all the C++ class definitions, storing
-// their locations in a map of strings/int's
-typedef std::map<std::string, int, std::less<std::string> > map_type;
-
-const char* re =
- // possibly leading whitespace:
- "^[[:space:]]*"
- // possible template declaration:
- "(template[[:space:]]*<[^;:{]+>[[:space:]]*)?"
- // class or struct:
- "(class|struct)[[:space:]]*"
- // leading declspec macros etc:
- "("
- "\\<\\w+\\>"
- "("
- "[[:blank:]]*\\([^)]*\\)"
- ")?"
- "[[:space:]]*"
- ")*"
- // the class name
- "(\\<\\w*\\>)[[:space:]]*"
- // template specialisation parameters
- "(<[^;:{]+>)?[[:space:]]*"
- // terminate in { or :
- "(\\{|:[^;\\{()]*\\{)";
-
-boost::regex expression(re);
-class IndexClassesPred
-{
- map_type& m;
- std::string::const_iterator base;
-public:
- IndexClassesPred(map_type& a, std::string::const_iterator b) : m(a), base(b) {}
- booloperator()(const smatch& what)
- {
- // what[0] contains the whole string
-// what[5] contains the class name.
-// what[6] contains the template specialisation if any.
-// add class name and position to map:
- m[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] =
- what[5].first - base;
- returntrue;
- }
-};
-void IndexClasses(map_type& m, const std::string& file)
-{
- std::string::const_iterator start, end;
- start = file.begin();
- end = file.end();
- regex_grep(IndexClassesPred(m, start), start, end, expression);
-}
-
-
Example: Use
- regex_grep to call a global callback function:
-
-#include <string>
-#include <map>
-#include <boost/regex.hpp>
-
-// purpose:
-// takes the contents of a file in the form of a string
-// and searches for all the C++ class definitions, storing
-// their locations in a map of strings/int's
-typedef std::map<std::string, int, std::less<std::string> > map_type;
-
-const char* re =
- // possibly leading whitespace:
- "^[[:space:]]*"
- // possible template declaration:
- "(template[[:space:]]*<[^;:{]+>[[:space:]]*)?"
- // class or struct:
- "(class|struct)[[:space:]]*"
- // leading declspec macros etc:
- "("
- "\\<\\w+\\>"
- "("
- "[[:blank:]]*\\([^)]*\\)"
- ")?"
- "[[:space:]]*"
- ")*"
- // the class name
- "(\\<\\w*\\>)[[:space:]]*"
- // template specialisation parameters
- "(<[^;:{]+>)?[[:space:]]*"
- // terminate in { or :
- "(\\{|:[^;\\{()]*\\{)";
-
-boost::regex expression(re);
-map_type class_index;
-std::string::const_iterator base;
-
-bool grep_callback(const boost::smatch& what)
-{
- // what[0] contains the whole string
-// what[5] contains the class name.
-// what[6] contains the template specialisation if any.
-// add class name and position to map:
- class_index[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] =
- what[5].first - base;
- returntrue;
-}
-void IndexClasses(const std::string& file)
-{
- std::string::const_iterator start, end;
- start = file.begin();
- end = file.end();
- base = start;
- regex_grep(grep_callback, start, end, expression, match_default);
-}
-
-
-
Example: use
- regex_grep to call a class member function, use the standard library adapters std::mem_fun
- and std::bind1st to convert the member function into a predicate:
-
-#include <string>
-#include <map>
-#include <boost/regex.hpp>
-#include <functional>
-// purpose:
-// takes the contents of a file in the form of a string
-// and searches for all the C++ class definitions, storing
-// their locations in a map of strings/int's
-
-typedef std::map<std::string, int, std::less<std::string> > map_type;
-class class_index
-{
- boost::regex expression;
- map_type index;
- std::string::const_iterator base;
- bool grep_callback(boost::smatch what);
-public:
- void IndexClasses(const std::string& file);
- class_index()
- : index(),
- expression("^(template[[:space:]]*<[^;:{]+>[[:space:]]*)?"
- "(class|struct)[[:space:]]*(\\<\\w+\\>([[:blank:]]*\\([^)]*\\))?"
- "[[:space:]]*)*(\\<\\w*\\>)[[:space:]]*(<[^;:{]+>[[:space:]]*)?"
- "(\\{|:[^;\\{()]*\\{)"
- ){}
-};
-bool class_index::grep_callback(boost::smatch what)
-{
- // what[0] contains the whole string
-// what[5] contains the class name.
-// what[6] contains the template specialisation if any.
-// add class name and position to map:
- index[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] =
- what[5].first - base;
- returntrue;
-}
-
-void class_index::IndexClasses(const std::string& file)
-{
- std::string::const_iterator start, end;
- start = file.begin();
- end = file.end();
- base = start;
- regex_grep(std::bind1st(std::mem_fun(&class_index::grep_callback), this),
- start,
- end,
- expression);
-}
-
-
-
Finally, C++
- Builder users can use C++ Builder's closure type as a callback argument:
-
-#include <string>
-#include <map>
-#include <boost/regex.hpp>
-#include <functional>
-// purpose:
-// takes the contents of a file in the form of a string
-// and searches for all the C++ class definitions, storing
-// their locations in a map of strings/int's
-
-typedef std::map<std::string, int, std::less<std::string> > map_type;
-class class_index
-{
- boost::regex expression;
- map_type index;
- std::string::const_iterator base;
- typedef boost::smatch arg_type;
- bool grep_callback(const arg_type& what);
-public:
- typedefbool (__closure* grep_callback_type)(const arg_type&);
- void IndexClasses(const std::string& file);
- class_index()
- : index(),
- expression("^(template[[:space:]]*<[^;:{]+>[[:space:]]*)?"
- "(class|struct)[[:space:]]*(\\<\\w+\\>([[:blank:]]*\\([^)]*\\))?"
- "[[:space:]]*)*(\\<\\w*\\>)[[:space:]]*(<[^;:{]+>[[:space:]]*)?"
- "(\\{|:[^;\\{()]*\\{)"
- ){}
-};
-
-bool class_index::grep_callback(const arg_type& what)
-{
- // what[0] contains the whole string
-// what[5] contains the class name.
-// what[6] contains the template specialisation if any.
-// add class name and position to map:
-index[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] =
- what[5].first - base;
- returntrue;
-}
-
-void class_index::IndexClasses(const std::string& file)
-{
- std::string::const_iterator start, end;
- start = file.begin();
- end = file.end();
- base = start;
- class_index::grep_callback_type cl = &(this->grep_callback);
- regex_grep(cl,
- start,
- end,
- expression);
-}
-
The iterator type regex_iterator will enumerate all of the regular expression
- matches found in some sequence: dereferencing a regex_iterator yields a
- reference to a match_results object.
A regex_iterator is constructed from a pair of iterators, and enumerates all
- occurrences of a regular expression within that iterator range.
-
-regex_iterator();
-
-
-
Effects: constructs an end of sequence regex_iterator.
-
regex_iterator(BidirectionalIterator a, BidirectionalIterator b,
- const regex_type& re,
- match_flag_type m = match_default);
-
-
-
Effects: constructs a regex_iterator that will enumerate all occurrences
- of the expression re, within the sequence [a,b), and found
- using match flags m. The object re must exist for the
- lifetime of the regex_iterator.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
Effects: dereferencing a regex_iterator object it yields a
- const reference to a match_results object,
- whose members are set as follows:
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
(*it).size()
-
-
-
re.mark_count()
-
-
-
-
-
(*it).empty()
-
-
-
false
-
-
-
-
-
(*it).prefix().first
-
-
-
The end of the last match found, or the start of the underlying sequence if
- this is the first match enumerated
-
-
-
-
-
(*it).prefix().last
-
-
-
The same as the start of the match found:
- (*it)[0].first
-
-
-
-
-
(*it).prefix().matched
-
-
-
True if the prefix did not match an empty string:
- (*it).prefix().first != (*it).prefix().second
-
-
-
-
-
(*it).suffix().first
-
-
-
The same as the end of the match found:
- (*it)[0].second
-
-
-
-
-
(*it).suffix().last
-
-
-
The end of the underlying sequence.
-
-
-
-
-
(*it).suffix().matched
-
-
-
True if the suffix did not match an empty string:
- (*it).suffix().first != (*it).suffix().second
-
-
-
-
-
(*it)[0].first
-
-
-
The start of the sequence of characters that matched the regular expression
-
-
-
-
-
(*it)[0].second
-
-
-
The end of the sequence of characters that matched the regular expression
-
-
-
-
-
(*it)[0].matched
-
-
-
true if a full match was found, and false if it was a
- partial match (found as a result of the match_partial flag being
- set).
-
-
-
-
-
(*it)[n].first
-
-
-
For all integers n < (*it).size(), the start of the sequence that matched
- sub-expression n. Alternatively, if sub-expression n did not participate
- in the match, then last.
-
-
-
-
-
(*it)[n].second
-
-
-
For all integers n < (*it).size(), the end of the sequence that matched
- sub-expression n. Alternatively, if sub-expression n did not participate
- in the match, then last.
-
-
-
-
-
(*it)[n].matched
-
-
-
For all integers n < (*it).size(), true if sub-expression n participated
- in the match, false otherwise.
-
-
-
-
(*it).position(n)
-
For all integers n < (*it).size(), then the
- distance from the start of the underlying sequence to the start of
- sub-expression match n.
-
-
-
-
-
-
-const value_type* operator->()const;
-
-
-
Effects: returns &(*this).
-
-regex_iterator& operator++();
-
-
Effects: moves the iterator to the next match in the
- underlying sequence, or the end of sequence iterator if none if found.
- When the last match found matched a zero length string, then the
- regex_iterator will find the next match as follows: if there exists a non-zero
- length match that starts at the same location as the last one, then returns it,
- otherwise starts looking for the next (possibly zero length) match from one
- position to the right of the last match.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
-
Returns:*this.
-
-regex_iterator operator++(int);
-
-
-
Effects: constructs a copy result of *this,
- then calls ++(*this).
-
-
Returns:result.
-
Examples
-
The following example
- takes a C++ source file and builds up an index of class names, and the location
- of that class in the file.
-
-#include <string>
-#include <map>
-#include <fstream>
-#include <iostream>
-#include <boost/regex.hpp>
-
-usingnamespace std;
-
-// purpose:
-// takes the contents of a file in the form of a string
-// and searches for all the C++ class definitions, storing
-// their locations in a map of strings/int's
-
-typedef std::map<std::string, std::string::difference_type, std::less<std::string> > map_type;
-
-constchar* re =
- // possibly leading whitespace:
- "^[[:space:]]*"
- // possible template declaration:
- "(template[[:space:]]*<[^;:{]+>[[:space:]]*)?"
- // class or struct:
- "(class|struct)[[:space:]]*"
- // leading declspec macros etc:
- "("
- "\\<\\w+\\>"
- "("
- "[[:blank:]]*\\([^)]*\\)"
- ")?"
- "[[:space:]]*"
- ")*"
- // the class name
- "(\\<\\w*\\>)[[:space:]]*"
- // template specialisation parameters
- "(<[^;:{]+>)?[[:space:]]*"
- // terminate in { or :
- "(\\{|:[^;\\{()]*\\{)";
-
-
-boost::regex expression(re);
-map_type class_index;
-
-bool regex_callback(const boost::match_results<std::string::const_iterator>& what)
-{
- // what[0] contains the whole string
- // what[5] contains the class name.
- // what[6] contains the template specialisation if any.
- // add class name and position to map:
- class_index[what[5].str() + what[6].str()] = what.position(5);
- returntrue;
-}
-
-void load_file(std::string& s, std::istream& is)
-{
- s.erase();
- s.reserve(is.rdbuf()->in_avail());
- char c;
- while(is.get(c))
- {
- if(s.capacity() == s.size())
- s.reserve(s.capacity() * 3);
- s.append(1, c);
- }
-}
-
-int main(int argc, constchar** argv)
-{
- std::string text;
- for(int i = 1; i < argc; ++i)
- {
- cout << "Processing file " << argv[i] << endl;
- std::ifstream fs(argv[i]);
- load_file(text, fs);
- // construct our iterators:
- boost::sregex_iterator m1(text.begin(), text.end(), expression);
- boost::sregex_iterator m2;
- std::for_each(m1, m2, ®ex_callback);
- // copy results:
- cout << class_index.size() << " matches found" << endl;
- map_type::iterator c, d;
- c = class_index.begin();
- d = class_index.end();
- while(c != d)
- {
- cout << "class \"" << (*c).first << "\" found at index: " << (*c).second << endl;
- ++c;
- }
- class_index.erase(class_index.begin(), class_index.end());
- }
- return 0;
-}
-
- The algorithm regex _match determines whether a given regular expression
- matches all of a given character sequence denoted by a pair of
- bidirectional-iterators, the algorithm is defined as follows, the main use of
- this function is data input validation.
-
Note that the result is true only if the expression matches the whole of
- the input sequence. If you want to search for an expression
- somewhere within the sequence then use regex_search.
- If you want to match a prefix of the character string then use
- regex_search with the flag match_continuous
- set.
-
template <class BidirectionalIterator, class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
- match_results<BidirectionalIterator, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template <class BidirectionalIterator, class charT, class traits, class Allocator2>
-bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template <class charT, class Allocator, class traits, class Allocator2>
-bool regex_match(const charT* str, match_results<const charT*, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template <class ST, class SA, class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_match(const basic_string<charT, ST, SA>& s,
- match_results<typename basic_string<charT, ST, SA>::const_iterator, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template <class charT, class traits, class Allocator2>
-bool regex_match(const charT* str,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template <class ST, class SA, class charT, class traits, class Allocator2>
-bool regex_match(const basic_string<charT, ST, SA>& s,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-
Description
-
template <class BidirectionalIterator, class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
- match_results<BidirectionalIterator, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Requires: Type BidirectionalIterator meets the requirements of a
- Bidirectional Iterator (24.1.4).
-
Effects: Determines whether there is an exact match between the regular
- expression e, and all of the character sequence [first, last), parameter
- flags is used to control how the expression
- is matched against the character sequence. Returns true if such a match
- exists, false otherwise.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
Postconditions: If the function returns false, then the effect on
- parameter m is undefined, otherwise the effects on parameter m are
- given in the table:
-
-
-
-
-
-
-
Element
-
-
-
-
Value
-
-
-
-
-
-
m.size()
-
-
-
e.mark_count()
-
-
-
-
-
m.empty()
-
-
-
false
-
-
-
-
-
m.prefix().first
-
-
-
first
-
-
-
-
-
m.prefix().last
-
-
-
first
-
-
-
-
-
m.prefix().matched
-
-
-
false
-
-
-
-
-
m.suffix().first
-
-
-
last
-
-
-
-
-
m.suffix().last
-
-
-
last
-
-
-
-
-
m.suffix().matched
-
-
-
false
-
-
-
-
-
m[0].first
-
-
-
first
-
-
-
-
-
m[0].second
-
-
-
last
-
-
-
-
-
m[0].matched
-
-
-
true if a full match was found, and false if it was
- a partial match (found as a result of the match_partial flag being
- set).
-
-
-
-
-
m[n].first
-
-
-
For all integers n < m.size(), the start of the sequence that matched
- sub-expression n. Alternatively, if sub-expression n did not participate
- in the match, then last.
-
-
-
-
-
m[n].second
-
-
-
For all integers n < m.size(), the end of the sequence that matched
- sub-expression n. Alternatively, if sub-expression n did not participate
- in the match, then last.
-
-
-
-
-
m[n].matched
-
-
-
For all integers n < m.size(), true if sub-expression n participated
- in the match, false otherwise.
-
-
-
-
-
-
-
-
template <class BidirectionalIterator, class charT, class traits, class Allocator2>
-bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Effects: Behaves "as if" by constructing an instance of
- match_results<BidirectionalIterator> what,
- and then returning the result of regex_match(first, last, what, e, flags).
-
template <class charT, class Allocator, class traits, class Allocator2>
-bool regex_match(const charT* str, match_results<const charT*, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_match(str, str +
- char_traits<charT>::length(str), m, e, flags).
-
template <class ST, class SA, class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_match(const basic_string<charT, ST, SA>& s,
- match_results<typename basic_string<charT, ST, SA>::const_iterator, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_match(s.begin(), s.end(), m, e,
- flags).
-
template <class charT, class traits, class Allocator2>
-bool regex_match(const charT* str,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_match(str, str +
- char_traits<charT>::length(str), e, flags).
-
template <class ST, class SA, class charT, class traits, class Allocator2>
-bool regex_match(const basic_string<charT, ST, SA>& s,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_match(s.begin(), s.end(), e,
- flags).
-
Examples
-
The following example
- processes an ftp response:
-
-
#include <stdlib.h>
-#include <boost/regex.hpp>
-#include <string>
-#include <iostream>
-
-using namespace boost;
-
-regex expression("([0-9]+)(\\-| |$)(.*)");
-
-// process_ftp:
-// on success returns the ftp response code, and fills
-// msg with the ftp response message.
-int process_ftp(constchar* response, std::string* msg)
-{
- cmatch what;
- if(regex_match(response, what, expression))
- {
- // what[0] contains the whole string
-// what[1] contains the response code
-// what[2] contains the separator character
-// what[3] contains the text message.
-if(msg)
- msg->assign(what[3].first, what[3].second);
- return std::atoi(what[1].first);
- }
- // failure did not match
-if(msg)
- msg->erase();
- return -1;
-}
-
The algorithm regex_replace searches through a string finding
- all the matches to the regular expression: for each match it then calls
- match_results::format to format the string and sends the result to the
- output iterator. Sections of text that do not match are copied to the output
- unchanged only if the flags parameter does not have the flag
- format_no_copy set. If the flag format_first_only
- is set then only the first occurrence is replaced rather than all
- occurrences.
template <class OutputIterator, class BidirectionalIterator, class traits,
- class Allocator, class charT>
-OutputIterator regex_replace(OutputIterator out,
- BidirectionalIterator first,
- BidirectionalIterator last,
- const basic_regex<charT, traits, Allocator>& e,
- const basic_string<charT>& fmt,
- match_flag_type flags = match_default);
-
-template <class traits, class Allocator, class charT>
-basic_string<charT> regex_replace(const basic_string<charT>& s,
- const basic_regex<charT, traits, Allocator>& e,
- const basic_string<charT>& fmt,
- match_flag_type flags = match_default);
-
-
-
Description
-
template <class OutputIterator, class BidirectionalIterator, class traits,
- class Allocator, class charT>
-OutputIterator regex_replace(OutputIterator out,
- BidirectionalIterator first,
- BidirectionalIterator last,
- const basic_regex<charT, traits, Allocator>& e,
- const basic_string<charT>& fmt,
- match_flag_type flags = match_default);
-
Enumerates all the occurences of expression e in the sequence [first,
- last), replacing each occurence with the string that results by merging the
- match found with the format string fmt, and copies the resulting
- string to out.
-
If the flag format_no_copy is set in flags then unmatched sections of
- text are not copied to output.
-
-
If the flag format_first_only is set in flags then only the first
- occurence of e is replaced.
-
-
The manner in which the format string fmt is interpretted, along with
- the rules used for finding matches, are determined by the
- flags set in flags
-
Effects: Constructs an
- regex_iterator
- object:
-
-
regex_iterator<BidirectionalIterator, charT, traits, Allocator> i(first, last, e, flags),
-
and uses
-
- i
- to enumerate through all of the matches m of type
-
- match_results
- <BidirectionalIterator> that
- occur within the sequence [first, last).
-
where
-
- last_m
-
- is a copy of the last match found.
-
-
If
- flags &
-format_first_only
- is non-zero then only the first match found is replaced.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
Returns:out.
-
-
template <class traits, class Allocator, class charT>
-basic_string<charT> regex_replace(const basic_string<charT>& s,
- const basic_regex<charT, traits, Allocator>& e,
- const basic_string<charT>& fmt,
- match_flag_type flags = match_default);
-
Effects: Constructs an object basic_string<charT> result,
- calls regex_replace(back_inserter(result), s.begin(), s.end(), e, fmt,
- flags), and then returns result.
-
Examples
-
The following example
- takes C/C++ source code as input, and outputs syntax highlighted HTML code.
The algorithm regex_search will search a range denoted by a pair of
- bidirectional-iterators for a given regular expression. The algorithm uses
- various heuristics to reduce the search time by only checking for a match if a
- match could conceivably start at that position. The algorithm is defined as
- follows:
-
template <class BidirectionalIterator,
- class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_search(BidirectionalIterator first, BidirectionalIterator last,
- match_results<BidirectionalIterator, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template <class ST, class SA,
- class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_search(const basic_string<charT, ST, SA>& s,
- match_results<
- typename basic_string<charT, ST,SA>::const_iterator,
- Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template<class charT, class Allocator, class traits,
- class Allocator2>
-bool regex_search(const charT* str,
- match_results<const charT*, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
-template <class BidirectionalIterator, class Allocator,
- class charT, class traits>
-bool regex_search(BidirectionalIterator first, BidirectionalIterator last,
- const basic_regex<charT, traits, Allocator>& e,
- match_flag_type flags = match_default);
-
-template <class charT, class Allocator,
- class traits>
-bool regex_search(const charT* str,
- const basic_regex<charT, traits, Allocator>& e,
- match_flag_type flags = match_default);
-
-template<class ST, class SA,
- class Allocator, class charT,
- class traits>
-bool regex_search(const basic_string<charT, ST, SA>& s,
- const basic_regex<charT, traits, Allocator>& e,
- match_flag_type flags = match_default);
-
-
Description
-
template <class BidirectionalIterator, class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_search(BidirectionalIterator first, BidirectionalIterator last,
- match_results<BidirectionalIterator, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Requires: Type BidirectionalIterator meets the requirements of a
- Bidirectional Iterator (24.1.4).
-
Effects: Determines whether there is some sub-sequence within
- [first,last) that matches the regular expression e, parameter flags
- is used to control how the expression is matched against the character
- sequence. Returns true if such a sequence exists, false otherwise.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
Postconditions: If the function returns false, then the effect on
- parameter m is undefined, otherwise the effects on parameter m are
- given in the table:
-
-
-
-
-
-
Element
-
-
-
Value
-
-
-
-
-
-
m.size()
-
-
-
e.mark_count()
-
-
-
-
-
m.empty()
-
-
-
false
-
-
-
-
-
m.prefix().first
-
-
-
first
-
-
-
-
-
m.prefix().last
-
-
-
m[0].first
-
-
-
-
-
m.prefix().matched
-
-
-
m.prefix().first != m.prefix().second
-
-
-
-
-
m.suffix().first
-
-
-
m[0].second
-
-
-
-
-
m.suffix().last
-
-
-
last
-
-
-
-
-
m.suffix().matched
-
-
-
m.suffix().first != m.suffix().second
-
-
-
-
-
m[0].first
-
-
-
The start of the sequence of characters that matched the regular expression
-
-
-
-
-
m[0].second
-
-
-
The end of the sequence of characters that matched the regular expression
-
-
-
-
-
m[0].matched
-
-
-
true if a full match was found, and false if it was
- a partial match (found as a result of the match_partial flag being
- set).
-
-
-
-
-
m[n].first
-
-
-
For all integers n < m.size(), the start of the sequence that matched
- sub-expression n. Alternatively, if sub-expression n did not participate
- in the match, then last.
-
-
-
-
-
m[n].second
-
-
-
For all integers n < m.size(), the end of the sequence that matched
- sub-expression n. Alternatively, if sub-expression n did not participate
- in the match, then last.
-
-
-
-
-
m[n].matched
-
-
-
For all integers n < m.size(), true if sub-expression n participated
- in the match, false otherwise.
-
-
-
-
-
-
template <class charT, class Allocator, class traits, class Allocator2>
-bool regex_search(const charT* str, match_results<const charT*, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_search(str, str +
- char_traits<charT>::length(str), m, e, flags).
-
template <class ST, class SA, class Allocator, class charT,
- class traits, class Allocator2>
-bool regex_search(const basic_string<charT, ST, SA>& s,
- match_results<typename basic_string<charT, ST, SA>::const_iterator, Allocator>& m,
- const basic_regex<charT, traits, Allocator2>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_search(s.begin(), s.end(), m,
- e, flags).
-
template <class iterator, class Allocator, class charT,
- class traits>
-bool regex_search(iterator first, iterator last,
- const basic_regex<charT, traits, Allocator>& e,
- match_flag_type flags = match_default);
-
Effects: Behaves "as if" by constructing an instance of
- match_results<BidirectionalIterator> what,
- and then returning the result of regex_search(first, last, what, e, flags).
-
template <class charT, class Allocator, class traits>
-bool regex_search(const charT* str
- const basic_regex<charT, traits, Allocator>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_search(str, str +
- char_traits<charT>::length(str), e, flags).
-
template <class ST, class SA, class Allocator, class charT,
- class traits>
-bool regex_search(const basic_string<charT, ST, SA>& s,
- const basic_regex<charT, traits, Allocator>& e,
- match_flag_type flags = match_default);
-
Effects: Returns the result of regex_search(s.begin(), s.end(), e,
- flags).
-
Examples
-
The following example,
- takes the contents of a file in the form of a string, and searches for all the
- C++ class declarations in the file. The code will work regardless of the way
- that std::string is implemented, for example it could easily be modified to
- work with the SGI rope class, which uses a non-contiguous storage strategy.
-
-
#include <string>
-#include <map>
-#include <boost/regex.hpp>
-
-// purpose:
-// takes the contents of a file in the form of a string
-// and searches for all the C++ class definitions, storing
-// their locations in a map of strings/int's
-typedef std::map<std::string, int, std::less<std::string> > map_type;
-
-boost::regex expression("^(template[[:space:]]*<[^;:{]+>[[:space:]]*)?(class|struct)[[:space:]]*(\\<\\w+\\>([[:blank:]]*\\([^)]*\\))?[[:space:]]*)*(\\<\\w*\\>)[[:space:]]*(<[^;:{]+>[[:space:]]*)?(\\{|:[^;\\{()]*\\{)");
-
-void IndexClasses(map_type& m, const std::string& file)
-{
- std::string::const_iterator start, end;
- start = file.begin();
- end = file.end();
- boost::match_results<std::string::const_iterator> what;
- boost::match_flag_type flags = boost::match_default;
- while(regex_search(start, end, what, expression, flags))
- {
- // what[0] contains the whole string
-// what[5] contains the class name.
-// what[6] contains the template specialisation if any.
-// add class name and position to map:
- m[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] =
- what[5].first - file.begin();
- // update search position:
- start = what[0].second;
- // update flags:
- flags |= boost::match_prev_avail;
- flags |= boost::match_not_bob;
- }
-}
-
The algorithm regex_split has been deprecated in favor of the iterator
- regex_token_iterator which has a more flexible and powerful interface,
- as well as following the more usual standard library "pull" rather than "push"
- semantics.
-
Code which uses regex_split will continue to compile, the following
- documentation is taken from the previous boost.regex version:
Algorithm regex_split performs a similar operation to the perl split operation,
- and comes in three overloaded forms:
-
-
template <class OutputIterator, class charT, class Traits1, class Alloc1, class Traits2, class Alloc2>
-std::size_t regex_split(OutputIterator out,
- std::basic_string<charT, Traits1, Alloc1>& s,
- const basic_regex<charT, Traits2, Alloc2>& e,
- boost::match_flag_type flags,
- std::size_t max_split);
-
-template <class OutputIterator, class charT, class Traits1, class Alloc1, class Traits2, class Alloc2>
-std::size_t regex_split(OutputIterator out,
- std::basic_string<charT, Traits1, Alloc1>& s,
- const basic_regex<charT, Traits2, Alloc2>& e,
- boost::match_flag_type flags = match_default);
-
-template <class OutputIterator, class charT, class Traits1, class Alloc1>
-std::size_t regex_split(OutputIterator out,
- std::basic_string<charT, Traits1, Alloc1>& s);
-
Effects: Each version of the algorithm takes an
- output-iterator for output, and a string for input. If the expression contains
- no marked sub-expressions, then the algorithm writes one string onto the
- output-iterator for each section of input that does not match the expression.
- If the expression does contain marked sub-expressions, then each time a match
- is found, one string for each marked sub-expression will be written to the
- output-iterator. No more than max_split strings will be written to the
- output-iterator. Before returning, all the input processed will be deleted from
- the string s (if max_split is not reached then all of s will
- be deleted). Returns the number of strings written to the output-iterator. If
- the parameter max_split is not specified then it defaults to UINT_MAX.
- If no expression is specified, then it defaults to "\s+", and splitting occurs
- on whitespace.
-
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
Example: the
- following function will split the input string into a series of tokens, and
- remove each token from the string s:
-
The template class regex_token_iterator is an iterator adapter;
- that is to say it represents a new view of an existing iterator sequence, by
- enumerating all the occurrences of a regular expression within that sequence,
- and presenting one or more character sequence for each match found. Each
- position enumerated by the iterator is a sub_match
- object that represents what matched a particular sub-expression within the
- regular expression. When class regex_token_iterator is used to
- enumerate a single sub-expression with index -1, then the iterator performs
- field splitting: that is to say it enumerates one character sequence for each
- section of the character container sequence that does not match the regular
- expression specified.
regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b, const regex_type& re,
- int submatch = 0, match_flag_type m = match_default);
-
Preconditions: !re.empty(). Object re shall exist
- for the lifetime of the iterator constructed from it.
-
Effects: constructs a regex_token_iterator that will enumerate one
- string for each regular expression match of the expression re found
- within the sequence [a,b), using match flags m. The
- string enumerated is the sub-expression submatch for each match
- found; if submatch is -1, then enumerates all the text sequences that
- did not match the expression re (that is to performs field splitting).
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b, const regex_type& re,
- const std::vector<int>& submatches, match_flag_type m = match_default);
-
Preconditions:submatches.size() && !re.empty().
- Object re shall exist for the lifetime of the iterator constructed from it.
-
Effects: constructs a regex_token_iterator that will enumerate submatches.size()
- strings for each regular expression match of the expression re found
- within the sequence [a,b), using match flags m. For
- each match found one string will be enumerated for each sub-expression
- index contained within submatches vector; if submatches[0]
- is -1, then the first string enumerated for each match will be all of the text
- from end of the last match to the start of the current match, in addition there
- will be one extra string enumerated when no more matches can be found: from the
- end of the last match found, to the end of the underlying sequence.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
template <std::size_t N>
-regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b, const regex_type& re,
- const int (&submatches)[R], match_flag_type m = match_default);
-
Preconditions: !re.empty(). Object re shall exist
- for the lifetime of the iterator constructed from it.
-
Effects: constructs a regex_token_iterator that will
- enumerate R strings for each regular expression match of the
- expression re found within the sequence [a,b), using match
- flags m. For each match found one string will be
- enumerated for each sub-expression index contained within the submatches
- array; if submatches[0] is -1, then the first string enumerated
- for each match will be all of the text from end of the last match to the start
- of the current match, in addition there will be one extra string enumerated
- when no more matches can be found: from the end of the last match found, to the
- end of the underlying sequence.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
- Effects: returns the current character sequence being enumerated.
-
const value_type* operator->()const;
-
- Effects: returns &(*this).
-
regex_token_iterator& operator++();
-
- Effects: Moves on to the next character sequence to be enumerated.
-
Throws:std::runtime_error if the complexity of
- matching the expression against an N character string begins to exceed O(N2),
- or if the program runs out of stack space while matching the expression (if
- Boost.regex is configured in recursive mode),
- or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
- configured in non-recursive mode).
-
-
- Returns: *this.
regex_token_iterator& operator++(int);
-
Effects: constructs a copy result of *this,
- then calls ++(*this).
-
Returns:result.
-
Examples
-
The following example
- takes a string and splits it into a series of tokens:
Boost.regex is intended to conform to the
- regular expression standardization proposal, which will appear in a
- future C++ standard technical report (and hopefully in a future version of the
- standard). Currently there are some differences in how the regular
- expression traits classes are defined, these will be fixed in a future release.
-
ECMAScript / JavaScript
-
All of the ECMAScript regular expression syntax features are supported, except
- that:
-
Negated class escapes (\S, \D and \W) are not permitted inside character class
- definitions ( [...] ).
-
The escape sequence \u matches any upper case character (the same as
- [[:upper:]]) rather than a Unicode escape sequence; use \x{DDDD} for
- Unicode escape sequences.
-
Perl
-
Almost all Perl features are supported, except for:
-
\N{name} Use [[:name:]] instead.
-
\pP and \PP
-
(?imsx-imsx)
-
(?<=pattern)
-
(?<!pattern)
-
(?{code})
-
(??{code})
-
(?(condition)yes-pattern) and (?(condition)yes-pattern|no-pattern)
-
These embarrassments / limitations will be removed in due course, mainly
- dependent upon user demand.
-
POSIX
-
All the POSIX basic and extended regular expression features are supported,
- except that:
-
No character collating names are recognized except those specified in the POSIX
- standard for the C locale, unless they are explicitly registered with the
- traits class.
-
Character equivalence classes ( [[=a=]] etc) are probably buggy except on
- Win32. Implementing this feature requires knowledge of the format of the
- string sort keys produced by the system; if you need this, and the default
- implementation doesn't work on your platform, then you will need to supply a
- custom traits class.
Regular expressions are different from many simple pattern-matching algorithms
- in that as well as finding an overall match they can also produce
- sub-expression matches: each sub-expression being delimited in the pattern by a
- pair of parenthesis (...). There has to be some method for reporting
- sub-expression matches back to the user: this is achieved this by defining a
- class match_results that acts as an
- indexed collection of sub-expression matches, each sub-expression match being
- contained in an object of type sub_match
- .
-
Objects of type sub_match may only obtained by subscripting an object
- of type match_results
- .
-
Objects of type sub_match may be compared to objects of type std::basic_string,
- or const charT* or const charT
- .
-
Objects of type sub_match may be added to objects of type std::basic_string,
- or const charT* or const charT, to produce a new std::basic_string
-
- object.
-
When the marked sub-expression denoted by an object of type sub_match<>
- participated in a regular expression match then member matched evaluates
- to true, and members first and second denote the
- range of characters [first,second) which formed that match.
- Otherwise matched is false, and members first and second
- contained undefined values.
-
When the marked sub-expression denoted by an object of type sub_match<>
- was repeated, then the sub_match object represents the match obtained by the
- last repeat. The complete set of all the captures obtained for all the
- repeats, may be accessed via the captures() member function (Note: this has
- serious performance implications, you have to explicitly enable this feature).
-
If an object of type sub_match<> represents sub-expression 0
- - that is to say the whole match - then member matched is always
- true, unless a partial match was obtained as a result of the flag match_partial
- being passed to a regular expression algorithm, in which case member matched
- is false, and members first and second represent the
- character range that formed the partial match.
Defines an implementation-specific type that satisfies the requirements of
- a standard library Sequence (21.1.1 including the optional Table 68
- operations), whose value_type is a sub_match<BidirectionalIterator>. This
- type happens to be std::vector<sub_match<BidirectionalIterator> >,
- but you shouldn't actually rely on that.
Effects: returns a sequence containing all the captures
- obtained for this sub-expression.
-
Preconditions: the library must be built and used with
- BOOST_REGEX_MATCH_EXTRA defined, and you must pass the flag
- match_extra to the regex matching functions (regex_match,
- regex_search, regex_iterator
- or regex_token_iterator) in order for
- this member function to be defined and return useful information.
-
Rationale: Enabling this feature has several consequences:
-
-
-
- sub_match occupies more memory resulting in complex expressions running out of
- memory or stack space more quickly during matching.
-
- The matching algorithms are less efficient at handling some features
- (independent sub-expressions for example), even when match_extra is not used.
-
- The matching algorithms are much less efficient (i.e. slower), when match_extra
- is used. Mostly this is down to the extra memory allocations that have to
- take place.
The addition operators for sub_match allow you to add a sub_match to any type
- to which you can add a std::string and obtain a new string as the result.
This section covers the regular expression syntax used by this library, this is
- a programmers guide, the actual syntax presented to your program's users will
- depend upon the flags used during expression compilation.
-
-
Literals
-
-
All characters are literals except: ".", "|", "*", "?", "+", "(", ")", "{",
- "}", "[", "]", "^", "$" and "\". These characters are literals when preceded by
- a "\". A literal is a character that matches itself, or matches the result of
- traits_type::translate(), where traits_type is the traits template parameter to
- class basic_regex.
-
Wildcard
-
-
The dot character "." matches any single character except : when match_not_dot_null
- is passed to the matching algorithms, the dot does not match a null character;
- when match_not_dot_newline is passed to the matching algorithms, then
- the dot does not match a newline character.
-
-
Repeats
-
-
A repeat is an expression that is repeated an arbitrary number of times. An
- expression followed by "*" can be repeated any number of times including zero.
- An expression followed by "+" can be repeated any number of times, but at least
- once, if the expression is compiled with the flag regex_constants::bk_plus_qm
- then "+" is an ordinary character and "\+" represents a repeat of once or more.
- An expression followed by "?" may be repeated zero or one times only, if the
- expression is compiled with the flag regex_constants::bk_plus_qm then "?" is an
- ordinary character and "\?" represents the repeat zero or once operator. When
- it is necessary to specify the minimum and maximum number of repeats
- explicitly, the bounds operator "{}" may be used, thus "a{2}" is the letter "a"
- repeated exactly twice, "a{2,4}" represents the letter "a" repeated between 2
- and 4 times, and "a{2,}" represents the letter "a" repeated at least twice with
- no upper limit. Note that there must be no white-space inside the {}, and there
- is no upper limit on the values of the lower and upper bounds. When the
- expression is compiled with the flag regex_constants::bk_braces then "{" and
- "}" are ordinary characters and "\{" and "\}" are used to delimit bounds
- instead. All repeat expressions refer to the shortest possible previous
- sub-expression: a single character; a character set, or a sub-expression
- grouped with "()" for example.
-
-
Examples:
-
-
"ba*" will match all of "b", "ba", "baaa" etc.
-
-
"ba+" will match "ba" or "baaaa" for example but not "b".
-
-
"ba?" will match "b" or "ba".
-
-
"ba{2,4}" will match "baa", "baaa" and "baaaa".
-
-
Non-greedy repeats
-
-
Whenever the "extended" regular expression syntax is in use (the default) then
- non-greedy repeats are possible by appending a '?' after the repeat; a
- non-greedy repeat is one which will match the shortest possible string.
-
-
For example to match html tag pairs one could use something like:
-
-
"<\s*tagname[^>]*>(.*?)<\s*/tagname\s*>"
-
-
In this case $1 will contain the text between the tag pairs, and will be the
- shortest possible matching string.
-
-
Parenthesis
-
-
Parentheses serve two purposes, to group items together into a sub-expression,
- and to mark what generated the match. For example the expression "(ab)*" would
- match all of the string "ababab". The matching algorithms
- regex_match and regex_search each take
- an instance of match_results that reports what
- caused the match, on exit from these functions the match_results
- contains information both on what the whole expression matched and on what each
- sub-expression matched. In the example above match_results[1] would contain a
- pair of iterators denoting the final "ab" of the matching string. It is
- permissible for sub-expressions to match null strings. If a sub-expression
- takes no part in a match - for example if it is part of an alternative that is
- not taken - then both of the iterators that are returned for that
- sub-expression point to the end of the input string, and the matched parameter
- for that sub-expression is false. Sub-expressions are indexed from left
- to right starting from 1, sub-expression 0 is the whole expression.
-
-
Non-Marking Parenthesis
-
-
Sometimes you need to group sub-expressions with parenthesis, but don't want
- the parenthesis to spit out another marked sub-expression, in this case a
- non-marking parenthesis (?:expression) can be used. For example the following
- expression creates no sub-expressions:
-
-
"(?:abc)*"
-
Forward Lookahead Asserts
-
-
There are two forms of these; one for positive forward lookahead asserts, and
- one for negative lookahead asserts:
-
"(?=abc)" matches zero characters only if they are followed by the expression
- "abc".
-
"(?!abc)" matches zero characters only if they are not followed by the
- expression "abc".
-
Independent sub-expressions
-
"(?>expression)" matches "expression" as an independent atom (the algorithm
- will not backtrack into it if a failure occurs later in the expression).
-
Alternatives
-
-
Alternatives occur when the expression can match either one sub-expression or
- another, each alternative is separated by a "|", or a "\|" if the flag
- regex_constants::bk_vbar is set, or by a newline character if the flag
- regex_constants::newline_alt is set. Each alternative is the largest possible
- previous sub-expression; this is the opposite behavior from repetition
- operators.
-
-
Examples:
-
-
"a(b|c)" could match "ab" or "ac".
-
-
"abc|def" could match "abc" or "def".
-
-
Sets
-
-
A set is a set of characters that can match any single character that is a
- member of the set. Sets are delimited by "[" and "]" and can contain literals,
- character ranges, character classes, collating elements and equivalence
- classes. Set declarations that start with "^" contain the complement of the
- elements that follow.
-
-
Examples:
-
-
Character literals:
-
-
"[abc]" will match either of "a", "b", or "c".
-
-
"[^abc] will match any character other than "a", "b", or "c".
-
-
Character ranges:
-
-
"[a-z]" will match any character in the range "a" to "z".
-
-
"[^A-Z]" will match any character other than those in the range "A" to "Z".
-
-
Note that character ranges are highly locale dependent if the flag
- regex_constants::collate is set: they match any character that collates between
- the endpoints of the range, ranges will only behave according to ASCII rules
- when the default "C" locale is in effect. For example if the library is
- compiled with the Win32 localization model, then [a-z] will match the ASCII
- characters a-z, and also 'A', 'B' etc, but not 'Z' which collates just after
- 'z'. This locale specific behavior is disabled by default (in perl mode), and
- forces ranges to collate according to ASCII character code.
-
-
Character classes are denoted using the syntax "[:classname:]" within a set
- declaration, for example "[[:space:]]" is the set of all whitespace characters.
- Character classes are only available if the flag regex_constants::char_classes
- is set. The available character classes are:
-
-
-
-
-
-
-
-
alnum
-
Any alpha numeric character.
-
-
-
-
-
alpha
-
Any alphabetical character a-z and A-Z. Other
- characters may also be included depending upon the locale.
-
-
-
-
-
blank
-
Any blank character, either a space or a tab.
-
-
-
-
-
cntrl
-
Any control character.
-
-
-
-
-
digit
-
Any digit 0-9.
-
-
-
-
-
graph
-
Any graphical character.
-
-
-
-
-
lower
-
Any lower case character a-z. Other characters may
- also be included depending upon the locale.
-
-
-
-
-
print
-
Any printable character.
-
-
-
-
-
punct
-
Any punctuation character.
-
-
-
-
-
space
-
Any whitespace character.
-
-
-
-
-
upper
-
Any upper case character A-Z. Other characters may
- also be included depending upon the locale.
-
-
-
-
-
xdigit
-
Any hexadecimal digit character, 0-9, a-f and A-F.
-
-
-
-
-
word
-
Any word character - all alphanumeric characters plus
- the underscore.
-
-
-
-
-
Unicode
-
Any character whose code is greater than 255, this
- applies to the wide character traits classes only.
-
-
-
-
-
There are some shortcuts that can be used in place of the character classes,
- provided the flag regex_constants::escape_in_lists is set then you can use:
-
-
\w in place of [:word:]
-
-
\s in place of [:space:]
-
-
\d in place of [:digit:]
-
-
\l in place of [:lower:]
-
-
\u in place of [:upper:]
-
-
Collating elements take the general form [.tagname.] inside a set declaration,
- where tagname is either a single character, or a name of a collating
- element, for example [[.a.]] is equivalent to [a], and [[.comma.]] is
- equivalent to [,]. The library supports all the standard POSIX collating
- element names, and in addition the following digraphs: "ae", "ch", "ll", "ss",
- "nj", "dz", "lj", each in lower, upper and title case variations.
- Multi-character collating elements can result in the set matching more than one
- character, for example [[.ae.]] would match two characters, but note that
- [^[.ae.]] would only match one character.
-
-
- Equivalence classes take the generalform[=tagname=] inside a set declaration,
- where tagname is either a single character, or a name of a collating
- element, and matches any character that is a member of the same primary
- equivalence class as the collating element [.tagname.]. An equivalence class is
- a set of characters that collate the same, a primary equivalence class is a set
- of characters whose primary sort key are all the same (for example strings are
- typically collated by character, then by accent, and then by case; the primary
- sort key then relates to the character, the secondary to the accentation, and
- the tertiary to the case). If there is no equivalence class corresponding to tagname
- ,then[=tagname=] is exactly the same as [.tagname.]. Unfortunately there is no
- locale independent method of obtaining the primary sort key for a character,
- except under Win32. For other operating systems the library will "guess" the
- primary sort key from the full sort key (obtained from strxfrm), so
- equivalence classes are probably best considered broken under any operating
- system other than Win32.
-
-
To include a literal "-" in a set declaration then: make it the first character
- after the opening "[" or "[^", the endpoint of a range, a collating element, or
- if the flag regex_constants::escape_in_lists is set then precede with an escape
- character as in "[\-]". To include a literal "[" or "]" or "^" in a set then
- make them the endpoint of a range, a collating element, or precede with an
- escape character if the flag regex_constants::escape_in_lists is set.
-
-
Line anchors
-
-
An anchor is something that matches the null string at the start or end of a
- line: "^" matches the null string at the start of a line, "$" matches the null
- string at the end of a line.
-
-
Back references
-
-
A back reference is a reference to a previous sub-expression that has already
- been matched, the reference is to what the sub-expression matched, not to the
- expression itself. A back reference consists of the escape character "\"
- followed by a digit "1" to "9", "\1" refers to the first sub-expression, "\2"
- to the second etc. For example the expression "(.*)\1" matches any string that
- is repeated about its mid-point for example "abcabc" or "xyzxyz". A back
- reference to a sub-expression that did not participate in any match, matches
- the null string: NB this is different to some other regular expression
- matchers. Back references are only available if the expression is compiled with
- the flag regex_constants::bk_refs set.
-
-
Characters by code
-
-
This is an extension to the algorithm that is not available in other libraries,
- it consists of the escape character followed by the digit "0" followed by the
- octal character code. For example "\023" represents the character whose octal
- code is 23. Where ambiguity could occur use parentheses to break the expression
- up: "\0103" represents the character whose code is 103, "(\010)3 represents the
- character 10 followed by "3". To match characters by their hexadecimal code,
- use \x followed by a string of hexadecimal digits, optionally enclosed inside
- {}, for example \xf0 or \x{aff}, notice the latter example is a Unicode
- character.
-
Word operators
-
-
The following operators are provided for compatibility with the GNU regular
- expression library.
-
-
"\w" matches any single character that is a member of the "word" character
- class, this is identical to the expression "[[:word:]]".
-
-
"\W" matches any single character that is not a member of the "word" character
- class, this is identical to the expression "[^[:word:]]".
-
-
"\<" matches the null string at the start of a word.
-
-
"\>" matches the null string at the end of the word.
-
-
"\b" matches the null string at either the start or the end of a word.
-
-
"\B" matches a null string within a word.
-
-
The start of the sequence passed to the matching algorithms is considered to be
- a potential start of a word unless the flag match_not_bow is set. The end of
- the sequence passed to the matching algorithms is considered to be a potential
- end of a word unless the flag match_not_eow is set.
-
-
Buffer operators
-
-
The following operators are provided for compatibility with the GNU regular
- expression library, and Perl regular expressions:
-
-
"\`" matches the start of a buffer.
-
-
"\A" matches the start of the buffer.
-
-
"\'" matches the end of a buffer.
-
-
"\z" matches the end of a buffer.
-
-
"\Z" matches the end of a buffer, or possibly one or more new line characters
- followed by the end of the buffer.
-
-
A buffer is considered to consist of the whole sequence passed to the matching
- algorithms, unless the flags match_not_bob or match_not_eob are set.
-
-
Escape operator
-
-
The escape character "\" has several meanings.
-
-
Inside a set declaration the escape character is a normal character unless the
- flag regex_constants::escape_in_lists is set in which case whatever follows the
- escape is a literal character regardless of its normal meaning.
-
-
The escape operator may introduce an operator for example: back references, or
- a word operator.
-
-
The escape operator may make the following character normal, for example "\*"
- represents a literal "*" rather than the repeat operator.
-
-
Single character escape sequences
-
-
The following escape sequences are aliases for single characters:
-
-
-
-
-
-
-
-
Escape sequence
-
-
Character code
-
-
Meaning
-
-
-
-
-
-
\a
-
-
0x07
-
-
Bell character.
-
-
-
-
-
-
\f
-
-
0x0C
-
-
Form feed.
-
-
-
-
-
-
\n
-
-
0x0A
-
-
Newline character.
-
-
-
-
-
-
\r
-
-
0x0D
-
-
Carriage return.
-
-
-
-
-
-
\t
-
-
0x09
-
-
Tab character.
-
-
-
-
-
-
\v
-
-
0x0B
-
-
Vertical tab.
-
-
-
-
-
-
\e
-
-
0x1B
-
-
ASCII Escape character.
-
-
-
-
-
-
\0dd
-
-
0dd
-
-
An octal character code, where dd is one or
- more octal digits.
-
-
-
-
-
-
\xXX
-
-
0xXX
-
-
A hexadecimal character code, where XX is one or more
- hexadecimal digits.
-
-
-
-
-
-
\x{XX}
-
-
0xXX
-
-
A hexadecimal character code, where XX is one or more
- hexadecimal digits, optionally a Unicode character.
-
-
-
-
-
-
\cZ
-
-
z-@
-
-
An ASCII escape sequence control-Z, where Z is any
- ASCII character greater than or equal to the character code for '@'.
-
-
-
-
-
-
Miscellaneous escape sequences:
-
-
The following are provided mostly for perl compatibility, but note that there
- are some differences in the meanings of \l \L \u and \U:
-
-
-
-
-
-
-
-
\w
-
-
Equivalent to [[:word:]].
-
-
-
-
-
-
\W
-
-
Equivalent to [^[:word:]].
-
-
-
-
-
-
\s
-
-
Equivalent to [[:space:]].
-
-
-
-
-
-
\S
-
-
Equivalent to [^[:space:]].
-
-
-
-
-
-
\d
-
-
Equivalent to [[:digit:]].
-
-
-
-
-
-
\D
-
-
Equivalent to [^[:digit:]].
-
-
-
-
-
-
\l
-
-
Equivalent to [[:lower:]].
-
-
-
-
-
-
\L
-
-
Equivalent to [^[:lower:]].
-
-
-
-
-
-
\u
-
-
Equivalent to [[:upper:]].
-
-
-
-
-
-
\U
-
-
Equivalent to [^[:upper:]].
-
-
-
-
-
-
\C
-
-
Any single character, equivalent to '.'.
-
-
-
-
-
-
\X
-
-
Match any Unicode combining character sequence, for
- example "a\x 0301" (a letter a with an acute).
-
-
-
-
-
-
\Q
-
-
The begin quote operator, everything that follows is
- treated as a literal character until a \E end quote operator is found.
-
-
-
-
-
-
\E
-
-
The end quote operator, terminates a sequence begun
- with \Q.
-
-
-
-
-
-
What gets matched?
-
-
- When the expression is compiled as a Perl-compatible regex then the matching
- algorithms will perform a depth first search on the state machine and report
- the first match found.
-
- When the expression is compiled as a POSIX-compatible regex then the matching
- algorithms will match the first possible matching string, if more than one
- string starting at a given location can match then it matches the longest
- possible string, unless the flag match_any is set, in which case the first
- match encountered is returned. Use of the match_any option can reduce the time
- taken to find the match - but is only useful if the user is less concerned
- about what matched - for example it would not be suitable for search and
- replace operations. In cases where their are multiple possible matches all
- starting at the same location, and all of the same length, then the match
- chosen is the one with the longest first sub-expression, if that is the same
- for two or more matches, then the second sub-expression will be examined and so
- on.
-
-
- The following table examples illustrate the main differences between Perl and
- POSIX regular expression matching rules:
-
-
-
-
-
-
-
Expression
-
-
-
Text
-
-
-
POSIX leftmost longest match
-
-
-
ECMAScript depth first search match
-
-
-
-
-
a|ab
-
-
-
xaby
-
-
-
-
"ab"
-
-
-
"a"
-
-
-
-
-
.*([[:alnum:]]+).*
-
-
-
" abc def xyz "
-
-
-
$0 = " abc def xyz "
- $1 = "abc"
-
-
-
$0 = " abc def xyz "
- $1 = "z"
-
-
-
-
-
.*(a|xayy)
-
-
-
zzxayyzz
-
-
-
"zzxayy"
-
-
-
"zzxa"
-
-
-
-
These differences between Perl matching rules, and POSIX matching rules, mean
- that these two regular expression syntaxes differ not only in the features
- offered, but also in the form that the state machine takes and/or the
- algorithms used to traverse the state machine.
Type syntax_option type is an implementation specific bitmask type that
- controls how a regular expression string is to be interpreted. For
- convenience note that all the constants listed here, are also duplicated within
- the scope of class template basic_regex.
The type syntax_option_type is an implementation specific bitmask
- type (17.3.2.1.2). Setting its elements has the effects listed in the table
- below, a valid value of type syntax_option_type will always have
- exactly one of the elements normal, basic, extended, awk, grep, egrep, sed
- or perl set.
-
Note that for convenience all the constants listed here are duplicated within
- the scope of class template basic_regex, so you can use any of:
-
boost::regex_constants::constant_name
-
or
-
boost::regex::constant_name
-
or
-
boost::wregex::constant_name
-
in an interchangeable manner.
-
-
-
-
-
Element
-
-
-
Effect if set
-
-
-
-
-
normal
-
-
-
Specifies that the grammar recognized by the regular expression engine uses its
- normal semantics: that is the same as that given in the ECMA-262, ECMAScript
- Language Specification, Chapter 15 part 10, RegExp (Regular Expression) Objects
- (FWD.1).
-
boost.regex also recognizes most perl-compatible extensions in this mode.
-
-
-
-
-
icase
-
-
-
Specifies that matching of regular expressions against a character container
- sequence shall be performed without regard to case.
-
-
-
-
-
nosubs
-
-
-
Specifies that when a regular expression is matched against a character
- container sequence, then no sub-expression matches are to be stored in the
- supplied match_results structure.
-
-
-
-
-
optimize
-
-
-
Specifies that the regular expression engine should pay more attention to the
- speed with which regular expressions are matched, and less to the speed with
- which regular expression objects are constructed. Otherwise it has no
- detectable effect on the program output. This currently has no effect for
- boost.regex.
-
-
-
-
-
collate
-
-
-
Specifies that character ranges of the form "[a-b]" should be locale sensitive.
-
-
-
-
-
ECMAScript
-
-
-
The same as normal.
-
-
-
-
-
JavaScript
-
-
-
The same as normal.
-
-
-
-
-
JScript
-
-
-
The same as normal.
-
-
-
-
-
basic
-
-
-
Specifies that the grammar recognized by the regular expression engine is the
- same as that used by POSIX basic regular expressions in IEEE Std 1003.1-2001,
- Portable Operating System Interface (POSIX ), Base Definitions and Headers,
- Section 9, Regular Expressions (FWD.1).
-
-
-
-
-
-
extended
-
-
-
Specifies that the grammar recognized by the regular expression engine is the
- same as that used by POSIX extended regular expressions in IEEE Std
- 1003.1-2001, Portable Operating System Interface (POSIX ), Base Definitions and
- Headers, Section 9, Regular Expressions (FWD.1).
-
-
-
-
-
awk
-
-
-
Specifies that the grammar recognized by the regular expression engine is the
- same as that used by POSIX utility awk in IEEE Std 1003.1-2001, Portable
- Operating System Interface (POSIX ), Shells and Utilities, Section 4, awk
- (FWD.1).
-
That is to say: the same as POSIX extended syntax, but with escape sequences in
- character classes permitted.
-
-
-
-
-
grep
-
-
-
Specifies that the grammar recognized by the regular expression engine is the
- same as that used by POSIX utility grep in IEEE Std 1003.1-2001, Portable
- Operating System Interface (POSIX ), Shells and Utilities, Section 4,
- Utilities, grep (FWD.1).
-
That is to say, the same as POSIX basic syntax, but with the newline character
- acting as an alternation character in addition to "|".
-
-
-
-
-
egrep
-
-
-
Specifies that the grammar recognized by the regular expression engine is the
- same as that used by POSIX utility grep when given the -E option in IEEE Std
- 1003.1-2001, Portable Operating System Interface (POSIX ), Shells and
- Utilities, Section 4, Utilities, grep (FWD.1).
-
That is to say, the same as POSIX extended syntax, but with the newline
- character acting as an alternation character in addition to "|".
Allows the use of the escape "\" character in sets of
- characters, for example [\]] represents the set of characters containing only
- "]". If this flag is not set then "\" is an ordinary character inside sets.
-
-
-
regbase::char_classes
-
When this bit is set, character classes [:classname:]
- are allowed inside character set declarations, for example "[[:word:]]"
- represents the set of all characters that belong to the character class "word".
-
-
-
regbase:: intervals
-
When this bit is set, repetition intervals are
- allowed, for example "a{2,4}" represents a repeat of between 2 and 4 letter
- a's.
-
-
-
regbase:: limited_ops
-
When this bit is set all of "+", "?" and "|" are
- ordinary characters in all situations.
-
-
-
regbase:: newline_alt
-
When this bit is set, then the newline character "\n"
- has the same effect as the alternation operator "|".
-
-
-
regbase:: bk_plus_qm
-
When this bit is set then "\+" represents the one or
- more repetition operator and "\?" represents the zero or one repetition
- operator. When this bit is not set then "+" and "?" are used instead.
-
-
-
regbase:: bk_braces
-
When this bit is set then "\{" and "\}" are used for
- bounded repetitions and "{" and "}" are normal characters. This is the opposite
- of default behavior.
-
-
-
regbase:: bk_parens
-
When this bit is set then "\(" and "\)" are used to
- group sub-expressions and "(" and ")" are ordinary characters, this is the
- opposite of default behavior.
-
-
-
regbase:: bk_refs
-
When this bit is set then back references are
- allowed.
-
-
-
regbase:: bk_vbar
-
When this bit is set then "\|" represents the
- alternation operator and "|" is an ordinary character. This is the opposite of
- default behavior.
-
-
-
regbase:: use_except
-
When this bit is set then a bad_expression
- exception will be thrown on error. Use of this flag is deprecated -
- basic_regex will always throw on error.
-
-
-
regbase:: failbit
-
This bit is set on error, if regbase::use_except is
- not set, then this bit should be checked to see if a regular expression is
- valid before usage.
-
-
-
regbase::literal
-
All characters in the string are treated as literals,
- there are no special characters or escape sequences.
-
-
-
regbase::emacs
-
Provides compatability with the emacs
- editor, eqivalent to: bk_braces | bk_parens | bk_refs | bk_vbar.
The regex library is thread safe when Boost is: you can verify that Boost is in
- thread safe mode by checking to see if BOOST_HAS_THREADS is defined: this macro
- is set automatically by the config system when threading support is turned on
- in your compiler.
-
-
Class basic_regex<> and its typedefs regex
- and wregex are thread safe, in that compiled regular expressions can safely be
- shared between threads. The matching algorithms regex_match,
- regex_search, regex_grep,
- regex_format and regex_merge
- are all re-entrant and thread safe. Class match_results
- is now thread safe, in that the results of a match can be safely copied from
- one thread to another (for example one thread may find matches and push
- match_results instances onto a queue, while another thread pops them off the
- other end), otherwise use a separate instance of match_results
- per thread.
-
-
The POSIX API functions are all re-entrant and
- thread safe, regular expressions compiled with regcomp can also be
- shared between threads.
-
-
The class RegEx is only thread safe if each thread
- gets its own RegEx instance (apartment threading) - this is a consequence of
- RegEx handling both compiling and matching regular expressions.
-
-
Finally note that changing the global locale invalidates all compiled regular
- expressions, therefore calling set_locale from one thread while another
- uses regular expressions will produce unpredictable results.
-
-
- There is also a requirement that there is only one thread executing prior to
- the start of main().
C++ Standard Library: Dinkumware standard library version 313.
-
OS: Win32.
-
Boost version: 1.31.0.
-
PCRE version: 3.9.
-
- As ever care should be taken in interpreting the results, only sensible regular
- expressions (rather than pathological cases) are given, most are taken from the
- Boost regex examples, or from the Library of
- Regular Expressions. In addition, some variation in the relative
- performance of these libraries can be expected on other machines - as memory
- access and processor caching effects can be quite large for most finite state
- machine algorithms.
-
Averages
-
The following are the average relative scores for all the tests: the perfect
- regular expression library would score 1, in practice any small number
- (say less that 4 or 5) is pretty good.
-
-
-
GRETA
-
GRETA
- (non-recursive mode)
-
Boost
-
Boost + C++ locale
-
POSIX
-
PCRE
-
-
-
2.31619
-
6.14203
-
2.30668
-
1.94363
-
124.752
-
2.09365
-
-
-
-
Comparison 1: Long Search
-
For each of the following regular expressions the time taken to find all
- occurrences of the expression within a long English language text was measured
- (mtent12.txt
- from Project Gutenberg, 19Mb).
For each of the following regular expressions the time taken to find all
- occurrences of the expression within a medium sized English language text was
- measured (the first 50K from mtent12.txt).
For each of the following regular expressions the time taken to find all
- occurrences of the expression within the C++ source file
- boost/crc.hpp was measured.
For each of the following regular expressions the time taken to find all
- occurrences of the expression within the html file libs/libraries.htm
- was measured.