[/ Copyright 2006-2007 John Maddock. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt). ] [section:basic_regex basic_regex] [h4 Synopsis] #include The template class `basic_regex` encapsulates regular expression parsing and compilation. The class takes two template parameters: * `charT`: determines the character type, i.e. either `char` or `wchar_t`; see [link boost_regex.ref.concepts.charT_concept charT concept]. * `traits`: determines the behavior of the character type, for example which character class names are recognized. A default traits class is provided: `regex_traits`. See also [link boost_regex.ref.concepts.traits_concept traits concept]. 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 non-standard character types (for example see [link boost_regex.ref.non_std_strings.icu unicode support]), you won't need to use anything other than these: namespace boost{ template > class basic_regex; typedef basic_regex regex; typedef basic_regex wregex; } 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`. namespace boost{ template > class basic_regex { public: // types: typedef charT value_type; typedef implementation-specific const_iterator; typedef const_iterator iterator; typedef charT& reference; typedef const charT& const_reference; typedef std::ptrdiff_t difference_type; typedef std::size_t size_type; typedef regex_constants::``[syntax_option_type]`` flag_type; typedef typename traits::locale_type locale_type; // constants: // main option selection: static const regex_constants::``[syntax_option_type]`` normal = regex_constants::normal; static const regex_constants::``[syntax_option_type]`` ECMAScript = normal; static const regex_constants::``[syntax_option_type]`` JavaScript = normal; static const regex_constants::``[syntax_option_type]`` JScript = normal; static const regex_constants::``[syntax_option_type]`` basic = regex_constants::basic; static const regex_constants::``[syntax_option_type]`` extended = regex_constants::extended; static const regex_constants::``[syntax_option_type]`` awk = regex_constants::awk; static const regex_constants::``[syntax_option_type]`` grep = regex_constants::grep; static const regex_constants::``[syntax_option_type]`` egrep = regex_constants::egrep; static const regex_constants::``[syntax_option_type]`` sed = basic = regex_constants::sed; static const regex_constants::``[syntax_option_type]`` perl = regex_constants::perl; static const regex_constants::``[syntax_option_type]`` literal = regex_constants::literal; // modifiers specific to perl expressions: static const regex_constants::``[syntax_option_type]`` no_mod_m = regex_constants::no_mod_m; static const regex_constants::``[syntax_option_type]`` no_mod_s = regex_constants::no_mod_s; static const regex_constants::``[syntax_option_type]`` mod_s = regex_constants::mod_s; static const regex_constants::``[syntax_option_type]`` mod_x = regex_constants::mod_x; // modifiers specific to POSIX basic expressions: static const regex_constants::``[syntax_option_type]`` bk_plus_qm = regex_constants::bk_plus_qm; static const regex_constants::``[syntax_option_type]`` bk_vbar = regex_constants::bk_vbar static const regex_constants::``[syntax_option_type]`` no_char_classes = regex_constants::no_char_classes static const regex_constants::``[syntax_option_type]`` no_intervals = regex_constants::no_intervals // common modifiers: static const regex_constants::``[syntax_option_type]`` nosubs = regex_constants::nosubs; static const regex_constants::``[syntax_option_type]`` optimize = regex_constants::optimize; static const regex_constants::``[syntax_option_type]`` collate = regex_constants::collate; static const regex_constants::``[syntax_option_type]`` newline_alt = regex_constants::newline_alt; static const regex_constants::``[syntax_option_type]`` no_except = regex_constants::newline_alt; // construct/copy/destroy: explicit ``[link boost_regex.basic_regex.construct1 basic_regex]`` (); explicit ``[link boost_regex.basic_regex.construct2 basic_regex]``(const charT* p, flag_type f = regex_constants::normal); ``[link boost_regex.basic_regex.construct3 basic_regex]``(const charT* p1, const charT* p2, flag_type f = regex_constants::normal); ``[link boost_regex.basic_regex.construct4 basic_regex]``(const charT* p, size_type len, flag_type f); ``[link boost_regex.basic_regex.construct5 basic_regex]``(const basic_regex&); template explicit ``[link boost_regex.basic_regex.construct6 basic_regex]``(const basic_string& p, flag_type f = regex_constants::normal); template ``[link boost_regex.basic_regex.construct7 basic_regex]``(InputIterator first, InputIterator last, flag_type f = regex_constants::normal); ~basic_regex(); ``[link boost_regex.basic_regex.opeq1 basic_regex& operator=]``(const basic_regex&); ``[link boost_regex.basic_regex.opeq2 basic_regex& operator=]`` (const charT* ptr); template ``[link boost_regex.basic_regex.opeq3 basic_regex& operator=]`` (const basic_string& p); // iterators: ``[link boost_regex.basic_regex.subexpression std::pair subexpression]``(size_type n) const; ``[link boost_regex.basic_regex.begin const_iterator begin]``() const; ``[link boost_regex.basic_regex.end const_iterator end]``() const; // capacity: ``[link boost_regex.basic_regex.size size_type size]``() const; ``[link boost_regex.basic_regex.max_size size_type max_size]``() const; ``[link boost_regex.basic_regex.empty bool empty]``() const; ``[link boost_regex.basic_regex.mark_count size_type mark_count]``()const; // // modifiers: ``[link boost_regex.basic_regex.assign1 basic_regex& assign]``(const basic_regex& that); ``[link boost_regex.basic_regex.assign2 basic_regex& assign]``(const charT* ptr, flag_type f = regex_constants::normal); ``[link boost_regex.basic_regex.assign3 basic_regex& assign]``(const charT* ptr, unsigned int len, flag_type f); template ``[link boost_regex.basic_regex.assign4 basic_regex& assign]``(const basic_string& s, flag_type f = regex_constants::normal); template ``[link boost_regex.basic_regex.assign5 basic_regex& assign]``(InputIterator first, InputIterator last, flag_type f = regex_constants::normal); // const operations: ``[link boost_regex.basic_regex.flags flag_type flags]``() const; ``[link boost_regex.basic_regex.status int status]``()const; ``[link boost_regex.basic_regex.str basic_string str]``() const; ``[link boost_regex.basic_regex.compare int compare]``(basic_regex&) const; // locale: ``[link boost_regex.basic_regex.imbue locale_type imbue]``(locale_type loc); ``[link boost_regex.basic_regex.getloc locale_type getloc]``() const; // swap ``[link boost_regex.basic_regex.swap void swap]``(basic_regex&) throw(); }; template ``[link boost_regex.basic_regex.op_eq bool operator ==]`` (const basic_regex& lhs, const basic_regex& rhs); template ``[link boost_regex.basic_regex.op_ne bool operator !=]`` (const basic_regex& lhs, const basic_regex& rhs); template ``[link boost_regex.basic_regex.op_lt bool operator <]`` (const basic_regex& lhs, const basic_regex& rhs); template ``[link boost_regex.basic_regex.op_le bool operator <=]`` (const basic_regex& lhs, const basic_regex& rhs); template ``[link boost_regex.basic_regex.op_ge bool operator >=]`` (const basic_regex& lhs, const basic_regex& rhs); template ``[link boost_regex.basic_regex.op_gt bool operator >]`` (const basic_regex& lhs, const basic_regex& rhs); template basic_ostream& ``[link boost_regex.basic_regex.op_stream operator <<]`` (basic_ostream& os, const basic_regex& e); template ``[link boost_regex.basic_regex.op_swap void swap]``(basic_regex& e1, basic_regex& e2); typedef basic_regex regex; typedef basic_regex wregex; } // namespace boost [h4 Description] Class `basic_regex` has the following public members: // main option selection: static const regex_constants::``[syntax_option_type]`` normal = regex_constants::normal; static const regex_constants::``[syntax_option_type]`` ECMAScript = normal; static const regex_constants::``[syntax_option_type]`` JavaScript = normal; static const regex_constants::``[syntax_option_type]`` JScript = normal; static const regex_constants::``[syntax_option_type]`` basic = regex_constants::basic; static const regex_constants::``[syntax_option_type]`` extended = regex_constants::extended; static const regex_constants::``[syntax_option_type]`` awk = regex_constants::awk; static const regex_constants::``[syntax_option_type]`` grep = regex_constants::grep; static const regex_constants::``[syntax_option_type]`` egrep = regex_constants::egrep; static const regex_constants::``[syntax_option_type]`` sed = regex_constants::sed; static const regex_constants::``[syntax_option_type]`` perl = regex_constants::perl; static const regex_constants::``[syntax_option_type]`` literal = regex_constants::literal; // modifiers specific to perl expressions: static const regex_constants::``[syntax_option_type]`` no_mod_m = regex_constants::no_mod_m; static const regex_constants::``[syntax_option_type]`` no_mod_s = regex_constants::no_mod_s; static const regex_constants::``[syntax_option_type]`` mod_s = regex_constants::mod_s; static const regex_constants::``[syntax_option_type]`` mod_x = regex_constants::mod_x; // modifiers specific to POSIX basic expressions: static const regex_constants::``[syntax_option_type]`` bk_plus_qm = regex_constants::bk_plus_qm; static const regex_constants::``[syntax_option_type]`` bk_vbar = regex_constants::bk_vbar static const regex_constants::``[syntax_option_type]`` no_char_classes = regex_constants::no_char_classes static const regex_constants::``[syntax_option_type]`` no_intervals = regex_constants::no_intervals // common modifiers: static const regex_constants::``[syntax_option_type]`` nosubs = regex_constants::nosubs; static const regex_constants::``[syntax_option_type]`` optimize = regex_constants::optimize; static const regex_constants::``[syntax_option_type]`` collate = regex_constants::collate; static const regex_constants::``[syntax_option_type]`` newline_alt = regex_constants::newline_alt; The meaning of these options is documented in the [syntax_option_type] section. 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. [#boost_regex.basic_regex.construct1] basic_regex(); [*Effects]: Constructs an object of class `basic_regex`. [table basic_regex default construction postconditions [[Element][Value]] [[`empty()`][`true`]] [[`size()`][`0`]] [[`str()`][`basic_string()`]] ] [#boost_regex.basic_regex.construct2] basic_regex(const charT* p, flag_type f = regex_constants::normal); [*Requires]: /p/ shall not be a null pointer. [*Throws]: [bad_expression] if /p/ is not a valid regular expression, unless the flag `no_except` is set in /f/. [*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 [link boost_regex.ref.syntax_option_type option flags] specified in /f/. [table Postconditions for basic_regex construction [[Element][Value]] [[`empty()`][`false`]] [[`size()`][`char_traits::length(p)`]] [[`str()`][`basic_string(p)`]] [[`flags()`][['f]]] [[`mark_count()`][The number of marked sub-expressions within the expression.]] ] [#boost_regex.basic_regex.construct3] basic_regex(const charT* p1, const charT* p2, flag_type f = regex_constants::normal); [*Requires]: /p1/ and /p2/ are not null pointers, `p1 < p2`. [*Throws]: bad_expression if \[p1,p2) is not a valid regular expression, unless the flag `no_except` is set in /f/. [*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 [link boost_regex.ref.syntax_option_type option flags] specified in /f/. [table Postconditions for basic_regex construction [[Element][Value]] [[`empty()`][`false`]] [[`size()`][`std::distance(p1,p2)`]] [[`str()`][`basic_string(p1,p2)`]] [[`flags()`][['f]]] [[`mark_count()`][The number of marked sub-expressions within the expression.]] ] [#boost_regex.basic_regex.construct4] basic_regex(const charT* p, size_type len, flag_type f); [*Requires]: /p/ shall not be a null pointer, `len < max_size()`. [*Throws]: [bad_expression] if /p/ is not a valid regular expression, unless the flag `no_except` is set in /f/. [*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/. [table Postconditions for basic_regex construction [[Element][Value]] [[`empty()`][`false`]] [[`size()`][['len]]] [[`str()`][`basic_string(p, len)`]] [[`flags()`][['f]]] [[`mark_count()`][The number of marked sub-expressions within the expression.]] ] [#boost_regex.basic_regex.construct5] basic_regex(const basic_regex& e); [*Effects]: Constructs an object of class [basic_regex] as a copy of the object /e/. [#boost_regex.basic_regex.construct6] template basic_regex(const basic_string& s, flag_type f = regex_constants::normal); [*Throws]: [bad_expression] if /s/ is not a valid regular expression, unless the flag `no_except` is set in /f/. [*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 [link boost_regex.ref.syntax_option_type option flags] specified in /f/. [table Postconditions for basic_regex construction [[Element][Value]] [[`empty()`][`false`]] [[`size()`][`s.size()`]] [[`str()`][['s]]] [[`flags()`][['f]]] [[`mark_count()`][The number of marked sub-expressions within the expression.]] ] [#boost_regex.basic_regex.construct7] template basic_regex(ForwardIterator first, ForwardIterator last, flag_type f = regex_constants::normal); [*Throws]: [bad_expression] if the sequence \[first, last) is not a valid regular expression, unless the flag `no_except` is set in /f/. [*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 [link boost_regex.ref.syntax_option_type option flags] specified in /f/. [table Postconditions for basic_regex construction [[Element][Value]] [[`empty()`][`false`]] [[`size()`][`distance(first,last)`]] [[`str()`][`basic_string(first,last)`]] [[`flags()`][['f]]] [[`mark_count()`][The number of marked sub-expressions within the expression.]] ] [#boost_regex.basic_regex.opeq1] basic_regex& operator=(const basic_regex& e); [*Effects]: Returns the result of `assign(e.str(), e.flags())`. [#boost_regex.basic_regex.opeq2] basic_regex& operator=(const charT* ptr); [*Requires]: /p/ shall not be a null pointer. [*Effects]: Returns the result of `assign(ptr)`. [#boost_regex.basic_regex.opeq3] template basic_regex& operator=(const basic_string& p); [*Effects]: Returns the result of `assign(p)`. [#boost_regex.basic_regex.subexpression] std::pair subexpression(size_type n) const; [*Effects]: Returns a pair of iterators denoting the location of marked subexpression /n/ within the original regular expression string. The returned iterators are relative to `begin()` and `end()`. [*Requires]: The expression must have been compiled with the [syntax_option_type] save_subexpression_location set. Argument /n/ must be in within the range `0 <= n < mark_count()`. [#boost_regex.basic_regex.begin] const_iterator begin() const; [*Effects]: Returns a starting iterator to a sequence of characters representing the regular expression. [#boost_regex.basic_regex.end] const_iterator end() const; [*Effects]: Returns termination iterator to a sequence of characters representing the regular expression. [#boost_regex.basic_regex.size] size_type size() const; [*Effects]: Returns the length of the sequence of characters representing the regular expression. [#boost_regex.basic_regex.max_size] size_type max_size() const; [*Effects]: Returns the maximum length of the sequence of characters representing the regular expression. [#boost_regex.basic_regex.empty] bool empty() const; [*Effects]: Returns true if the object does not contain a valid regular expression, otherwise false. [#boost_regex.basic_regex.mark_count] size_type mark_count() const; [*Effects]: Returns the number of marked sub-expressions within the regular expression. [#boost_regex.basic_regex.assign1] basic_regex& assign(const basic_regex& that); [*Effects]: Returns [link boost_regex.basic_regex.assign4 `assign(that.str(), that.flags())`]. [#boost_regex.basic_regex.assign2] basic_regex& assign(const charT* ptr, flag_type f = regex_constants::normal); [*Effects]: Returns [link boost_regex.basic_regex.assign4 `assign(string_type(ptr), f)`]. [#boost_regex.basic_regex.assign3] basic_regex& assign(const charT* ptr, unsigned int len, flag_type f); [*Effects]: Returns [link boost_regex.basic_regex.assign4 `assign(string_type(ptr, len), f)`]. [#boost_regex.basic_regex.assign4] template basic_regex& assign(const basic_string& s, flag_type f = regex_constants::normal); [*Throws]: [bad_expression] if /s/ is not a valid regular expression, unless the flag `no_except` is set in /f/. [*Returns]: *this. [*Effects]: Assigns the regular expression contained in the string /s/, interpreted according the [link boost_regex.ref.syntax_option_type option flags] specified in /f/. [table Postconditions for basic_regex::assign [[Element][Value]] [[`empty()`][`false`]] [[`size()`][`s.size()`]] [[`str()`][['s]]] [[`flags()`][['f]]] [[`mark_count()`][The number of marked sub-expressions within the expression.]] ] [#boost_regex.basic_regex.assign5] template basic_regex& assign(InputIterator first, InputIterator last, flag_type f = regex_constants::normal); [*Requires]: The type `InputIterator` corresponds to the [@http://input_iterator Input Iterator requirements (24.1.1)]. [*Effects]: Returns [link boost_regex.basic_regex.assign4 `assign(string_type(first, last), f)`]. [#boost_regex.basic_regex.flags] flag_type flags() const; [*Effects]: Returns a copy of the [link boost_regex.ref.syntax_option_type regular expression syntax flags] that were passed to the object's constructor, or the last call to `assign`. [#boost_regex.basic_regex.status] int status() const; [*Effects]: Returns zero if the expression contains a valid regular expression, otherwise an error code. This member function is retained for use in environments that cannot use exception handling. [#boost_regex.basic_regex.str] basic_string str() const; [*Effects]: Returns a copy of the character sequence passed to the object's constructor, or the last call to assign. [#boost_regex.basic_regex.compare] int compare(basic_regex& e)const; [*Effects]: If `flags() == e.flags()` then returns `str().compare(e.str())`, otherwise returns `flags() - e.flags()`. [#boost_regex.basic_regex.imbue] 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`. [#boost_regex.basic_regex.getloc] 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. [#boost_regex.basic_regex.swap] void swap(basic_regex& e) throw(); [*Effects]: Swaps the contents of the two regular expressions. [*Postcondition]: `*this` contains the regular expression that was in /e/, /e/ contains the regular expression that was in `*this`. [*Complexity]: constant time. [note Comparisons between [basic_regex] objects are provided on an experimental basis: please note that these are not present in the [tr1], so use with care if you are writing code that may need to be ported to other implementations of [basic_regex].] [#boost_regex.basic_regex.op_eq] template bool operator == (const basic_regex& lhs, const basic_regex& rhs); [*Effects]: Returns `lhs.compare(rhs) == 0`. [#boost_regex.basic_regex.op_ne] template bool operator != (const basic_regex& lhs, const basic_regex& rhs); [*Effects]: Returns `lhs.compare(rhs) != 0`. [#boost_regex.basic_regex.op_lt] template bool operator < (const basic_regex& lhs, const basic_regex& rhs); [*Effects]: Returns `lhs.compare(rhs) < 0`. [#boost_regex.basic_regex.op_le] template bool operator <= (const basic_regex& lhs, const basic_regex& rhs); [*Effects]: Returns `lhs.compare(rhs) <= 0`. [#boost_regex.basic_regex.op_ge] template bool operator >= (const basic_regex& lhs, const basic_regex& rhs); [*Effects]: Returns `lhs.compare(rhs) >= 0`. [#boost_regex.basic_regex.op_gt] template bool operator > (const basic_regex& lhs, const basic_regex& rhs); [*Effects]: Returns `lhs.compare(rhs) > 0`. [note The basic_regex stream inserter is provided on an experimental basis, and outputs the textual representation of the expression to the stream.] [#boost_regex.basic_regex.op_stream] template basic_ostream& operator << (basic_ostream& os const basic_regex& e); [*Effects]: Returns `(os << e.str())`. [#boost_regex.basic_regex.op_swap] template void swap(basic_regex& lhs, basic_regex& rhs); [*Effects]: calls `lhs.swap(rhs)`. [endsect]