Merged accumulated patches from Trunk.

[SVN r62831]

doc/html/boost_regex/ref/match_results.html

@@ -27,7 +27,7 @@
 <a name="boost_regex.ref.match_results"></a><a class="link" href="match_results.html" title="match_results"> match_results</a>
 </h3></div></div></div>
 <a name="boost_regex.ref.match_results.synopsis"></a><h5>
-<a name="id819686"></a>
+<a name="id710291"></a>
         <a class="link" href="match_results.html#boost_regex.ref.match_results.synopsis">Synopsis</a>
       </h5>
 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">regex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
@@ -167,7 +167,7 @@
          <span class="identifier">match_results</span><span class="special">&lt;</span><span class="identifier">BidirectionalIterator</span><span class="special">,</span> <span class="identifier">Allocator</span><span class="special">&gt;&amp;</span> <span class="identifier">m2</span><span class="special">);</span>
 </pre>
 <a name="boost_regex.ref.match_results.description"></a><h5>
-<a name="id824304"></a>
+<a name="id713816"></a>
         <a class="link" href="match_results.html#boost_regex.ref.match_results.description">Description</a>
       </h5>
 <p>
@@ -406,14 +406,21 @@
 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">charT</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Traits</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A</span><span class="special">&gt;</span>
 <span class="identifier">difference_type</span> <span class="identifier">length</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_string</span><span class="special">&lt;</span><span class="identifier">charT</span><span class="special">,</span> <span class="identifier">Traits</span><span class="special">,</span> <span class="identifier">A</span><span class="special">&gt;&amp;)</span><span class="keyword">const</span><span class="special">;</span>
 </pre>
+<p>
+        <span class="bold"><strong>Requires</strong></span>: that the match_results object
+        has been initialized as a result of a successful call to <a class="link" href="regex_search.html" title="regex_search"><code class="computeroutput"><span class="identifier">regex_search</span></code></a> or <a class="link" href="regex_match.html" title="regex_match"><code class="computeroutput"><span class="identifier">regex_match</span></code></a> or was returned from
+        a <a class="link" href="regex_iterator.html" title="regex_iterator"><code class="computeroutput"><span class="identifier">regex_iterator</span></code></a>,
+        and that the underlying iterators have not been subsequently invalidated.
+        Will raise a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span></code> if the match_results object
+        was not initialized.
+      </p>
 <p>
         <span class="bold"><strong>Effects</strong></span>: Returns the length of sub-expression
         <span class="emphasis"><em>sub</em></span>, that is to say: <code class="computeroutput"><span class="special">(*</span><span class="keyword">this</span><span class="special">)[</span><span class="identifier">sub</span><span class="special">].</span><span class="identifier">length</span><span class="special">()</span></code>.
       </p>
 <p>
         The overloads that accept a string refer to a named sub-expression <span class="emphasis"><em>n</em></span>.
-        In the event that there is no such named sub-expression then returns an empty
-        string.
+        In the event that there is no such named sub-expression then returns zero.
       </p>
 <p>
         The template overloads of this function, allow the string and/or character
@@ -434,6 +441,14 @@
 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">charT</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Traits</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A</span><span class="special">&gt;</span>
 <span class="identifier">difference_type</span> <span class="identifier">position</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_string</span><span class="special">&lt;</span><span class="identifier">charT</span><span class="special">,</span> <span class="identifier">Traits</span><span class="special">,</span> <span class="identifier">A</span><span class="special">&gt;&amp;)</span><span class="keyword">const</span><span class="special">;</span>
 </pre>
+<p>
+        <span class="bold"><strong>Requires</strong></span>: that the match_results object
+        has been initialized as a result of a successful call to <a class="link" href="regex_search.html" title="regex_search"><code class="computeroutput"><span class="identifier">regex_search</span></code></a> or <a class="link" href="regex_match.html" title="regex_match"><code class="computeroutput"><span class="identifier">regex_match</span></code></a> or was returned from
+        a <a class="link" href="regex_iterator.html" title="regex_iterator"><code class="computeroutput"><span class="identifier">regex_iterator</span></code></a>,
+        and that the underlying iterators have not been subsequently invalidated.
+        Will raise a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span></code> if the match_results object
+        was not initialized.
+      </p>
 <p>
         <span class="bold"><strong>Effects</strong></span>: Returns the starting location of
         sub-expression <span class="emphasis"><em>sub</em></span>, or -1 if <span class="emphasis"><em>sub</em></span>
@@ -443,8 +458,7 @@
       </p>
 <p>
         The overloads that accept a string refer to a named sub-expression <span class="emphasis"><em>n</em></span>.
-        In the event that there is no such named sub-expression then returns an empty
-        string.
+        In the event that there is no such named sub-expression then returns -1.
       </p>
 <p>
         The template overloads of this function, allow the string and/or character
