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