5 // Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com)
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)
11 #ifndef BOOST_ASIO_READ_UNTIL_HPP
12 #define BOOST_ASIO_READ_UNTIL_HPP
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18 #include <boost/asio/detail/config.hpp>
20 #if !defined(BOOST_ASIO_NO_IOSTREAM)
24 #include <boost/asio/async_result.hpp>
25 #include <boost/asio/basic_streambuf.hpp>
26 #include <boost/asio/detail/regex_fwd.hpp>
27 #include <boost/asio/detail/type_traits.hpp>
28 #include <boost/asio/error.hpp>
30 #include <boost/asio/detail/push_options.hpp>
37 char (&has_result_type_helper(...))[2];
40 char has_result_type_helper(T*, typename T::result_type* = 0);
43 struct has_result_type
45 enum { value = (sizeof((has_result_type_helper)((T*)(0))) == 1) };
49 /// Type trait used to determine whether a type can be used as a match condition
50 /// function with read_until and async_read_until.
52 struct is_match_condition
54 #if defined(GENERATING_DOCUMENTATION)
55 /// The value member is true if the type may be used as a match condition.
56 static const bool value;
60 value = boost::asio::is_function<
61 typename boost::asio::remove_pointer<T>::type>::value
62 || detail::has_result_type<T>::value
68 * @defgroup read_until boost::asio::read_until
70 * @brief Read data into a streambuf until it contains a delimiter, matches a
71 * regular expression, or a function object indicates a match.
75 /// Read data into a streambuf until it contains a specified delimiter.
77 * This function is used to read data into the specified streambuf until the
78 * streambuf's get area contains the specified delimiter. The call will block
79 * until one of the following conditions is true:
81 * @li The get area of the streambuf contains the specified delimiter.
83 * @li An error occurred.
85 * This operation is implemented in terms of zero or more calls to the stream's
86 * read_some function. If the streambuf's get area already contains the
87 * delimiter, the function returns immediately.
89 * @param s The stream from which the data is to be read. The type must support
90 * the SyncReadStream concept.
92 * @param b A streambuf object into which the data will be read.
94 * @param delim The delimiter character.
96 * @returns The number of bytes in the streambuf's get area up to and including
99 * @throws boost::system::system_error Thrown on failure.
101 * @note After a successful read_until operation, the streambuf may contain
102 * additional data beyond the delimiter. An application will typically leave
103 * that data in the streambuf for a subsequent read_until operation to examine.
106 * To read data into a streambuf until a newline is encountered:
107 * @code boost::asio::streambuf b;
108 * boost::asio::read_until(s, b, '\n');
109 * std::istream is(&b);
111 * std::getline(is, line); @endcode
112 * After the @c read_until operation completes successfully, the buffer @c b
113 * contains the delimiter:
114 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
115 * The call to @c std::getline then extracts the data up to and including the
116 * delimiter, so that the string @c line contains:
117 * @code { 'a', 'b', ..., 'c', '\n' } @endcode
118 * The remaining data is left in the buffer @c b as follows:
119 * @code { 'd', 'e', ... } @endcode
120 * This data may be the start of a new line, to be extracted by a subsequent
121 * @c read_until operation.
123 template <typename SyncReadStream, typename Allocator>
124 std::size_t read_until(SyncReadStream& s,
125 boost::asio::basic_streambuf<Allocator>& b, char delim);
127 /// Read data into a streambuf until it contains a specified delimiter.
129 * This function is used to read data into the specified streambuf until the
130 * streambuf's get area contains the specified delimiter. The call will block
131 * until one of the following conditions is true:
133 * @li The get area of the streambuf contains the specified delimiter.
135 * @li An error occurred.
137 * This operation is implemented in terms of zero or more calls to the stream's
138 * read_some function. If the streambuf's get area already contains the
139 * delimiter, the function returns immediately.
141 * @param s The stream from which the data is to be read. The type must support
142 * the SyncReadStream concept.
144 * @param b A streambuf object into which the data will be read.
146 * @param delim The delimiter character.
148 * @param ec Set to indicate what error occurred, if any.
150 * @returns The number of bytes in the streambuf's get area up to and including
151 * the delimiter. Returns 0 if an error occurred.
153 * @note After a successful read_until operation, the streambuf may contain
154 * additional data beyond the delimiter. An application will typically leave
155 * that data in the streambuf for a subsequent read_until operation to examine.
157 template <typename SyncReadStream, typename Allocator>
158 std::size_t read_until(SyncReadStream& s,
159 boost::asio::basic_streambuf<Allocator>& b, char delim,
160 boost::system::error_code& ec);
162 /// Read data into a streambuf until it contains a specified delimiter.
164 * This function is used to read data into the specified streambuf until the
165 * streambuf's get area contains the specified delimiter. The call will block
166 * until one of the following conditions is true:
168 * @li The get area of the streambuf contains the specified delimiter.
170 * @li An error occurred.
172 * This operation is implemented in terms of zero or more calls to the stream's
173 * read_some function. If the streambuf's get area already contains the
174 * delimiter, the function returns immediately.
176 * @param s The stream from which the data is to be read. The type must support
177 * the SyncReadStream concept.
179 * @param b A streambuf object into which the data will be read.
181 * @param delim The delimiter string.
183 * @returns The number of bytes in the streambuf's get area up to and including
186 * @throws boost::system::system_error Thrown on failure.
188 * @note After a successful read_until operation, the streambuf may contain
189 * additional data beyond the delimiter. An application will typically leave
190 * that data in the streambuf for a subsequent read_until operation to examine.
193 * To read data into a streambuf until a newline is encountered:
194 * @code boost::asio::streambuf b;
195 * boost::asio::read_until(s, b, "\r\n");
196 * std::istream is(&b);
198 * std::getline(is, line); @endcode
199 * After the @c read_until operation completes successfully, the buffer @c b
200 * contains the delimiter:
201 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
202 * The call to @c std::getline then extracts the data up to and including the
203 * delimiter, so that the string @c line contains:
204 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
205 * The remaining data is left in the buffer @c b as follows:
206 * @code { 'd', 'e', ... } @endcode
207 * This data may be the start of a new line, to be extracted by a subsequent
208 * @c read_until operation.
210 template <typename SyncReadStream, typename Allocator>
211 std::size_t read_until(SyncReadStream& s,
212 boost::asio::basic_streambuf<Allocator>& b, const std::string& delim);
214 /// Read data into a streambuf until it contains a specified delimiter.
216 * This function is used to read data into the specified streambuf until the
217 * streambuf's get area contains the specified delimiter. The call will block
218 * until one of the following conditions is true:
220 * @li The get area of the streambuf contains the specified delimiter.
222 * @li An error occurred.
224 * This operation is implemented in terms of zero or more calls to the stream's
225 * read_some function. If the streambuf's get area already contains the
226 * delimiter, the function returns immediately.
228 * @param s The stream from which the data is to be read. The type must support
229 * the SyncReadStream concept.
231 * @param b A streambuf object into which the data will be read.
233 * @param delim The delimiter string.
235 * @param ec Set to indicate what error occurred, if any.
237 * @returns The number of bytes in the streambuf's get area up to and including
238 * the delimiter. Returns 0 if an error occurred.
240 * @note After a successful read_until operation, the streambuf may contain
241 * additional data beyond the delimiter. An application will typically leave
242 * that data in the streambuf for a subsequent read_until operation to examine.
244 template <typename SyncReadStream, typename Allocator>
245 std::size_t read_until(SyncReadStream& s,
246 boost::asio::basic_streambuf<Allocator>& b, const std::string& delim,
247 boost::system::error_code& ec);
249 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
250 || defined(GENERATING_DOCUMENTATION)
252 /// Read data into a streambuf until some part of the data it contains matches
253 /// a regular expression.
255 * This function is used to read data into the specified streambuf until the
256 * streambuf's get area contains some data that matches a regular expression.
257 * The call will block until one of the following conditions is true:
259 * @li A substring of the streambuf's get area matches the regular expression.
261 * @li An error occurred.
263 * This operation is implemented in terms of zero or more calls to the stream's
264 * read_some function. If the streambuf's get area already contains data that
265 * matches the regular expression, the function returns immediately.
267 * @param s The stream from which the data is to be read. The type must support
268 * the SyncReadStream concept.
270 * @param b A streambuf object into which the data will be read.
272 * @param expr The regular expression.
274 * @returns The number of bytes in the streambuf's get area up to and including
275 * the substring that matches the regular expression.
277 * @throws boost::system::system_error Thrown on failure.
279 * @note After a successful read_until operation, the streambuf may contain
280 * additional data beyond that which matched the regular expression. An
281 * application will typically leave that data in the streambuf for a subsequent
282 * read_until operation to examine.
285 * To read data into a streambuf until a CR-LF sequence is encountered:
286 * @code boost::asio::streambuf b;
287 * boost::asio::read_until(s, b, boost::regex("\r\n"));
288 * std::istream is(&b);
290 * std::getline(is, line); @endcode
291 * After the @c read_until operation completes successfully, the buffer @c b
292 * contains the data which matched the regular expression:
293 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
294 * The call to @c std::getline then extracts the data up to and including the
295 * match, so that the string @c line contains:
296 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
297 * The remaining data is left in the buffer @c b as follows:
298 * @code { 'd', 'e', ... } @endcode
299 * This data may be the start of a new line, to be extracted by a subsequent
300 * @c read_until operation.
302 template <typename SyncReadStream, typename Allocator>
303 std::size_t read_until(SyncReadStream& s,
304 boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr);
306 /// Read data into a streambuf until some part of the data it contains matches
307 /// a regular expression.
309 * This function is used to read data into the specified streambuf until the
310 * streambuf's get area contains some data that matches a regular expression.
311 * The call will block until one of the following conditions is true:
313 * @li A substring of the streambuf's get area matches the regular expression.
315 * @li An error occurred.
317 * This operation is implemented in terms of zero or more calls to the stream's
318 * read_some function. If the streambuf's get area already contains data that
319 * matches the regular expression, the function returns immediately.
321 * @param s The stream from which the data is to be read. The type must support
322 * the SyncReadStream concept.
324 * @param b A streambuf object into which the data will be read.
326 * @param expr The regular expression.
328 * @param ec Set to indicate what error occurred, if any.
330 * @returns The number of bytes in the streambuf's get area up to and including
331 * the substring that matches the regular expression. Returns 0 if an error
334 * @note After a successful read_until operation, the streambuf may contain
335 * additional data beyond that which matched the regular expression. An
336 * application will typically leave that data in the streambuf for a subsequent
337 * read_until operation to examine.
339 template <typename SyncReadStream, typename Allocator>
340 std::size_t read_until(SyncReadStream& s,
341 boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr,
342 boost::system::error_code& ec);
344 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
345 // || defined(GENERATING_DOCUMENTATION)
347 /// Read data into a streambuf until a function object indicates a match.
349 * This function is used to read data into the specified streambuf until a
350 * user-defined match condition function object, when applied to the data
351 * contained in the streambuf, indicates a successful match. The call will
352 * block until one of the following conditions is true:
354 * @li The match condition function object returns a std::pair where the second
355 * element evaluates to true.
357 * @li An error occurred.
359 * This operation is implemented in terms of zero or more calls to the stream's
360 * read_some function. If the match condition function object already indicates
361 * a match, the function returns immediately.
363 * @param s The stream from which the data is to be read. The type must support
364 * the SyncReadStream concept.
366 * @param b A streambuf object into which the data will be read.
368 * @param match_condition The function object to be called to determine whether
369 * a match exists. The signature of the function object must be:
370 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
372 * where @c iterator represents the type:
373 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
375 * The iterator parameters @c begin and @c end define the range of bytes to be
376 * scanned to determine whether there is a match. The @c first member of the
377 * return value is an iterator marking one-past-the-end of the bytes that have
378 * been consumed by the match function. This iterator is used to calculate the
379 * @c begin parameter for any subsequent invocation of the match condition. The
380 * @c second member of the return value is true if a match has been found, false
383 * @returns The number of bytes in the streambuf's get area that have been fully
384 * consumed by the match function.
386 * @throws boost::system::system_error Thrown on failure.
388 * @note After a successful read_until operation, the streambuf may contain
389 * additional data beyond that which matched the function object. An application
390 * will typically leave that data in the streambuf for a subsequent
392 * @note The default implementation of the @c is_match_condition type trait
393 * evaluates to true for function pointers and function objects with a
394 * @c result_type typedef. It must be specialised for other user-defined
398 * To read data into a streambuf until whitespace is encountered:
399 * @code typedef boost::asio::buffers_iterator<
400 * boost::asio::streambuf::const_buffers_type> iterator;
402 * std::pair<iterator, bool>
403 * match_whitespace(iterator begin, iterator end)
405 * iterator i = begin;
407 * if (std::isspace(*i++))
408 * return std::make_pair(i, true);
409 * return std::make_pair(i, false);
412 * boost::asio::streambuf b;
413 * boost::asio::read_until(s, b, match_whitespace);
416 * To read data into a streambuf until a matching character is found:
417 * @code class match_char
420 * explicit match_char(char c) : c_(c) {}
422 * template <typename Iterator>
423 * std::pair<Iterator, bool> operator()(
424 * Iterator begin, Iterator end) const
426 * Iterator i = begin;
429 * return std::make_pair(i, true);
430 * return std::make_pair(i, false);
438 * template <> struct is_match_condition<match_char>
439 * : public boost::true_type {};
440 * } // namespace asio
442 * boost::asio::streambuf b;
443 * boost::asio::read_until(s, b, match_char('a'));
446 template <typename SyncReadStream, typename Allocator, typename MatchCondition>
447 std::size_t read_until(SyncReadStream& s,
448 boost::asio::basic_streambuf<Allocator>& b, MatchCondition match_condition,
449 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
451 /// Read data into a streambuf until a function object indicates a match.
453 * This function is used to read data into the specified streambuf until a
454 * user-defined match condition function object, when applied to the data
455 * contained in the streambuf, indicates a successful match. The call will
456 * block until one of the following conditions is true:
458 * @li The match condition function object returns a std::pair where the second
459 * element evaluates to true.
461 * @li An error occurred.
463 * This operation is implemented in terms of zero or more calls to the stream's
464 * read_some function. If the match condition function object already indicates
465 * a match, the function returns immediately.
467 * @param s The stream from which the data is to be read. The type must support
468 * the SyncReadStream concept.
470 * @param b A streambuf object into which the data will be read.
472 * @param match_condition The function object to be called to determine whether
473 * a match exists. The signature of the function object must be:
474 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
476 * where @c iterator represents the type:
477 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
479 * The iterator parameters @c begin and @c end define the range of bytes to be
480 * scanned to determine whether there is a match. The @c first member of the
481 * return value is an iterator marking one-past-the-end of the bytes that have
482 * been consumed by the match function. This iterator is used to calculate the
483 * @c begin parameter for any subsequent invocation of the match condition. The
484 * @c second member of the return value is true if a match has been found, false
487 * @param ec Set to indicate what error occurred, if any.
489 * @returns The number of bytes in the streambuf's get area that have been fully
490 * consumed by the match function. Returns 0 if an error occurred.
492 * @note After a successful read_until operation, the streambuf may contain
493 * additional data beyond that which matched the function object. An application
494 * will typically leave that data in the streambuf for a subsequent
496 * @note The default implementation of the @c is_match_condition type trait
497 * evaluates to true for function pointers and function objects with a
498 * @c result_type typedef. It must be specialised for other user-defined
501 template <typename SyncReadStream, typename Allocator, typename MatchCondition>
502 std::size_t read_until(SyncReadStream& s,
503 boost::asio::basic_streambuf<Allocator>& b,
504 MatchCondition match_condition, boost::system::error_code& ec,
505 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
509 * @defgroup async_read_until boost::asio::async_read_until
511 * @brief Start an asynchronous operation to read data into a streambuf until it
512 * contains a delimiter, matches a regular expression, or a function object
517 /// Start an asynchronous operation to read data into a streambuf until it
518 /// contains a specified delimiter.
520 * This function is used to asynchronously read data into the specified
521 * streambuf until the streambuf's get area contains the specified delimiter.
522 * The function call always returns immediately. The asynchronous operation
523 * will continue until one of the following conditions is true:
525 * @li The get area of the streambuf contains the specified delimiter.
527 * @li An error occurred.
529 * This operation is implemented in terms of zero or more calls to the stream's
530 * async_read_some function, and is known as a <em>composed operation</em>. If
531 * the streambuf's get area already contains the delimiter, this asynchronous
532 * operation completes immediately. The program must ensure that the stream
533 * performs no other read operations (such as async_read, async_read_until, the
534 * stream's async_read_some function, or any other composed operations that
535 * perform reads) until this operation completes.
537 * @param s The stream from which the data is to be read. The type must support
538 * the AsyncReadStream concept.
540 * @param b A streambuf object into which the data will be read. Ownership of
541 * the streambuf is retained by the caller, which must guarantee that it remains
542 * valid until the handler is called.
544 * @param delim The delimiter character.
546 * @param handler The handler to be called when the read operation completes.
547 * Copies will be made of the handler as required. The function signature of the
549 * @code void handler(
550 * // Result of operation.
551 * const boost::system::error_code& error,
553 * // The number of bytes in the streambuf's get
554 * // area up to and including the delimiter.
555 * // 0 if an error occurred.
556 * std::size_t bytes_transferred
558 * Regardless of whether the asynchronous operation completes immediately or
559 * not, the handler will not be invoked from within this function. Invocation of
560 * the handler will be performed in a manner equivalent to using
561 * boost::asio::io_service::post().
563 * @note After a successful async_read_until operation, the streambuf may
564 * contain additional data beyond the delimiter. An application will typically
565 * leave that data in the streambuf for a subsequent async_read_until operation
569 * To asynchronously read data into a streambuf until a newline is encountered:
570 * @code boost::asio::streambuf b;
572 * void handler(const boost::system::error_code& e, std::size_t size)
576 * std::istream is(&b);
578 * std::getline(is, line);
583 * boost::asio::async_read_until(s, b, '\n', handler); @endcode
584 * After the @c async_read_until operation completes successfully, the buffer
585 * @c b contains the delimiter:
586 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
587 * The call to @c std::getline then extracts the data up to and including the
588 * delimiter, so that the string @c line contains:
589 * @code { 'a', 'b', ..., 'c', '\n' } @endcode
590 * The remaining data is left in the buffer @c b as follows:
591 * @code { 'd', 'e', ... } @endcode
592 * This data may be the start of a new line, to be extracted by a subsequent
593 * @c async_read_until operation.
595 template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
596 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
597 void (boost::system::error_code, std::size_t))
598 async_read_until(AsyncReadStream& s,
599 boost::asio::basic_streambuf<Allocator>& b,
600 char delim, BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
602 /// Start an asynchronous operation to read data into a streambuf until it
603 /// contains a specified delimiter.
605 * This function is used to asynchronously read data into the specified
606 * streambuf until the streambuf's get area contains the specified delimiter.
607 * The function call always returns immediately. The asynchronous operation
608 * will continue until one of the following conditions is true:
610 * @li The get area of the streambuf contains the specified delimiter.
612 * @li An error occurred.
614 * This operation is implemented in terms of zero or more calls to the stream's
615 * async_read_some function, and is known as a <em>composed operation</em>. If
616 * the streambuf's get area already contains the delimiter, this asynchronous
617 * operation completes immediately. The program must ensure that the stream
618 * performs no other read operations (such as async_read, async_read_until, the
619 * stream's async_read_some function, or any other composed operations that
620 * perform reads) until this operation completes.
622 * @param s The stream from which the data is to be read. The type must support
623 * the AsyncReadStream concept.
625 * @param b A streambuf object into which the data will be read. Ownership of
626 * the streambuf is retained by the caller, which must guarantee that it remains
627 * valid until the handler is called.
629 * @param delim The delimiter string.
631 * @param handler The handler to be called when the read operation completes.
632 * Copies will be made of the handler as required. The function signature of the
634 * @code void handler(
635 * // Result of operation.
636 * const boost::system::error_code& error,
638 * // The number of bytes in the streambuf's get
639 * // area up to and including the delimiter.
640 * // 0 if an error occurred.
641 * std::size_t bytes_transferred
643 * Regardless of whether the asynchronous operation completes immediately or
644 * not, the handler will not be invoked from within this function. Invocation of
645 * the handler will be performed in a manner equivalent to using
646 * boost::asio::io_service::post().
648 * @note After a successful async_read_until operation, the streambuf may
649 * contain additional data beyond the delimiter. An application will typically
650 * leave that data in the streambuf for a subsequent async_read_until operation
654 * To asynchronously read data into a streambuf until a newline is encountered:
655 * @code boost::asio::streambuf b;
657 * void handler(const boost::system::error_code& e, std::size_t size)
661 * std::istream is(&b);
663 * std::getline(is, line);
668 * boost::asio::async_read_until(s, b, "\r\n", handler); @endcode
669 * After the @c async_read_until operation completes successfully, the buffer
670 * @c b contains the delimiter:
671 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
672 * The call to @c std::getline then extracts the data up to and including the
673 * delimiter, so that the string @c line contains:
674 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
675 * The remaining data is left in the buffer @c b as follows:
676 * @code { 'd', 'e', ... } @endcode
677 * This data may be the start of a new line, to be extracted by a subsequent
678 * @c async_read_until operation.
680 template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
681 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
682 void (boost::system::error_code, std::size_t))
683 async_read_until(AsyncReadStream& s,
684 boost::asio::basic_streambuf<Allocator>& b, const std::string& delim,
685 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
687 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
688 || defined(GENERATING_DOCUMENTATION)
690 /// Start an asynchronous operation to read data into a streambuf until some
691 /// part of its data matches a regular expression.
693 * This function is used to asynchronously read data into the specified
694 * streambuf until the streambuf's get area contains some data that matches a
695 * regular expression. The function call always returns immediately. The
696 * asynchronous operation will continue until one of the following conditions
699 * @li A substring of the streambuf's get area matches the regular expression.
701 * @li An error occurred.
703 * This operation is implemented in terms of zero or more calls to the stream's
704 * async_read_some function, and is known as a <em>composed operation</em>. If
705 * the streambuf's get area already contains data that matches the regular
706 * expression, this asynchronous operation completes immediately. The program
707 * must ensure that the stream performs no other read operations (such as
708 * async_read, async_read_until, the stream's async_read_some function, or any
709 * other composed operations that perform reads) until this operation
712 * @param s The stream from which the data is to be read. The type must support
713 * the AsyncReadStream concept.
715 * @param b A streambuf object into which the data will be read. Ownership of
716 * the streambuf is retained by the caller, which must guarantee that it remains
717 * valid until the handler is called.
719 * @param expr The regular expression.
721 * @param handler The handler to be called when the read operation completes.
722 * Copies will be made of the handler as required. The function signature of the
724 * @code void handler(
725 * // Result of operation.
726 * const boost::system::error_code& error,
728 * // The number of bytes in the streambuf's get
729 * // area up to and including the substring
730 * // that matches the regular. expression.
731 * // 0 if an error occurred.
732 * std::size_t bytes_transferred
734 * Regardless of whether the asynchronous operation completes immediately or
735 * not, the handler will not be invoked from within this function. Invocation of
736 * the handler will be performed in a manner equivalent to using
737 * boost::asio::io_service::post().
739 * @note After a successful async_read_until operation, the streambuf may
740 * contain additional data beyond that which matched the regular expression. An
741 * application will typically leave that data in the streambuf for a subsequent
742 * async_read_until operation to examine.
745 * To asynchronously read data into a streambuf until a CR-LF sequence is
747 * @code boost::asio::streambuf b;
749 * void handler(const boost::system::error_code& e, std::size_t size)
753 * std::istream is(&b);
755 * std::getline(is, line);
760 * boost::asio::async_read_until(s, b, boost::regex("\r\n"), handler); @endcode
761 * After the @c async_read_until operation completes successfully, the buffer
762 * @c b contains the data which matched the regular expression:
763 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
764 * The call to @c std::getline then extracts the data up to and including the
765 * match, so that the string @c line contains:
766 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
767 * The remaining data is left in the buffer @c b as follows:
768 * @code { 'd', 'e', ... } @endcode
769 * This data may be the start of a new line, to be extracted by a subsequent
770 * @c async_read_until operation.
772 template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
773 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
774 void (boost::system::error_code, std::size_t))
775 async_read_until(AsyncReadStream& s,
776 boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr,
777 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
779 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
780 // || defined(GENERATING_DOCUMENTATION)
782 /// Start an asynchronous operation to read data into a streambuf until a
783 /// function object indicates a match.
785 * This function is used to asynchronously read data into the specified
786 * streambuf until a user-defined match condition function object, when applied
787 * to the data contained in the streambuf, indicates a successful match. The
788 * function call always returns immediately. The asynchronous operation will
789 * continue until one of the following conditions is true:
791 * @li The match condition function object returns a std::pair where the second
792 * element evaluates to true.
794 * @li An error occurred.
796 * This operation is implemented in terms of zero or more calls to the stream's
797 * async_read_some function, and is known as a <em>composed operation</em>. If
798 * the match condition function object already indicates a match, this
799 * asynchronous operation completes immediately. The program must ensure that
800 * the stream performs no other read operations (such as async_read,
801 * async_read_until, the stream's async_read_some function, or any other
802 * composed operations that perform reads) until this operation completes.
804 * @param s The stream from which the data is to be read. The type must support
805 * the AsyncReadStream concept.
807 * @param b A streambuf object into which the data will be read.
809 * @param match_condition The function object to be called to determine whether
810 * a match exists. The signature of the function object must be:
811 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
813 * where @c iterator represents the type:
814 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
816 * The iterator parameters @c begin and @c end define the range of bytes to be
817 * scanned to determine whether there is a match. The @c first member of the
818 * return value is an iterator marking one-past-the-end of the bytes that have
819 * been consumed by the match function. This iterator is used to calculate the
820 * @c begin parameter for any subsequent invocation of the match condition. The
821 * @c second member of the return value is true if a match has been found, false
824 * @param handler The handler to be called when the read operation completes.
825 * Copies will be made of the handler as required. The function signature of the
827 * @code void handler(
828 * // Result of operation.
829 * const boost::system::error_code& error,
831 * // The number of bytes in the streambuf's get
832 * // area that have been fully consumed by the
833 * // match function. O if an error occurred.
834 * std::size_t bytes_transferred
836 * Regardless of whether the asynchronous operation completes immediately or
837 * not, the handler will not be invoked from within this function. Invocation of
838 * the handler will be performed in a manner equivalent to using
839 * boost::asio::io_service::post().
841 * @note After a successful async_read_until operation, the streambuf may
842 * contain additional data beyond that which matched the function object. An
843 * application will typically leave that data in the streambuf for a subsequent
844 * async_read_until operation to examine.
846 * @note The default implementation of the @c is_match_condition type trait
847 * evaluates to true for function pointers and function objects with a
848 * @c result_type typedef. It must be specialised for other user-defined
852 * To asynchronously read data into a streambuf until whitespace is encountered:
853 * @code typedef boost::asio::buffers_iterator<
854 * boost::asio::streambuf::const_buffers_type> iterator;
856 * std::pair<iterator, bool>
857 * match_whitespace(iterator begin, iterator end)
859 * iterator i = begin;
861 * if (std::isspace(*i++))
862 * return std::make_pair(i, true);
863 * return std::make_pair(i, false);
866 * void handler(const boost::system::error_code& e, std::size_t size);
868 * boost::asio::streambuf b;
869 * boost::asio::async_read_until(s, b, match_whitespace, handler);
872 * To asynchronously read data into a streambuf until a matching character is
874 * @code class match_char
877 * explicit match_char(char c) : c_(c) {}
879 * template <typename Iterator>
880 * std::pair<Iterator, bool> operator()(
881 * Iterator begin, Iterator end) const
883 * Iterator i = begin;
886 * return std::make_pair(i, true);
887 * return std::make_pair(i, false);
895 * template <> struct is_match_condition<match_char>
896 * : public boost::true_type {};
897 * } // namespace asio
899 * void handler(const boost::system::error_code& e, std::size_t size);
901 * boost::asio::streambuf b;
902 * boost::asio::async_read_until(s, b, match_char('a'), handler);
905 template <typename AsyncReadStream, typename Allocator,
906 typename MatchCondition, typename ReadHandler>
907 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
908 void (boost::system::error_code, std::size_t))
909 async_read_until(AsyncReadStream& s,
910 boost::asio::basic_streambuf<Allocator>& b,
911 MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
912 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
919 #include <boost/asio/detail/pop_options.hpp>
921 #include <boost/asio/impl/read_until.hpp>
923 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
925 #endif // BOOST_ASIO_READ_UNTIL_HPP