1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 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< 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>> 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 & s, 41 boost::asio::basic_streambuf< Allocator > & b, 42 MatchCondition match_condition, 43 ReadHandler && 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< is_match_condition< MatchCondition >::value >::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<iterator, bool> 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<basic_streambuf<Allocator>::const_buffers_type> 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& 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< 161 boost::asio::streambuf::const_buffers_type> iterator; 162 163std::pair<iterator, bool> 164match_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... 173void handler(const boost::system::error_code& e, std::size_t size); 174... 175boost::asio::streambuf b; 176boost::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{ 184public: 185 explicit match_char(char c) : c_(c) {} 186 187 template <typename Iterator> 188 std::pair<Iterator, bool> 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 198private: 199 char c_; 200}; 201 202namespace asio { 203 template <> struct is_match_condition<match_char> 204 : public boost::true_type {}; 205} // namespace asio 206... 207void handler(const boost::system::error_code& e, std::size_t size); 208... 209boost::asio::streambuf b; 210boost::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 © 2003-2020 Christopher M. 216 Kohlhoff<p> 217 Distributed under the Boost Software License, Version 1.0. (See accompanying 218 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>) 219 </p> 220</div></td> 221</tr></table> 222<hr> 223<div class="spirit-nav"> 224<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> 225</div> 226</body> 227</html> 228
