/Src/Dependencies/Boost/boost/asio/read_until.hpp

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