ceph/src/boost/libs/xpressive/doc/results.qbk

   1 [/
   2  / Copyright (c) 2008 Eric Niebler
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8 [section Accessing Results]
   9
  10 [h2 Overview]
  11
  12 Sometimes, it is not enough to know simply whether a _regex_match_ or _regex_search_ was successful or not. If
  13 you pass an object of type _match_results_ to _regex_match_ or _regex_search_, then after the algorithm has completed
  14 successfully the _match_results_ will contain extra information about which parts of the regex matched which parts
  15 of the sequence. In Perl, these sub-sequences are called ['back-references], and they are stored in the variables
  16 [^$1], [^$2], etc. In xpressive, they are objects of type _sub_match_, and they are stored in the _match_results_
  17 structure, which acts as a vector of _sub_match_ objects.
  18
  19 [h2 match_results]
  20
  21 So, you've passed a _match_results_ object to a regex algorithm, and the algorithm has succeeded. Now you want
  22 to examine the results. Most of what you'll be doing with the _match_results_ object is indexing into it to access
  23 its internally stored _sub_match_ objects, but there are a few other things you can do with a _match_results_
  24 object besides.
  25
  26 The table below shows how to access the information stored in a _match_results_ object named `what`.
  27
  28 [table match_results<> Accessors
  29     [[Accessor]             [Effects]]
  30     [[`what.size()`]        [Returns the number of sub-matches, which is always greater than zero after a successful match because the full match is stored in the zero-th sub-match.]]
  31     [[`what[n]`]            [Returns the ['n]-th sub-match.]]
  32     [[`what.length(n)`]     [Returns the length of the ['n]-th sub-match. Same as `what[n].length()`.]]
  33     [[`what.position(n)`]   [Returns the offset into the input sequence at which the ['n]-th sub-match begins.]]
  34     [[`what.str(n)`]        [Returns a `std::basic_string<>` constructed from the ['n]-th sub-match. Same as `what[n].str()`.]]
  35     [[`what.prefix()`]      [Returns a _sub_match_ object which represents the sub-sequence from the beginning of the input sequence to the start of the full match.]]
  36     [[`what.suffix()`]      [Returns a _sub_match_ object which represents the sub-sequence from the end of the full match to the end of the input sequence.]]
  37     [[`what.regex_id()`]    [Returns the `regex_id` of the _basic_regex_ object that was last used with this _match_results_ object.]]
  38 ]
  39
  40 There is more you can do with the _match_results_ object, but that will be covered when we talk about
  41 [link boost_xpressive.user_s_guide.grammars_and_nested_matches Grammars and Nested Matches].
  42
  43 [h2 sub_match]
  44
  45 When you index into a _match_results_ object, you get back a _sub_match_ object. A _sub_match_ is basically a pair
  46 of iterators. It is defined like this:
  47
  48     template< class BidirectionalIterator >
  49     struct sub_match
  50         : std::pair< BidirectionalIterator, BidirectionalIterator >
  51     {
  52         bool matched;
  53         // ...
  54     };
  55
  56 Since it inherits publicaly from `std::pair<>`, _sub_match_ has `first` and `second` data members of type
  57 `BidirectionalIterator`. These are the beginning and end of the sub-sequence this _sub_match_ represents.
  58 _sub_match_ also has a Boolean `matched` data member, which is true if this _sub_match_ participated in the full
  59 match.
  60
  61 The following table shows how you might access the information stored in a _sub_match_ object called `sub`.
  62
  63 [table sub_match<> Accessors
  64     [[Accessor]             [Effects]]
  65     [[`sub.length()`]       [Returns the length of the sub-match. Same as `std::distance(sub.first,sub.second)`.]]
  66     [[`sub.str()`]          [Returns a `std::basic_string<>` constructed from the sub-match. Same as `std::basic_string<char_type>(sub.first,sub.second)`.]]
  67     [[`sub.compare(str)`]   [Performs a string comparison between the sub-match and `str`, where `str` can be a `std::basic_string<>`, C-style null-terminated string, or another sub-match. Same as `sub.str().compare(str)`.]]
  68 ]
  69
  70 [h2 __alert__ Results Invalidation __alert__]
  71
  72 Results are stored as iterators into the input sequence. Anything which invalidates
  73 the input sequence will invalidate the match results. For instance, if you match a `std::string` object,
  74 the results are only valid until your next call to a non-const member function of that `std::string` object.
  75 After that, the results held by the _match_results_ object are invalid. Don't use them!
  76
  77 [endsect]