@@ -467,6 +481,14 @@
 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">charT</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Traits</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A</span><span class="special">&gt;</span>
 <span class="identifier">string_type</span> <span class="identifier">str</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_string</span><span class="special">&lt;</span><span class="identifier">charT</span><span class="special">,</span> <span class="identifier">Traits</span><span class="special">,</span> <span class="identifier">A</span><span class="special">&gt;&amp;</span> <span class="identifier">sub</span><span class="special">)</span><span class="keyword">const</span><span class="special">;</span>
 </pre>
+<p>
+        <span class="bold"><strong>Requires</strong></span>: that the match_results object
+        has been initialized as a result of a successful call to <a class="link" href="regex_search.html" title="regex_search"><code class="computeroutput"><span class="identifier">regex_search</span></code></a> or <a class="link" href="regex_match.html" title="regex_match"><code class="computeroutput"><span class="identifier">regex_match</span></code></a> or was returned from
+        a <a class="link" href="regex_iterator.html" title="regex_iterator"><code class="computeroutput"><span class="identifier">regex_iterator</span></code></a>,
+        and that the underlying iterators have not been subsequently invalidated.
+        Will raise a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span></code> if the match_results object
+        was not initialized.
+      </p>
 <p>
         <span class="bold"><strong>Effects</strong></span>: Returns sub-expression <span class="emphasis"><em>sub</em></span>
         as a string: <code class="computeroutput"><span class="identifier">string_type</span><span class="special">((*</span><span class="keyword">this</span><span class="special">)[</span><span class="identifier">sub</span><span class="special">])</span></code>.
@@ -497,6 +519,14 @@
 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">charT</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Traits</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A</span><span class="special">&gt;</span>
 <span class="identifier">const_reference</span> <span class="keyword">operator</span><span class="special">[](</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_string</span><span class="special">&lt;</span><span class="identifier">charT</span><span class="special">,</span> <span class="identifier">Traits</span><span class="special">,</span> <span class="identifier">A</span><span class="special">&gt;&amp;</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
 </pre>
+<p>
+        <span class="bold"><strong>Requires</strong></span>: that the match_results object
+        has been initialized as a result of a successful call to <a class="link" href="regex_search.html" title="regex_search"><code class="computeroutput"><span class="identifier">regex_search</span></code></a> or <a class="link" href="regex_match.html" title="regex_match"><code class="computeroutput"><span class="identifier">regex_match</span></code></a> or was returned from
+        a <a class="link" href="regex_iterator.html" title="regex_iterator"><code class="computeroutput"><span class="identifier">regex_iterator</span></code></a>,
+        and that the underlying iterators have not been subsequently invalidated.
+        Will raise a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span></code> if the match_results object
+        was not initialized.
+      </p>
 <p>
         <span class="bold"><strong>Effects</strong></span>: Returns a reference to the <a class="link" href="sub_match.html" title="sub_match"><code class="computeroutput"><span class="identifier">sub_match</span></code></a>
         object representing the character sequence that matched marked sub-expression
@@ -527,6 +557,14 @@
       </p>
 <pre class="programlisting"><span class="identifier">const_reference</span> <span class="identifier">prefix</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
 </pre>
+<p>
+        <span class="bold"><strong>Requires</strong></span>: that the match_results object
+        has been initialized as a result of a successful call to <a class="link" href="regex_search.html" title="regex_search"><code class="computeroutput"><span class="identifier">regex_search</span></code></a> or <a class="link" href="regex_match.html" title="regex_match"><code class="computeroutput"><span class="identifier">regex_match</span></code></a> or was returned from
+        a <a class="link" href="regex_iterator.html" title="regex_iterator"><code class="computeroutput"><span class="identifier">regex_iterator</span></code></a>,
+        and that the underlying iterators have not been subsequently invalidated.
+        Will raise a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span></code> if the match_results object
+        was not initialized.
+      </p>
 <p>
         <span class="bold"><strong>Effects</strong></span>: Returns a reference to the <a class="link" href="sub_match.html" title="sub_match"><code class="computeroutput"><span class="identifier">sub_match</span></code></a>
         object representing the character sequence from the start of the string being
@@ -536,6 +574,14 @@
       </p>
 <pre class="programlisting"><span class="identifier">const_reference</span> <span class="identifier">suffix</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
 </pre>
+<p>
+        <span class="bold"><strong>Requires</strong></span>: that the match_results object
+        has been initialized as a result of a successful call to <a class="link" href="regex_search.html" title="regex_search"><code class="computeroutput"><span class="identifier">regex_search</span></code></a> or <a class="link" href="regex_match.html" title="regex_match"><code class="computeroutput"><span class="identifier">regex_match</span></code></a> or was returned from
+        a <a class="link" href="regex_iterator.html" title="regex_iterator"><code class="computeroutput"><span class="identifier">regex_iterator</span></code></a>,
+        and that the underlying iterators have not been subsequently invalidated.
+        Will raise a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span></code> if the match_results object
+        was not initialized.
+      </p>
 <p>
         <span class="bold"><strong>Effects</strong></span>: Returns a reference to the <a class="link" href="sub_match.html" title="sub_match"><code class="computeroutput"><span class="identifier">sub_match</span></code></a>
         object representing the character sequence from the end of the match found
@@ -579,7 +625,18 @@
         <span class="identifier">out</span><span class="special">)</span></code>
         or <code class="computeroutput"><span class="identifier">fmt</span><span class="special">(*</span><span class="keyword">this</span><span class="special">,</span> <span class="identifier">out</span><span class="special">,</span> <span class="identifier">flags</span><span class="special">)</span></code>, both of which write the replacement text
         to <code class="computeroutput"><span class="special">*</span><span class="identifier">out</span></code>,
