1[/ 2 Copyright 2006-2007 John Maddock. 3 Distributed under the Boost Software License, Version 1.0. 4 (See accompanying file LICENSE_1_0.txt or copy at 5 http://www.boost.org/LICENSE_1_0.txt). 6] 7 8[section:match_results match_results] 9 10[h4 Synopsis] 11 12 #include <boost/regex.hpp> 13 14Regular expressions are different from many simple pattern-matching algorithms 15in that as well as finding an overall match they can also produce 16sub-expression matches: each sub-expression being delimited in the 17pattern by a pair of parenthesis (...). There has to be some method for 18reporting sub-expression matches back to the user: this is achieved this by 19defining a class `match_results` that acts as an indexed collection of 20sub-expression matches, each sub-expression match being contained in an 21object of type [sub_match]. 22 23Template class `match_results` denotes a collection of character 24sequences representing the result of a regular expression match. Objects of 25type `match_results` are passed to the algorithms [regex_match] and [regex_search], 26and are returned by the iterator [regex_iterator]. Storage for the 27collection is allocated and freed as necessary by the member functions of 28class `match_results`. 29 30The template class `match_results` conforms to the requirements of a Sequence, 31as specified in (lib.sequence.reqmts), except that only operations defined for 32const-qualified Sequences are supported. 33 34Class template `match_results` is most commonly used as one of the typedefs 35`cmatch`, `wcmatch`, `smatch`, or `wsmatch`: 36 37 template <class BidirectionalIterator, 38 class Allocator = std::allocator<sub_match<BidirectionalIterator> > 39 class match_results; 40 41 typedef match_results<const char*> cmatch; 42 typedef match_results<const wchar_t*> wcmatch; 43 typedef match_results<string::const_iterator> smatch; 44 typedef match_results<wstring::const_iterator> wsmatch; 45 46 template <class BidirectionalIterator, 47 class Allocator = std::allocator<sub_match<BidirectionalIterator> > 48 class match_results 49 { 50 public: 51 typedef sub_match<BidirectionalIterator> value_type; 52 typedef const value_type& const_reference; 53 typedef const_reference reference; 54 typedef implementation defined const_iterator; 55 typedef const_iterator iterator; 56 typedef typename iterator_traits<BidirectionalIterator>::difference_type difference_type; 57 typedef typename Allocator::size_type size_type; 58 typedef Allocator allocator_type; 59 typedef typename iterator_traits<BidirectionalIterator>::value_type char_type; 60 typedef basic_string<char_type> string_type; 61 62 // construct/copy/destroy: 63 ``[link boost_regex.match_results.construct explicit match_results]``(const Allocator& a = Allocator()); 64 ``[link boost_regex.match_results.copy_construct match_results]``(const match_results& m); 65 ``[link boost_regex.match_results.assign match_results& operator=]``(const match_results& m); 66 ~match_results(); 67 68 // size: 69 size_type ``[link boost_regex.match_results.size size]``() const; 70 size_type ``[link boost_regex.match_results.max_size max_size]``() const; 71 bool ``[link boost_regex.match_results.empty empty]``() const; 72 // element access: 73 difference_type ``[link boost_regex.match_results.length length]``(int sub = 0) const; 74 difference_type ``[link boost_regex.match_results.length length]``(const char_type* sub) const; 75 template <class charT> 76 difference_type ``[link boost_regex.match_results.length length]``(const charT* sub) const; 77 template <class charT, class Traits, class A> 78 difference_type ``[link boost_regex.match_results.length length]``(const std::basic_string<charT, Traits, A>& sub) const; 79 difference_type ``[link boost_regex.match_results.position position]``(unsigned int sub = 0) const; 80 difference_type ``[link boost_regex.match_results.position position]``(const char_type* sub) const; 81 template <class charT> 82 difference_type ``[link boost_regex.match_results.position position]``(const charT* sub) const; 83 template <class charT, class Traits, class A> 84 difference_type ``[link boost_regex.match_results.position position]``(const std::basic_string<charT, Traits, A>& sub) const; 85 string_type ``[link boost_regex.match_results.str str]``(int sub = 0) const; 86 string_type ``[link boost_regex.match_results.str str]``(const char_type* sub)const; 87 template <class Traits, class A> 88 string_type ``[link boost_regex.match_results.str str]``(const std::basic_string<char_type, Traits, A>& sub)const; 89 template <class charT> 90 string_type ``[link boost_regex.match_results.str str]``(const charT* sub)const; 91 template <class charT, class Traits, class A> 92 string_type ``[link boost_regex.match_results.str str]``(const std::basic_string<charT, Traits, A>& sub)const; 93 const_reference ``[link boost_regex.match_results.subscript operator\[\]]``(int n) const; 94 const_reference ``[link boost_regex.match_results.subscript operator\[\]]``(const char_type* n) const; 95 template <class Traits, class A> 96 const_reference ``[link boost_regex.match_results.subscript operator\[\]]``(const std::basic_string<char_type, Traits, A>& n) const; 97 template <class charT> 98 const_reference ``[link boost_regex.match_results.subscript operator\[\]]``(const charT* n) const; 99 template <class charT, class Traits, class A> 100 const_reference ``[link boost_regex.match_results.subscript operator\[\]]``(const std::basic_string<charT, Traits, A>& n) const; 101 102 const_reference ``[link boost_regex.match_results.prefix prefix]``() const; 103 104 const_reference ``[link boost_regex.match_results.suffix suffix]``() const; 105 const_iterator ``[link boost_regex.match_results.begin begin]``() const; 106 const_iterator ``[link boost_regex.match_results.end end]``() const; 107 // format: 108 template <class OutputIterator, class Formatter> 109 OutputIterator ``[link boost_regex.match_results.format format]``(OutputIterator out, 110 Formatter fmt, 111 match_flag_type flags = format_default) const; 112 template <class Formatter> 113 string_type ``[link boost_regex.match_results.format2 format]``(Formatter fmt, 114 match_flag_type flags = format_default) const; 115 116 allocator_type ``[link boost_regex.match_results.get_allocator get_allocator]``() const; 117 void ``[link boost_regex.match_results.swap swap]``(match_results& that); 118 119 #ifdef BOOST_REGEX_MATCH_EXTRA 120 typedef typename value_type::capture_sequence_type capture_sequence_type; 121 const capture_sequence_type& ``[link boost_regex.match_results.captures captures]``(std::size_t i)const; 122 #endif 123 124 }; 125 126 template <class BidirectionalIterator, class Allocator> 127 bool ``[link boost_regex.match_results.op_eq operator ==]`` (const match_results<BidirectionalIterator, Allocator>& m1, 128 const match_results<BidirectionalIterator, Allocator>& m2); 129 template <class BidirectionalIterator, class Allocator> 130 bool ``[link boost_regex.match_results.op_ne operator !=]`` (const match_results<BidirectionalIterator, Allocator>& m1, 131 const match_results<BidirectionalIterator, Allocator>& m2); 132 133 template <class charT, class traits, class BidirectionalIterator, class Allocator> 134 basic_ostream<charT, traits>& 135 ``[link boost_regex.match_results.op_stream operator <<]`` (basic_ostream<charT, traits>& os, 136 const match_results<BidirectionalIterator, Allocator>& m); 137 138 template <class BidirectionalIterator, class Allocator> 139 void ``[link boost_regex.match_results.op_swap swap]``(match_results<BidirectionalIterator, Allocator>& m1, 140 match_results<BidirectionalIterator, Allocator>& m2); 141 142[h4 Description] 143 144In all `match_results` constructors, a copy of the Allocator argument is used 145for any memory allocation performed by the constructor or member functions 146during the lifetime of the object. 147 148[#boost_regex.match_results.construct] 149 150 match_results(const Allocator& a = Allocator()); 151 152[*Effects]: Constructs an object of class `match_results`. The postconditions of 153this function are indicated in the table: 154 155[table 156[[Element][Value]] 157[[empty()][true]] 158[[size()][0]] 159[[str()][basic_string<charT>()]] 160] 161 162 163 164[#boost_regex.match_results.copy_construct] 165 166 match_results(const match_results& m); 167 168[*Effects]: Constructs an object of class match_results, as a copy of m. 169 170 171[#boost_regex.match_results.assign] 172 173 match_results& operator=(const match_results& m); 174 175[*Effects]: Assigns m to *this. The postconditions of this function are 176indicated in the table: 177 178[table 179[[Element][Value]] 180[[empty()][m.empty().]] 181[[size()][m.size().]] 182[[str(n)][m.str(n) for all integers n < m.size().]] 183[[prefix()][m.prefix().]] 184[[suffix()][m.suffix().]] 185[[(*this)\[n\]][m\[n\] for all integers n < m.size().]] 186[[length(n)][m.length(n) for all integers n < m.size().]] 187[[position(n)][m.position(n) for all integers n < m.size().]] 188] 189 190[#boost_regex.match_results.size] 191 192 size_type size()const; 193 194[*Effects]: Returns the number of [sub_match] elements stored in *this; that is 195the number of marked sub-expressions in the regular expression that was 196matched plus one. 197 198 199[#boost_regex.match_results.max_size] 200 201 size_type max_size()const; 202 203[*Effects]: Returns the maximum number of [sub_match] elements that can be 204stored in *this. 205 206 207[#boost_regex.match_results.empty] 208 209 bool empty()const; 210 211[*Effects]: Returns size() == 0. 212 213 214 215[#boost_regex.match_results.length] 216 217 difference_type length(int sub = 0)const; 218 difference_type length(const char_type* sub)const; 219 template <class charT> 220 difference_type length(const charT* sub)const; 221 template <class charT, class Traits, class A> 222 difference_type length(const std::basic_string<charT, Traits, A>&)const; 223 224 225[*Requires]: that the match_results object has been initialized as a result of a 226successful call to [regex_search] or [regex_match] or was returned from a [regex_iterator], and 227that the underlying iterators have not been subsequently invalidated. Will raise a 228`std::logic_error` if the match_results object was not initialized. 229 230[*Effects]: Returns the length of sub-expression /sub/, that is to say: 231`(*this)[sub].length()`. 232 233The overloads that accept a string refer to a named sub-expression /n/. 234In the event that there is no such named sub-expression then returns zero. 235 236The template overloads of this function, allow the string and\/or character type 237to be different from the character type of the underlying sequence and\/or regular expression: 238in this case the characters will be widened to the underlying character type of the original regular expression. 239A compiler error will occur if the argument passes a wider character type than the underlying sequence. 240These overloads allow a normal narrow character C string literal to be used as an argument, even when 241the underlying character type of the expression being matched may be something more exotic such as a 242Unicode character type. 243 244[#boost_regex.match_results.position] 245 246 difference_type position(unsigned int sub = 0)const; 247 difference_type position(const char_type* sub)const; 248 template <class charT> 249 difference_type position(const charT* sub)const; 250 template <class charT, class Traits, class A> 251 difference_type position(const std::basic_string<charT, Traits, A>&)const; 252 253[*Requires]: that the match_results object has been initialized as a result of a 254successful call to [regex_search] or [regex_match] or was returned from a [regex_iterator], and 255that the underlying iterators have not been subsequently invalidated. Will raise a 256`std::logic_error` if the match_results object was not initialized. 257 258[*Effects]: Returns the starting location of sub-expression /sub/, or -1 if /sub/ was 259not matched. Note that if this represents a partial match , then `position()` 260will return the location of the partial match even though `(*this)[0].matched` is false. 261 262The overloads that accept a string refer to a named sub-expression /n/. 263In the event that there is no such named sub-expression then returns -1. 264 265The template overloads of this function, allow the string and\/or character type 266to be different from the character type of the underlying sequence and\/or regular expression: 267in this case the characters will be widened to the underlying character type of the original regular expression. 268A compiler error will occur if the argument passes a wider character type than the underlying sequence. 269These overloads allow a normal narrow character C string literal to be used as an argument, even when 270the underlying character type of the expression being matched may be something more exotic such as a 271Unicode character type. 272 273 274[#boost_regex.match_results.str] 275 276 string_type str(int sub = 0)const; 277 string_type str(const char_type* sub)const; 278 template <class Traits, class A> 279 string_type str(const std::basic_string<char_type, Traits, A>& sub)const; 280 template <class charT> 281 string_type str(const charT* sub)const; 282 template <class charT, class Traits, class A> 283 string_type str(const std::basic_string<charT, Traits, A>& sub)const; 284 285[*Requires]: that the match_results object has been initialized as a result of a 286successful call to [regex_search] or [regex_match] or was returned from a [regex_iterator], and 287that the underlying iterators have not been subsequently invalidated. Will raise a 288`std::logic_error` if the match_results object was not initialized. 289 290[*Effects]: Returns sub-expression /sub/ as a string: `string_type((*this)[sub])`. 291 292The overloads that accept a string, return the string that matched the named sub-expression /n/. 293In the event that there is no such named sub-expression then returns an empty string. 294 295The template overloads of this function, allow the string and\/or character type 296to be different from the character type of the underlying sequence and\/or regular expression: 297in this case the characters will be widened to the underlying character type of the original regular expression. 298A compiler error will occur if the argument passes a wider character type than the underlying sequence. 299These overloads allow a normal narrow character C string literal to be used as an argument, even when 300the underlying character type of the expression being matched may be something more exotic such as a 301Unicode character type. 302 303 304[#boost_regex.match_results.subscript] 305 306 const_reference operator[](int n) const; 307 const_reference operator[](const char_type* n) const; 308 template <class Traits, class A> 309 const_reference operator[](const std::basic_string<char_type, Traits, A>& n) const; 310 template <class charT> 311 const_reference operator[](const charT* n) const; 312 template <class charT, class Traits, class A> 313 const_reference operator[](const std::basic_string<charT, Traits, A>& n) const; 314 315[*Requires]: that the match_results object has been initialized as a result of a 316successful call to [regex_search] or [regex_match] or was returned from a [regex_iterator], and 317that the underlying iterators have not been subsequently invalidated. Will raise a 318`std::logic_error` if the match_results object was not initialized. 319 320[*Effects]: Returns a reference to the [sub_match] object representing the character 321sequence that matched marked sub-expression /n/. If `n == 0` then returns a 322reference to a [sub_match] object representing the character sequence that 323matched the whole regular expression. If /n/ is out of range, or if /n/ is an 324unmatched sub-expression, then returns a [sub_match] object whose matched 325member is false. 326 327The overloads that accept a string, return a reference to the [sub_match] 328object representing the character sequence that matched the named sub-expression /n/. 329In the event that there is no such named sub-expression then returns a [sub_match] object whose matched 330member is false. 331 332The template overloads of this function, allow the string and\/or character type 333to be different from the character type of the underlying sequence and\/or regular expression: 334in this case the characters will be widened to the underlying character type of the original regular expression. 335A compiler error will occur if the argument passes a wider character type than the underlying sequence. 336These overloads allow a normal narrow character C string literal to be used as an argument, even when 337the underlying character type of the expression being matched may be something more exotic such as a 338Unicode character type. 339 340 341[#boost_regex.match_results.prefix] 342 343 const_reference prefix()const; 344 345[*Requires]: that the match_results object has been initialized as a result of a 346successful call to [regex_search] or [regex_match] or was returned from a [regex_iterator], and 347that the underlying iterators have not been subsequently invalidated. Will raise a 348`std::logic_error` if the match_results object was not initialized. 349 350[*Effects]: Returns a reference to the [sub_match] object representing the 351character sequence from the start of the string being matched or searched, to the 352start of the match found. 353 354 355[#boost_regex.match_results.suffix] 356 357 const_reference suffix()const; 358 359[*Requires]: that the match_results object has been initialized as a result of a 360successful call to [regex_search] or [regex_match] or was returned from a [regex_iterator], and 361that the underlying iterators have not been subsequently invalidated. Will raise a 362`std::logic_error` if the match_results object was not initialized. 363 364[*Effects]: Returns a reference to the [sub_match] object representing the 365character sequence from the end of the match found to the end of the 366string being matched or searched. 367 368 369[#boost_regex.match_results.begin] 370 371 const_iterator begin()const; 372 373[*Effects]: Returns a starting iterator that enumerates over all the marked 374sub-expression matches stored in *this. 375 376 377[#boost_regex.match_results.end] 378 379 const_iterator end()const; 380 381[*Effects]: Returns a terminating iterator that enumerates over all the 382marked sub-expression matches stored in *this. 383 384[#boost_regex.match_results_format] 385[#boost_regex.match_results.format] 386 387 template <class OutputIterator, class Formatter> 388 OutputIterator format(OutputIterator out, 389 Formatter fmt, 390 match_flag_type flags = format_default); 391 392[*Requires]: The type `OutputIterator` conforms to the Output Iterator requirements 393(C++ std 24.1.2). 394 395The type `Formatter` must be either a pointer to a null-terminated string 396of type `char_type[]`, or be a container of `char_type`'s (for example 397`std::basic_string<char_type>`) or be a unary, binary or ternary functor 398that computes the replacement string from a function call: either 399`fmt(*this)` which must return a container of `char_type`'s to be used as the 400replacement text, or either `fmt(*this, out)` or `fmt(*this, out, flags)`, both of 401which write the replacement text to `*out`, and then return the new 402OutputIterator position. Note that if the formatter is a functor, then it is 403['passed by value]: users that want to pass function objects with internal state 404might want to use [@../../../../doc/html/ref.html Boost.Ref] to wrap the object so 405that it's passed by reference. 406 407[*Requires]: that the match_results object has been initialized as a result of a 408successful call to [regex_search] or [regex_match] or was returned from a [regex_iterator], and 409that the underlying iterators have not been subsequently invalidated. Will raise a 410`std::logic_error` if the match_results object was not initialized. 411 412[*Effects]: If `fmt` is either a null-terminated string, or a 413container of `char_type`'s, then copies the character sequence `[fmt.begin(), fmt.end())` to 414`OutputIterator` /out/. For each format specifier or escape sequence in 415/fmt/, replace that sequence with either the character(s) it represents, 416or the sequence of characters within `*this` to which it refers. 417The bitmasks specified in flags determines what format specifiers or 418escape sequences are recognized, by default this is the format used by 419ECMA-262, ECMAScript Language Specification, Chapter 15 part 4205.4.11 String.prototype.replace. 421 422If `fmt` is a function object, then depending on the number of arguments 423the function object accepts, it will either: 424 425* Call `fmt(*this)` and copy the string returned to `OutputIterator` 426/out/. 427* Call `fmt(*this, out)`. 428* Call `fmt(*this, out, flags)`. 429 430In all cases the new position of the `OutputIterator` is returned. 431 432See the [link boost_regex.format format syntax guide for more information]. 433 434[*Returns]: out. 435 436 437[#boost_regex.match_results.format2] 438 439 template <class Formatter> 440 string_type format(Formatter fmt, 441 match_flag_type flags = format_default); 442 443[*Requires] 444The type `Formatter` must be either a pointer to a null-terminated string 445of type `char_type[]`, or be a container of `char_type`'s (for example 446`std::basic_string<char_type>`) or be a unary, binary or ternary functor 447that computes the replacement string from a function call: either 448`fmt(*this)` which must return a container of `char_type`'s to be used as the 449replacement text, or either `fmt(*this, out)` or `fmt(*this, out, flags)`, both of 450which write the replacement text to `*out`, and then return the new 451OutputIterator position. 452 453[*Requires]: that the match_results object has been initialized as a result of a 454successful call to [regex_search] or [regex_match] or was returned from a [regex_iterator], and 455that the underlying iterators have not been subsequently invalidated. Will raise a 456`std::logic_error` if the match_results object was not initialized. 457 458[*Effects]: 459If `fmt` is either a null-terminated string, or a 460container of `char_type`'s, then copies the string /fmt/: For each format specifier or 461escape sequence in /fmt/, replace that sequence with either the 462character(s) it represents, or the sequence of characters within `*this` to 463which it refers. The bitmasks specified in flags determines what format 464specifiers or escape sequences are recognized, by default this is the format 465used by ECMA-262, ECMAScript Language Specification, Chapter 15 part 4665.4.11 String.prototype.replace. 467 468If `fmt` is a function object, then depending on the number of arguments 469the function object accepts, it will either: 470 471* Call `fmt(*this)` and return the result. 472* Call `fmt(*this, unspecified-output-iterator)`, where `unspecified-output-iterator` 473is an unspecified OutputIterator type used to copy the output to the string result. 474* Call `fmt(*this, unspecified-output-iterator, flags)`, where `unspecified-output-iterator` 475is an unspecified OutputIterator type used to copy the output to the string result. 476 477See the [link boost_regex.format format syntax guide for more information]. 478 479[#boost_regex.match_results.get_allocator] 480 481 allocator_type get_allocator()const; 482 483[*Effects]: Returns a copy of the Allocator that was passed to the object's constructor. 484 485[#boost_regex.match_results.swap] 486 487 void swap(match_results& that); 488 489[*Effects]: Swaps the contents of the two sequences. 490 491[*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. 492 493[*Complexity]: constant time. 494 495[#boost_regex.match_results.capture_type] 496 497 typedef typename value_type::capture_sequence_type capture_sequence_type; 498 499Defines an implementation-specific type that satisfies the requirements of 500a standard library Sequence (21.1.1 including the optional Table 68 operations), 501whose value_type is a `sub_match<BidirectionalIterator>`. This type happens to be 502`std::vector<sub_match<BidirectionalIterator> >`, but you shouldn't actually 503rely on that. 504 505[#boost_regex.match_results.captures] 506 507 const capture_sequence_type& captures(std::size_t i)const; 508 509[*Requires]: that the match_results object has been initialized as a result of a 510successful call to [regex_search] or [regex_match] or was returned from a [regex_iterator], and 511that the underlying iterators have not been subsequently invalidated. Will raise a 512`std::logic_error` if the match_results object was not initialized. 513 514[*Effects]: returns a sequence containing all the captures obtained for sub-expression i. 515 516[*Returns]: `(*this)[i].captures();` 517 518[*Preconditions]: the library must be built and used with BOOST_REGEX_MATCH_EXTRA defined, 519and you must pass the flag match_extra to the regex matching functions 520([regex_match], [regex_search], [regex_iterator] or [regex_token_iterator]) in 521order for this member function to be defined and return useful information. 522 523[*Rationale]: Enabling this feature has several consequences: 524 525* sub_match occupies more memory resulting in complex expressions running out of memory or stack space more quickly during matching. 526* The matching algorithms are less efficient at handling some features (independent sub-expressions for example), even when match_extra is not used. 527* 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. 528 529[#boost_regex.match_results.op_eq] 530 531 template <class BidirectionalIterator, class Allocator> 532 bool operator == (const match_results<BidirectionalIterator, Allocator>& m1, 533 const match_results<BidirectionalIterator, Allocator>& m2); 534 535[*Effects]: Compares the two sequences for equality. 536 537[#boost_regex.match_results.op_ne] 538 539 template <class BidirectionalIterator, class Allocator> 540 bool operator != (const match_results<BidirectionalIterator, Allocator>& m1, 541 const match_results<BidirectionalIterator, Allocator>& m2); 542 543[*Effects]: Compares the two sequences for inequality. 544 545[#boost_regex.match_results.op_stream] 546 547 template <class charT, class traits, class BidirectionalIterator, class Allocator> 548 basic_ostream<charT, traits>& 549 operator << (basic_ostream<charT, traits>& os, 550 const match_results<BidirectionalIterator, Allocator>& m); 551 552[*Effects]: Writes the contents of /m/ to the stream /os/ as if by calling 553`os << m.str()`; Returns /os/. 554 555[#boost_regex.match_results.op_swap] 556 557 template <class BidirectionalIterator, class Allocator> 558 void swap(match_results<BidirectionalIterator, Allocator>& m1, 559 match_results<BidirectionalIterator, Allocator>& m2); 560 561[*Effects]: Swaps the contents of the two sequences. 562 563[endsect] 564 565