[ceph.git] / ceph / src / boost / libs / regex / doc / regex_token_iterator.qbk

[/ 
  Copyright 2006-2007 John Maddock.
  Distributed under 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).
]


[section:regex_token_iterator regex_token_iterator]

The template class [regex_token_iterator] is an iterator adapter; that is to 
say it represents a new view of an existing iterator sequence, 
by enumerating all the occurrences of a regular expression within that 
sequence, and presenting one or more character sequence for each match found. 
Each position enumerated by the iterator is a [sub_match] object that represents 
what matched a particular sub-expression within the regular expression. 
When class [regex_token_iterator] is used to enumerate a single sub-expression 
with index -1, then the iterator performs field splitting: that is 
to say it enumerates one character sequence for each section of the character 
container sequence that does not match the regular expression specified.

   template <class BidirectionalIterator, 
            class charT = iterator_traits<BidirectionalIterator>::value_type,
            class traits = regex_traits<charT> >
   class regex_token_iterator 
   {
   public:
      typedef          basic_regex<charT, traits>                              regex_type;
      typedef          sub_match<BidirectionalIterator>                        value_type;
      typedef typename iterator_traits<BidirectionalIterator>::difference_type difference_type;
      typedef          const value_type*                                       pointer;
      typedef          const value_type&                                       reference;
      typedef          std::forward_iterator_tag                               iterator_category;
      
      ``[link boost_regex.regex_token_iterator.construct1 regex_token_iterator]``();
      ``[link boost_regex.regex_token_iterator.construct2 regex_token_iterator]``(BidirectionalIterator a, 
                           BidirectionalIterator b, 
                           const regex_type& re, 
                           int submatch = 0, 
                           match_flag_type m = match_default);
      ``[link boost_regex.regex_token_iterator.construct3 regex_token_iterator]``(BidirectionalIterator a, 
                           BidirectionalIterator b, 
                           const regex_type& re, 
                           const std::vector<int>& submatches, 
                           match_flag_type m = match_default);
      template <std::size_t N>
      ``[link boost_regex.regex_token_iterator.construct4 regex_token_iterator]``(BidirectionalIterator a, 
                           BidirectionalIterator b, 
                           const regex_type& re, 
                           const int (&submatches)[N], 
                           match_flag_type m = match_default);
      ``[link boost_regex.regex_token_iterator.construct5 regex_token_iterator]``(const regex_token_iterator&);
      regex_token_iterator& ``[link boost_regex.regex_token_iterator.assign operator=]``(const regex_token_iterator&);
      bool ``[link boost_regex.regex_token_iterator.op_eq operator==]``(const regex_token_iterator&)const;
      bool ``[link boost_regex.regex_token_iterator.op_ne operator!=]``(const regex_token_iterator&)const;
      const value_type& ``[link boost_regex.regex_token_iterator.op_deref operator*]``()const;
      const value_type* ``[link boost_regex.regex_token_iterator.op_arrow operator->]``()const;
      regex_token_iterator& ``[link boost_regex.regex_token_iterator.op_inc1 operator++]``();
      regex_token_iterator ``[link boost_regex.regex_token_iterator.op_inc2 operator++]``(int);
   };

   typedef regex_token_iterator<const char*>                   cregex_token_iterator;
   typedef regex_token_iterator<std::string::const_iterator>   sregex_token_iterator;
   #ifndef BOOST_NO_WREGEX
   typedef regex_token_iterator<const wchar_t*>                wcregex_token_iterator;
   typedef regex_token_iterator<<std::wstring::const_iterator> wsregex_token_iterator;
   #endif

   template <class charT, class traits>
   regex_token_iterator<const charT*, charT, traits> 
      ``[link boost_regex.regex_token_iterator.make make_regex_token_iterator]``(
            const charT* p, 
            const basic_regex<charT, traits>& e, 
            int submatch = 0, 
            regex_constants::match_flag_type m = regex_constants::match_default);
                                
   template <class charT, class traits, class ST, class SA>
   regex_token_iterator<typename std::basic_string<charT, ST, SA>::const_iterator, charT, traits> 
      ``[link boost_regex.regex_token_iterator.make make_regex_token_iterator]``(
            const std::basic_string<charT, ST, SA>& p, 
            const basic_regex<charT, traits>& e, 
            int submatch = 0, 
            regex_constants::match_flag_type m = regex_constants::match_default);
                                
   template <class charT, class traits, std::size_t N>
   regex_token_iterator<const charT*, charT, traits> 
   ``[link boost_regex.regex_token_iterator.make make_regex_token_iterator]``(
            const charT* p, 
            const basic_regex<charT, traits>& e, 
            const int (&submatch)[N], 
            regex_constants::match_flag_type m = regex_constants::match_default);
                               
   template <class charT, class traits, class ST, class SA, std::size_t N>
   regex_token_iterator<typename std::basic_string<charT, ST, SA>::const_iterator, charT, traits> 
      ``[link boost_regex.regex_token_iterator.make make_regex_token_iterator]``(
            const std::basic_string<charT, ST, SA>& p, 
            const basic_regex<charT, traits>& e, 
            const int (&submatch)[N], 
            regex_constants::match_flag_type m = regex_constants::match_default);
                                
   template <class charT, class traits>
   regex_token_iterator<const charT*, charT, traits> 
      ``[link boost_regex.regex_token_iterator.make make_regex_token_iterator]``(
            const charT* p, 
            const basic_regex<charT, traits>& e, 
            const std::vector<int>& submatch, 
            regex_constants::match_flag_type m = regex_constants::match_default);
                                
   template <class charT, class traits, class ST, class SA>
   regex_token_iterator<
         typename std::basic_string<charT, ST, SA>::const_iterator, charT, traits> 
      ``[link boost_regex.regex_token_iterator.make make_regex_token_iterator]``(
            const std::basic_string<charT, ST, SA>& p, 
            const basic_regex<charT, traits>& e, 
            const std::vector<int>& submatch, 
            regex_constants::match_flag_type m = regex_constants::match_default);

