match_results

Synopsis

#include <boost/regex.hpp>

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:

template <class BidirectionalIterator,
         class Allocator = std::allocator<sub_match<BidirectionalIterator> >
class match_results;

typedef match_results<const char*>              cmatch;
typedef match_results<const wchar_t*>           wcmatch;
typedef match_results<string::const_iterator>   smatch;
typedef match_results<wstring::const_iterator>  wsmatch;

template <class BidirectionalIterator,
         class Allocator = std::allocator<sub_match<BidirectionalIterator> >
class match_results
{ 
public: 
   typedef          sub_match<BidirectionalIterator>                        value_type;
   typedef          const value_type&                                       const_reference;
   typedef          const_reference                                         reference;
   typedef          implementation defined                                  const_iterator;
   typedef          const_iterator                                          iterator;
   typedef typename iterator_traits<BidirectionalIterator>::difference_type difference_type;
   typedef typename Allocator::size_type                                    size_type;
   typedef          Allocator                                               allocator_type;
   typedef typename iterator_traits<BidirectionalIterator>::value_type      char_type;
   typedef          basic_string<char_type>                                 string_type;

   // construct/copy/destroy:
   explicit match_results(const Allocator& a = Allocator());
   match_results(const match_results& m);
   match_results& operator=(const match_results& m); 
   ~match_results();

   // size:
   size_type size() const;
   size_type max_size() const;
   bool empty() const;
   // element access:
   difference_type length(int sub = 0) const;
   difference_type position(unsigned int sub = 0) const;
   string_type str(int sub = 0) const;
   const_reference operator[](int n) const;

   const_reference prefix() const;

   const_reference suffix() const;
   const_iterator begin() const;
   const_iterator end() const;
   // format:
   template <class OutputIterator>
   OutputIterator format(OutputIterator out,
                        const string_type& fmt,
                        match_flag_type flags = format_default) const;
   string_type format(const string_type& fmt,
                     match_flag_type flags = format_default) const;

   allocator_type get_allocator() const;
   void swap(match_results& that);

#ifdef BOOST_REGEX_MATCH_EXTRA
   typedef typename value_type::capture_sequence_type capture_sequence_type;
   const capture_sequence_type& captures(std::size_t i)const;
#endif

};

template <class BidirectionalIterator, class Allocator>
bool operator == (const match_results<BidirectionalIterator, Allocator>& m1,
                  const match_results<BidirectionalIterator, Allocator>& m2);
template <class BidirectionalIterator, class Allocator>
bool operator != (const match_results<BidirectionalIterator, Allocator>& m1,
                  const match_results<BidirectionalIterator, Allocator>& m2);

template <class charT, class traits, class BidirectionalIterator, class Allocator>
basic_ostream<charT, traits>&
   operator << (basic_ostream<charT, traits>& os,
               const match_results<BidirectionalIterator, Allocator>& m);

template <class BidirectionalIterator, class Allocator>
void swap(match_results<BidirectionalIterator, Allocator>& m1,
         match_results<BidirectionalIterator, Allocator>& m2);

Description

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.

match_results& operator=(const match_results& 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().

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.

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. Note that if this represents a partial match , then position() will return the location of the partial match even though (*this)[0].matched is false.

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 or 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 or 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.

template <class OutputIterator>
OutputIterator format(OutputIterator out,
                     const string_type& fmt,
                     match_flag_type flags = format_default);

Requires: The type OutputIterator conforms to the Output Iterator requirements (C++ std 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.

See the format syntax guide for more information.

Returns: out.

string_type format(const string_type& fmt,
                  match_flag_type flags = format_default);

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.

See the format syntax guide for more information.

allocator_type get_allocator()const;

Effects: Returns a copy of the Allocator that was passed to the object's constructor.

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.

Complexity: constant time.

typedef typename value_type::capture_sequence_type capture_sequence_type;

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.

const capture_sequence_type& captures(std::size_t i)const;

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.

template <class BidirectionalIterator, class Allocator>
bool operator == (const match_results<BidirectionalIterator, Allocator>& m1,
                  const match_results<BidirectionalIterator, Allocator>& m2);

Effects: Compares the two sequences for equality.

template <class BidirectionalIterator, class Allocator>
bool operator != (const match_results<BidirectionalIterator, Allocator>& m1,
                  const match_results<BidirectionalIterator, Allocator>& m2);

Effects: Compares the two sequences for inequality.

template <class charT, class traits, class BidirectionalIterator, class Allocator>
basic_ostream<charT, traits>&
   operator << (basic_ostream<charT, traits>& os,
               const match_results<BidirectionalIterator, Allocator>& m);

Effects: Writes the contents of m to the stream os as if by calling os << m.str(); Returns os.

template <class BidirectionalIterator, class Allocator>
void swap(match_results<BidirectionalIterator, Allocator>& m1,
         match_results<BidirectionalIterator, Allocator>& m2);

Effects: Swaps the contents of the two sequences.

Boost C++ Libraries

match_results

Synopsis

Description