1 | // |
2 | // read_until.hpp |
3 | // ~~~~~~~~~~~~~~ |
4 | // |
5 | // Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com) |
6 | // |
7 | // Distributed under the Boost Software License, Version 1.0. (See accompanying |
8 | // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) |
9 | // |
10 | |
11 | #ifndef BOOST_ASIO_READ_UNTIL_HPP |
12 | #define BOOST_ASIO_READ_UNTIL_HPP |
13 | |
14 | #if defined(_MSC_VER) && (_MSC_VER >= 1200) |
15 | # pragma once |
16 | #endif // defined(_MSC_VER) && (_MSC_VER >= 1200) |
17 | |
18 | #include <boost/asio/detail/config.hpp> |
19 | |
20 | #if !defined(BOOST_ASIO_NO_IOSTREAM) |
21 | |
22 | #include <cstddef> |
23 | #include <string> |
24 | #include <boost/asio/async_result.hpp> |
25 | #include <boost/asio/basic_streambuf.hpp> |
26 | #include <boost/asio/detail/regex_fwd.hpp> |
27 | #include <boost/asio/detail/type_traits.hpp> |
28 | #include <boost/asio/error.hpp> |
29 | |
30 | #include <boost/asio/detail/push_options.hpp> |
31 | |
32 | namespace boost { |
33 | namespace asio { |
34 | |
35 | namespace detail |
36 | { |
37 | char (&has_result_type_helper(...))[2]; |
38 | |
39 | template <typename T> |
40 | char has_result_type_helper(T*, typename T::result_type* = 0); |
41 | |
42 | template <typename T> |
43 | struct has_result_type |
44 | { |
45 | enum { value = (sizeof((has_result_type_helper)((T*)(0))) == 1) }; |
46 | }; |
47 | } // namespace detail |
48 | |
49 | /// Type trait used to determine whether a type can be used as a match condition |
50 | /// function with read_until and async_read_until. |
51 | template <typename T> |
52 | struct is_match_condition |
53 | { |
54 | #if defined(GENERATING_DOCUMENTATION) |
55 | /// The value member is true if the type may be used as a match condition. |
56 | static const bool value; |
57 | #else |
58 | enum |
59 | { |
60 | value = boost::asio::is_function< |
61 | typename boost::asio::remove_pointer<T>::type>::value |
62 | || detail::has_result_type<T>::value |
63 | }; |
64 | #endif |
65 | }; |
66 | |
67 | /** |
68 | * @defgroup read_until boost::asio::read_until |
69 | * |
70 | * @brief Read data into a streambuf until it contains a delimiter, matches a |
71 | * regular expression, or a function object indicates a match. |
72 | */ |
73 | /*@{*/ |
74 | |
75 | /// Read data into a streambuf until it contains a specified delimiter. |
76 | /** |
77 | * This function is used to read data into the specified streambuf until the |
78 | * streambuf's get area contains the specified delimiter. The call will block |
79 | * until one of the following conditions is true: |
80 | * |
81 | * @li The get area of the streambuf contains the specified delimiter. |
82 | * |
83 | * @li An error occurred. |
84 | * |
85 | * This operation is implemented in terms of zero or more calls to the stream's |
86 | * read_some function. If the streambuf's get area already contains the |
87 | * delimiter, the function returns immediately. |
88 | * |
89 | * @param s The stream from which the data is to be read. The type must support |
90 | * the SyncReadStream concept. |
91 | * |
92 | * @param b A streambuf object into which the data will be read. |
93 | * |
94 | * @param delim The delimiter character. |
95 | * |
96 | * @returns The number of bytes in the streambuf's get area up to and including |
97 | * the delimiter. |
98 | * |
99 | * @throws boost::system::system_error Thrown on failure. |
100 | * |
101 | * @note After a successful read_until operation, the streambuf may contain |
102 | * additional data beyond the delimiter. An application will typically leave |
103 | * that data in the streambuf for a subsequent read_until operation to examine. |
104 | * |
105 | * @par Example |
106 | * To read data into a streambuf until a newline is encountered: |
107 | * @code boost::asio::streambuf b; |
108 | * boost::asio::read_until(s, b, '\n'); |
109 | * std::istream is(&b); |
110 | * std::string line; |
111 | * std::getline(is, line); @endcode |
112 | * After the @c read_until operation completes successfully, the buffer @c b |
113 | * contains the delimiter: |
114 | * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode |
115 | * The call to @c std::getline then extracts the data up to and including the |
116 | * delimiter, so that the string @c line contains: |
117 | * @code { 'a', 'b', ..., 'c', '\n' } @endcode |
118 | * The remaining data is left in the buffer @c b as follows: |
119 | * @code { 'd', 'e', ... } @endcode |
120 | * This data may be the start of a new line, to be extracted by a subsequent |
121 | * @c read_until operation. |
122 | */ |
123 | template <typename SyncReadStream, typename Allocator> |
124 | std::size_t read_until(SyncReadStream& s, |
125 | boost::asio::basic_streambuf<Allocator>& b, char delim); |
126 | |
127 | /// Read data into a streambuf until it contains a specified delimiter. |
128 | /** |
129 | * This function is used to read data into the specified streambuf until the |
130 | * streambuf's get area contains the specified delimiter. The call will block |
131 | * until one of the following conditions is true: |
132 | * |
133 | * @li The get area of the streambuf contains the specified delimiter. |
134 | * |
135 | * @li An error occurred. |
136 | * |
137 | * This operation is implemented in terms of zero or more calls to the stream's |
138 | * read_some function. If the streambuf's get area already contains the |
139 | * delimiter, the function returns immediately. |
140 | * |
141 | * @param s The stream from which the data is to be read. The type must support |
142 | * the SyncReadStream concept. |
143 | * |
144 | * @param b A streambuf object into which the data will be read. |
145 | * |
146 | * @param delim The delimiter character. |
147 | * |
148 | * @param ec Set to indicate what error occurred, if any. |
149 | * |
150 | * @returns The number of bytes in the streambuf's get area up to and including |
151 | * the delimiter. Returns 0 if an error occurred. |
152 | * |
153 | * @note After a successful read_until operation, the streambuf may contain |
154 | * additional data beyond the delimiter. An application will typically leave |
155 | * that data in the streambuf for a subsequent read_until operation to examine. |
156 | */ |
157 | template <typename SyncReadStream, typename Allocator> |
158 | std::size_t read_until(SyncReadStream& s, |
159 | boost::asio::basic_streambuf<Allocator>& b, char delim, |
160 | boost::system::error_code& ec); |
161 | |
162 | /// Read data into a streambuf until it contains a specified delimiter. |
163 | /** |
164 | * This function is used to read data into the specified streambuf until the |
165 | * streambuf's get area contains the specified delimiter. The call will block |
166 | * until one of the following conditions is true: |
167 | * |
168 | * @li The get area of the streambuf contains the specified delimiter. |
169 | * |
170 | * @li An error occurred. |
171 | * |
172 | * This operation is implemented in terms of zero or more calls to the stream's |
173 | * read_some function. If the streambuf's get area already contains the |
174 | * delimiter, the function returns immediately. |
175 | * |
176 | * @param s The stream from which the data is to be read. The type must support |
177 | * the SyncReadStream concept. |
178 | * |
179 | * @param b A streambuf object into which the data will be read. |
180 | * |
181 | * @param delim The delimiter string. |
182 | * |
183 | * @returns The number of bytes in the streambuf's get area up to and including |
184 | * the delimiter. |
185 | * |
186 | * @throws boost::system::system_error Thrown on failure. |
187 | * |
188 | * @note After a successful read_until operation, the streambuf may contain |
189 | * additional data beyond the delimiter. An application will typically leave |
190 | * that data in the streambuf for a subsequent read_until operation to examine. |
191 | * |
192 | * @par Example |
193 | * To read data into a streambuf until a newline is encountered: |
194 | * @code boost::asio::streambuf b; |
195 | * boost::asio::read_until(s, b, "\r\n"); |
196 | * std::istream is(&b); |
197 | * std::string line; |
198 | * std::getline(is, line); @endcode |
199 | * After the @c read_until operation completes successfully, the buffer @c b |
200 | * contains the delimiter: |
201 | * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode |
202 | * The call to @c std::getline then extracts the data up to and including the |
203 | * delimiter, so that the string @c line contains: |
204 | * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode |
205 | * The remaining data is left in the buffer @c b as follows: |
206 | * @code { 'd', 'e', ... } @endcode |
207 | * This data may be the start of a new line, to be extracted by a subsequent |
208 | * @c read_until operation. |
209 | */ |
210 | template <typename SyncReadStream, typename Allocator> |
211 | std::size_t read_until(SyncReadStream& s, |
212 | boost::asio::basic_streambuf<Allocator>& b, const std::string& delim); |
213 | |
214 | /// Read data into a streambuf until it contains a specified delimiter. |
215 | /** |
216 | * This function is used to read data into the specified streambuf until the |
217 | * streambuf's get area contains the specified delimiter. The call will block |
218 | * until one of the following conditions is true: |
219 | * |
220 | * @li The get area of the streambuf contains the specified delimiter. |
221 | * |
222 | * @li An error occurred. |
223 | * |
224 | * This operation is implemented in terms of zero or more calls to the stream's |
225 | * read_some function. If the streambuf's get area already contains the |
226 | * delimiter, the function returns immediately. |
227 | * |
228 | * @param s The stream from which the data is to be read. The type must support |
229 | * the SyncReadStream concept. |
230 | * |
231 | * @param b A streambuf object into which the data will be read. |
232 | * |
233 | * @param delim The delimiter string. |
234 | * |
235 | * @param ec Set to indicate what error occurred, if any. |
236 | * |
237 | * @returns The number of bytes in the streambuf's get area up to and including |
238 | * the delimiter. Returns 0 if an error occurred. |
239 | * |
240 | * @note After a successful read_until operation, the streambuf may contain |
241 | * additional data beyond the delimiter. An application will typically leave |
242 | * that data in the streambuf for a subsequent read_until operation to examine. |
243 | */ |
244 | template <typename SyncReadStream, typename Allocator> |
245 | std::size_t read_until(SyncReadStream& s, |
246 | boost::asio::basic_streambuf<Allocator>& b, const std::string& delim, |
247 | boost::system::error_code& ec); |
248 | |
249 | #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \ |
250 | || defined(GENERATING_DOCUMENTATION) |
251 | |
252 | /// Read data into a streambuf until some part of the data it contains matches |
253 | /// a regular expression. |
254 | /** |
255 | * This function is used to read data into the specified streambuf until the |
256 | * streambuf's get area contains some data that matches a regular expression. |
257 | * The call will block until one of the following conditions is true: |
258 | * |
259 | * @li A substring of the streambuf's get area matches the regular expression. |
260 | * |
261 | * @li An error occurred. |
262 | * |
263 | * This operation is implemented in terms of zero or more calls to the stream's |
264 | * read_some function. If the streambuf's get area already contains data that |
265 | * matches the regular expression, the function returns immediately. |
266 | * |
267 | * @param s The stream from which the data is to be read. The type must support |
268 | * the SyncReadStream concept. |
269 | * |
270 | * @param b A streambuf object into which the data will be read. |
271 | * |
272 | * @param expr The regular expression. |
273 | * |
274 | * @returns The number of bytes in the streambuf's get area up to and including |
275 | * the substring that matches the regular expression. |
276 | * |
277 | * @throws boost::system::system_error Thrown on failure. |
278 | * |
279 | * @note After a successful read_until operation, the streambuf may contain |
280 | * additional data beyond that which matched the regular expression. An |
281 | * application will typically leave that data in the streambuf for a subsequent |
282 | * read_until operation to examine. |
283 | * |
284 | * @par Example |
285 | * To read data into a streambuf until a CR-LF sequence is encountered: |
286 | * @code boost::asio::streambuf b; |
287 | * boost::asio::read_until(s, b, boost::regex("\r\n")); |
288 | * std::istream is(&b); |
289 | * std::string line; |
290 | * std::getline(is, line); @endcode |
291 | * After the @c read_until operation completes successfully, the buffer @c b |
292 | * contains the data which matched the regular expression: |
293 | * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode |
294 | * The call to @c std::getline then extracts the data up to and including the |
295 | * match, so that the string @c line contains: |
296 | * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode |
297 | * The remaining data is left in the buffer @c b as follows: |
298 | * @code { 'd', 'e', ... } @endcode |
299 | * This data may be the start of a new line, to be extracted by a subsequent |
300 | * @c read_until operation. |
301 | */ |
302 | template <typename SyncReadStream, typename Allocator> |
303 | std::size_t read_until(SyncReadStream& s, |
304 | boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr); |
305 | |
306 | /// Read data into a streambuf until some part of the data it contains matches |
307 | /// a regular expression. |
308 | /** |
309 | * This function is used to read data into the specified streambuf until the |
310 | * streambuf's get area contains some data that matches a regular expression. |
311 | * The call will block until one of the following conditions is true: |
312 | * |
313 | * @li A substring of the streambuf's get area matches the regular expression. |
314 | * |
315 | * @li An error occurred. |
316 | * |
317 | * This operation is implemented in terms of zero or more calls to the stream's |
318 | * read_some function. If the streambuf's get area already contains data that |
319 | * matches the regular expression, the function returns immediately. |
320 | * |
321 | * @param s The stream from which the data is to be read. The type must support |
322 | * the SyncReadStream concept. |
323 | * |
324 | * @param b A streambuf object into which the data will be read. |
325 | * |
326 | * @param expr The regular expression. |
327 | * |
328 | * @param ec Set to indicate what error occurred, if any. |
329 | * |
330 | * @returns The number of bytes in the streambuf's get area up to and including |
331 | * the substring that matches the regular expression. Returns 0 if an error |
332 | * occurred. |
333 | * |
334 | * @note After a successful read_until operation, the streambuf may contain |
335 | * additional data beyond that which matched the regular expression. An |
336 | * application will typically leave that data in the streambuf for a subsequent |
337 | * read_until operation to examine. |
338 | */ |
339 | template <typename SyncReadStream, typename Allocator> |
340 | std::size_t read_until(SyncReadStream& s, |
341 | boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr, |
342 | boost::system::error_code& ec); |
343 | |
344 | #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX) |
345 | // || defined(GENERATING_DOCUMENTATION) |
346 | |
347 | /// Read data into a streambuf until a function object indicates a match. |
348 | /** |
349 | * This function is used to read data into the specified streambuf until a |
350 | * user-defined match condition function object, when applied to the data |
351 | * contained in the streambuf, indicates a successful match. The call will |
352 | * block until one of the following conditions is true: |
353 | * |
354 | * @li The match condition function object returns a std::pair where the second |
355 | * element evaluates to true. |
356 | * |
357 | * @li An error occurred. |
358 | * |
359 | * This operation is implemented in terms of zero or more calls to the stream's |
360 | * read_some function. If the match condition function object already indicates |
361 | * a match, the function returns immediately. |
362 | * |
363 | * @param s The stream from which the data is to be read. The type must support |
364 | * the SyncReadStream concept. |
365 | * |
366 | * @param b A streambuf object into which the data will be read. |
367 | * |
368 | * @param match_condition The function object to be called to determine whether |
369 | * a match exists. The signature of the function object must be: |
370 | * @code pair<iterator, bool> match_condition(iterator begin, iterator end); |
371 | * @endcode |
372 | * where @c iterator represents the type: |
373 | * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type> |
374 | * @endcode |
375 | * The iterator parameters @c begin and @c end define the range of bytes to be |
376 | * scanned to determine whether there is a match. The @c first member of the |
377 | * return value is an iterator marking one-past-the-end of the bytes that have |
378 | * been consumed by the match function. This iterator is used to calculate the |
379 | * @c begin parameter for any subsequent invocation of the match condition. The |
380 | * @c second member of the return value is true if a match has been found, false |
381 | * otherwise. |
382 | * |
383 | * @returns The number of bytes in the streambuf's get area that have been fully |
384 | * consumed by the match function. |
385 | * |
386 | * @throws boost::system::system_error Thrown on failure. |
387 | * |
388 | * @note After a successful read_until operation, the streambuf may contain |
389 | * additional data beyond that which matched the function object. An application |
390 | * will typically leave that data in the streambuf for a subsequent |
391 | * |
392 | * @note The default implementation of the @c is_match_condition type trait |
393 | * evaluates to true for function pointers and function objects with a |
394 | * @c result_type typedef. It must be specialised for other user-defined |
395 | * function objects. |
396 | * |
397 | * @par Examples |
398 | * To read data into a streambuf until whitespace is encountered: |
399 | * @code typedef boost::asio::buffers_iterator< |
400 | * boost::asio::streambuf::const_buffers_type> iterator; |
401 | * |
402 | * std::pair<iterator, bool> |
403 | * match_whitespace(iterator begin, iterator end) |
404 | * { |
405 | * iterator i = begin; |
406 | * while (i != end) |
407 | * if (std::isspace(*i++)) |
408 | * return std::make_pair(i, true); |
409 | * return std::make_pair(i, false); |
410 | * } |
411 | * ... |
412 | * boost::asio::streambuf b; |
413 | * boost::asio::read_until(s, b, match_whitespace); |
414 | * @endcode |
415 | * |
416 | * To read data into a streambuf until a matching character is found: |
417 | * @code class match_char |
418 | * { |
419 | * public: |
420 | * explicit match_char(char c) : c_(c) {} |
421 | * |
422 | * template <typename Iterator> |
423 | * std::pair<Iterator, bool> operator()( |
424 | * Iterator begin, Iterator end) const |
425 | * { |
426 | * Iterator i = begin; |
427 | * while (i != end) |
428 | * if (c_ == *i++) |
429 | * return std::make_pair(i, true); |
430 | * return std::make_pair(i, false); |
431 | * } |
432 | * |
433 | * private: |
434 | * char c_; |
435 | * }; |
436 | * |
437 | * namespace asio { |
438 | * template <> struct is_match_condition<match_char> |
439 | * : public boost::true_type {}; |
440 | * } // namespace asio |
441 | * ... |
442 | * boost::asio::streambuf b; |
443 | * boost::asio::read_until(s, b, match_char('a')); |
444 | * @endcode |
445 | */ |
446 | template <typename SyncReadStream, typename Allocator, typename MatchCondition> |
447 | std::size_t read_until(SyncReadStream& s, |
448 | boost::asio::basic_streambuf<Allocator>& b, MatchCondition match_condition, |
449 | typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0); |
450 | |
451 | /// Read data into a streambuf until a function object indicates a match. |
452 | /** |
453 | * This function is used to read data into the specified streambuf until a |
454 | * user-defined match condition function object, when applied to the data |
455 | * contained in the streambuf, indicates a successful match. The call will |
456 | * block until one of the following conditions is true: |
457 | * |
458 | * @li The match condition function object returns a std::pair where the second |
459 | * element evaluates to true. |
460 | * |
461 | * @li An error occurred. |
462 | * |
463 | * This operation is implemented in terms of zero or more calls to the stream's |
464 | * read_some function. If the match condition function object already indicates |
465 | * a match, the function returns immediately. |
466 | * |
467 | * @param s The stream from which the data is to be read. The type must support |
468 | * the SyncReadStream concept. |
469 | * |
470 | * @param b A streambuf object into which the data will be read. |
471 | * |
472 | * @param match_condition The function object to be called to determine whether |
473 | * a match exists. The signature of the function object must be: |
474 | * @code pair<iterator, bool> match_condition(iterator begin, iterator end); |
475 | * @endcode |
476 | * where @c iterator represents the type: |
477 | * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type> |
478 | * @endcode |
479 | * The iterator parameters @c begin and @c end define the range of bytes to be |
480 | * scanned to determine whether there is a match. The @c first member of the |
481 | * return value is an iterator marking one-past-the-end of the bytes that have |
482 | * been consumed by the match function. This iterator is used to calculate the |
483 | * @c begin parameter for any subsequent invocation of the match condition. The |
484 | * @c second member of the return value is true if a match has been found, false |
485 | * otherwise. |
486 | * |
487 | * @param ec Set to indicate what error occurred, if any. |
488 | * |
489 | * @returns The number of bytes in the streambuf's get area that have been fully |
490 | * consumed by the match function. Returns 0 if an error occurred. |
491 | * |
492 | * @note After a successful read_until operation, the streambuf may contain |
493 | * additional data beyond that which matched the function object. An application |
494 | * will typically leave that data in the streambuf for a subsequent |
495 | * |
496 | * @note The default implementation of the @c is_match_condition type trait |
497 | * evaluates to true for function pointers and function objects with a |
498 | * @c result_type typedef. It must be specialised for other user-defined |
499 | * function objects. |
500 | */ |
501 | template <typename SyncReadStream, typename Allocator, typename MatchCondition> |
502 | std::size_t read_until(SyncReadStream& s, |
503 | boost::asio::basic_streambuf<Allocator>& b, |
504 | MatchCondition match_condition, boost::system::error_code& ec, |
505 | typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0); |
506 | |
507 | /*@}*/ |
508 | /** |
509 | * @defgroup async_read_until boost::asio::async_read_until |
510 | * |
511 | * @brief Start an asynchronous operation to read data into a streambuf until it |
512 | * contains a delimiter, matches a regular expression, or a function object |
513 | * indicates a match. |
514 | */ |
515 | /*@{*/ |
516 | |
517 | /// Start an asynchronous operation to read data into a streambuf until it |
518 | /// contains a specified delimiter. |
519 | /** |
520 | * This function is used to asynchronously read data into the specified |
521 | * streambuf until the streambuf's get area contains the specified delimiter. |
522 | * The function call always returns immediately. The asynchronous operation |
523 | * will continue until one of the following conditions is true: |
524 | * |
525 | * @li The get area of the streambuf contains the specified delimiter. |
526 | * |
527 | * @li An error occurred. |
528 | * |
529 | * This operation is implemented in terms of zero or more calls to the stream's |
530 | * async_read_some function, and is known as a <em>composed operation</em>. If |
531 | * the streambuf's get area already contains the delimiter, this asynchronous |
532 | * operation completes immediately. The program must ensure that the stream |
533 | * performs no other read operations (such as async_read, async_read_until, the |
534 | * stream's async_read_some function, or any other composed operations that |
535 | * perform reads) until this operation completes. |
536 | * |
537 | * @param s The stream from which the data is to be read. The type must support |
538 | * the AsyncReadStream concept. |
539 | * |
540 | * @param b A streambuf object into which the data will be read. Ownership of |
541 | * the streambuf is retained by the caller, which must guarantee that it remains |
542 | * valid until the handler is called. |
543 | * |
544 | * @param delim The delimiter character. |
545 | * |
546 | * @param handler The handler to be called when the read operation completes. |
547 | * Copies will be made of the handler as required. The function signature of the |
548 | * handler must be: |
549 | * @code void handler( |
550 | * // Result of operation. |
551 | * const boost::system::error_code& error, |
552 | * |
553 | * // The number of bytes in the streambuf's get |
554 | * // area up to and including the delimiter. |
555 | * // 0 if an error occurred. |
556 | * std::size_t bytes_transferred |
557 | * ); @endcode |
558 | * Regardless of whether the asynchronous operation completes immediately or |
559 | * not, the handler will not be invoked from within this function. Invocation of |
560 | * the handler will be performed in a manner equivalent to using |
561 | * boost::asio::io_service::post(). |
562 | * |
563 | * @note After a successful async_read_until operation, the streambuf may |
564 | * contain additional data beyond the delimiter. An application will typically |
565 | * leave that data in the streambuf for a subsequent async_read_until operation |
566 | * to examine. |
567 | * |
568 | * @par Example |
569 | * To asynchronously read data into a streambuf until a newline is encountered: |
570 | * @code boost::asio::streambuf b; |
571 | * ... |
572 | * void handler(const boost::system::error_code& e, std::size_t size) |
573 | * { |
574 | * if (!e) |
575 | * { |
576 | * std::istream is(&b); |
577 | * std::string line; |
578 | * std::getline(is, line); |
579 | * ... |
580 | * } |
581 | * } |
582 | * ... |
583 | * boost::asio::async_read_until(s, b, '\n', handler); @endcode |
584 | * After the @c async_read_until operation completes successfully, the buffer |
585 | * @c b contains the delimiter: |
586 | * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode |
587 | * The call to @c std::getline then extracts the data up to and including the |
588 | * delimiter, so that the string @c line contains: |
589 | * @code { 'a', 'b', ..., 'c', '\n' } @endcode |
590 | * The remaining data is left in the buffer @c b as follows: |
591 | * @code { 'd', 'e', ... } @endcode |
592 | * This data may be the start of a new line, to be extracted by a subsequent |
593 | * @c async_read_until operation. |
594 | */ |
595 | template <typename AsyncReadStream, typename Allocator, typename ReadHandler> |
596 | BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, |
597 | void (boost::system::error_code, std::size_t)) |
598 | async_read_until(AsyncReadStream& s, |
599 | boost::asio::basic_streambuf<Allocator>& b, |
600 | char delim, BOOST_ASIO_MOVE_ARG(ReadHandler) handler); |
601 | |
602 | /// Start an asynchronous operation to read data into a streambuf until it |
603 | /// contains a specified delimiter. |
604 | /** |
605 | * This function is used to asynchronously read data into the specified |
606 | * streambuf until the streambuf's get area contains the specified delimiter. |
607 | * The function call always returns immediately. The asynchronous operation |
608 | * will continue until one of the following conditions is true: |
609 | * |
610 | * @li The get area of the streambuf contains the specified delimiter. |
611 | * |
612 | * @li An error occurred. |
613 | * |
614 | * This operation is implemented in terms of zero or more calls to the stream's |
615 | * async_read_some function, and is known as a <em>composed operation</em>. If |
616 | * the streambuf's get area already contains the delimiter, this asynchronous |
617 | * operation completes immediately. The program must ensure that the stream |
618 | * performs no other read operations (such as async_read, async_read_until, the |
619 | * stream's async_read_some function, or any other composed operations that |
620 | * perform reads) until this operation completes. |
621 | * |
622 | * @param s The stream from which the data is to be read. The type must support |
623 | * the AsyncReadStream concept. |
624 | * |
625 | * @param b A streambuf object into which the data will be read. Ownership of |
626 | * the streambuf is retained by the caller, which must guarantee that it remains |
627 | * valid until the handler is called. |
628 | * |
629 | * @param delim The delimiter string. |
630 | * |
631 | * @param handler The handler to be called when the read operation completes. |
632 | * Copies will be made of the handler as required. The function signature of the |
633 | * handler must be: |
634 | * @code void handler( |
635 | * // Result of operation. |
636 | * const boost::system::error_code& error, |
637 | * |
638 | * // The number of bytes in the streambuf's get |
639 | * // area up to and including the delimiter. |
640 | * // 0 if an error occurred. |
641 | * std::size_t bytes_transferred |
642 | * ); @endcode |
643 | * Regardless of whether the asynchronous operation completes immediately or |
644 | * not, the handler will not be invoked from within this function. Invocation of |
645 | * the handler will be performed in a manner equivalent to using |
646 | * boost::asio::io_service::post(). |
647 | * |
648 | * @note After a successful async_read_until operation, the streambuf may |
649 | * contain additional data beyond the delimiter. An application will typically |
650 | * leave that data in the streambuf for a subsequent async_read_until operation |
651 | * to examine. |
652 | * |
653 | * @par Example |
654 | * To asynchronously read data into a streambuf until a newline is encountered: |
655 | * @code boost::asio::streambuf b; |
656 | * ... |
657 | * void handler(const boost::system::error_code& e, std::size_t size) |
658 | * { |
659 | * if (!e) |
660 | * { |
661 | * std::istream is(&b); |
662 | * std::string line; |
663 | * std::getline(is, line); |
664 | * ... |
665 | * } |
666 | * } |
667 | * ... |
668 | * boost::asio::async_read_until(s, b, "\r\n", handler); @endcode |
669 | * After the @c async_read_until operation completes successfully, the buffer |
670 | * @c b contains the delimiter: |
671 | * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode |
672 | * The call to @c std::getline then extracts the data up to and including the |
673 | * delimiter, so that the string @c line contains: |
674 | * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode |
675 | * The remaining data is left in the buffer @c b as follows: |
676 | * @code { 'd', 'e', ... } @endcode |
677 | * This data may be the start of a new line, to be extracted by a subsequent |
678 | * @c async_read_until operation. |
679 | */ |
680 | template <typename AsyncReadStream, typename Allocator, typename ReadHandler> |
681 | BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, |
682 | void (boost::system::error_code, std::size_t)) |
683 | async_read_until(AsyncReadStream& s, |
684 | boost::asio::basic_streambuf<Allocator>& b, const std::string& delim, |
685 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler); |
686 | |
687 | #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \ |
688 | || defined(GENERATING_DOCUMENTATION) |
689 | |
690 | /// Start an asynchronous operation to read data into a streambuf until some |
691 | /// part of its data matches a regular expression. |
692 | /** |
693 | * This function is used to asynchronously read data into the specified |
694 | * streambuf until the streambuf's get area contains some data that matches a |
695 | * regular expression. The function call always returns immediately. The |
696 | * asynchronous operation will continue until one of the following conditions |
697 | * is true: |
698 | * |
699 | * @li A substring of the streambuf's get area matches the regular expression. |
700 | * |
701 | * @li An error occurred. |
702 | * |
703 | * This operation is implemented in terms of zero or more calls to the stream's |
704 | * async_read_some function, and is known as a <em>composed operation</em>. If |
705 | * the streambuf's get area already contains data that matches the regular |
706 | * expression, this asynchronous operation completes immediately. The program |
707 | * must ensure that the stream performs no other read operations (such as |
708 | * async_read, async_read_until, the stream's async_read_some function, or any |
709 | * other composed operations that perform reads) until this operation |
710 | * completes. |
711 | * |
712 | * @param s The stream from which the data is to be read. The type must support |
713 | * the AsyncReadStream concept. |
714 | * |
715 | * @param b A streambuf object into which the data will be read. Ownership of |
716 | * the streambuf is retained by the caller, which must guarantee that it remains |
717 | * valid until the handler is called. |
718 | * |
719 | * @param expr The regular expression. |
720 | * |
721 | * @param handler The handler to be called when the read operation completes. |
722 | * Copies will be made of the handler as required. The function signature of the |
723 | * handler must be: |
724 | * @code void handler( |
725 | * // Result of operation. |
726 | * const boost::system::error_code& error, |
727 | * |
728 | * // The number of bytes in the streambuf's get |
729 | * // area up to and including the substring |
730 | * // that matches the regular. expression. |
731 | * // 0 if an error occurred. |
732 | * std::size_t bytes_transferred |
733 | * ); @endcode |
734 | * Regardless of whether the asynchronous operation completes immediately or |
735 | * not, the handler will not be invoked from within this function. Invocation of |
736 | * the handler will be performed in a manner equivalent to using |
737 | * boost::asio::io_service::post(). |
738 | * |
739 | * @note After a successful async_read_until operation, the streambuf may |
740 | * contain additional data beyond that which matched the regular expression. An |
741 | * application will typically leave that data in the streambuf for a subsequent |
742 | * async_read_until operation to examine. |
743 | * |
744 | * @par Example |
745 | * To asynchronously read data into a streambuf until a CR-LF sequence is |
746 | * encountered: |
747 | * @code boost::asio::streambuf b; |
748 | * ... |
749 | * void handler(const boost::system::error_code& e, std::size_t size) |
750 | * { |
751 | * if (!e) |
752 | * { |
753 | * std::istream is(&b); |
754 | * std::string line; |
755 | * std::getline(is, line); |
756 | * ... |
757 | * } |
758 | * } |
759 | * ... |
760 | * boost::asio::async_read_until(s, b, boost::regex("\r\n"), handler); @endcode |
761 | * After the @c async_read_until operation completes successfully, the buffer |
762 | * @c b contains the data which matched the regular expression: |
763 | * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode |
764 | * The call to @c std::getline then extracts the data up to and including the |
765 | * match, so that the string @c line contains: |
766 | * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode |
767 | * The remaining data is left in the buffer @c b as follows: |
768 | * @code { 'd', 'e', ... } @endcode |
769 | * This data may be the start of a new line, to be extracted by a subsequent |
770 | * @c async_read_until operation. |
771 | */ |
772 | template <typename AsyncReadStream, typename Allocator, typename ReadHandler> |
773 | BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, |
774 | void (boost::system::error_code, std::size_t)) |
775 | async_read_until(AsyncReadStream& s, |
776 | boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr, |
777 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler); |
778 | |
779 | #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX) |
780 | // || defined(GENERATING_DOCUMENTATION) |
781 | |
782 | /// Start an asynchronous operation to read data into a streambuf until a |
783 | /// function object indicates a match. |
784 | /** |
785 | * This function is used to asynchronously read data into the specified |
786 | * streambuf until a user-defined match condition function object, when applied |
787 | * to the data contained in the streambuf, indicates a successful match. The |
788 | * function call always returns immediately. The asynchronous operation will |
789 | * continue until one of the following conditions is true: |
790 | * |
791 | * @li The match condition function object returns a std::pair where the second |
792 | * element evaluates to true. |
793 | * |
794 | * @li An error occurred. |
795 | * |
796 | * This operation is implemented in terms of zero or more calls to the stream's |
797 | * async_read_some function, and is known as a <em>composed operation</em>. If |
798 | * the match condition function object already indicates a match, this |
799 | * asynchronous operation completes immediately. The program must ensure that |
800 | * the stream performs no other read operations (such as async_read, |
801 | * async_read_until, the stream's async_read_some function, or any other |
802 | * composed operations that perform reads) until this operation completes. |
803 | * |
804 | * @param s The stream from which the data is to be read. The type must support |
805 | * the AsyncReadStream concept. |
806 | * |
807 | * @param b A streambuf object into which the data will be read. |
808 | * |
809 | * @param match_condition The function object to be called to determine whether |
810 | * a match exists. The signature of the function object must be: |
811 | * @code pair<iterator, bool> match_condition(iterator begin, iterator end); |
812 | * @endcode |
813 | * where @c iterator represents the type: |
814 | * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type> |
815 | * @endcode |
816 | * The iterator parameters @c begin and @c end define the range of bytes to be |
817 | * scanned to determine whether there is a match. The @c first member of the |
818 | * return value is an iterator marking one-past-the-end of the bytes that have |
819 | * been consumed by the match function. This iterator is used to calculate the |
820 | * @c begin parameter for any subsequent invocation of the match condition. The |
821 | * @c second member of the return value is true if a match has been found, false |
822 | * otherwise. |
823 | * |
824 | * @param handler The handler to be called when the read operation completes. |
825 | * Copies will be made of the handler as required. The function signature of the |
826 | * handler must be: |
827 | * @code void handler( |
828 | * // Result of operation. |
829 | * const boost::system::error_code& error, |
830 | * |
831 | * // The number of bytes in the streambuf's get |
832 | * // area that have been fully consumed by the |
833 | * // match function. O if an error occurred. |
834 | * std::size_t bytes_transferred |
835 | * ); @endcode |
836 | * Regardless of whether the asynchronous operation completes immediately or |
837 | * not, the handler will not be invoked from within this function. Invocation of |
838 | * the handler will be performed in a manner equivalent to using |
839 | * boost::asio::io_service::post(). |
840 | * |
841 | * @note After a successful async_read_until operation, the streambuf may |
842 | * contain additional data beyond that which matched the function object. An |
843 | * application will typically leave that data in the streambuf for a subsequent |
844 | * async_read_until operation to examine. |
845 | * |
846 | * @note The default implementation of the @c is_match_condition type trait |
847 | * evaluates to true for function pointers and function objects with a |
848 | * @c result_type typedef. It must be specialised for other user-defined |
849 | * function objects. |
850 | * |
851 | * @par Examples |
852 | * To asynchronously read data into a streambuf until whitespace is encountered: |
853 | * @code typedef boost::asio::buffers_iterator< |
854 | * boost::asio::streambuf::const_buffers_type> iterator; |
855 | * |
856 | * std::pair<iterator, bool> |
857 | * match_whitespace(iterator begin, iterator end) |
858 | * { |
859 | * iterator i = begin; |
860 | * while (i != end) |
861 | * if (std::isspace(*i++)) |
862 | * return std::make_pair(i, true); |
863 | * return std::make_pair(i, false); |
864 | * } |
865 | * ... |
866 | * void handler(const boost::system::error_code& e, std::size_t size); |
867 | * ... |
868 | * boost::asio::streambuf b; |
869 | * boost::asio::async_read_until(s, b, match_whitespace, handler); |
870 | * @endcode |
871 | * |
872 | * To asynchronously read data into a streambuf until a matching character is |
873 | * found: |
874 | * @code class match_char |
875 | * { |
876 | * public: |
877 | * explicit match_char(char c) : c_(c) {} |
878 | * |
879 | * template <typename Iterator> |
880 | * std::pair<Iterator, bool> operator()( |
881 | * Iterator begin, Iterator end) const |
882 | * { |
883 | * Iterator i = begin; |
884 | * while (i != end) |
885 | * if (c_ == *i++) |
886 | * return std::make_pair(i, true); |
887 | * return std::make_pair(i, false); |
888 | * } |
889 | * |
890 | * private: |
891 | * char c_; |
892 | * }; |
893 | * |
894 | * namespace asio { |
895 | * template <> struct is_match_condition<match_char> |
896 | * : public boost::true_type {}; |
897 | * } // namespace asio |
898 | * ... |
899 | * void handler(const boost::system::error_code& e, std::size_t size); |
900 | * ... |
901 | * boost::asio::streambuf b; |
902 | * boost::asio::async_read_until(s, b, match_char('a'), handler); |
903 | * @endcode |
904 | */ |
905 | template <typename AsyncReadStream, typename Allocator, |
906 | typename MatchCondition, typename ReadHandler> |
907 | BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, |
908 | void (boost::system::error_code, std::size_t)) |
909 | async_read_until(AsyncReadStream& s, |
910 | boost::asio::basic_streambuf<Allocator>& b, |
911 | MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadHandler) handler, |
912 | typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0); |
913 | |
914 | /*@}*/ |
915 | |
916 | } // namespace asio |
917 | } // namespace boost |
918 | |
919 | #include <boost/asio/detail/pop_options.hpp> |
920 | |
921 | #include <boost/asio/impl/read_until.hpp> |
922 | |
923 | #endif // !defined(BOOST_ASIO_NO_IOSTREAM) |
924 | |
925 | #endif // BOOST_ASIO_READ_UNTIL_HPP |
926 | |