|  | Home | Libraries | People | FAQ | More | 
#include <boost/regex.hpp>
        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 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<charT>. See also 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 unicode support),
        you won't need to use anything other than these:
      
namespace boost{ template <class charT, class traits = regex_traits<charT> > class basic_regex; typedef basic_regex<char> regex; typedef basic_regex<wchar_t> 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 charT, class traits = regex_traits<charT> > 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_typeflag_type; typedef typename traits::locale_type locale_type; // constants: // main option selection: static const regex_constants::syntax_option_typenormal = regex_constants::normal; static const regex_constants::syntax_option_typeECMAScript = normal; static const regex_constants::syntax_option_typeJavaScript = normal; static const regex_constants::syntax_option_typeJScript = normal; static const regex_constants::syntax_option_typebasic = regex_constants::basic; static const regex_constants::syntax_option_typeextended = regex_constants::extended; static const regex_constants::syntax_option_typeawk = regex_constants::awk; static const regex_constants::syntax_option_typegrep = regex_constants::grep; static const regex_constants::syntax_option_typeegrep = regex_constants::egrep; static const regex_constants::syntax_option_typesed = basic = regex_constants::sed; static const regex_constants::syntax_option_typeperl = regex_constants::perl; static const regex_constants::syntax_option_typeliteral = regex_constants::literal; // modifiers specific to perl expressions: static const regex_constants::syntax_option_typeno_mod_m = regex_constants::no_mod_m; static const regex_constants::syntax_option_typeno_mod_s = regex_constants::no_mod_s; static const regex_constants::syntax_option_typemod_s = regex_constants::mod_s; static const regex_constants::syntax_option_typemod_x = regex_constants::mod_x; // modifiers specific to POSIX basic expressions: static const regex_constants::syntax_option_typebk_plus_qm = regex_constants::bk_plus_qm; static const regex_constants::syntax_option_typebk_vbar = regex_constants::bk_vbar static const regex_constants::syntax_option_typeno_char_classes = regex_constants::no_char_classes static const regex_constants::syntax_option_typeno_intervals = regex_constants::no_intervals // common modifiers: static const regex_constants::syntax_option_typenosubs = regex_constants::nosubs; static const regex_constants::syntax_option_typeoptimize = regex_constants::optimize; static const regex_constants::syntax_option_typecollate = regex_constants::collate; static const regex_constants::syntax_option_typenewline_alt = regex_constants::newline_alt; static const regex_constants::syntax_option_typeno_except = regex_constants::newline_alt; // construct/copy/destroy: explicit basic_regex (); explicit basic_regex(const charT* p, flag_type f = regex_constants::normal); basic_regex(const charT* p1, const charT* p2, flag_type f = regex_constants::normal); basic_regex(const charT* p, size_type len, flag_type f); basic_regex(const basic_regex&); template <class ST, class SA> explicit basic_regex(const basic_string<charT, ST, SA>& p, flag_type f = regex_constants::normal); template <class InputIterator> basic_regex(InputIterator first, InputIterator last, flag_type f = regex_constants::normal); ~basic_regex(); basic_regex& operator=(const basic_regex&); basic_regex& operator= (const charT* ptr); template <class ST, class SA> basic_regex& operator= (const basic_string<charT, ST, SA>& p); // iterators: std::pair<const_iterator, const_iterator> subexpression(size_type n) const; const_iterator begin() const; const_iterator end() const; // capacity: size_type size() const; size_type max_size() const; bool empty() const; size_type mark_count()const; // // modifiers: basic_regex& assign(const basic_regex& that); basic_regex& assign(const charT* ptr, flag_type f = regex_constants::normal); basic_regex& assign(const charT* ptr, unsigned int len, flag_type f); template <class string_traits, class A> basic_regex& assign(const basic_string<charT, string_traits, A>& s, flag_type f = regex_constants::normal); template <class InputIterator> basic_regex& assign(InputIterator first, InputIterator last, flag_type f = regex_constants::normal); // const operations: flag_type flags() const; int status()const; basic_string<charT> str() const; int compare(basic_regex&) const; // locale: locale_type imbue(locale_type loc); locale_type getloc() const; // swap void swap(basic_regex&) throw(); }; template <class charT, class traits> bool operator == (const basic_regex<charT, traits>& lhs, const basic_regex<charT, traits>& rhs); template <class charT, class traits> bool operator != (const basic_regex<charT, traits>& lhs, const basic_regex<charT, traits>& rhs); template <class charT, class traits> bool operator < (const basic_regex<charT, traits>& lhs, const basic_regex<charT, traits>& rhs); template <class charT, class traits> bool operator <= (const basic_regex<charT, traits>& lhs, const basic_regex<charT, traits>& rhs); template <class charT, class traits> bool operator >= (const basic_regex<charT, traits>& lhs, const basic_regex<charT, traits>& rhs); template <class charT, class traits> bool operator > (const basic_regex<charT, traits>& lhs, const basic_regex<charT, traits>& rhs); template <class charT, class io_traits, class re_traits> basic_ostream<charT, io_traits>& operator << (basic_ostream<charT, io_traits>& os, const basic_regex<charT, re_traits>& e); template <class charT, class traits> void swap(basic_regex<charT, traits>& e1, basic_regex<charT, traits>& e2); typedef basic_regex<char> regex; typedef basic_regex<wchar_t> wregex; } // namespace boost
        Class basic_regex has the
        following public members:
      
// main option selection: static const regex_constants::syntax_option_typenormal = regex_constants::normal; static const regex_constants::syntax_option_typeECMAScript = normal; static const regex_constants::syntax_option_typeJavaScript = normal; static const regex_constants::syntax_option_typeJScript = normal; static const regex_constants::syntax_option_typebasic = regex_constants::basic; static const regex_constants::syntax_option_typeextended = regex_constants::extended; static const regex_constants::syntax_option_typeawk = regex_constants::awk; static const regex_constants::syntax_option_typegrep = regex_constants::grep; static const regex_constants::syntax_option_typeegrep = regex_constants::egrep; static const regex_constants::syntax_option_typesed = regex_constants::sed; static const regex_constants::syntax_option_typeperl = regex_constants::perl; static const regex_constants::syntax_option_typeliteral = regex_constants::literal; // modifiers specific to perl expressions: static const regex_constants::syntax_option_typeno_mod_m = regex_constants::no_mod_m; static const regex_constants::syntax_option_typeno_mod_s = regex_constants::no_mod_s; static const regex_constants::syntax_option_typemod_s = regex_constants::mod_s; static const regex_constants::syntax_option_typemod_x = regex_constants::mod_x; // modifiers specific to POSIX basic expressions: static const regex_constants::syntax_option_typebk_plus_qm = regex_constants::bk_plus_qm; static const regex_constants::syntax_option_typebk_vbar = regex_constants::bk_vbar static const regex_constants::syntax_option_typeno_char_classes = regex_constants::no_char_classes static const regex_constants::syntax_option_typeno_intervals = regex_constants::no_intervals // common modifiers: static const regex_constants::syntax_option_typenosubs = regex_constants::nosubs; static const regex_constants::syntax_option_typeoptimize = regex_constants::optimize; static const regex_constants::syntax_option_typecollate = regex_constants::collate; static const regex_constants::syntax_option_typenewline_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.
      
basic_regex();
        Effects: Constructs an object of class
        basic_regex.
      
Table 1. basic_regex default construction postconditions
| Element | Value | 
|---|---|
| 
                   | 
                   | 
| 
                   | 
                   | 
| 
                   | 
                   | 
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 option
        flags specified in f.
      
Table 2. Postconditions for basic_regex construction
| Element | Value | 
|---|---|
| 
                   | 
                   | 
| 
                   | 
                   | 
| 
                   | 
                   | 
| 
                   | f | 
| 
                   | The number of marked sub-expressions within the expression. | 
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 option flags
        specified in f.
      
Table 3. Postconditions for basic_regex construction
| Element | Value | 
|---|---|
| 
                   | 
                   | 
| 
                   | 
                   | 
| 
                   | 
                   | 
| 
                   | f | 
| 
                   | The number of marked sub-expressions within the expression. | 
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 4. Postconditions for basic_regex construction
| Element | Value | 
|---|---|
| 
                   | 
                   | 
| 
                   | len | 
| 
                   | 
                   | 
| 
                   | f | 
| 
                   | 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.
      
template <class ST, class SA> basic_regex(const basic_string<charT, ST, SA>& 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 option
        flags specified in f.
      
Table 5. Postconditions for basic_regex construction
| Element | Value | 
|---|---|
| 
                   | 
                   | 
| 
                   | 
                   | 
| 
                   | s | 
| 
                   | f | 
| 
                   | The number of marked sub-expressions within the expression. | 
template <class ForwardIterator> 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 option
        flags specified in f.
      
Table 6. Postconditions for basic_regex construction
| Element | Value | 
|---|---|
| 
                   | 
                   | 
| 
                   | 
                   | 
| 
                   | 
                   | 
| 
                   | f | 
| 
                   | 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()).
      
basic_regex& operator=(const charT* ptr);
Requires: p shall not be a null pointer.
        Effects: Returns the result of assign(ptr).
      
template <class ST, class SA> basic_regex& operator=(const basic_string<charT, ST, SA>& p);
        Effects: Returns the result of assign(p).
      
std::pair<const_iterator, const_iterator> 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().
      
const_iterator begin() const;
Effects: Returns a starting iterator to a sequence of characters representing the regular expression.
const_iterator end() const;
Effects: Returns termination iterator to a sequence of characters representing the regular expression.
size_type size() const;
Effects: Returns the length of the sequence of characters representing the regular expression.
size_type max_size() const;
Effects: Returns the maximum length of the sequence of characters representing the regular expression.
bool empty() const;
Effects: Returns true if the object does not contain a valid regular expression, otherwise false.
size_type mark_count() const;
Effects: Returns the number of marked sub-expressions within the regular expression.
basic_regex& assign(const basic_regex& that);
        Effects: Returns assign(that.str(), that.flags()).
      
basic_regex& assign(const charT* ptr, flag_type f = regex_constants::normal);
        Effects: Returns assign(string_type(ptr), f).
      
basic_regex& assign(const charT* ptr, unsigned int len, flag_type f);
        Effects: Returns assign(string_type(ptr, len), f).
      
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, unless the flag no_except
        is set in f.
      
Returns: *this.
Effects: Assigns the regular expression contained in the string s, interpreted according the option flags specified in f.
Table 7. Postconditions for basic_regex::assign
| Element | Value | 
|---|---|
| 
                   | 
                   | 
| 
                   | 
                   | 
| 
                   | s | 
| 
                   | f | 
| 
                   | 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 assign(string_type(first, last), f).
      
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.
      
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.
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().
      
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.
      
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]](../../../../../../doc/src/images/note.png) | Note | 
|---|---|
| 
          Comparisons between  | 
