Boost.Regex: basic_regex

###  | # Boost.Regex ## basic_regex | ###

### Synopsis

    #include <boost/regex.hpp>

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:

    namespace boost{
    template <class charT, class traits = regex_traits<charT>, class Allocator = std::allocator<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 Allocator = allocator<charT> >
    class basic_regex
    {
    public:
       // types:
       typedef          charT                                value_type;
       typedef          implementation defined               const_iterator;
       typedef          const_iterator                       iterator;
       typedef typename Allocator::reference                 reference;
       typedef typename Allocator::const_reference           const_reference;
       typedef typename Allocator::difference_type           difference_type;
       typedef typename Allocator::size_type                 size_type;
       typedef          Allocator                            allocator_type;
       typedef          regex_constants::syntax_option_type  flag_type;
       typedef typename traits::locale_type                  locale_type;

       // constants:
       static const regex_constants::syntax_option_type normal = regex_constants::normal;
       static const regex_constants::syntax_option_type icase = regex_constants::icase;
       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 ECMAScript = normal;
       static const regex_constants::syntax_option_type JavaScript = normal;
       static const regex_constants::syntax_option_type JScript = normal;
       // these flags are optional, if the functionality is supported
       // then the flags shall take these names.
       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;

       // construct/copy/destroy:
       explicit basic_regex(const Allocator& a = Allocator());
       explicit basic_regex(const charT* p, flag_type f = regex_constants::normal,
                            const Allocator& a = Allocator());
       basic_regex(const charT* p1, const charT* p2, flag_type f = regex_constants::normal,
                   const Allocator& a = Allocator());
       basic_regex(const charT* p, size_type len, flag_type f,
                   const Allocator& a = Allocator());
       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,
                            const Allocator& a = Allocator());
       template <class InputIterator>
       basic_regex(InputIterator first, inputIterator last,
                   flag_type f = regex_constants::normal,
                   const Allocator& a = Allocator());

       ~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:
       const_iterator begin() const;
       const_iterator end() const;
       // capacity:
       size_type size() const;
       size_type max_size() const;
       bool empty() const;
       unsigned 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:
       Allocator get_allocator() const;
       flag_type flags() 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, class Allocator>
    bool operator == (const basic_regex<charT, traits, Allocator>& lhs,
                      const basic_regex<charT, traits, Allocator>& rhs);
    template <class charT, class traits, class Allocator>
    bool operator != (const basic_regex<charT, traits, Allocator>& lhs,
                      const basic_regex<charT, traits, Allocator>& rhs);
    template <class charT, class traits, class Allocator>
    bool operator < (const basic_regex<charT, traits, Allocator>& lhs,
                     const basic_regex<charT, traits, Allocator>& rhs);
    template <class charT, class traits, class Allocator>
    bool operator <= (const basic_regex<charT, traits, Allocator>& lhs,
                      const basic_regex<charT, traits, Allocator>& rhs);
    template <class charT, class traits, class Allocator>
    bool operator >= (const basic_regex<charT, traits, Allocator>& lhs,
                      const basic_regex<charT, traits, Allocator>& rhs);
    template <class charT, class traits, class Allocator>
    bool operator > (const basic_regex<charT, traits, Allocator>& lhs,
                     const basic_regex<charT, traits, Allocator>& rhs);

    template <class charT, class io_traits, class re_traits, class Allocator>
    basic_ostream<charT, io_traits>&
       operator << (basic_ostream<charT, io_traits>& os,
                    const basic_regex<charT, re_traits, Allocator>& e);

    template <class charT, class traits, class Allocator>
    void swap(basic_regex<charT, traits, Allocator>& e1,
              basic_regex<charT, traits, Allocator>& e2);

    typedef basic_regex<char> regex;
    typedef basic_regex<wchar_t> wregex;

    } // namespace boost

### Description

Class basic_regex has the following public member functions:

#### basic_regex constants

    static const regex_constants::syntax_option_type normal = regex_constants::normal;
    static const regex_constants::syntax_option_type icase = regex_constants::icase;
    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 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;

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.

    basic_regex(const charT* p, size_type len, flag_type f, const Allocator& a = Allocator());

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())`.

    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)`.

#### basic_regex iterators

    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.

#### basic_regex capacity

    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.

    unsigned mark_count() const;

Effects: Returns the number of marked sub-expressions within the regular expresion.

#### basic_regex assign

    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.

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 `assign(string_type(first, last), f)`.

#### basic_regex constant operations

    Allocator get_allocator() const;

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.

    template <class charT, class traits, class Allocator>
    bool operator == (const basic_regex<charT, traits, Allocator>& lhs,
                      const basic_regex<charT, traits, Allocator>& rhs);

Effects: Returns `lhs.compare(rhs) == 0`.

    template <class charT, class traits, class Allocator>
    bool operator != (const basic_regex<charT, traits, Allocator>& lhs,
                      const basic_regex<charT, traits, Allocator>& rhs);

Effects: Returns `lhs.compare(rhs) != 0`.

    template <class charT, class traits, class Allocator>
    bool operator < (const basic_regex<charT, traits, Allocator>& lhs,
                     const basic_regex<charT, traits, Allocator>& rhs);

Effects: Returns `lhs.compare(rhs) < 0`.

    template <class charT, class traits, class Allocator>
    bool operator <= (const basic_regex<charT, traits, Allocator>& lhs,
                      const basic_regex<charT, traits, Allocator>& rhs);

Effects: Returns `lhs.compare(rhs) <= 0`.

    template <class charT, class traits, class Allocator>
    bool operator >= (const basic_regex<charT, traits, Allocator>& lhs,
                      const basic_regex<charT, traits, Allocator>& rhs);

Effects: Returns `lhs.compare(rhs) >= 0`.

    template <class charT, class traits, class Allocator>
    bool operator > (const basic_regex<charT, traits, Allocator>& lhs,
                     const basic_regex<charT, traits, Allocator>& rhs);

Effects: Returns `lhs.compare(rhs) > 0`.

##### basic_regex inserter.

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, class Allocator>
    basic_ostream<charT, io_traits>&
       operator << (basic_ostream<charT, io_traits>& os
                    const basic_regex<charT, re_traits, Allocator>& e);

Effects: Returns (os << e.str()).

##### basic_regex non-member swap

    template <class charT, class traits, class Allocator>
    void swap(basic_regex<charT, traits, Allocator>& lhs,
              basic_regex<charT, traits, Allocator>& rhs);

Effects: calls `lhs.swap(rhs)`.

Revised 24 Oct 2003

© Copyright John Maddock 1998- 2003

Use, modification and distribution are subject to 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)