doc/html/boost_asio/reference/async_read_until/overload8.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>async_read_until (8 of 12 overloads)</title>
   5 <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../../../boost_asio.html" title="Boost.Asio">
   8 <link rel="up" href="../async_read_until.html" title="async_read_until">
   9 <link rel="prev" href="overload7.html" title="async_read_until (7 of 12 overloads)">
  10 <link rel="next" href="overload9.html" title="async_read_until (9 of 12 overloads)">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="overload7.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../async_read_until.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="overload9.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h4 class="title">
  27 <a name="boost_asio.reference.async_read_until.overload8"></a><a class="link" href="overload8.html" title="async_read_until (8 of 12 overloads)">async_read_until
  28         (8 of 12 overloads)</a>
  29 </h4></div></div></div>
  30 <p>
  31           Start an asynchronous operation to read data into a streambuf until a function
  32           object indicates a match.
  33         </p>
  34 <pre class="programlisting">template&lt;
  35     typename <a class="link" href="../AsyncReadStream.html" title="Buffer-oriented asynchronous read stream requirements">AsyncReadStream</a>,
  36     typename Allocator,
  37     typename MatchCondition,
  38     typename <a class="link" href="../ReadHandler.html" title="Read handler requirements">ReadHandler</a> = <a class="link" href="../asynchronous_operations.html#boost_asio.reference.asynchronous_operations.default_completion_tokens"><span class="emphasis"><em>DEFAULT</em></span></a>&gt;
  39 <a class="link" href="../asynchronous_operations.html#boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type"><span class="emphasis"><em>DEDUCED</em></span></a> async_read_until(
  40     AsyncReadStream &amp; s,
  41     boost::asio::basic_streambuf&lt; Allocator &gt; &amp; b,
  42     MatchCondition match_condition,
  43     ReadHandler &amp;&amp; handler = <a class="link" href="../asynchronous_operations.html#boost_asio.reference.asynchronous_operations.default_completion_tokens"><span class="emphasis"><em>DEFAULT</em></span></a>,
  44     typename enable_if&lt; is_match_condition&lt; MatchCondition &gt;::value &gt;::type *  = 0);
  45 </pre>
  46 <p>
  47           This function is used to asynchronously read data into the specified streambuf
  48           until a user-defined match condition function object, when applied to the
  49           data contained in the streambuf, indicates a successful match. The function
  50           call always returns immediately. The asynchronous operation will continue
  51           until one of the following conditions is true:
  52         </p>
  53 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  54 <li class="listitem">
  55               The match condition function object returns a std::pair where the second
  56               element evaluates to true.
  57             </li>
  58 <li class="listitem">
  59               An error occurred.
  60             </li>
  61 </ul></div>
  62 <p>
  63           This operation is implemented in terms of zero or more calls to the stream's
  64           async_read_some function, and is known as a <span class="emphasis"><em>composed operation</em></span>.
  65           If the match condition function object already indicates a match, this
  66           asynchronous operation completes immediately. The program must ensure that
  67           the stream performs no other read operations (such as async_read, async_read_until,
  68           the stream's async_read_some function, or any other composed operations
  69           that perform reads) until this operation completes.
  70         </p>
  71 <h6>
  72 <a name="boost_asio.reference.async_read_until.overload8.h0"></a>
  73           <span class="phrase"><a name="boost_asio.reference.async_read_until.overload8.parameters"></a></span><a class="link" href="overload8.html#boost_asio.reference.async_read_until.overload8.parameters">Parameters</a>
  74         </h6>
  75 <div class="variablelist">
  76 <p class="title"><b></b></p>
  77 <dl class="variablelist">
  78 <dt><span class="term">s</span></dt>
  79 <dd><p>
  80                 The stream from which the data is to be read. The type must support
  81                 the AsyncReadStream concept.
  82               </p></dd>
  83 <dt><span class="term">b</span></dt>
  84 <dd><p>
  85                 A streambuf object into which the data will be read.
  86               </p></dd>
  87 <dt><span class="term">match_condition</span></dt>
  88 <dd>
  89 <p>
  90                 The function object to be called to determine whether a match exists.
  91                 The signature of the function object must be:
  92 </p>
  93 <pre class="programlisting">pair&lt;iterator, bool&gt; match_condition(iterator begin, iterator end);
  94 </pre>
  95 <p>
  96                 where <code class="computeroutput">iterator</code> represents the type:
  97 </p>
  98 <pre class="programlisting">buffers_iterator&lt;basic_streambuf&lt;Allocator&gt;::const_buffers_type&gt;
  99 </pre>
 100 <p>
 101                 The iterator parameters <code class="computeroutput">begin</code> and <code class="computeroutput">end</code> define
 102                 the range of bytes to be scanned to determine whether there is a
 103                 match. The <code class="computeroutput">first</code> member of the return value is an iterator
 104                 marking one-past-the-end of the bytes that have been consumed by
 105                 the match function. This iterator is used to calculate the <code class="computeroutput">begin</code>
 106                 parameter for any subsequent invocation of the match condition. The
 107                 <code class="computeroutput">second</code> member of the return value is true if a match
 108                 has been found, false otherwise.
 109               </p>
 110 </dd>
 111 <dt><span class="term">handler</span></dt>
 112 <dd>
 113 <p>
 114                 The handler to be called when the read operation completes. Copies
 115                 will be made of the handler as required. The function signature of
 116                 the handler must be:
 117 </p>
 118 <pre class="programlisting">void handler(
 119   // Result of operation.
 120   const boost::system::error_code&amp; error,
 121
 122   // The number of bytes in the streambuf's get
 123   // area that have been fully consumed by the
 124   // match function. O if an error occurred.
 125   std::size_t bytes_transferred
 126 );
 127 </pre>
 128 <p>
 129                 Regardless of whether the asynchronous operation completes immediately
 130                 or not, the handler will not be invoked from within this function.
 131                 On immediate completion, invocation of the handler will be performed
 132                 in a manner equivalent to using <a class="link" href="../post.html" title="post"><code class="computeroutput">post</code></a>.
 133               </p>
 134 </dd>
 135 </dl>
 136 </div>
 137 <h6>
 138 <a name="boost_asio.reference.async_read_until.overload8.h1"></a>
 139           <span class="phrase"><a name="boost_asio.reference.async_read_until.overload8.remarks"></a></span><a class="link" href="overload8.html#boost_asio.reference.async_read_until.overload8.remarks">Remarks</a>
 140         </h6>
 141 <p>
 142           After a successful async_read_until operation, the streambuf may contain
 143           additional data beyond that which matched the function object. An application
 144           will typically leave that data in the streambuf for a subsequent async_read_until
 145           operation to examine.
 146         </p>
 147 <p>
 148           The default implementation of the <code class="computeroutput">is_match_condition</code> type
 149           trait evaluates to true for function pointers and function objects with
 150           a <code class="computeroutput">result_type</code> typedef. It must be specialised for other user-defined
 151           function objects.
 152         </p>
 153 <h6>
 154 <a name="boost_asio.reference.async_read_until.overload8.h2"></a>
 155           <span class="phrase"><a name="boost_asio.reference.async_read_until.overload8.examples"></a></span><a class="link" href="overload8.html#boost_asio.reference.async_read_until.overload8.examples">Examples</a>
 156         </h6>
 157 <p>
 158           To asynchronously read data into a streambuf until whitespace is encountered:
 159         </p>
 160 <pre class="programlisting">typedef boost::asio::buffers_iterator&lt;
 161     boost::asio::streambuf::const_buffers_type&gt; iterator;
 162
 163 std::pair&lt;iterator, bool&gt;
 164 match_whitespace(iterator begin, iterator end)
 165 {
 166   iterator i = begin;
 167   while (i != end)
 168     if (std::isspace(*i++))
 169       return std::make_pair(i, true);
 170   return std::make_pair(i, false);
 171 }
 172 ...
 173 void handler(const boost::system::error_code&amp; e, std::size_t size);
 174 ...
 175 boost::asio::streambuf b;
 176 boost::asio::async_read_until(s, b, match_whitespace, handler);
 177 </pre>
 178 <p>
 179           To asynchronously read data into a streambuf until a matching character
 180           is found:
 181         </p>
 182 <pre class="programlisting">class match_char
 183 {
 184 public:
 185   explicit match_char(char c) : c_(c) {}
 186
 187   template &lt;typename Iterator&gt;
 188   std::pair&lt;Iterator, bool&gt; operator()(
 189       Iterator begin, Iterator end) const
 190   {
 191     Iterator i = begin;
 192     while (i != end)
 193       if (c_ == *i++)
 194         return std::make_pair(i, true);
 195     return std::make_pair(i, false);
 196   }
 197
 198 private:
 199   char c_;
 200 };
 201
 202 namespace asio {
 203   template &lt;&gt; struct is_match_condition&lt;match_char&gt;
 204     : public boost::true_type {};
 205 } // namespace asio
 206 ...
 207 void handler(const boost::system::error_code&amp; e, std::size_t size);
 208 ...
 209 boost::asio::streambuf b;
 210 boost::asio::async_read_until(s, b, match_char('a'), handler);
 211 </pre>
 212 </div>
 213 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 214 <td align="left"></td>
 215 <td align="right"><div class="copyright-footer">Copyright &#169; 2003-2019 Christopher M. Kohlhoff<p>
 216         Distributed under the Boost Software License, Version 1.0. (See accompanying
 217         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 218       </p>
 219 </div></td>
 220 </tr></table>
 221 <hr>
 222 <div class="spirit-nav">
 223 <a accesskey="p" href="overload7.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../async_read_until.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="overload9.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 224 </div>
 225 </body>
 226 </html>