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
32namespace boost {
33namespace asio {
34
35namespace 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.
51template <typename T>
52struct 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 */
123template <typename SyncReadStream, typename Allocator>
124std::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 */
157template <typename SyncReadStream, typename Allocator>
158std::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 */
210template <typename SyncReadStream, typename Allocator>
211std::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 */
244template <typename SyncReadStream, typename Allocator>
245std::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 */
302template <typename SyncReadStream, typename Allocator>
303std::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 */
339template <typename SyncReadStream, typename Allocator>
340std::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 */
446template <typename SyncReadStream, typename Allocator, typename MatchCondition>
447std::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 */
501template <typename SyncReadStream, typename Allocator, typename MatchCondition>
502std::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 */
595template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
596BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
597 void (boost::system::error_code, std::size_t))
598async_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 */
680template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
681BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
682 void (boost::system::error_code, std::size_t))
683async_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 */
772template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
773BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
774 void (boost::system::error_code, std::size_t))
775async_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 */
905template <typename AsyncReadStream, typename Allocator,
906 typename MatchCondition, typename ReadHandler>
907BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
908 void (boost::system::error_code, std::size_t))
909async_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