-        and then return the new OutputIterator position.
+        and then return the new OutputIterator position. Note that if the formatter
+        is a functor, then it is <span class="emphasis"><em>passed by value</em></span>: users that
+        want to pass function objects with internal state might want to use <a href="../../../../../../doc/html/ref.html" target="_top">Boost.Ref</a> to wrap the object
+        so that it's passed by reference.
+      </p>
+<p>
+        <span class="bold"><strong>Requires</strong></span>: that the match_results object
+        has been initialized as a result of a successful call to <a class="link" href="regex_search.html" title="regex_search"><code class="computeroutput"><span class="identifier">regex_search</span></code></a> or <a class="link" href="regex_match.html" title="regex_match"><code class="computeroutput"><span class="identifier">regex_match</span></code></a> or was returned from
+        a <a class="link" href="regex_iterator.html" title="regex_iterator"><code class="computeroutput"><span class="identifier">regex_iterator</span></code></a>,
+        and that the underlying iterators have not been subsequently invalidated.
+        Will raise a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span></code> if the match_results object
+        was not initialized.
       </p>
 <p>
         <span class="bold"><strong>Effects</strong></span>: If <code class="computeroutput"><span class="identifier">fmt</span></code>
@@ -601,7 +658,7 @@
 <div class="itemizedlist"><ul type="disc">
 <li>
           Call <code class="computeroutput"><span class="identifier">fmt</span><span class="special">(*</span><span class="keyword">this</span><span class="special">)</span></code> and
-          copy the result to <code class="computeroutput"><span class="identifier">OutputIterator</span></code><span class="emphasis"><em>out</em></span>.
+          copy the string returned to <code class="computeroutput"><span class="identifier">OutputIterator</span></code><span class="emphasis"><em>out</em></span>.
         </li>
 <li>
           Call <code class="computeroutput"><span class="identifier">fmt</span><span class="special">(*</span><span class="keyword">this</span><span class="special">,</span> <span class="identifier">out</span><span class="special">)</span></code>.
@@ -640,6 +697,14 @@
         to <code class="computeroutput"><span class="special">*</span><span class="identifier">out</span></code>,
         and then return the new OutputIterator position.
       </p>
+<p>
+        <span class="bold"><strong>Requires</strong></span>: that the match_results object
+        has been initialized as a result of a successful call to <a class="link" href="regex_search.html" title="regex_search"><code class="computeroutput"><span class="identifier">regex_search</span></code></a> or <a class="link" href="regex_match.html" title="regex_match"><code class="computeroutput"><span class="identifier">regex_match</span></code></a> or was returned from
+        a <a class="link" href="regex_iterator.html" title="regex_iterator"><code class="computeroutput"><span class="identifier">regex_iterator</span></code></a>,
+        and that the underlying iterators have not been subsequently invalidated.
+        Will raise a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span></code> if the match_results object
+        was not initialized.
+      </p>
 <p>
         <span class="bold"><strong>Effects</strong></span>: If <code class="computeroutput"><span class="identifier">fmt</span></code>
         is either a null-terminated string, or a container of <code class="computeroutput"><span class="identifier">char_type</span></code>'s,
@@ -713,6 +778,14 @@
       </p>
 <pre class="programlisting"><span class="keyword">const</span> <span class="identifier">capture_sequence_type</span><span class="special">&amp;</span> <span class="identifier">captures</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">i</span><span class="special">)</span><span class="keyword">const</span><span class="special">;</span> 
 </pre>
+<p>
+        <span class="bold"><strong>Requires</strong></span>: that the match_results object
+        has been initialized as a result of a successful call to <a class="link" href="regex_search.html" title="regex_search"><code class="computeroutput"><span class="identifier">regex_search</span></code></a> or <a class="link" href="regex_match.html" title="regex_match"><code class="computeroutput"><span class="identifier">regex_match</span></code></a> or was returned from
+        a <a class="link" href="regex_iterator.html" title="regex_iterator"><code class="computeroutput"><span class="identifier">regex_iterator</span></code></a>,
+        and that the underlying iterators have not been subsequently invalidated.
+        Will raise a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span></code> if the match_results object
+        was not initialized.
+      </p>
 <p>
         <span class="bold"><strong>Effects</strong></span>: returns a sequence containing all
         the captures obtained for sub-expression i.