[h4 Description]

[#boost_regex.regex_token_iterator.construct1]

   regex_token_iterator();

[*Effects]: constructs an end of sequence iterator.

[#boost_regex.regex_token_iterator.construct2]

   regex_token_iterator(BidirectionalIterator a, 
                        BidirectionalIterator b, 
                        const regex_type& re, 
                        int submatch = 0, 
                        match_flag_type m = match_default);

[*Preconditions]: `!re.empty()`.  Object /re/ shall exist for the lifetime of 
the iterator constructed from it.

[*Effects]: constructs a [regex_token_iterator] that will enumerate one string for 
each regular expression match of the expression /re/ found within the sequence \[a,b), 
using match flags /m/ (see [match_flag_type]).  The string enumerated is the sub-expression /submatch/ 
for each match found; if /submatch/ is -1, then enumerates all the text 
sequences that did not match the expression /re/ (that is to performs field 
splitting).

[*Throws]: `std::runtime_error` if the complexity of matching the expression against 
an N character string begins to exceed O(N[super 2]), or if the program runs 
out of stack space while matching the expression (if Boost.Regex is configured 
in recursive mode), or if the matcher exhausts its permitted memory 
allocation (if Boost.Regex is configured in non-recursive mode).

[#boost_regex.regex_token_iterator.construct3]

   regex_token_iterator(BidirectionalIterator a, 
                        BidirectionalIterator b, 
                        const regex_type& re, 
                        const std::vector<int>& submatches, 
                        match_flag_type m = match_default);

[*Preconditions]: `submatches.size() && !re.empty()`.  Object /re/ shall 
exist for the lifetime of the iterator constructed from it.

[*Effects]: constructs a [regex_token_iterator] that will enumerate 
`submatches.size()` strings for each regular expression match of 
the expression /re/ found within the sequence \[a,b), using match flags /m/ 
(see [match_flag_type]).  For each match found one string will be enumerated 
for each sub-expression index contained within submatches vector; if 
`submatches[0]` is -1, then the first string enumerated for each match will be 
all of the text from end of the last match to the start of the current match, 
in addition there will be one extra string enumerated when no more matches can 
be found: from the end of the last match found, to the end of the underlying sequence.

[*Throws]: `std::runtime_error` if the complexity of matching the expression 
against an N character string begins to exceed O(N[super 2]), or if the 
program runs out of stack space while matching the expression (if Boost.Regex is 
configured in recursive mode), or if the matcher exhausts its permitted memory 
allocation (if Boost.Regex is configured in non-recursive mode).

[#boost_regex.regex_token_iterator.construct4]

   template <std::size_t N>
   regex_token_iterator(BidirectionalIterator a, 
                        BidirectionalIterator b, 
                        const regex_type& re, 
                        const int (&submatches)[R], 
                        match_flag_type m = match_default);

[*Preconditions]: `!re.empty()`.  Object /re/ shall exist for the lifetime of the iterator constructed from it.

[*Effects]: constructs a [regex_token_iterator] that will enumerate /R/ strings 
for each regular expression match of the expression /re/ found within the sequence 
\[a,b), using match flags /m/ (see [match_flag_type]).  For each match found one 
string will be enumerated for each sub-expression index contained within the 
/submatches/ array; if `submatches[0]` is -1, then the first string enumerated for 
each match will be all of the text from end of the last match to the start 
of the current match, in addition there will be one extra string enumerated when 
no more matches can be found: from the end of the last match found, to 
the end of the underlying sequence.

[*Throws]: `std::runtime_error` if the complexity of matching the expression 
against an N character string begins to exceed O(N[super 2]), or if the 
program runs out of stack space while matching the expression (if Boost.Regex 
is configured in recursive mode), or if the matcher exhausts its 
permitted memory allocation (if Boost.Regex is configured in non-recursive mode).

[#boost_regex.regex_token_iterator.construct5]

   regex_token_iterator(const regex_token_iterator& that);

[*Effects]: constructs a copy of `that`.

[*Postconditions]: `*this == that`.

[#boost_regex.regex_token_iterator.assign]

   regex_token_iterator& operator=(const regex_token_iterator& that);

[*Effects]: sets `*this` to be equal to `that`.

[*Postconditions]: `*this == that`.

[#boost_regex.regex_token_iterator.op_eq]

   bool operator==(const regex_token_iterator&)const;

[*Effects]: returns true if `*this` is the same position as `that`.

[#boost_regex.regex_token_iterator.op_ne]

   bool operator!=(const regex_token_iterator&)const;

[*Effects]: returns `!(*this == that)`.

[#boost_regex.regex_token_iterator.op_deref]

   const value_type& operator*()const;

[*Effects]: returns the current character sequence being enumerated.

[#boost_regex.regex_token_iterator.op_arrow]

   const value_type* operator->()const;

[*Effects]: returns `&(*this)`.

[#boost_regex.regex_token_iterator.op_inc1]

   regex_token_iterator& operator++();

[*Effects]: Moves on to the next character sequence to be enumerated.

[*Throws]: `std::runtime_error` if the complexity of matching the expression 
against an N character string begins to exceed O(N[super 2]), or if the program 
runs out of stack space while matching the expression (if Boost.Regex is 
configured in recursive mode), or if the matcher exhausts its permitted 
memory allocation (if Boost.Regex is configured in non-recursive mode).

[*Returns]: `*this`.

[#boost_regex.regex_token_iterator.op_inc2]

   regex_token_iterator& operator++(int);

[*Effects]: constructs a copy result of `*this`, then calls `++(*this)`.

[*Returns]: result.

[#boost_regex.regex_token_iterator.make]

   template <class charT, class traits>
   regex_token_iterator<const charT*, charT, traits> 
      make_regex_token_iterator(
            const charT* p, 
            const basic_regex<charT, traits>& e, 
            int submatch = 0, 
            regex_constants::match_flag_type m = regex_constants::match_default);
                             
   template <class charT, class traits, class ST, class SA>
   regex_token_iterator<typename std::basic_string<charT, ST, SA>::const_iterator, charT, traits> 
      make_regex_token_iterator(
            const std::basic_string<charT, ST, SA>& p, 
            const basic_regex<charT, traits>& e, 
            int submatch = 0, 
            regex_constants::match_flag_type m = regex_constants::match_default);
                                
   template <class charT, class traits, std::size_t N>
   regex_token_iterator<const charT*, charT, traits> 
   make_regex_token_iterator(
            const charT* p, 
            const basic_regex<charT, traits>& e, 
            const int (&submatch)[N], 
            regex_constants::match_flag_type m = regex_constants::match_default);
                               
   template <class charT, class traits, class ST, class SA, std::size_t N>
   regex_token_iterator<
         typename std::basic_string<charT, ST, SA>::const_iterator, charT, traits> 
      make_regex_token_iterator(
            const std::basic_string<charT, ST, SA>& p, 
            const basic_regex<charT, traits>& e, 
            const int (&submatch)[N], 
            regex_constants::match_flag_type m = regex_constants::match_default);
                                
   template <class charT, class traits>
   regex_token_iterator<const charT*, charT, traits> 
      make_regex_token_iterator(
            const charT* p, 
            const basic_regex<charT, traits>& e, 
            const std::vector<int>& submatch, 
            regex_constants::match_flag_type m = regex_constants::match_default);
                                
   template <class charT, class traits, class ST, class SA>
   regex_token_iterator<
         typename std::basic_string<charT, ST, SA>::const_iterator, charT, traits> 
      make_regex_token_iterator(
            const std::basic_string<charT, ST, SA>& p, 
            const basic_regex<charT, traits>& e, 
            const std::vector<int>& submatch, 
            regex_constants::match_flag_type m = regex_constants::match_default);

[*Effects]: returns a [regex_token_iterator] that enumerates one [sub_match] 
for each value in /submatch/ for each occurrence of regular expression /e/ 
in string /p/, matched using [match_flag_type] /m/.

[h4 Examples]

The following example takes a string and splits it into a series of tokens:

   #include <iostream>
   #include <boost/regex.hpp>

   using namespace std;

   int main(int argc)
   {
      string s;
      do{
         if(argc == 1)
         {
            cout << "Enter text to split (or \"quit\" to exit): ";
            getline(cin, s);
            if(s == "quit") break;
         }
         else
            s = "This is a string of tokens";

         boost::regex re("\\s+");
         boost::sregex_token_iterator i(s.begin(), s.end(), re, -1);
         boost::sregex_token_iterator j;

         unsigned count = 0;
         while(i != j)
         {
            cout << *i++ << endl;
            count++;
         }
         cout << "There were " << count << " tokens found." << endl;

      }while(argc == 1);
      return 0;
   }


The following example takes a html file and outputs a list of all the linked files:

   #include <fstream>
   #include <iostream>
   #include <iterator>
   #include <boost/regex.hpp>

   boost::regex e("<\\s*A\\s+[^>]*href\\s*=\\s*\"([^\"]*)\"",
                  boost::regex::normal | boost::regbase::icase);

   void load_file(std::string& s, std::istream& is)
   {
      s.erase();
      //
      // attempt to grow string buffer to match file size,
      // this doesn't always work...
      s.reserve(is.rdbuf()->in_avail());
      char c;
      while(is.get(c))
      {
         // use logarithmic growth strategy, in case
         // in_avail (above) returned zero:
         if(s.capacity() == s.size())
            s.reserve(s.capacity() * 3);
         s.append(1, c);
      }
   }

   int main(int argc, char** argv)
   {
      std::string s;
      int i;
      for(i = 1; i < argc; ++i)
      {
         std::cout << "Findings URL's in " << argv[i] << ":" << std::endl;
         s.erase();
         std::ifstream is(argv[i]);
         load_file(s, is);
         boost::sregex_token_iterator i(s.begin(), s.end(), e, 1);
         boost::sregex_token_iterator j;
         while(i != j)
         {
            std::cout << *i++ << std::endl;
         }
      }
      //
      // alternative method:
      // test the array-literal constructor, and split out the whole
      // match as well as $1....
      //
      for(i = 1; i < argc; ++i)
      {
         std::cout << "Findings URL's in " << argv[i] << ":" << std::endl;
         s.erase();
         std::ifstream is(argv[i]);
         load_file(s, is);
         const int subs[] = {1, 0,};
         boost::sregex_token_iterator i(s.begin(), s.end(), e, subs);
         boost::sregex_token_iterator j;
         while(i != j)
         {
            std::cout << *i++ << std::endl;
         }
      }

      return 0;
   }

     
[endsect]
Commit	Line	Data
7c673cae FG	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
	9	[section:regex_token_iterator regex_token_iterator]
	10
	11	The template class [regex_token_iterator] is an iterator adapter; that is to
	12	say it represents a new view of an existing iterator sequence,
	13	by enumerating all the occurrences of a regular expression within that
	14	sequence, and presenting one or more character sequence for each match found.
	15	Each position enumerated by the iterator is a [sub_match] object that represents
	16	what matched a particular sub-expression within the regular expression.
	17	When class [regex_token_iterator] is used to enumerate a single sub-expression
	18	with index -1, then the iterator performs field splitting: that is
	19	to say it enumerates one character sequence for each section of the character
	20	container sequence that does not match the regular expression specified.
	21
	22	template <class BidirectionalIterator,
	23	class charT = iterator_traits<BidirectionalIterator>::value_type,
	24	class traits = regex_traits<charT> >
	25	class regex_token_iterator
	26	{
	27	public:
	28	typedef basic_regex<charT, traits> regex_type;
	29	typedef sub_match<BidirectionalIterator> value_type;
	30	typedef typename iterator_traits<BidirectionalIterator>::difference_type difference_type;
	31	typedef const value_type* pointer;
	32	typedef const value_type& reference;
	33	typedef std::forward_iterator_tag iterator_category;
	34
	35	``[link boost_regex.regex_token_iterator.construct1 regex_token_iterator]``();
	36	``[link boost_regex.regex_token_iterator.construct2 regex_token_iterator]``(BidirectionalIterator a,
	37	BidirectionalIterator b,
	38	const regex_type& re,
	39	int submatch = 0,
	40	match_flag_type m = match_default);
	41	``[link boost_regex.regex_token_iterator.construct3 regex_token_iterator]``(BidirectionalIterator a,
	42	BidirectionalIterator b,
	43	const regex_type& re,
	44	const std::vector<int>& submatches,
	45	match_flag_type m = match_default);
	46	template <std::size_t N>
	47	``[link boost_regex.regex_token_iterator.construct4 regex_token_iterator]``(BidirectionalIterator a,
	48	BidirectionalIterator b,
	49	const regex_type& re,
	50	const int (&submatches)[N],
	51	match_flag_type m = match_default);
	52	``[link boost_regex.regex_token_iterator.construct5 regex_token_iterator]``(const regex_token_iterator&);
	53	regex_token_iterator& ``[link boost_regex.regex_token_iterator.assign operator=]``(const regex_token_iterator&);
	54	bool ``[link boost_regex.regex_token_iterator.op_eq operator==]``(const regex_token_iterator&)const;
	55	bool ``[link boost_regex.regex_token_iterator.op_ne operator!=]``(const regex_token_iterator&)const;
	56	const value_type& ``[link boost_regex.regex_token_iterator.op_deref operator*]``()const;
	57	const value_type* ``[link boost_regex.regex_token_iterator.op_arrow operator->]``()const;
	58	regex_token_iterator& ``[link boost_regex.regex_token_iterator.op_inc1 operator++]``();
	59	regex_token_iterator ``[link boost_regex.regex_token_iterator.op_inc2 operator++]``(int);
	60	};
	61
	62	typedef regex_token_iterator<const char*> cregex_token_iterator;
	63	typedef regex_token_iterator<std::string::const_iterator> sregex_token_iterator;
	64	#ifndef BOOST_NO_WREGEX
65	typedef regex_token_iterator<const wchar_t*> wcregex_token_iterator;
66	typedef regex_token_iterator<<std::wstring::const_iterator> wsregex_token_iterator;
67	#endif
68
69	template <class charT, class traits>
70	regex_token_iterator<const charT*, charT, traits>
71	``[link boost_regex.regex_token_iterator.make make_regex_token_iterator]``(
72	const charT* p,
73	const basic_regex<charT, traits>& e,
74	int submatch = 0,
75	regex_constants::match_flag_type m = regex_constants::match_default);
76
77	template <class charT, class traits, class ST, class SA>
78	regex_token_iterator<typename std::basic_string<charT, ST, SA>::const_iterator, charT, traits>
79	``[link boost_regex.regex_token_iterator.make make_regex_token_iterator]``(
80	const std::basic_string<charT, ST, SA>& p,
81	const basic_regex<charT, traits>& e,
82	int submatch = 0,
83	regex_constants::match_flag_type m = regex_constants::match_default);
84
85	template <class charT, class traits, std::size_t N>
86	regex_token_iterator<const charT*, charT, traits>
87	``[link boost_regex.regex_token_iterator.make make_regex_token_iterator]``(
88	const charT* p,
89	const basic_regex<charT, traits>& e,
90	const int (&submatch)[N],
91	regex_constants::match_flag_type m = regex_constants::match_default);
92
93	template <class charT, class traits, class ST, class SA, std::size_t N>
94	regex_token_iterator<typename std::basic_string<charT, ST, SA>::const_iterator, charT, traits>
95	``[link boost_regex.regex_token_iterator.make make_regex_token_iterator]``(
96	const std::basic_string<charT, ST, SA>& p,
97	const basic_regex<charT, traits>& e,
98	const int (&submatch)[N],
99	regex_constants::match_flag_type m = regex_constants::match_default);
100
101	template <class charT, class traits>
102	regex_token_iterator<const charT*, charT, traits>
103	``[link boost_regex.regex_token_iterator.make make_regex_token_iterator]``(
104	const charT* p,
105	const basic_regex<charT, traits>& e,
106	const std::vector<int>& submatch,
107	regex_constants::match_flag_type m = regex_constants::match_default);
108
109	template <class charT, class traits, class ST, class SA>
110	regex_token_iterator<
111	typename std::basic_string<charT, ST, SA>::const_iterator, charT, traits>
112	``[link boost_regex.regex_token_iterator.make make_regex_token_iterator]``(
113	const std::basic_string<charT, ST, SA>& p,
114	const basic_regex<charT, traits>& e,
115	const std::vector<int>& submatch,
116	regex_constants::match_flag_type m = regex_constants::match_default);
117
118	[h4 Description]
119
120	[#boost_regex.regex_token_iterator.construct1]
121
122	regex_token_iterator();
123
124	[*Effects]: constructs an end of sequence iterator.
125
126	[#boost_regex.regex_token_iterator.construct2]
127
128	regex_token_iterator(BidirectionalIterator a,
129	BidirectionalIterator b,
130	const regex_type& re,
131	int submatch = 0,
132	match_flag_type m = match_default);
133
134	[*Preconditions]: `!re.empty()`. Object /re/ shall exist for the lifetime of
135	the iterator constructed from it.
136
137	[*Effects]: constructs a [regex_token_iterator] that will enumerate one string for
138	each regular expression match of the expression /re/ found within the sequence \[a,b),
139	using match flags /m/ (see [match_flag_type]). The string enumerated is the sub-expression /submatch/
140	for each match found; if /submatch/ is -1, then enumerates all the text
141	sequences that did not match the expression /re/ (that is to performs field
142	splitting).
143
144	[*Throws]: `std::runtime_error` if the complexity of matching the expression against
145	an N character string begins to exceed O(N[super 2]), or if the program runs
146	out of stack space while matching the expression (if Boost.Regex is configured
147	in recursive mode), or if the matcher exhausts its permitted memory
148	allocation (if Boost.Regex is configured in non-recursive mode).
149
150	[#boost_regex.regex_token_iterator.construct3]
151
152	regex_token_iterator(BidirectionalIterator a,
153	BidirectionalIterator b,
154	const regex_type& re,
155	const std::vector<int>& submatches,
156	match_flag_type m = match_default);
157
158	[*Preconditions]: `submatches.size() && !re.empty()`. Object /re/ shall
159	exist for the lifetime of the iterator constructed from it.
160
161	[*Effects]: constructs a [regex_token_iterator] that will enumerate
162	`submatches.size()` strings for each regular expression match of
163	the expression /re/ found within the sequence \[a,b), using match flags /m/
164	(see [match_flag_type]). For each match found one string will be enumerated
165	for each sub-expression index contained within submatches vector; if
166	`submatches[0]` is -1, then the first string enumerated for each match will be
167	all of the text from end of the last match to the start of the current match,
168	in addition there will be one extra string enumerated when no more matches can
169	be found: from the end of the last match found, to the end of the underlying sequence.
170
171	[*Throws]: `std::runtime_error` if the complexity of matching the expression
172	against an N character string begins to exceed O(N[super 2]), or if the
173	program runs out of stack space while matching the expression (if Boost.Regex is
174	configured in recursive mode), or if the matcher exhausts its permitted memory
175	allocation (if Boost.Regex is configured in non-recursive mode).
176
177	[#boost_regex.regex_token_iterator.construct4]
178
179	template <std::size_t N>
180	regex_token_iterator(BidirectionalIterator a,
181	BidirectionalIterator b,
182	const regex_type& re,
183	const int (&submatches)[R],
184	match_flag_type m = match_default);
185
186	[*Preconditions]: `!re.empty()`. Object /re/ shall exist for the lifetime of the iterator constructed from it.
187
188	[*Effects]: constructs a [regex_token_iterator] that will enumerate /R/ strings
189	for each regular expression match of the expression /re/ found within the sequence
190	\[a,b), using match flags /m/ (see [match_flag_type]). For each match found one
191	string will be enumerated for each sub-expression index contained within the
192	/submatches/ array; if `submatches[0]` is -1, then the first string enumerated for
193	each match will be all of the text from end of the last match to the start
194	of the current match, in addition there will be one extra string enumerated when
195	no more matches can be found: from the end of the last match found, to
196	the end of the underlying sequence.
197
198	[*Throws]: `std::runtime_error` if the complexity of matching the expression
199	against an N character string begins to exceed O(N[super 2]), or if the
200	program runs out of stack space while matching the expression (if Boost.Regex
201	is configured in recursive mode), or if the matcher exhausts its
202	permitted memory allocation (if Boost.Regex is configured in non-recursive mode).
203
204	[#boost_regex.regex_token_iterator.construct5]
205
206	regex_token_iterator(const regex_token_iterator& that);
207
208	[*Effects]: constructs a copy of `that`.
209
210	[Postconditions]: `this == that`.
211
212	[#boost_regex.regex_token_iterator.assign]
213
214	regex_token_iterator& operator=(const regex_token_iterator& that);
215
216	[Effects]: sets `this` to be equal to `that`.
217
218	[Postconditions]: `this == that`.
219
220	[#boost_regex.regex_token_iterator.op_eq]
221
222	bool operator==(const regex_token_iterator&)const;
223
224	[Effects]: returns true if `this` is the same position as `that`.
225
226	[#boost_regex.regex_token_iterator.op_ne]
227
228	bool operator!=(const regex_token_iterator&)const;
229
230	[Effects]: returns `!(this == that)`.
231
232	[#boost_regex.regex_token_iterator.op_deref]
233
234	const value_type& operator*()const;
235
236	[*Effects]: returns the current character sequence being enumerated.
237
238	[#boost_regex.regex_token_iterator.op_arrow]
239
240	const value_type* operator->()const;
241
242	[Effects]: returns `&(this)`.
243
244	[#boost_regex.regex_token_iterator.op_inc1]
245
246	regex_token_iterator& operator++();
247
248	[*Effects]: Moves on to the next character sequence to be enumerated.
249
250	[*Throws]: `std::runtime_error` if the complexity of matching the expression
251	against an N character string begins to exceed O(N[super 2]), or if the program
252	runs out of stack space while matching the expression (if Boost.Regex is
253	configured in recursive mode), or if the matcher exhausts its permitted
254	memory allocation (if Boost.Regex is configured in non-recursive mode).
255
256	[Returns]: `this`.
257
258	[#boost_regex.regex_token_iterator.op_inc2]
259
260	regex_token_iterator& operator++(int);
261
262	[Effects]: constructs a copy result of `this`, then calls `++(*this)`.
263
264	[*Returns]: result.
265
266	[#boost_regex.regex_token_iterator.make]
267
268	template <class charT, class traits>
269	regex_token_iterator<const charT*, charT, traits>
270	make_regex_token_iterator(
271	const charT* p,
272	const basic_regex<charT, traits>& e,
273	int submatch = 0,
274	regex_constants::match_flag_type m = regex_constants::match_default);
275
276	template <class charT, class traits, class ST, class SA>
277	regex_token_iterator<typename std::basic_string<charT, ST, SA>::const_iterator, charT, traits>
278	make_regex_token_iterator(
279	const std::basic_string<charT, ST, SA>& p,
280	const basic_regex<charT, traits>& e,
281	int submatch = 0,
282	regex_constants::match_flag_type m = regex_constants::match_default);
283
284	template <class charT, class traits, std::size_t N>
285	regex_token_iterator<const charT*, charT, traits>
286	make_regex_token_iterator(
287	const charT* p,
288	const basic_regex<charT, traits>& e,
289	const int (&submatch)[N],
290	regex_constants::match_flag_type m = regex_constants::match_default);
291
292	template <class charT, class traits, class ST, class SA, std::size_t N>
293	regex_token_iterator<
294	typename std::basic_string<charT, ST, SA>::const_iterator, charT, traits>
295	make_regex_token_iterator(
296	const std::basic_string<charT, ST, SA>& p,
297	const basic_regex<charT, traits>& e,
298	const int (&submatch)[N],
299	regex_constants::match_flag_type m = regex_constants::match_default);
300
301	template <class charT, class traits>
302	regex_token_iterator<const charT*, charT, traits>
303	make_regex_token_iterator(
304	const charT* p,
305	const basic_regex<charT, traits>& e,
306	const std::vector<int>& submatch,
307	regex_constants::match_flag_type m = regex_constants::match_default);
308
309	template <class charT, class traits, class ST, class SA>
310	regex_token_iterator<
311	typename std::basic_string<charT, ST, SA>::const_iterator, charT, traits>
312	make_regex_token_iterator(
313	const std::basic_string<charT, ST, SA>& p,
314	const basic_regex<charT, traits>& e,
315	const std::vector<int>& submatch,
316	regex_constants::match_flag_type m = regex_constants::match_default);
317
318	[*Effects]: returns a [regex_token_iterator] that enumerates one [sub_match]
319	for each value in /submatch/ for each occurrence of regular expression /e/
320	in string /p/, matched using [match_flag_type] /m/.
321
322	[h4 Examples]
323
324	The following example takes a string and splits it into a series of tokens:
325
326	#include <iostream>
327	#include <boost/regex.hpp>
328
329	using namespace std;
330
331	int main(int argc)
332	{
333	string s;
334	do{
335	if(argc == 1)
336	{
337	cout << "Enter text to split (or \"quit\" to exit): ";
338	getline(cin, s);
339	if(s == "quit") break;
340	}
341	else
342	s = "This is a string of tokens";
343
344	boost::regex re("\\s+");
345	boost::sregex_token_iterator i(s.begin(), s.end(), re, -1);
346	boost::sregex_token_iterator j;
347
348	unsigned count = 0;
349	while(i != j)
350	{
351	cout << *i++ << endl;
352	count++;
353	}
354	cout << "There were " << count << " tokens found." << endl;
355
356	}while(argc == 1);
357	return 0;
358	}
359
360
361	The following example takes a html file and outputs a list of all the linked files:
362
363	#include <fstream>
364	#include <iostream>
365	#include <iterator>
366	#include <boost/regex.hpp>
367
368	boost::regex e("<\\sA\\s+[^>]href\\s=\\s\"([^\"]*)\"",
369	boost::regex::normal \| boost::regbase::icase);
370
371	void load_file(std::string& s, std::istream& is)
372	{
373	s.erase();
374	//
375	// attempt to grow string buffer to match file size,
376	// this doesn't always work...
377	s.reserve(is.rdbuf()->in_avail());
378	char c;
379	while(is.get(c))
380	{
381	// use logarithmic growth strategy, in case
382	// in_avail (above) returned zero:
383	if(s.capacity() == s.size())
384	s.reserve(s.capacity() * 3);
385	s.append(1, c);
386	}
387	}
388
389	int main(int argc, char** argv)
390	{
391	std::string s;
392	int i;
393	for(i = 1; i < argc; ++i)
394	{
395	std::cout << "Findings URL's in " << argv[i] << ":" << std::endl;
396	s.erase();
397	std::ifstream is(argv[i]);
398	load_file(s, is);
399	boost::sregex_token_iterator i(s.begin(), s.end(), e, 1);
400	boost::sregex_token_iterator j;
401	while(i != j)
402	{
403	std::cout << *i++ << std::endl;
404	}
405	}
406	//
407	// alternative method:
408	// test the array-literal constructor, and split out the whole
409	// match as well as $1....
410	//
411	for(i = 1; i < argc; ++i)
412	{
413	std::cout << "Findings URL's in " << argv[i] << ":" << std::endl;
414	s.erase();
415	std::ifstream is(argv[i]);
416	load_file(s, is);
417	const int subs[] = {1, 0,};
418	boost::sregex_token_iterator i(s.begin(), s.end(), e, subs);
419	boost::sregex_token_iterator j;
420	while(i != j)
421	{
422	std::cout << *i++ << std::endl;
423	}
424	}
425
426	return 0;
427	}
428
429
430	[endsect]
431