template <class charT, class traits> bool operator == (const basic_regex<charT, traits>& lhs, const basic_regex<charT, traits>& rhs);
        Effects: Returns lhs.compare(rhs)
        == 0.
      
template <class charT, class traits> bool operator != (const basic_regex<charT, traits>& lhs, const basic_regex<charT, traits>& rhs);
        Effects: Returns lhs.compare(rhs)
        != 0.
      
template <class charT, class traits> bool operator < (const basic_regex<charT, traits>& lhs, const basic_regex<charT, traits>& rhs);
        Effects: Returns lhs.compare(rhs)
        < 0.
      
template <class charT, class traits> bool operator <= (const basic_regex<charT, traits>& lhs, const basic_regex<charT, traits>& rhs);
        Effects: Returns lhs.compare(rhs)
        <= 0.
      
template <class charT, class traits> bool operator >= (const basic_regex<charT, traits>& lhs, const basic_regex<charT, traits>& rhs);
        Effects: Returns lhs.compare(rhs)
        >= 0.
      
template <class charT, class traits> bool operator > (const basic_regex<charT, traits>& lhs, const basic_regex<charT, traits>& rhs);
        Effects: Returns lhs.compare(rhs)
        > 0.
      
| ![[Note]](../../../../../../doc/src/images/note.png) | Note | 
|---|---|
| The basic_regex stream inserter is provided on an experimental basis, and outputs the textual representation of the expression to the stream. | 
template <class charT, class io_traits, class re_traits> basic_ostream<charT, io_traits>& operator << (basic_ostream<charT, io_traits>& os const basic_regex<charT, re_traits>& e);
        Effects: Returns (os << e.str()).
      
template <class charT, class traits> void swap(basic_regex<charT, traits>& lhs, basic_regex<charT, traits>& rhs);
        Effects: calls lhs.swap(rhs).