boost/asio/read_until.hpp

   1 //
   2 // read_until.hpp
   3 // ~~~~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2014 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