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

http://hadesmem.googlecode.com/ · C++ Header · 906 lines · 97 code · 31 blank · 778 comment · 3 complexity · 08ce55436c132bbabe976ea716986de7 MD5 · raw file

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