Chris@16: // Chris@16: // read_until.hpp Chris@16: // ~~~~~~~~~~~~~~ Chris@16: // Chris@101: // Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com) Chris@16: // Chris@16: // Distributed under the Boost Software License, Version 1.0. (See accompanying Chris@16: // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Chris@16: // Chris@16: Chris@16: #ifndef BOOST_ASIO_READ_UNTIL_HPP Chris@16: #define BOOST_ASIO_READ_UNTIL_HPP Chris@16: Chris@16: #if defined(_MSC_VER) && (_MSC_VER >= 1200) Chris@16: # pragma once Chris@16: #endif // defined(_MSC_VER) && (_MSC_VER >= 1200) Chris@16: Chris@16: #include Chris@16: Chris@16: #if !defined(BOOST_ASIO_NO_IOSTREAM) Chris@16: Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: Chris@16: #include Chris@16: Chris@16: namespace boost { Chris@16: namespace asio { Chris@16: Chris@16: namespace detail Chris@16: { Chris@16: char (&has_result_type_helper(...))[2]; Chris@16: Chris@16: template Chris@16: char has_result_type_helper(T*, typename T::result_type* = 0); Chris@16: Chris@16: template Chris@16: struct has_result_type Chris@16: { Chris@16: enum { value = (sizeof((has_result_type_helper)((T*)(0))) == 1) }; Chris@16: }; Chris@16: } // namespace detail Chris@16: Chris@16: /// Type trait used to determine whether a type can be used as a match condition Chris@16: /// function with read_until and async_read_until. Chris@16: template Chris@16: struct is_match_condition Chris@16: { Chris@16: #if defined(GENERATING_DOCUMENTATION) Chris@16: /// The value member is true if the type may be used as a match condition. Chris@16: static const bool value; Chris@16: #else Chris@16: enum Chris@16: { Chris@16: value = boost::asio::is_function< Chris@16: typename boost::asio::remove_pointer::type>::value Chris@16: || detail::has_result_type::value Chris@16: }; Chris@16: #endif Chris@16: }; Chris@16: Chris@16: /** Chris@16: * @defgroup read_until boost::asio::read_until Chris@16: * Chris@16: * @brief Read data into a streambuf until it contains a delimiter, matches a Chris@16: * regular expression, or a function object indicates a match. Chris@16: */ Chris@16: /*@{*/ Chris@16: Chris@16: /// Read data into a streambuf until it contains a specified delimiter. Chris@16: /** Chris@16: * This function is used to read data into the specified streambuf until the Chris@16: * streambuf's get area contains the specified delimiter. The call will block Chris@16: * until one of the following conditions is true: Chris@16: * Chris@16: * @li The get area of the streambuf contains the specified delimiter. Chris@16: * Chris@16: * @li An error occurred. Chris@16: * Chris@16: * This operation is implemented in terms of zero or more calls to the stream's Chris@16: * read_some function. If the streambuf's get area already contains the Chris@16: * delimiter, the function returns immediately. Chris@16: * Chris@16: * @param s The stream from which the data is to be read. The type must support Chris@16: * the SyncReadStream concept. Chris@16: * Chris@16: * @param b A streambuf object into which the data will be read. Chris@16: * Chris@16: * @param delim The delimiter character. Chris@16: * Chris@16: * @returns The number of bytes in the streambuf's get area up to and including Chris@16: * the delimiter. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @note After a successful read_until operation, the streambuf may contain Chris@16: * additional data beyond the delimiter. An application will typically leave Chris@16: * that data in the streambuf for a subsequent read_until operation to examine. Chris@16: * Chris@16: * @par Example Chris@16: * To read data into a streambuf until a newline is encountered: Chris@16: * @code boost::asio::streambuf b; Chris@16: * boost::asio::read_until(s, b, '\n'); Chris@16: * std::istream is(&b); Chris@16: * std::string line; Chris@16: * std::getline(is, line); @endcode Chris@16: * After the @c read_until operation completes successfully, the buffer @c b Chris@16: * contains the delimiter: Chris@16: * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode Chris@16: * The call to @c std::getline then extracts the data up to and including the Chris@16: * delimiter, so that the string @c line contains: Chris@16: * @code { 'a', 'b', ..., 'c', '\n' } @endcode Chris@16: * The remaining data is left in the buffer @c b as follows: Chris@16: * @code { 'd', 'e', ... } @endcode Chris@16: * This data may be the start of a new line, to be extracted by a subsequent Chris@16: * @c read_until operation. Chris@16: */ Chris@16: template Chris@16: std::size_t read_until(SyncReadStream& s, Chris@16: boost::asio::basic_streambuf& b, char delim); Chris@16: Chris@16: /// Read data into a streambuf until it contains a specified delimiter. Chris@16: /** Chris@16: * This function is used to read data into the specified streambuf until the Chris@16: * streambuf's get area contains the specified delimiter. The call will block Chris@16: * until one of the following conditions is true: Chris@16: * Chris@16: * @li The get area of the streambuf contains the specified delimiter. Chris@16: * Chris@16: * @li An error occurred. Chris@16: * Chris@16: * This operation is implemented in terms of zero or more calls to the stream's Chris@16: * read_some function. If the streambuf's get area already contains the Chris@16: * delimiter, the function returns immediately. Chris@16: * Chris@16: * @param s The stream from which the data is to be read. The type must support Chris@16: * the SyncReadStream concept. Chris@16: * Chris@16: * @param b A streambuf object into which the data will be read. Chris@16: * Chris@16: * @param delim The delimiter character. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @returns The number of bytes in the streambuf's get area up to and including Chris@16: * the delimiter. Returns 0 if an error occurred. Chris@16: * Chris@16: * @note After a successful read_until operation, the streambuf may contain Chris@16: * additional data beyond the delimiter. An application will typically leave Chris@16: * that data in the streambuf for a subsequent read_until operation to examine. Chris@16: */ Chris@16: template Chris@16: std::size_t read_until(SyncReadStream& s, Chris@16: boost::asio::basic_streambuf& b, char delim, Chris@16: boost::system::error_code& ec); Chris@16: Chris@16: /// Read data into a streambuf until it contains a specified delimiter. Chris@16: /** Chris@16: * This function is used to read data into the specified streambuf until the Chris@16: * streambuf's get area contains the specified delimiter. The call will block Chris@16: * until one of the following conditions is true: Chris@16: * Chris@16: * @li The get area of the streambuf contains the specified delimiter. Chris@16: * Chris@16: * @li An error occurred. Chris@16: * Chris@16: * This operation is implemented in terms of zero or more calls to the stream's Chris@16: * read_some function. If the streambuf's get area already contains the Chris@16: * delimiter, the function returns immediately. Chris@16: * Chris@16: * @param s The stream from which the data is to be read. The type must support Chris@16: * the SyncReadStream concept. Chris@16: * Chris@16: * @param b A streambuf object into which the data will be read. Chris@16: * Chris@16: * @param delim The delimiter string. Chris@16: * Chris@16: * @returns The number of bytes in the streambuf's get area up to and including Chris@16: * the delimiter. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @note After a successful read_until operation, the streambuf may contain Chris@16: * additional data beyond the delimiter. An application will typically leave Chris@16: * that data in the streambuf for a subsequent read_until operation to examine. Chris@16: * Chris@16: * @par Example Chris@16: * To read data into a streambuf until a newline is encountered: Chris@16: * @code boost::asio::streambuf b; Chris@16: * boost::asio::read_until(s, b, "\r\n"); Chris@16: * std::istream is(&b); Chris@16: * std::string line; Chris@16: * std::getline(is, line); @endcode Chris@16: * After the @c read_until operation completes successfully, the buffer @c b Chris@16: * contains the delimiter: Chris@16: * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode Chris@16: * The call to @c std::getline then extracts the data up to and including the Chris@16: * delimiter, so that the string @c line contains: Chris@16: * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode Chris@16: * The remaining data is left in the buffer @c b as follows: Chris@16: * @code { 'd', 'e', ... } @endcode Chris@16: * This data may be the start of a new line, to be extracted by a subsequent Chris@16: * @c read_until operation. Chris@16: */ Chris@16: template Chris@16: std::size_t read_until(SyncReadStream& s, Chris@16: boost::asio::basic_streambuf& b, const std::string& delim); Chris@16: Chris@16: /// Read data into a streambuf until it contains a specified delimiter. Chris@16: /** Chris@16: * This function is used to read data into the specified streambuf until the Chris@16: * streambuf's get area contains the specified delimiter. The call will block Chris@16: * until one of the following conditions is true: Chris@16: * Chris@16: * @li The get area of the streambuf contains the specified delimiter. Chris@16: * Chris@16: * @li An error occurred. Chris@16: * Chris@16: * This operation is implemented in terms of zero or more calls to the stream's Chris@16: * read_some function. If the streambuf's get area already contains the Chris@16: * delimiter, the function returns immediately. Chris@16: * Chris@16: * @param s The stream from which the data is to be read. The type must support Chris@16: * the SyncReadStream concept. Chris@16: * Chris@16: * @param b A streambuf object into which the data will be read. Chris@16: * Chris@16: * @param delim The delimiter string. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @returns The number of bytes in the streambuf's get area up to and including Chris@16: * the delimiter. Returns 0 if an error occurred. Chris@16: * Chris@16: * @note After a successful read_until operation, the streambuf may contain Chris@16: * additional data beyond the delimiter. An application will typically leave Chris@16: * that data in the streambuf for a subsequent read_until operation to examine. Chris@16: */ Chris@16: template Chris@16: std::size_t read_until(SyncReadStream& s, Chris@16: boost::asio::basic_streambuf& b, const std::string& delim, Chris@16: boost::system::error_code& ec); Chris@16: Chris@16: #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \ Chris@16: || defined(GENERATING_DOCUMENTATION) Chris@16: Chris@16: /// Read data into a streambuf until some part of the data it contains matches Chris@16: /// a regular expression. Chris@16: /** Chris@16: * This function is used to read data into the specified streambuf until the Chris@16: * streambuf's get area contains some data that matches a regular expression. Chris@16: * The call will block until one of the following conditions is true: Chris@16: * Chris@16: * @li A substring of the streambuf's get area matches the regular expression. Chris@16: * Chris@16: * @li An error occurred. Chris@16: * Chris@16: * This operation is implemented in terms of zero or more calls to the stream's Chris@16: * read_some function. If the streambuf's get area already contains data that Chris@16: * matches the regular expression, the function returns immediately. Chris@16: * Chris@16: * @param s The stream from which the data is to be read. The type must support Chris@16: * the SyncReadStream concept. Chris@16: * Chris@16: * @param b A streambuf object into which the data will be read. Chris@16: * Chris@16: * @param expr The regular expression. Chris@16: * Chris@16: * @returns The number of bytes in the streambuf's get area up to and including Chris@16: * the substring that matches the regular expression. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @note After a successful read_until operation, the streambuf may contain Chris@16: * additional data beyond that which matched the regular expression. An Chris@16: * application will typically leave that data in the streambuf for a subsequent Chris@16: * read_until operation to examine. Chris@16: * Chris@16: * @par Example Chris@16: * To read data into a streambuf until a CR-LF sequence is encountered: Chris@16: * @code boost::asio::streambuf b; Chris@16: * boost::asio::read_until(s, b, boost::regex("\r\n")); Chris@16: * std::istream is(&b); Chris@16: * std::string line; Chris@16: * std::getline(is, line); @endcode Chris@16: * After the @c read_until operation completes successfully, the buffer @c b Chris@16: * contains the data which matched the regular expression: Chris@16: * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode Chris@16: * The call to @c std::getline then extracts the data up to and including the Chris@16: * match, so that the string @c line contains: Chris@16: * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode Chris@16: * The remaining data is left in the buffer @c b as follows: Chris@16: * @code { 'd', 'e', ... } @endcode Chris@16: * This data may be the start of a new line, to be extracted by a subsequent Chris@16: * @c read_until operation. Chris@16: */ Chris@16: template Chris@16: std::size_t read_until(SyncReadStream& s, Chris@16: boost::asio::basic_streambuf& b, const boost::regex& expr); Chris@16: Chris@16: /// Read data into a streambuf until some part of the data it contains matches Chris@16: /// a regular expression. Chris@16: /** Chris@16: * This function is used to read data into the specified streambuf until the Chris@16: * streambuf's get area contains some data that matches a regular expression. Chris@16: * The call will block until one of the following conditions is true: Chris@16: * Chris@16: * @li A substring of the streambuf's get area matches the regular expression. Chris@16: * Chris@16: * @li An error occurred. Chris@16: * Chris@16: * This operation is implemented in terms of zero or more calls to the stream's Chris@16: * read_some function. If the streambuf's get area already contains data that Chris@16: * matches the regular expression, the function returns immediately. Chris@16: * Chris@16: * @param s The stream from which the data is to be read. The type must support Chris@16: * the SyncReadStream concept. Chris@16: * Chris@16: * @param b A streambuf object into which the data will be read. Chris@16: * Chris@16: * @param expr The regular expression. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @returns The number of bytes in the streambuf's get area up to and including Chris@16: * the substring that matches the regular expression. Returns 0 if an error Chris@16: * occurred. Chris@16: * Chris@16: * @note After a successful read_until operation, the streambuf may contain Chris@16: * additional data beyond that which matched the regular expression. An Chris@16: * application will typically leave that data in the streambuf for a subsequent Chris@16: * read_until operation to examine. Chris@16: */ Chris@16: template Chris@16: std::size_t read_until(SyncReadStream& s, Chris@16: boost::asio::basic_streambuf& b, const boost::regex& expr, Chris@16: boost::system::error_code& ec); Chris@16: Chris@16: #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX) Chris@16: // || defined(GENERATING_DOCUMENTATION) Chris@16: Chris@16: /// Read data into a streambuf until a function object indicates a match. Chris@16: /** Chris@16: * This function is used to read data into the specified streambuf until a Chris@16: * user-defined match condition function object, when applied to the data Chris@16: * contained in the streambuf, indicates a successful match. The call will Chris@16: * block until one of the following conditions is true: Chris@16: * Chris@16: * @li The match condition function object returns a std::pair where the second Chris@16: * element evaluates to true. Chris@16: * Chris@16: * @li An error occurred. Chris@16: * Chris@16: * This operation is implemented in terms of zero or more calls to the stream's Chris@16: * read_some function. If the match condition function object already indicates Chris@16: * a match, the function returns immediately. Chris@16: * Chris@16: * @param s The stream from which the data is to be read. The type must support Chris@16: * the SyncReadStream concept. Chris@16: * Chris@16: * @param b A streambuf object into which the data will be read. Chris@16: * Chris@16: * @param match_condition The function object to be called to determine whether Chris@16: * a match exists. The signature of the function object must be: Chris@16: * @code pair match_condition(iterator begin, iterator end); Chris@16: * @endcode Chris@16: * where @c iterator represents the type: Chris@16: * @code buffers_iterator::const_buffers_type> Chris@16: * @endcode Chris@16: * The iterator parameters @c begin and @c end define the range of bytes to be Chris@16: * scanned to determine whether there is a match. The @c first member of the Chris@16: * return value is an iterator marking one-past-the-end of the bytes that have Chris@16: * been consumed by the match function. This iterator is used to calculate the Chris@16: * @c begin parameter for any subsequent invocation of the match condition. The Chris@16: * @c second member of the return value is true if a match has been found, false Chris@16: * otherwise. Chris@16: * Chris@16: * @returns The number of bytes in the streambuf's get area that have been fully Chris@16: * consumed by the match function. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @note After a successful read_until operation, the streambuf may contain Chris@16: * additional data beyond that which matched the function object. An application Chris@16: * will typically leave that data in the streambuf for a subsequent Chris@16: * Chris@16: * @note The default implementation of the @c is_match_condition type trait Chris@16: * evaluates to true for function pointers and function objects with a Chris@16: * @c result_type typedef. It must be specialised for other user-defined Chris@16: * function objects. Chris@16: * Chris@16: * @par Examples Chris@16: * To read data into a streambuf until whitespace is encountered: Chris@16: * @code typedef boost::asio::buffers_iterator< Chris@16: * boost::asio::streambuf::const_buffers_type> iterator; Chris@16: * Chris@16: * std::pair Chris@16: * match_whitespace(iterator begin, iterator end) Chris@16: * { Chris@16: * iterator i = begin; Chris@16: * while (i != end) Chris@16: * if (std::isspace(*i++)) Chris@16: * return std::make_pair(i, true); Chris@16: * return std::make_pair(i, false); Chris@16: * } Chris@16: * ... Chris@16: * boost::asio::streambuf b; Chris@16: * boost::asio::read_until(s, b, match_whitespace); Chris@16: * @endcode Chris@16: * Chris@16: * To read data into a streambuf until a matching character is found: Chris@16: * @code class match_char Chris@16: * { Chris@16: * public: Chris@16: * explicit match_char(char c) : c_(c) {} Chris@16: * Chris@16: * template Chris@16: * std::pair operator()( Chris@16: * Iterator begin, Iterator end) const Chris@16: * { Chris@16: * Iterator i = begin; Chris@16: * while (i != end) Chris@16: * if (c_ == *i++) Chris@16: * return std::make_pair(i, true); Chris@16: * return std::make_pair(i, false); Chris@16: * } Chris@16: * Chris@16: * private: Chris@16: * char c_; Chris@16: * }; Chris@16: * Chris@16: * namespace asio { Chris@16: * template <> struct is_match_condition Chris@16: * : public boost::true_type {}; Chris@16: * } // namespace asio Chris@16: * ... Chris@16: * boost::asio::streambuf b; Chris@16: * boost::asio::read_until(s, b, match_char('a')); Chris@16: * @endcode Chris@16: */ Chris@16: template Chris@16: std::size_t read_until(SyncReadStream& s, Chris@16: boost::asio::basic_streambuf& b, MatchCondition match_condition, Chris@16: typename enable_if::value>::type* = 0); Chris@16: Chris@16: /// Read data into a streambuf until a function object indicates a match. Chris@16: /** Chris@16: * This function is used to read data into the specified streambuf until a Chris@16: * user-defined match condition function object, when applied to the data Chris@16: * contained in the streambuf, indicates a successful match. The call will Chris@16: * block until one of the following conditions is true: Chris@16: * Chris@16: * @li The match condition function object returns a std::pair where the second Chris@16: * element evaluates to true. Chris@16: * Chris@16: * @li An error occurred. Chris@16: * Chris@16: * This operation is implemented in terms of zero or more calls to the stream's Chris@16: * read_some function. If the match condition function object already indicates Chris@16: * a match, the function returns immediately. Chris@16: * Chris@16: * @param s The stream from which the data is to be read. The type must support Chris@16: * the SyncReadStream concept. Chris@16: * Chris@16: * @param b A streambuf object into which the data will be read. Chris@16: * Chris@16: * @param match_condition The function object to be called to determine whether Chris@16: * a match exists. The signature of the function object must be: Chris@16: * @code pair match_condition(iterator begin, iterator end); Chris@16: * @endcode Chris@16: * where @c iterator represents the type: Chris@16: * @code buffers_iterator::const_buffers_type> Chris@16: * @endcode Chris@16: * The iterator parameters @c begin and @c end define the range of bytes to be Chris@16: * scanned to determine whether there is a match. The @c first member of the Chris@16: * return value is an iterator marking one-past-the-end of the bytes that have Chris@16: * been consumed by the match function. This iterator is used to calculate the Chris@16: * @c begin parameter for any subsequent invocation of the match condition. The Chris@16: * @c second member of the return value is true if a match has been found, false Chris@16: * otherwise. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @returns The number of bytes in the streambuf's get area that have been fully Chris@16: * consumed by the match function. Returns 0 if an error occurred. Chris@16: * Chris@16: * @note After a successful read_until operation, the streambuf may contain Chris@16: * additional data beyond that which matched the function object. An application Chris@16: * will typically leave that data in the streambuf for a subsequent Chris@16: * Chris@16: * @note The default implementation of the @c is_match_condition type trait Chris@16: * evaluates to true for function pointers and function objects with a Chris@16: * @c result_type typedef. It must be specialised for other user-defined Chris@16: * function objects. Chris@16: */ Chris@16: template Chris@16: std::size_t read_until(SyncReadStream& s, Chris@16: boost::asio::basic_streambuf& b, Chris@16: MatchCondition match_condition, boost::system::error_code& ec, Chris@16: typename enable_if::value>::type* = 0); Chris@16: Chris@16: /*@}*/ Chris@16: /** Chris@16: * @defgroup async_read_until boost::asio::async_read_until Chris@16: * Chris@16: * @brief Start an asynchronous operation to read data into a streambuf until it Chris@16: * contains a delimiter, matches a regular expression, or a function object Chris@16: * indicates a match. Chris@16: */ Chris@16: /*@{*/ Chris@16: Chris@16: /// Start an asynchronous operation to read data into a streambuf until it Chris@16: /// contains a specified delimiter. Chris@16: /** Chris@16: * This function is used to asynchronously read data into the specified Chris@16: * streambuf until the streambuf's get area contains the specified delimiter. Chris@16: * The function call always returns immediately. The asynchronous operation Chris@16: * will continue until one of the following conditions is true: Chris@16: * Chris@16: * @li The get area of the streambuf contains the specified delimiter. Chris@16: * Chris@16: * @li An error occurred. Chris@16: * Chris@16: * This operation is implemented in terms of zero or more calls to the stream's Chris@16: * async_read_some function, and is known as a composed operation. If Chris@16: * the streambuf's get area already contains the delimiter, this asynchronous Chris@16: * operation completes immediately. The program must ensure that the stream Chris@16: * performs no other read operations (such as async_read, async_read_until, the Chris@16: * stream's async_read_some function, or any other composed operations that Chris@16: * perform reads) until this operation completes. Chris@16: * Chris@16: * @param s The stream from which the data is to be read. The type must support Chris@16: * the AsyncReadStream concept. Chris@16: * Chris@16: * @param b A streambuf object into which the data will be read. Ownership of Chris@16: * the streambuf is retained by the caller, which must guarantee that it remains Chris@16: * valid until the handler is called. Chris@16: * Chris@16: * @param delim The delimiter character. Chris@16: * Chris@16: * @param handler The handler to be called when the read operation completes. Chris@16: * Copies will be made of the handler as required. The function signature of the Chris@16: * handler must be: Chris@16: * @code void handler( Chris@16: * // Result of operation. Chris@16: * const boost::system::error_code& error, Chris@16: * Chris@16: * // The number of bytes in the streambuf's get Chris@16: * // area up to and including the delimiter. Chris@16: * // 0 if an error occurred. Chris@16: * std::size_t bytes_transferred Chris@16: * ); @endcode Chris@16: * Regardless of whether the asynchronous operation completes immediately or Chris@16: * not, the handler will not be invoked from within this function. Invocation of Chris@16: * the handler will be performed in a manner equivalent to using Chris@16: * boost::asio::io_service::post(). Chris@16: * Chris@16: * @note After a successful async_read_until operation, the streambuf may Chris@16: * contain additional data beyond the delimiter. An application will typically Chris@16: * leave that data in the streambuf for a subsequent async_read_until operation Chris@16: * to examine. Chris@16: * Chris@16: * @par Example Chris@16: * To asynchronously read data into a streambuf until a newline is encountered: Chris@16: * @code boost::asio::streambuf b; Chris@16: * ... Chris@16: * void handler(const boost::system::error_code& e, std::size_t size) Chris@16: * { Chris@16: * if (!e) Chris@16: * { Chris@16: * std::istream is(&b); Chris@16: * std::string line; Chris@16: * std::getline(is, line); Chris@16: * ... Chris@16: * } Chris@16: * } Chris@16: * ... Chris@16: * boost::asio::async_read_until(s, b, '\n', handler); @endcode Chris@16: * After the @c async_read_until operation completes successfully, the buffer Chris@16: * @c b contains the delimiter: Chris@16: * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode Chris@16: * The call to @c std::getline then extracts the data up to and including the Chris@16: * delimiter, so that the string @c line contains: Chris@16: * @code { 'a', 'b', ..., 'c', '\n' } @endcode Chris@16: * The remaining data is left in the buffer @c b as follows: Chris@16: * @code { 'd', 'e', ... } @endcode Chris@16: * This data may be the start of a new line, to be extracted by a subsequent Chris@16: * @c async_read_until operation. Chris@16: */ Chris@16: template Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, Chris@16: void (boost::system::error_code, std::size_t)) Chris@16: async_read_until(AsyncReadStream& s, Chris@16: boost::asio::basic_streambuf& b, Chris@16: char delim, BOOST_ASIO_MOVE_ARG(ReadHandler) handler); Chris@16: Chris@16: /// Start an asynchronous operation to read data into a streambuf until it Chris@16: /// contains a specified delimiter. Chris@16: /** Chris@16: * This function is used to asynchronously read data into the specified Chris@16: * streambuf until the streambuf's get area contains the specified delimiter. Chris@16: * The function call always returns immediately. The asynchronous operation Chris@16: * will continue until one of the following conditions is true: Chris@16: * Chris@16: * @li The get area of the streambuf contains the specified delimiter. Chris@16: * Chris@16: * @li An error occurred. Chris@16: * Chris@16: * This operation is implemented in terms of zero or more calls to the stream's Chris@16: * async_read_some function, and is known as a composed operation. If Chris@16: * the streambuf's get area already contains the delimiter, this asynchronous Chris@16: * operation completes immediately. The program must ensure that the stream Chris@16: * performs no other read operations (such as async_read, async_read_until, the Chris@16: * stream's async_read_some function, or any other composed operations that Chris@16: * perform reads) until this operation completes. Chris@16: * Chris@16: * @param s The stream from which the data is to be read. The type must support Chris@16: * the AsyncReadStream concept. Chris@16: * Chris@16: * @param b A streambuf object into which the data will be read. Ownership of Chris@16: * the streambuf is retained by the caller, which must guarantee that it remains Chris@16: * valid until the handler is called. Chris@16: * Chris@16: * @param delim The delimiter string. Chris@16: * Chris@16: * @param handler The handler to be called when the read operation completes. Chris@16: * Copies will be made of the handler as required. The function signature of the Chris@16: * handler must be: Chris@16: * @code void handler( Chris@16: * // Result of operation. Chris@16: * const boost::system::error_code& error, Chris@16: * Chris@16: * // The number of bytes in the streambuf's get Chris@16: * // area up to and including the delimiter. Chris@16: * // 0 if an error occurred. Chris@16: * std::size_t bytes_transferred Chris@16: * ); @endcode Chris@16: * Regardless of whether the asynchronous operation completes immediately or Chris@16: * not, the handler will not be invoked from within this function. Invocation of Chris@16: * the handler will be performed in a manner equivalent to using Chris@16: * boost::asio::io_service::post(). Chris@16: * Chris@16: * @note After a successful async_read_until operation, the streambuf may Chris@16: * contain additional data beyond the delimiter. An application will typically Chris@16: * leave that data in the streambuf for a subsequent async_read_until operation Chris@16: * to examine. Chris@16: * Chris@16: * @par Example Chris@16: * To asynchronously read data into a streambuf until a newline is encountered: Chris@16: * @code boost::asio::streambuf b; Chris@16: * ... Chris@16: * void handler(const boost::system::error_code& e, std::size_t size) Chris@16: * { Chris@16: * if (!e) Chris@16: * { Chris@16: * std::istream is(&b); Chris@16: * std::string line; Chris@16: * std::getline(is, line); Chris@16: * ... Chris@16: * } Chris@16: * } Chris@16: * ... Chris@16: * boost::asio::async_read_until(s, b, "\r\n", handler); @endcode Chris@16: * After the @c async_read_until operation completes successfully, the buffer Chris@16: * @c b contains the delimiter: Chris@16: * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode Chris@16: * The call to @c std::getline then extracts the data up to and including the Chris@16: * delimiter, so that the string @c line contains: Chris@16: * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode Chris@16: * The remaining data is left in the buffer @c b as follows: Chris@16: * @code { 'd', 'e', ... } @endcode Chris@16: * This data may be the start of a new line, to be extracted by a subsequent Chris@16: * @c async_read_until operation. Chris@16: */ Chris@16: template Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, Chris@16: void (boost::system::error_code, std::size_t)) Chris@16: async_read_until(AsyncReadStream& s, Chris@16: boost::asio::basic_streambuf& b, const std::string& delim, Chris@16: BOOST_ASIO_MOVE_ARG(ReadHandler) handler); Chris@16: Chris@16: #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \ Chris@16: || defined(GENERATING_DOCUMENTATION) Chris@16: Chris@16: /// Start an asynchronous operation to read data into a streambuf until some Chris@16: /// part of its data matches a regular expression. Chris@16: /** Chris@16: * This function is used to asynchronously read data into the specified Chris@16: * streambuf until the streambuf's get area contains some data that matches a Chris@16: * regular expression. The function call always returns immediately. The Chris@16: * asynchronous operation will continue until one of the following conditions Chris@16: * is true: Chris@16: * Chris@16: * @li A substring of the streambuf's get area matches the regular expression. Chris@16: * Chris@16: * @li An error occurred. Chris@16: * Chris@16: * This operation is implemented in terms of zero or more calls to the stream's Chris@16: * async_read_some function, and is known as a composed operation. If Chris@16: * the streambuf's get area already contains data that matches the regular Chris@16: * expression, this asynchronous operation completes immediately. The program Chris@16: * must ensure that the stream performs no other read operations (such as Chris@16: * async_read, async_read_until, the stream's async_read_some function, or any Chris@16: * other composed operations that perform reads) until this operation Chris@16: * completes. Chris@16: * Chris@16: * @param s The stream from which the data is to be read. The type must support Chris@16: * the AsyncReadStream concept. Chris@16: * Chris@16: * @param b A streambuf object into which the data will be read. Ownership of Chris@16: * the streambuf is retained by the caller, which must guarantee that it remains Chris@16: * valid until the handler is called. Chris@16: * Chris@16: * @param expr The regular expression. Chris@16: * Chris@16: * @param handler The handler to be called when the read operation completes. Chris@16: * Copies will be made of the handler as required. The function signature of the Chris@16: * handler must be: Chris@16: * @code void handler( Chris@16: * // Result of operation. Chris@16: * const boost::system::error_code& error, Chris@16: * Chris@16: * // The number of bytes in the streambuf's get Chris@16: * // area up to and including the substring Chris@16: * // that matches the regular. expression. Chris@16: * // 0 if an error occurred. Chris@16: * std::size_t bytes_transferred Chris@16: * ); @endcode Chris@16: * Regardless of whether the asynchronous operation completes immediately or Chris@16: * not, the handler will not be invoked from within this function. Invocation of Chris@16: * the handler will be performed in a manner equivalent to using Chris@16: * boost::asio::io_service::post(). Chris@16: * Chris@16: * @note After a successful async_read_until operation, the streambuf may Chris@16: * contain additional data beyond that which matched the regular expression. An Chris@16: * application will typically leave that data in the streambuf for a subsequent Chris@16: * async_read_until operation to examine. Chris@16: * Chris@16: * @par Example Chris@16: * To asynchronously read data into a streambuf until a CR-LF sequence is Chris@16: * encountered: Chris@16: * @code boost::asio::streambuf b; Chris@16: * ... Chris@16: * void handler(const boost::system::error_code& e, std::size_t size) Chris@16: * { Chris@16: * if (!e) Chris@16: * { Chris@16: * std::istream is(&b); Chris@16: * std::string line; Chris@16: * std::getline(is, line); Chris@16: * ... Chris@16: * } Chris@16: * } Chris@16: * ... Chris@16: * boost::asio::async_read_until(s, b, boost::regex("\r\n"), handler); @endcode Chris@16: * After the @c async_read_until operation completes successfully, the buffer Chris@16: * @c b contains the data which matched the regular expression: Chris@16: * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode Chris@16: * The call to @c std::getline then extracts the data up to and including the Chris@16: * match, so that the string @c line contains: Chris@16: * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode Chris@16: * The remaining data is left in the buffer @c b as follows: Chris@16: * @code { 'd', 'e', ... } @endcode Chris@16: * This data may be the start of a new line, to be extracted by a subsequent Chris@16: * @c async_read_until operation. Chris@16: */ Chris@16: template Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, Chris@16: void (boost::system::error_code, std::size_t)) Chris@16: async_read_until(AsyncReadStream& s, Chris@16: boost::asio::basic_streambuf& b, const boost::regex& expr, Chris@16: BOOST_ASIO_MOVE_ARG(ReadHandler) handler); Chris@16: Chris@16: #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX) Chris@16: // || defined(GENERATING_DOCUMENTATION) Chris@16: Chris@16: /// Start an asynchronous operation to read data into a streambuf until a Chris@16: /// function object indicates a match. Chris@16: /** Chris@16: * This function is used to asynchronously read data into the specified Chris@16: * streambuf until a user-defined match condition function object, when applied Chris@16: * to the data contained in the streambuf, indicates a successful match. The Chris@16: * function call always returns immediately. The asynchronous operation will Chris@16: * continue until one of the following conditions is true: Chris@16: * Chris@16: * @li The match condition function object returns a std::pair where the second Chris@16: * element evaluates to true. Chris@16: * Chris@16: * @li An error occurred. Chris@16: * Chris@16: * This operation is implemented in terms of zero or more calls to the stream's Chris@16: * async_read_some function, and is known as a composed operation. If Chris@16: * the match condition function object already indicates a match, this Chris@16: * asynchronous operation completes immediately. The program must ensure that Chris@16: * the stream performs no other read operations (such as async_read, Chris@16: * async_read_until, the stream's async_read_some function, or any other Chris@16: * composed operations that perform reads) until this operation completes. Chris@16: * Chris@16: * @param s The stream from which the data is to be read. The type must support Chris@16: * the AsyncReadStream concept. Chris@16: * Chris@16: * @param b A streambuf object into which the data will be read. Chris@16: * Chris@16: * @param match_condition The function object to be called to determine whether Chris@16: * a match exists. The signature of the function object must be: Chris@16: * @code pair match_condition(iterator begin, iterator end); Chris@16: * @endcode Chris@16: * where @c iterator represents the type: Chris@16: * @code buffers_iterator::const_buffers_type> Chris@16: * @endcode Chris@16: * The iterator parameters @c begin and @c end define the range of bytes to be Chris@16: * scanned to determine whether there is a match. The @c first member of the Chris@16: * return value is an iterator marking one-past-the-end of the bytes that have Chris@16: * been consumed by the match function. This iterator is used to calculate the Chris@16: * @c begin parameter for any subsequent invocation of the match condition. The Chris@16: * @c second member of the return value is true if a match has been found, false Chris@16: * otherwise. Chris@16: * Chris@16: * @param handler The handler to be called when the read operation completes. Chris@16: * Copies will be made of the handler as required. The function signature of the Chris@16: * handler must be: Chris@16: * @code void handler( Chris@16: * // Result of operation. Chris@16: * const boost::system::error_code& error, Chris@16: * Chris@16: * // The number of bytes in the streambuf's get Chris@16: * // area that have been fully consumed by the Chris@16: * // match function. O if an error occurred. Chris@16: * std::size_t bytes_transferred Chris@16: * ); @endcode Chris@16: * Regardless of whether the asynchronous operation completes immediately or Chris@16: * not, the handler will not be invoked from within this function. Invocation of Chris@16: * the handler will be performed in a manner equivalent to using Chris@16: * boost::asio::io_service::post(). Chris@16: * Chris@16: * @note After a successful async_read_until operation, the streambuf may Chris@16: * contain additional data beyond that which matched the function object. An Chris@16: * application will typically leave that data in the streambuf for a subsequent Chris@16: * async_read_until operation to examine. Chris@16: * Chris@16: * @note The default implementation of the @c is_match_condition type trait Chris@16: * evaluates to true for function pointers and function objects with a Chris@16: * @c result_type typedef. It must be specialised for other user-defined Chris@16: * function objects. Chris@16: * Chris@16: * @par Examples Chris@16: * To asynchronously read data into a streambuf until whitespace is encountered: Chris@16: * @code typedef boost::asio::buffers_iterator< Chris@16: * boost::asio::streambuf::const_buffers_type> iterator; Chris@16: * Chris@16: * std::pair Chris@16: * match_whitespace(iterator begin, iterator end) Chris@16: * { Chris@16: * iterator i = begin; Chris@16: * while (i != end) Chris@16: * if (std::isspace(*i++)) Chris@16: * return std::make_pair(i, true); Chris@16: * return std::make_pair(i, false); Chris@16: * } Chris@16: * ... Chris@16: * void handler(const boost::system::error_code& e, std::size_t size); Chris@16: * ... Chris@16: * boost::asio::streambuf b; Chris@16: * boost::asio::async_read_until(s, b, match_whitespace, handler); Chris@16: * @endcode Chris@16: * Chris@16: * To asynchronously read data into a streambuf until a matching character is Chris@16: * found: Chris@16: * @code class match_char Chris@16: * { Chris@16: * public: Chris@16: * explicit match_char(char c) : c_(c) {} Chris@16: * Chris@16: * template Chris@16: * std::pair operator()( Chris@16: * Iterator begin, Iterator end) const Chris@16: * { Chris@16: * Iterator i = begin; Chris@16: * while (i != end) Chris@16: * if (c_ == *i++) Chris@16: * return std::make_pair(i, true); Chris@16: * return std::make_pair(i, false); Chris@16: * } Chris@16: * Chris@16: * private: Chris@16: * char c_; Chris@16: * }; Chris@16: * Chris@16: * namespace asio { Chris@16: * template <> struct is_match_condition Chris@16: * : public boost::true_type {}; Chris@16: * } // namespace asio Chris@16: * ... Chris@16: * void handler(const boost::system::error_code& e, std::size_t size); Chris@16: * ... Chris@16: * boost::asio::streambuf b; Chris@16: * boost::asio::async_read_until(s, b, match_char('a'), handler); Chris@16: * @endcode Chris@16: */ Chris@16: template Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, Chris@16: void (boost::system::error_code, std::size_t)) Chris@16: async_read_until(AsyncReadStream& s, Chris@16: boost::asio::basic_streambuf& b, Chris@16: MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadHandler) handler, Chris@16: typename enable_if::value>::type* = 0); Chris@16: Chris@16: /*@}*/ Chris@16: Chris@16: } // namespace asio Chris@16: } // namespace boost Chris@16: Chris@16: #include Chris@16: Chris@16: #include Chris@16: Chris@16: #endif // !defined(BOOST_ASIO_NO_IOSTREAM) Chris@16: Chris@16: #endif // BOOST_ASIO_READ_UNTIL_HPP