5 // Copyright (c) 2003-2019 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>
21 #include <boost/asio/async_result.hpp>
22 #include <boost/asio/buffer.hpp>
23 #include <boost/asio/detail/regex_fwd.hpp>
24 #include <boost/asio/detail/string_view.hpp>
25 #include <boost/asio/detail/type_traits.hpp>
26 #include <boost/asio/error.hpp>
28 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
29 # include <boost/asio/basic_streambuf_fwd.hpp>
30 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
32 #include <boost/asio/detail/push_options.hpp>
39 char (&has_result_type_helper(...))[2];
42 char has_result_type_helper(T*, typename T::result_type* = 0);
45 struct has_result_type
47 enum { value = (sizeof((has_result_type_helper)((T*)(0))) == 1) };
51 /// Type trait used to determine whether a type can be used as a match condition
52 /// function with read_until and async_read_until.
54 struct is_match_condition
56 #if defined(GENERATING_DOCUMENTATION)
57 /// The value member is true if the type may be used as a match condition.
58 static const bool value;
62 value = boost::asio::is_function<
63 typename boost::asio::remove_pointer<T>::type>::value
64 || detail::has_result_type<T>::value
70 * @defgroup read_until boost::asio::read_until
72 * @brief The @c read_until function is a composed operation that reads data
73 * into a dynamic buffer sequence, or into a streambuf, until it contains a
74 * delimiter, matches a regular expression, or a function object indicates a
79 #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
81 /// Read data into a dynamic buffer sequence until it contains a specified
84 * This function is used to read data into the specified dynamic buffer
85 * sequence until the dynamic buffer sequence's get area contains the specified
86 * delimiter. The call will block until one of the following conditions is
89 * @li The get area of the dynamic buffer sequence contains the specified
92 * @li An error occurred.
94 * This operation is implemented in terms of zero or more calls to the stream's
95 * read_some function. If the dynamic buffer sequence's get area already
96 * contains the delimiter, the function returns immediately.
98 * @param s The stream from which the data is to be read. The type must support
99 * the SyncReadStream concept.
101 * @param buffers The dynamic buffer sequence into which the data will be read.
103 * @param delim The delimiter character.
105 * @returns The number of bytes in the dynamic buffer sequence's get area up to
106 * and including the delimiter.
108 * @throws boost::system::system_error Thrown on failure.
110 * @note After a successful read_until operation, the dynamic buffer sequence
111 * may contain additional data beyond the delimiter. An application will
112 * typically leave that data in the dynamic buffer sequence for a subsequent
113 * read_until operation to examine.
116 * To read data into a @c std::string until a newline is encountered:
117 * @code std::string data;
118 * std::string n = boost::asio::read_until(s,
119 * boost::asio::dynamic_buffer(data), '\n');
120 * std::string line = data.substr(0, n);
121 * data.erase(0, n); @endcode
122 * After the @c read_until operation completes successfully, the string @c data
123 * contains the delimiter:
124 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
125 * The call to @c substr then extracts the data up to and including the
126 * delimiter, so that the string @c line contains:
127 * @code { 'a', 'b', ..., 'c', '\n' } @endcode
128 * After the call to @c erase, the remaining data is left in the buffer @c b as
130 * @code { 'd', 'e', ... } @endcode
131 * This data may be the start of a new line, to be extracted by a subsequent
132 * @c read_until operation.
134 template <typename SyncReadStream, typename DynamicBuffer_v1>
135 std::size_t read_until(SyncReadStream& s,
136 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, char delim,
138 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
139 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
142 /// Read data into a dynamic buffer sequence until it contains a specified
145 * This function is used to read data into the specified dynamic buffer
146 * sequence until the dynamic buffer sequence's get area contains the specified
147 * delimiter. The call will block until one of the following conditions is
150 * @li The get area of the dynamic buffer sequence contains the specified
153 * @li An error occurred.
155 * This operation is implemented in terms of zero or more calls to the stream's
156 * read_some function. If the dynamic buffer sequence's get area already
157 * contains the delimiter, the function returns immediately.
159 * @param s The stream from which the data is to be read. The type must support
160 * the SyncReadStream concept.
162 * @param buffers The dynamic buffer sequence into which the data will be read.
164 * @param delim The delimiter character.
166 * @param ec Set to indicate what error occurred, if any.
168 * @returns The number of bytes in the dynamic buffer sequence's get area up to
169 * and including the delimiter. Returns 0 if an error occurred.
171 * @note After a successful read_until operation, the dynamic buffer sequence
172 * may contain additional data beyond the delimiter. An application will
173 * typically leave that data in the dynamic buffer sequence for a subsequent
174 * read_until operation to examine.
176 template <typename SyncReadStream, typename DynamicBuffer_v1>
177 std::size_t read_until(SyncReadStream& s,
178 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
179 char delim, boost::system::error_code& ec,
181 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
182 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
185 /// Read data into a dynamic buffer sequence until it contains a specified
188 * This function is used to read data into the specified dynamic buffer
189 * sequence until the dynamic buffer sequence's get area contains the specified
190 * delimiter. The call will block until one of the following conditions is
193 * @li The get area of the dynamic buffer sequence contains the specified
196 * @li An error occurred.
198 * This operation is implemented in terms of zero or more calls to the stream's
199 * read_some function. If the dynamic buffer sequence's get area already
200 * contains the delimiter, the function returns immediately.
202 * @param s The stream from which the data is to be read. The type must support
203 * the SyncReadStream concept.
205 * @param buffers The dynamic buffer sequence into which the data will be read.
207 * @param delim The delimiter string.
209 * @returns The number of bytes in the dynamic buffer sequence's get area up to
210 * and including the delimiter.
212 * @note After a successful read_until operation, the dynamic buffer sequence
213 * may contain additional data beyond the delimiter. An application will
214 * typically leave that data in the dynamic buffer sequence for a subsequent
215 * read_until operation to examine.
218 * To read data into a @c std::string until a CR-LF sequence is encountered:
219 * @code std::string data;
220 * std::string n = boost::asio::read_until(s,
221 * boost::asio::dynamic_buffer(data), "\r\n");
222 * std::string line = data.substr(0, n);
223 * data.erase(0, n); @endcode
224 * After the @c read_until operation completes successfully, the string @c data
225 * contains the delimiter:
226 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
227 * The call to @c substr then extracts the data up to and including the
228 * delimiter, so that the string @c line contains:
229 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
230 * After the call to @c erase, the remaining data is left in the buffer @c b as
232 * @code { 'd', 'e', ... } @endcode
233 * This data may be the start of a new line, to be extracted by a subsequent
234 * @c read_until operation.
236 template <typename SyncReadStream, typename DynamicBuffer_v1>
237 std::size_t read_until(SyncReadStream& s,
238 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
239 BOOST_ASIO_STRING_VIEW_PARAM delim,
241 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
242 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
245 /// Read data into a dynamic buffer sequence until it contains a specified
248 * This function is used to read data into the specified dynamic buffer
249 * sequence until the dynamic buffer sequence's get area contains the specified
250 * delimiter. The call will block until one of the following conditions is
253 * @li The get area of the dynamic buffer sequence contains the specified
256 * @li An error occurred.
258 * This operation is implemented in terms of zero or more calls to the stream's
259 * read_some function. If the dynamic buffer sequence's get area already
260 * contains the delimiter, the function returns immediately.
262 * @param s The stream from which the data is to be read. The type must support
263 * the SyncReadStream concept.
265 * @param buffers The dynamic buffer sequence into which the data will be read.
267 * @param delim The delimiter string.
269 * @param ec Set to indicate what error occurred, if any.
271 * @returns The number of bytes in the dynamic buffer sequence's get area up to
272 * and including the delimiter. Returns 0 if an error occurred.
274 * @note After a successful read_until operation, the dynamic buffer sequence
275 * may contain additional data beyond the delimiter. An application will
276 * typically leave that data in the dynamic buffer sequence for a subsequent
277 * read_until operation to examine.
279 template <typename SyncReadStream, typename DynamicBuffer_v1>
280 std::size_t read_until(SyncReadStream& s,
281 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
282 BOOST_ASIO_STRING_VIEW_PARAM delim,
283 boost::system::error_code& ec,
285 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
286 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
289 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
290 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
291 || defined(GENERATING_DOCUMENTATION)
293 /// Read data into a dynamic buffer sequence until some part of the data it
294 /// contains matches a regular expression.
296 * This function is used to read data into the specified dynamic buffer
297 * sequence until the dynamic buffer sequence's get area contains some data
298 * that matches a regular expression. The call will block until one of the
299 * following conditions is true:
301 * @li A substring of the dynamic buffer sequence's get area matches the
302 * regular expression.
304 * @li An error occurred.
306 * This operation is implemented in terms of zero or more calls to the stream's
307 * read_some function. If the dynamic buffer sequence's get area already
308 * contains data that matches the regular expression, the function returns
311 * @param s The stream from which the data is to be read. The type must support
312 * the SyncReadStream concept.
314 * @param buffers A dynamic buffer sequence into which the data will be read.
316 * @param expr The regular expression.
318 * @returns The number of bytes in the dynamic buffer sequence's get area up to
319 * and including the substring that matches the regular expression.
321 * @throws boost::system::system_error Thrown on failure.
323 * @note After a successful read_until operation, the dynamic buffer sequence
324 * may contain additional data beyond that which matched the regular
325 * expression. An application will typically leave that data in the dynamic
326 * buffer sequence for a subsequent read_until operation to examine.
329 * To read data into a @c std::string until a CR-LF sequence is encountered:
330 * @code std::string data;
331 * std::string n = boost::asio::read_until(s,
332 * boost::asio::dynamic_buffer(data), boost::regex("\r\n"));
333 * std::string line = data.substr(0, n);
334 * data.erase(0, n); @endcode
335 * After the @c read_until operation completes successfully, the string @c data
336 * contains the delimiter:
337 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
338 * The call to @c substr then extracts the data up to and including the
339 * delimiter, so that the string @c line contains:
340 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
341 * After the call to @c erase, the remaining data is left in the buffer @c b as
343 * @code { 'd', 'e', ... } @endcode
344 * This data may be the start of a new line, to be extracted by a subsequent
345 * @c read_until operation.
347 template <typename SyncReadStream, typename DynamicBuffer_v1>
348 std::size_t read_until(SyncReadStream& s,
349 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
350 const boost::regex& expr,
352 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
353 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
356 /// Read data into a dynamic buffer sequence until some part of the data it
357 /// contains matches a regular expression.
359 * This function is used to read data into the specified dynamic buffer
360 * sequence until the dynamic buffer sequence's get area contains some data
361 * that matches a regular expression. The call will block until one of the
362 * following conditions is true:
364 * @li A substring of the dynamic buffer sequence's get area matches the
365 * regular expression.
367 * @li An error occurred.
369 * This operation is implemented in terms of zero or more calls to the stream's
370 * read_some function. If the dynamic buffer sequence's get area already
371 * contains data that matches the regular expression, the function returns
374 * @param s The stream from which the data is to be read. The type must support
375 * the SyncReadStream concept.
377 * @param buffers A dynamic buffer sequence into which the data will be read.
379 * @param expr The regular expression.
381 * @param ec Set to indicate what error occurred, if any.
383 * @returns The number of bytes in the dynamic buffer sequence's get area up to
384 * and including the substring that matches the regular expression. Returns 0
385 * if an error occurred.
387 * @note After a successful read_until operation, the dynamic buffer sequence
388 * may contain additional data beyond that which matched the regular
389 * expression. An application will typically leave that data in the dynamic
390 * buffer sequence for a subsequent read_until operation to examine.
392 template <typename SyncReadStream, typename DynamicBuffer_v1>
393 std::size_t read_until(SyncReadStream& s,
394 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
395 const boost::regex& expr, boost::system::error_code& ec,
397 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
398 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
401 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
402 // || defined(GENERATING_DOCUMENTATION)
404 /// Read data into a dynamic buffer sequence until a function object indicates a
408 * This function is used to read data into the specified dynamic buffer
409 * sequence until a user-defined match condition function object, when applied
410 * to the data contained in the dynamic buffer sequence, indicates a successful
411 * match. The call will block until one of the following conditions is true:
413 * @li The match condition function object returns a std::pair where the second
414 * element evaluates to true.
416 * @li An error occurred.
418 * This operation is implemented in terms of zero or more calls to the stream's
419 * read_some function. If the match condition function object already indicates
420 * a match, the function returns immediately.
422 * @param s The stream from which the data is to be read. The type must support
423 * the SyncReadStream concept.
425 * @param buffers A dynamic buffer sequence into which the data will be read.
427 * @param match_condition The function object to be called to determine whether
428 * a match exists. The signature of the function object must be:
429 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
431 * where @c iterator represents the type:
432 * @code buffers_iterator<typename DynamicBuffer_v1::const_buffers_type>
434 * The iterator parameters @c begin and @c end define the range of bytes to be
435 * scanned to determine whether there is a match. The @c first member of the
436 * return value is an iterator marking one-past-the-end of the bytes that have
437 * been consumed by the match function. This iterator is used to calculate the
438 * @c begin parameter for any subsequent invocation of the match condition. The
439 * @c second member of the return value is true if a match has been found, false
442 * @returns The number of bytes in the dynamic_buffer's get area that
443 * have been fully consumed by the match function.
445 * @throws boost::system::system_error Thrown on failure.
447 * @note After a successful read_until operation, the dynamic buffer sequence
448 * may contain additional data beyond that which matched the function object.
449 * An application will typically leave that data in the dynamic buffer sequence
450 * for a subsequent read_until operation to examine.
452 * @note The default implementation of the @c is_match_condition type trait
453 * evaluates to true for function pointers and function objects with a
454 * @c result_type typedef. It must be specialised for other user-defined
458 * To read data into a dynamic buffer sequence until whitespace is encountered:
459 * @code typedef boost::asio::buffers_iterator<
460 * boost::asio::const_buffers_1> iterator;
462 * std::pair<iterator, bool>
463 * match_whitespace(iterator begin, iterator end)
465 * iterator i = begin;
467 * if (std::isspace(*i++))
468 * return std::make_pair(i, true);
469 * return std::make_pair(i, false);
473 * boost::asio::read_until(s, data, match_whitespace);
476 * To read data into a @c std::string until a matching character is found:
477 * @code class match_char
480 * explicit match_char(char c) : c_(c) {}
482 * template <typename Iterator>
483 * std::pair<Iterator, bool> operator()(
484 * Iterator begin, Iterator end) const
486 * Iterator i = begin;
489 * return std::make_pair(i, true);
490 * return std::make_pair(i, false);
498 * template <> struct is_match_condition<match_char>
499 * : public boost::true_type {};
500 * } // namespace asio
503 * boost::asio::read_until(s, data, match_char('a'));
506 template <typename SyncReadStream,
507 typename DynamicBuffer_v1, typename MatchCondition>
508 std::size_t read_until(SyncReadStream& s,
509 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
510 MatchCondition match_condition,
512 is_match_condition<MatchCondition>::value
513 && is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
514 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
517 /// Read data into a dynamic buffer sequence until a function object indicates a
520 * This function is used to read data into the specified dynamic buffer
521 * sequence until a user-defined match condition function object, when applied
522 * to the data contained in the dynamic buffer sequence, indicates a successful
523 * match. The call will block until one of the following conditions is true:
525 * @li The match condition function object returns a std::pair where the second
526 * element evaluates to true.
528 * @li An error occurred.
530 * This operation is implemented in terms of zero or more calls to the stream's
531 * read_some function. If the match condition function object already indicates
532 * a match, the function returns immediately.
534 * @param s The stream from which the data is to be read. The type must support
535 * the SyncReadStream concept.
537 * @param buffers A dynamic buffer sequence into which the data will be read.
539 * @param match_condition The function object to be called to determine whether
540 * a match exists. The signature of the function object must be:
541 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
543 * where @c iterator represents the type:
544 * @code buffers_iterator<DynamicBuffer_v1::const_buffers_type>
546 * The iterator parameters @c begin and @c end define the range of bytes to be
547 * scanned to determine whether there is a match. The @c first member of the
548 * return value is an iterator marking one-past-the-end of the bytes that have
549 * been consumed by the match function. This iterator is used to calculate the
550 * @c begin parameter for any subsequent invocation of the match condition. The
551 * @c second member of the return value is true if a match has been found, false
554 * @param ec Set to indicate what error occurred, if any.
556 * @returns The number of bytes in the dynamic buffer sequence's get area that
557 * have been fully consumed by the match function. Returns 0 if an error
560 * @note After a successful read_until operation, the dynamic buffer sequence
561 * may contain additional data beyond that which matched the function object.
562 * An application will typically leave that data in the dynamic buffer sequence
563 * for a subsequent read_until operation to examine.
565 * @note The default implementation of the @c is_match_condition type trait
566 * evaluates to true for function pointers and function objects with a
567 * @c result_type typedef. It must be specialised for other user-defined
570 template <typename SyncReadStream,
571 typename DynamicBuffer_v1, typename MatchCondition>
572 std::size_t read_until(SyncReadStream& s,
573 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
574 MatchCondition match_condition, boost::system::error_code& ec,
576 is_match_condition<MatchCondition>::value
577 && is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
578 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
581 #if !defined(BOOST_ASIO_NO_IOSTREAM)
583 /// Read data into a streambuf until it contains a specified delimiter.
585 * This function is used to read data into the specified streambuf until the
586 * streambuf's get area contains the specified delimiter. The call will block
587 * until one of the following conditions is true:
589 * @li The get area of the streambuf contains the specified delimiter.
591 * @li An error occurred.
593 * This operation is implemented in terms of zero or more calls to the stream's
594 * read_some function. If the streambuf's get area already contains the
595 * delimiter, the function returns immediately.
597 * @param s The stream from which the data is to be read. The type must support
598 * the SyncReadStream concept.
600 * @param b A streambuf object into which the data will be read.
602 * @param delim The delimiter character.
604 * @returns The number of bytes in the streambuf's get area up to and including
607 * @throws boost::system::system_error Thrown on failure.
609 * @note After a successful read_until operation, the streambuf may contain
610 * additional data beyond the delimiter. An application will typically leave
611 * that data in the streambuf for a subsequent read_until operation to examine.
614 * To read data into a streambuf until a newline is encountered:
615 * @code boost::asio::streambuf b;
616 * boost::asio::read_until(s, b, '\n');
617 * std::istream is(&b);
619 * std::getline(is, line); @endcode
620 * After the @c read_until operation completes successfully, the buffer @c b
621 * contains the delimiter:
622 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
623 * The call to @c std::getline then extracts the data up to and including the
624 * newline (which is discarded), so that the string @c line contains:
625 * @code { 'a', 'b', ..., 'c' } @endcode
626 * The remaining data is left in the buffer @c b as follows:
627 * @code { 'd', 'e', ... } @endcode
628 * This data may be the start of a new line, to be extracted by a subsequent
629 * @c read_until operation.
631 template <typename SyncReadStream, typename Allocator>
632 std::size_t read_until(SyncReadStream& s,
633 boost::asio::basic_streambuf<Allocator>& b, char delim);
635 /// Read data into a streambuf until it contains a specified delimiter.
637 * This function is used to read data into the specified streambuf until the
638 * streambuf's get area contains the specified delimiter. The call will block
639 * until one of the following conditions is true:
641 * @li The get area of the streambuf contains the specified delimiter.
643 * @li An error occurred.
645 * This operation is implemented in terms of zero or more calls to the stream's
646 * read_some function. If the streambuf's get area already contains the
647 * delimiter, the function returns immediately.
649 * @param s The stream from which the data is to be read. The type must support
650 * the SyncReadStream concept.
652 * @param b A streambuf object into which the data will be read.
654 * @param delim The delimiter character.
656 * @param ec Set to indicate what error occurred, if any.
658 * @returns The number of bytes in the streambuf's get area up to and including
659 * the delimiter. Returns 0 if an error occurred.
661 * @note After a successful read_until operation, the streambuf may contain
662 * additional data beyond the delimiter. An application will typically leave
663 * that data in the streambuf for a subsequent read_until operation to examine.
665 template <typename SyncReadStream, typename Allocator>
666 std::size_t read_until(SyncReadStream& s,
667 boost::asio::basic_streambuf<Allocator>& b, char delim,
668 boost::system::error_code& ec);
670 /// Read data into a streambuf until it contains a specified delimiter.
672 * This function is used to read data into the specified streambuf until the
673 * streambuf's get area contains the specified delimiter. The call will block
674 * until one of the following conditions is true:
676 * @li The get area of the streambuf contains the specified delimiter.
678 * @li An error occurred.
680 * This operation is implemented in terms of zero or more calls to the stream's
681 * read_some function. If the streambuf's get area already contains the
682 * delimiter, the function returns immediately.
684 * @param s The stream from which the data is to be read. The type must support
685 * the SyncReadStream concept.
687 * @param b A streambuf object into which the data will be read.
689 * @param delim The delimiter string.
691 * @returns The number of bytes in the streambuf's get area up to and including
694 * @throws boost::system::system_error Thrown on failure.
696 * @note After a successful read_until operation, the streambuf may contain
697 * additional data beyond the delimiter. An application will typically leave
698 * that data in the streambuf for a subsequent read_until operation to examine.
701 * To read data into a streambuf until a newline is encountered:
702 * @code boost::asio::streambuf b;
703 * boost::asio::read_until(s, b, "\r\n");
704 * std::istream is(&b);
706 * std::getline(is, line); @endcode
707 * After the @c read_until operation completes successfully, the buffer @c b
708 * contains the delimiter:
709 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
710 * The call to @c std::getline then extracts the data up to and including the
711 * newline (which is discarded), so that the string @c line contains:
712 * @code { 'a', 'b', ..., 'c', '\r' } @endcode
713 * The remaining data is left in the buffer @c b as follows:
714 * @code { 'd', 'e', ... } @endcode
715 * This data may be the start of a new line, to be extracted by a subsequent
716 * @c read_until operation.
718 template <typename SyncReadStream, typename Allocator>
719 std::size_t read_until(SyncReadStream& s,
720 boost::asio::basic_streambuf<Allocator>& b,
721 BOOST_ASIO_STRING_VIEW_PARAM delim);
723 /// Read data into a streambuf until it contains a specified delimiter.
725 * This function is used to read data into the specified streambuf until the
726 * streambuf's get area contains the specified delimiter. The call will block
727 * until one of the following conditions is true:
729 * @li The get area of the streambuf contains the specified delimiter.
731 * @li An error occurred.
733 * This operation is implemented in terms of zero or more calls to the stream's
734 * read_some function. If the streambuf's get area already contains the
735 * delimiter, the function returns immediately.
737 * @param s The stream from which the data is to be read. The type must support
738 * the SyncReadStream concept.
740 * @param b A streambuf object into which the data will be read.
742 * @param delim The delimiter string.
744 * @param ec Set to indicate what error occurred, if any.
746 * @returns The number of bytes in the streambuf's get area up to and including
747 * the delimiter. Returns 0 if an error occurred.
749 * @note After a successful read_until operation, the streambuf may contain
750 * additional data beyond the delimiter. An application will typically leave
751 * that data in the streambuf for a subsequent read_until operation to examine.
753 template <typename SyncReadStream, typename Allocator>
754 std::size_t read_until(SyncReadStream& s,
755 boost::asio::basic_streambuf<Allocator>& b,
756 BOOST_ASIO_STRING_VIEW_PARAM delim, boost::system::error_code& ec);
758 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
759 || defined(GENERATING_DOCUMENTATION)
761 /// Read data into a streambuf until some part of the data it contains matches
762 /// a regular expression.
764 * This function is used to read data into the specified streambuf until the
765 * streambuf's get area contains some data that matches a regular expression.
766 * The call will block until one of the following conditions is true:
768 * @li A substring of the streambuf's get area matches the regular expression.
770 * @li An error occurred.
772 * This operation is implemented in terms of zero or more calls to the stream's
773 * read_some function. If the streambuf's get area already contains data that
774 * matches the regular expression, the function returns immediately.
776 * @param s The stream from which the data is to be read. The type must support
777 * the SyncReadStream concept.
779 * @param b A streambuf object into which the data will be read.
781 * @param expr The regular expression.
783 * @returns The number of bytes in the streambuf's get area up to and including
784 * the substring that matches the regular expression.
786 * @throws boost::system::system_error Thrown on failure.
788 * @note After a successful read_until operation, the streambuf may contain
789 * additional data beyond that which matched the regular expression. An
790 * application will typically leave that data in the streambuf for a subsequent
791 * read_until operation to examine.
794 * To read data into a streambuf until a CR-LF sequence is encountered:
795 * @code boost::asio::streambuf b;
796 * boost::asio::read_until(s, b, boost::regex("\r\n"));
797 * std::istream is(&b);
799 * std::getline(is, line); @endcode
800 * After the @c read_until operation completes successfully, the buffer @c b
801 * contains the data which matched the regular expression:
802 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
803 * The call to @c std::getline then extracts the data up to and including the
804 * newline (which is discarded), so that the string @c line contains:
805 * @code { 'a', 'b', ..., 'c', '\r' } @endcode
806 * The remaining data is left in the buffer @c b as follows:
807 * @code { 'd', 'e', ... } @endcode
808 * This data may be the start of a new line, to be extracted by a subsequent
809 * @c read_until operation.
811 template <typename SyncReadStream, typename Allocator>
812 std::size_t read_until(SyncReadStream& s,
813 boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr);
815 /// Read data into a streambuf until some part of the data it contains matches
816 /// a regular expression.
818 * This function is used to read data into the specified streambuf until the
819 * streambuf's get area contains some data that matches a regular expression.
820 * The call will block until one of the following conditions is true:
822 * @li A substring of the streambuf's get area matches the regular expression.
824 * @li An error occurred.
826 * This operation is implemented in terms of zero or more calls to the stream's
827 * read_some function. If the streambuf's get area already contains data that
828 * matches the regular expression, the function returns immediately.
830 * @param s The stream from which the data is to be read. The type must support
831 * the SyncReadStream concept.
833 * @param b A streambuf object into which the data will be read.
835 * @param expr The regular expression.
837 * @param ec Set to indicate what error occurred, if any.
839 * @returns The number of bytes in the streambuf's get area up to and including
840 * the substring that matches the regular expression. Returns 0 if an error
843 * @note After a successful read_until operation, the streambuf may contain
844 * additional data beyond that which matched the regular expression. An
845 * application will typically leave that data in the streambuf for a subsequent
846 * read_until operation to examine.
848 template <typename SyncReadStream, typename Allocator>
849 std::size_t read_until(SyncReadStream& s,
850 boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr,
851 boost::system::error_code& ec);
853 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
854 // || defined(GENERATING_DOCUMENTATION)
856 /// Read data into a streambuf until a function object indicates a match.
858 * This function is used to read data into the specified streambuf until a
859 * user-defined match condition function object, when applied to the data
860 * contained in the streambuf, indicates a successful match. The call will
861 * block until one of the following conditions is true:
863 * @li The match condition function object returns a std::pair where the second
864 * element evaluates to true.
866 * @li An error occurred.
868 * This operation is implemented in terms of zero or more calls to the stream's
869 * read_some function. If the match condition function object already indicates
870 * a match, the function returns immediately.
872 * @param s The stream from which the data is to be read. The type must support
873 * the SyncReadStream concept.
875 * @param b A streambuf object into which the data will be read.
877 * @param match_condition The function object to be called to determine whether
878 * a match exists. The signature of the function object must be:
879 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
881 * where @c iterator represents the type:
882 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
884 * The iterator parameters @c begin and @c end define the range of bytes to be
885 * scanned to determine whether there is a match. The @c first member of the
886 * return value is an iterator marking one-past-the-end of the bytes that have
887 * been consumed by the match function. This iterator is used to calculate the
888 * @c begin parameter for any subsequent invocation of the match condition. The
889 * @c second member of the return value is true if a match has been found, false
892 * @returns The number of bytes in the streambuf's get area that have been fully
893 * consumed by the match function.
895 * @throws boost::system::system_error Thrown on failure.
897 * @note After a successful read_until operation, the streambuf may contain
898 * additional data beyond that which matched the function object. An application
899 * will typically leave that data in the streambuf for a subsequent read_until
900 * operation to examine.
902 * @note The default implementation of the @c is_match_condition type trait
903 * evaluates to true for function pointers and function objects with a
904 * @c result_type typedef. It must be specialised for other user-defined
908 * To read data into a streambuf until whitespace is encountered:
909 * @code typedef boost::asio::buffers_iterator<
910 * boost::asio::streambuf::const_buffers_type> iterator;
912 * std::pair<iterator, bool>
913 * match_whitespace(iterator begin, iterator end)
915 * iterator i = begin;
917 * if (std::isspace(*i++))
918 * return std::make_pair(i, true);
919 * return std::make_pair(i, false);
922 * boost::asio::streambuf b;
923 * boost::asio::read_until(s, b, match_whitespace);
926 * To read data into a streambuf until a matching character is found:
927 * @code class match_char
930 * explicit match_char(char c) : c_(c) {}
932 * template <typename Iterator>
933 * std::pair<Iterator, bool> operator()(
934 * Iterator begin, Iterator end) const
936 * Iterator i = begin;
939 * return std::make_pair(i, true);
940 * return std::make_pair(i, false);
948 * template <> struct is_match_condition<match_char>
949 * : public boost::true_type {};
950 * } // namespace asio
952 * boost::asio::streambuf b;
953 * boost::asio::read_until(s, b, match_char('a'));
956 template <typename SyncReadStream, typename Allocator, typename MatchCondition>
957 std::size_t read_until(SyncReadStream& s,
958 boost::asio::basic_streambuf<Allocator>& b, MatchCondition match_condition,
959 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
961 /// Read data into a streambuf until a function object indicates a match.
963 * This function is used to read data into the specified streambuf until a
964 * user-defined match condition function object, when applied to the data
965 * contained in the streambuf, indicates a successful match. The call will
966 * block until one of the following conditions is true:
968 * @li The match condition function object returns a std::pair where the second
969 * element evaluates to true.
971 * @li An error occurred.
973 * This operation is implemented in terms of zero or more calls to the stream's
974 * read_some function. If the match condition function object already indicates
975 * a match, the function returns immediately.
977 * @param s The stream from which the data is to be read. The type must support
978 * the SyncReadStream concept.
980 * @param b A streambuf object into which the data will be read.
982 * @param match_condition The function object to be called to determine whether
983 * a match exists. The signature of the function object must be:
984 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
986 * where @c iterator represents the type:
987 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
989 * The iterator parameters @c begin and @c end define the range of bytes to be
990 * scanned to determine whether there is a match. The @c first member of the
991 * return value is an iterator marking one-past-the-end of the bytes that have
992 * been consumed by the match function. This iterator is used to calculate the
993 * @c begin parameter for any subsequent invocation of the match condition. The
994 * @c second member of the return value is true if a match has been found, false
997 * @param ec Set to indicate what error occurred, if any.
999 * @returns The number of bytes in the streambuf's get area that have been fully
1000 * consumed by the match function. Returns 0 if an error occurred.
1002 * @note After a successful read_until operation, the streambuf may contain
1003 * additional data beyond that which matched the function object. An application
1004 * will typically leave that data in the streambuf for a subsequent read_until
1005 * operation to examine.
1007 * @note The default implementation of the @c is_match_condition type trait
1008 * evaluates to true for function pointers and function objects with a
1009 * @c result_type typedef. It must be specialised for other user-defined
1012 template <typename SyncReadStream, typename Allocator, typename MatchCondition>
1013 std::size_t read_until(SyncReadStream& s,
1014 boost::asio::basic_streambuf<Allocator>& b,
1015 MatchCondition match_condition, boost::system::error_code& ec,
1016 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
1018 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
1019 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
1020 #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
1022 /// Read data into a dynamic buffer sequence until it contains a specified
1025 * This function is used to read data into the specified dynamic buffer
1026 * sequence until the dynamic buffer sequence's get area contains the specified
1027 * delimiter. The call will block until one of the following conditions is
1030 * @li The get area of the dynamic buffer sequence contains the specified
1033 * @li An error occurred.
1035 * This operation is implemented in terms of zero or more calls to the stream's
1036 * read_some function. If the dynamic buffer sequence's get area already
1037 * contains the delimiter, the function returns immediately.
1039 * @param s The stream from which the data is to be read. The type must support
1040 * the SyncReadStream concept.
1042 * @param buffers The dynamic buffer sequence into which the data will be read.
1044 * @param delim The delimiter character.
1046 * @returns The number of bytes in the dynamic buffer sequence's get area up to
1047 * and including the delimiter.
1049 * @throws boost::system::system_error Thrown on failure.
1051 * @note After a successful read_until operation, the dynamic buffer sequence
1052 * may contain additional data beyond the delimiter. An application will
1053 * typically leave that data in the dynamic buffer sequence for a subsequent
1054 * read_until operation to examine.
1057 * To read data into a @c std::string until a newline is encountered:
1058 * @code std::string data;
1059 * std::string n = boost::asio::read_until(s,
1060 * boost::asio::dynamic_buffer(data), '\n');
1061 * std::string line = data.substr(0, n);
1062 * data.erase(0, n); @endcode
1063 * After the @c read_until operation completes successfully, the string @c data
1064 * contains the delimiter:
1065 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
1066 * The call to @c substr then extracts the data up to and including the
1067 * delimiter, so that the string @c line contains:
1068 * @code { 'a', 'b', ..., 'c', '\n' } @endcode
1069 * After the call to @c erase, the remaining data is left in the buffer @c b as
1071 * @code { 'd', 'e', ... } @endcode
1072 * This data may be the start of a new line, to be extracted by a subsequent
1073 * @c read_until operation.
1075 template <typename SyncReadStream, typename DynamicBuffer_v2>
1076 std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers, char delim,
1078 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1081 /// Read data into a dynamic buffer sequence until it contains a specified
1084 * This function is used to read data into the specified dynamic buffer
1085 * sequence until the dynamic buffer sequence's get area contains the specified
1086 * delimiter. The call will block until one of the following conditions is
1089 * @li The get area of the dynamic buffer sequence contains the specified
1092 * @li An error occurred.
1094 * This operation is implemented in terms of zero or more calls to the stream's
1095 * read_some function. If the dynamic buffer sequence's get area already
1096 * contains the delimiter, the function returns immediately.
1098 * @param s The stream from which the data is to be read. The type must support
1099 * the SyncReadStream concept.
1101 * @param buffers The dynamic buffer sequence into which the data will be read.
1103 * @param delim The delimiter character.
1105 * @param ec Set to indicate what error occurred, if any.
1107 * @returns The number of bytes in the dynamic buffer sequence's get area up to
1108 * and including the delimiter. Returns 0 if an error occurred.
1110 * @note After a successful read_until operation, the dynamic buffer sequence
1111 * may contain additional data beyond the delimiter. An application will
1112 * typically leave that data in the dynamic buffer sequence for a subsequent
1113 * read_until operation to examine.
1115 template <typename SyncReadStream, typename DynamicBuffer_v2>
1116 std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
1117 char delim, boost::system::error_code& ec,
1119 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1122 /// Read data into a dynamic buffer sequence until it contains a specified
1125 * This function is used to read data into the specified dynamic buffer
1126 * sequence until the dynamic buffer sequence's get area contains the specified
1127 * delimiter. The call will block until one of the following conditions is
1130 * @li The get area of the dynamic buffer sequence contains the specified
1133 * @li An error occurred.
1135 * This operation is implemented in terms of zero or more calls to the stream's
1136 * read_some function. If the dynamic buffer sequence's get area already
1137 * contains the delimiter, the function returns immediately.
1139 * @param s The stream from which the data is to be read. The type must support
1140 * the SyncReadStream concept.
1142 * @param buffers The dynamic buffer sequence into which the data will be read.
1144 * @param delim The delimiter string.
1146 * @returns The number of bytes in the dynamic buffer sequence's get area up to
1147 * and including the delimiter.
1149 * @note After a successful read_until operation, the dynamic buffer sequence
1150 * may contain additional data beyond the delimiter. An application will
1151 * typically leave that data in the dynamic buffer sequence for a subsequent
1152 * read_until operation to examine.
1155 * To read data into a @c std::string until a CR-LF sequence is encountered:
1156 * @code std::string data;
1157 * std::string n = boost::asio::read_until(s,
1158 * boost::asio::dynamic_buffer(data), "\r\n");
1159 * std::string line = data.substr(0, n);
1160 * data.erase(0, n); @endcode
1161 * After the @c read_until operation completes successfully, the string @c data
1162 * contains the delimiter:
1163 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
1164 * The call to @c substr then extracts the data up to and including the
1165 * delimiter, so that the string @c line contains:
1166 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
1167 * After the call to @c erase, the remaining data is left in the buffer @c b as
1169 * @code { 'd', 'e', ... } @endcode
1170 * This data may be the start of a new line, to be extracted by a subsequent
1171 * @c read_until operation.
1173 template <typename SyncReadStream, typename DynamicBuffer_v2>
1174 std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
1175 BOOST_ASIO_STRING_VIEW_PARAM delim,
1177 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1180 /// Read data into a dynamic buffer sequence until it contains a specified
1183 * This function is used to read data into the specified dynamic buffer
1184 * sequence until the dynamic buffer sequence's get area contains the specified
1185 * delimiter. The call will block until one of the following conditions is
1188 * @li The get area of the dynamic buffer sequence contains the specified
1191 * @li An error occurred.
1193 * This operation is implemented in terms of zero or more calls to the stream's
1194 * read_some function. If the dynamic buffer sequence's get area already
1195 * contains the delimiter, the function returns immediately.
1197 * @param s The stream from which the data is to be read. The type must support
1198 * the SyncReadStream concept.
1200 * @param buffers The dynamic buffer sequence into which the data will be read.
1202 * @param delim The delimiter string.
1204 * @param ec Set to indicate what error occurred, if any.
1206 * @returns The number of bytes in the dynamic buffer sequence's get area up to
1207 * and including the delimiter. Returns 0 if an error occurred.
1209 * @note After a successful read_until operation, the dynamic buffer sequence
1210 * may contain additional data beyond the delimiter. An application will
1211 * typically leave that data in the dynamic buffer sequence for a subsequent
1212 * read_until operation to examine.
1214 template <typename SyncReadStream, typename DynamicBuffer_v2>
1215 std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
1216 BOOST_ASIO_STRING_VIEW_PARAM delim, boost::system::error_code& ec,
1218 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1221 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
1222 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
1223 || defined(GENERATING_DOCUMENTATION)
1225 /// Read data into a dynamic buffer sequence until some part of the data it
1226 /// contains matches a regular expression.
1228 * This function is used to read data into the specified dynamic buffer
1229 * sequence until the dynamic buffer sequence's get area contains some data
1230 * that matches a regular expression. The call will block until one of the
1231 * following conditions is true:
1233 * @li A substring of the dynamic buffer sequence's get area matches the
1234 * regular expression.
1236 * @li An error occurred.
1238 * This operation is implemented in terms of zero or more calls to the stream's
1239 * read_some function. If the dynamic buffer sequence's get area already
1240 * contains data that matches the regular expression, the function returns
1243 * @param s The stream from which the data is to be read. The type must support
1244 * the SyncReadStream concept.
1246 * @param buffers A dynamic buffer sequence into which the data will be read.
1248 * @param expr The regular expression.
1250 * @returns The number of bytes in the dynamic buffer sequence's get area up to
1251 * and including the substring that matches the regular expression.
1253 * @throws boost::system::system_error Thrown on failure.
1255 * @note After a successful read_until operation, the dynamic buffer sequence
1256 * may contain additional data beyond that which matched the regular
1257 * expression. An application will typically leave that data in the dynamic
1258 * buffer sequence for a subsequent read_until operation to examine.
1261 * To read data into a @c std::string until a CR-LF sequence is encountered:
1262 * @code std::string data;
1263 * std::string n = boost::asio::read_until(s,
1264 * boost::asio::dynamic_buffer(data), boost::regex("\r\n"));
1265 * std::string line = data.substr(0, n);
1266 * data.erase(0, n); @endcode
1267 * After the @c read_until operation completes successfully, the string @c data
1268 * contains the delimiter:
1269 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
1270 * The call to @c substr then extracts the data up to and including the
1271 * delimiter, so that the string @c line contains:
1272 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
1273 * After the call to @c erase, the remaining data is left in the buffer @c b as
1275 * @code { 'd', 'e', ... } @endcode
1276 * This data may be the start of a new line, to be extracted by a subsequent
1277 * @c read_until operation.
1279 template <typename SyncReadStream, typename DynamicBuffer_v2>
1280 std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
1281 const boost::regex& expr,
1283 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1286 /// Read data into a dynamic buffer sequence until some part of the data it
1287 /// contains matches a regular expression.
1289 * This function is used to read data into the specified dynamic buffer
1290 * sequence until the dynamic buffer sequence's get area contains some data
1291 * that matches a regular expression. The call will block until one of the
1292 * following conditions is true:
1294 * @li A substring of the dynamic buffer sequence's get area matches the
1295 * regular expression.
1297 * @li An error occurred.
1299 * This operation is implemented in terms of zero or more calls to the stream's
1300 * read_some function. If the dynamic buffer sequence's get area already
1301 * contains data that matches the regular expression, the function returns
1304 * @param s The stream from which the data is to be read. The type must support
1305 * the SyncReadStream concept.
1307 * @param buffers A dynamic buffer sequence into which the data will be read.
1309 * @param expr The regular expression.
1311 * @param ec Set to indicate what error occurred, if any.
1313 * @returns The number of bytes in the dynamic buffer sequence's get area up to
1314 * and including the substring that matches the regular expression. Returns 0
1315 * if an error occurred.
1317 * @note After a successful read_until operation, the dynamic buffer sequence
1318 * may contain additional data beyond that which matched the regular
1319 * expression. An application will typically leave that data in the dynamic
1320 * buffer sequence for a subsequent read_until operation to examine.
1322 template <typename SyncReadStream, typename DynamicBuffer_v2>
1323 std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
1324 const boost::regex& expr, boost::system::error_code& ec,
1326 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1329 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
1330 // || defined(GENERATING_DOCUMENTATION)
1332 /// Read data into a dynamic buffer sequence until a function object indicates a
1336 * This function is used to read data into the specified dynamic buffer
1337 * sequence until a user-defined match condition function object, when applied
1338 * to the data contained in the dynamic buffer sequence, indicates a successful
1339 * match. The call will block until one of the following conditions is true:
1341 * @li The match condition function object returns a std::pair where the second
1342 * element evaluates to true.
1344 * @li An error occurred.
1346 * This operation is implemented in terms of zero or more calls to the stream's
1347 * read_some function. If the match condition function object already indicates
1348 * a match, the function returns immediately.
1350 * @param s The stream from which the data is to be read. The type must support
1351 * the SyncReadStream concept.
1353 * @param buffers A dynamic buffer sequence into which the data will be read.
1355 * @param match_condition The function object to be called to determine whether
1356 * a match exists. The signature of the function object must be:
1357 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
1359 * where @c iterator represents the type:
1360 * @code buffers_iterator<typename DynamicBuffer_v2::const_buffers_type>
1362 * The iterator parameters @c begin and @c end define the range of bytes to be
1363 * scanned to determine whether there is a match. The @c first member of the
1364 * return value is an iterator marking one-past-the-end of the bytes that have
1365 * been consumed by the match function. This iterator is used to calculate the
1366 * @c begin parameter for any subsequent invocation of the match condition. The
1367 * @c second member of the return value is true if a match has been found, false
1370 * @returns The number of bytes in the dynamic_buffer's get area that
1371 * have been fully consumed by the match function.
1373 * @throws boost::system::system_error Thrown on failure.
1375 * @note After a successful read_until operation, the dynamic buffer sequence
1376 * may contain additional data beyond that which matched the function object.
1377 * An application will typically leave that data in the dynamic buffer sequence
1378 * for a subsequent read_until operation to examine.
1380 * @note The default implementation of the @c is_match_condition type trait
1381 * evaluates to true for function pointers and function objects with a
1382 * @c result_type typedef. It must be specialised for other user-defined
1386 * To read data into a dynamic buffer sequence until whitespace is encountered:
1387 * @code typedef boost::asio::buffers_iterator<
1388 * boost::asio::const_buffers_1> iterator;
1390 * std::pair<iterator, bool>
1391 * match_whitespace(iterator begin, iterator end)
1393 * iterator i = begin;
1395 * if (std::isspace(*i++))
1396 * return std::make_pair(i, true);
1397 * return std::make_pair(i, false);
1401 * boost::asio::read_until(s, data, match_whitespace);
1404 * To read data into a @c std::string until a matching character is found:
1405 * @code class match_char
1408 * explicit match_char(char c) : c_(c) {}
1410 * template <typename Iterator>
1411 * std::pair<Iterator, bool> operator()(
1412 * Iterator begin, Iterator end) const
1414 * Iterator i = begin;
1417 * return std::make_pair(i, true);
1418 * return std::make_pair(i, false);
1426 * template <> struct is_match_condition<match_char>
1427 * : public boost::true_type {};
1428 * } // namespace asio
1431 * boost::asio::read_until(s, data, match_char('a'));
1434 template <typename SyncReadStream,
1435 typename DynamicBuffer_v2, typename MatchCondition>
1436 std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
1437 MatchCondition match_condition,
1439 is_match_condition<MatchCondition>::value
1440 && is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1443 /// Read data into a dynamic buffer sequence until a function object indicates a
1446 * This function is used to read data into the specified dynamic buffer
1447 * sequence until a user-defined match condition function object, when applied
1448 * to the data contained in the dynamic buffer sequence, indicates a successful
1449 * match. The call will block until one of the following conditions is true:
1451 * @li The match condition function object returns a std::pair where the second
1452 * element evaluates to true.
1454 * @li An error occurred.
1456 * This operation is implemented in terms of zero or more calls to the stream's
1457 * read_some function. If the match condition function object already indicates
1458 * a match, the function returns immediately.
1460 * @param s The stream from which the data is to be read. The type must support
1461 * the SyncReadStream concept.
1463 * @param buffers A dynamic buffer sequence into which the data will be read.
1465 * @param match_condition The function object to be called to determine whether
1466 * a match exists. The signature of the function object must be:
1467 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
1469 * where @c iterator represents the type:
1470 * @code buffers_iterator<DynamicBuffer_v2::const_buffers_type>
1472 * The iterator parameters @c begin and @c end define the range of bytes to be
1473 * scanned to determine whether there is a match. The @c first member of the
1474 * return value is an iterator marking one-past-the-end of the bytes that have
1475 * been consumed by the match function. This iterator is used to calculate the
1476 * @c begin parameter for any subsequent invocation of the match condition. The
1477 * @c second member of the return value is true if a match has been found, false
1480 * @param ec Set to indicate what error occurred, if any.
1482 * @returns The number of bytes in the dynamic buffer sequence's get area that
1483 * have been fully consumed by the match function. Returns 0 if an error
1486 * @note After a successful read_until operation, the dynamic buffer sequence
1487 * may contain additional data beyond that which matched the function object.
1488 * An application will typically leave that data in the dynamic buffer sequence
1489 * for a subsequent read_until operation to examine.
1491 * @note The default implementation of the @c is_match_condition type trait
1492 * evaluates to true for function pointers and function objects with a
1493 * @c result_type typedef. It must be specialised for other user-defined
1496 template <typename SyncReadStream,
1497 typename DynamicBuffer_v2, typename MatchCondition>
1498 std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
1499 MatchCondition match_condition, boost::system::error_code& ec,
1501 is_match_condition<MatchCondition>::value
1502 && is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1505 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
1509 * @defgroup async_read_until boost::asio::async_read_until
1511 * @brief The @c async_read_until function is a composed asynchronous operation
1512 * that reads data into a dynamic buffer sequence, or into a streambuf, until
1513 * it contains a delimiter, matches a regular expression, or a function object
1514 * indicates a match.
1518 #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
1520 /// Start an asynchronous operation to read data into a dynamic buffer sequence
1521 /// until it contains a specified delimiter.
1523 * This function is used to asynchronously read data into the specified dynamic
1524 * buffer sequence until the dynamic buffer sequence's get area contains the
1525 * specified delimiter. The function call always returns immediately. The
1526 * asynchronous operation will continue until one of the following conditions
1529 * @li The get area of the dynamic buffer sequence contains the specified
1532 * @li An error occurred.
1534 * This operation is implemented in terms of zero or more calls to the stream's
1535 * async_read_some function, and is known as a <em>composed operation</em>. If
1536 * the dynamic buffer sequence's get area already contains the delimiter, this
1537 * asynchronous operation completes immediately. The program must ensure that
1538 * the stream performs no other read operations (such as async_read,
1539 * async_read_until, the stream's async_read_some function, or any other
1540 * composed operations that perform reads) until this operation completes.
1542 * @param s The stream from which the data is to be read. The type must support
1543 * the AsyncReadStream concept.
1545 * @param buffers The dynamic buffer sequence into which the data will be read.
1546 * Although the buffers object may be copied as necessary, ownership of the
1547 * underlying memory blocks is retained by the caller, which must guarantee
1548 * that they remain valid until the handler is called.
1550 * @param delim The delimiter character.
1552 * @param handler The handler to be called when the read operation completes.
1553 * Copies will be made of the handler as required. The function signature of the
1555 * @code void handler(
1556 * // Result of operation.
1557 * const boost::system::error_code& error,
1559 * // The number of bytes in the dynamic buffer sequence's
1560 * // get area up to and including the delimiter.
1561 * // 0 if an error occurred.
1562 * std::size_t bytes_transferred
1564 * Regardless of whether the asynchronous operation completes immediately or
1565 * not, the handler will not be invoked from within this function. On
1566 * immediate completion, invocation of the handler will be performed in a
1567 * manner equivalent to using boost::asio::post().
1569 * @note After a successful async_read_until operation, the dynamic buffer
1570 * sequence may contain additional data beyond the delimiter. An application
1571 * will typically leave that data in the dynamic buffer sequence for a
1572 * subsequent async_read_until operation to examine.
1575 * To asynchronously read data into a @c std::string until a newline is
1577 * @code std::string data;
1579 * void handler(const boost::system::error_code& e, std::size_t size)
1583 * std::string line = data.substr(0, n);
1589 * boost::asio::async_read_until(s, data, '\n', handler); @endcode
1590 * After the @c async_read_until operation completes successfully, the buffer
1591 * @c data contains the delimiter:
1592 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
1593 * The call to @c substr then extracts the data up to and including the
1594 * delimiter, so that the string @c line contains:
1595 * @code { 'a', 'b', ..., 'c', '\n' } @endcode
1596 * After the call to @c erase, the remaining data is left in the buffer @c data
1598 * @code { 'd', 'e', ... } @endcode
1599 * This data may be the start of a new line, to be extracted by a subsequent
1600 * @c async_read_until operation.
1602 template <typename AsyncReadStream,
1603 typename DynamicBuffer_v1, typename ReadHandler>
1604 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
1605 void (boost::system::error_code, std::size_t))
1606 async_read_until(AsyncReadStream& s,
1607 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
1608 char delim, BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
1610 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
1611 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
1614 /// Start an asynchronous operation to read data into a dynamic buffer sequence
1615 /// until it contains a specified delimiter.
1617 * This function is used to asynchronously read data into the specified dynamic
1618 * buffer sequence until the dynamic buffer sequence's get area contains the
1619 * specified delimiter. The function call always returns immediately. The
1620 * asynchronous operation will continue until one of the following conditions
1623 * @li The get area of the dynamic buffer sequence contains the specified
1626 * @li An error occurred.
1628 * This operation is implemented in terms of zero or more calls to the stream's
1629 * async_read_some function, and is known as a <em>composed operation</em>. If
1630 * the dynamic buffer sequence's get area already contains the delimiter, this
1631 * asynchronous operation completes immediately. The program must ensure that
1632 * the stream performs no other read operations (such as async_read,
1633 * async_read_until, the stream's async_read_some function, or any other
1634 * composed operations that perform reads) until this operation completes.
1636 * @param s The stream from which the data is to be read. The type must support
1637 * the AsyncReadStream concept.
1639 * @param buffers The dynamic buffer sequence into which the data will be read.
1640 * Although the buffers object may be copied as necessary, ownership of the
1641 * underlying memory blocks is retained by the caller, which must guarantee
1642 * that they remain valid until the handler is called.
1644 * @param delim The delimiter string.
1646 * @param handler The handler to be called when the read operation completes.
1647 * Copies will be made of the handler as required. The function signature of the
1649 * @code void handler(
1650 * // Result of operation.
1651 * const boost::system::error_code& error,
1653 * // The number of bytes in the dynamic buffer sequence's
1654 * // get area up to and including the delimiter.
1655 * // 0 if an error occurred.
1656 * std::size_t bytes_transferred
1658 * Regardless of whether the asynchronous operation completes immediately or
1659 * not, the handler will not be invoked from within this function. On
1660 * immediate completion, invocation of the handler will be performed in a
1661 * manner equivalent to using boost::asio::post().
1663 * @note After a successful async_read_until operation, the dynamic buffer
1664 * sequence may contain additional data beyond the delimiter. An application
1665 * will typically leave that data in the dynamic buffer sequence for a
1666 * subsequent async_read_until operation to examine.
1669 * To asynchronously read data into a @c std::string until a CR-LF sequence is
1671 * @code std::string data;
1673 * void handler(const boost::system::error_code& e, std::size_t size)
1677 * std::string line = data.substr(0, n);
1683 * boost::asio::async_read_until(s, data, "\r\n", handler); @endcode
1684 * After the @c async_read_until operation completes successfully, the string
1685 * @c data contains the delimiter:
1686 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
1687 * The call to @c substr then extracts the data up to and including the
1688 * delimiter, so that the string @c line contains:
1689 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
1690 * After the call to @c erase, the remaining data is left in the string @c data
1692 * @code { 'd', 'e', ... } @endcode
1693 * This data may be the start of a new line, to be extracted by a subsequent
1694 * @c async_read_until operation.
1696 template <typename AsyncReadStream,
1697 typename DynamicBuffer_v1, typename ReadHandler>
1698 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
1699 void (boost::system::error_code, std::size_t))
1700 async_read_until(AsyncReadStream& s,
1701 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
1702 BOOST_ASIO_STRING_VIEW_PARAM delim,
1703 BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
1705 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
1706 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
1709 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
1710 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
1711 || defined(GENERATING_DOCUMENTATION)
1713 /// Start an asynchronous operation to read data into a dynamic buffer sequence
1714 /// until some part of its data matches a regular expression.
1716 * This function is used to asynchronously read data into the specified dynamic
1717 * buffer sequence until the dynamic buffer sequence's get area contains some
1718 * data that matches a regular expression. The function call always returns
1719 * immediately. The asynchronous operation will continue until one of the
1720 * following conditions is true:
1722 * @li A substring of the dynamic buffer sequence's get area matches the regular
1725 * @li An error occurred.
1727 * This operation is implemented in terms of zero or more calls to the stream's
1728 * async_read_some function, and is known as a <em>composed operation</em>. If
1729 * the dynamic buffer sequence's get area already contains data that matches
1730 * the regular expression, this asynchronous operation completes immediately.
1731 * The program must ensure that the stream performs no other read operations
1732 * (such as async_read, async_read_until, the stream's async_read_some
1733 * function, or any other composed operations that perform reads) until this
1734 * operation completes.
1736 * @param s The stream from which the data is to be read. The type must support
1737 * the AsyncReadStream concept.
1739 * @param buffers The dynamic buffer sequence into which the data will be read.
1740 * Although the buffers object may be copied as necessary, ownership of the
1741 * underlying memory blocks is retained by the caller, which must guarantee
1742 * that they remain valid until the handler is called.
1744 * @param expr The regular expression.
1746 * @param handler The handler to be called when the read operation completes.
1747 * Copies will be made of the handler as required. The function signature of the
1749 * @code void handler(
1750 * // Result of operation.
1751 * const boost::system::error_code& error,
1753 * // The number of bytes in the dynamic buffer
1754 * // sequence's get area up to and including the
1755 * // substring that matches the regular expression.
1756 * // 0 if an error occurred.
1757 * std::size_t bytes_transferred
1759 * Regardless of whether the asynchronous operation completes immediately or
1760 * not, the handler will not be invoked from within this function. On
1761 * immediate completion, invocation of the handler will be performed in a
1762 * manner equivalent to using boost::asio::post().
1764 * @note After a successful async_read_until operation, the dynamic buffer
1765 * sequence may contain additional data beyond that which matched the regular
1766 * expression. An application will typically leave that data in the dynamic
1767 * buffer sequence for a subsequent async_read_until operation to examine.
1770 * To asynchronously read data into a @c std::string until a CR-LF sequence is
1772 * @code std::string data;
1774 * void handler(const boost::system::error_code& e, std::size_t size)
1778 * std::string line = data.substr(0, n);
1784 * boost::asio::async_read_until(s, data,
1785 * boost::regex("\r\n"), handler); @endcode
1786 * After the @c async_read_until operation completes successfully, the string
1787 * @c data contains the data which matched the regular expression:
1788 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
1789 * The call to @c substr then extracts the data up to and including the match,
1790 * so that the string @c line contains:
1791 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
1792 * After the call to @c erase, the remaining data is left in the string @c data
1794 * @code { 'd', 'e', ... } @endcode
1795 * This data may be the start of a new line, to be extracted by a subsequent
1796 * @c async_read_until operation.
1798 template <typename AsyncReadStream,
1799 typename DynamicBuffer_v1, typename ReadHandler>
1800 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
1801 void (boost::system::error_code, std::size_t))
1802 async_read_until(AsyncReadStream& s,
1803 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
1804 const boost::regex& expr,
1805 BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
1807 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
1808 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
1811 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
1812 // || defined(GENERATING_DOCUMENTATION)
1814 /// Start an asynchronous operation to read data into a dynamic buffer sequence
1815 /// until a function object indicates a match.
1817 * This function is used to asynchronously read data into the specified dynamic
1818 * buffer sequence until a user-defined match condition function object, when
1819 * applied to the data contained in the dynamic buffer sequence, indicates a
1820 * successful match. The function call always returns immediately. The
1821 * asynchronous operation will continue until one of the following conditions
1824 * @li The match condition function object returns a std::pair where the second
1825 * element evaluates to true.
1827 * @li An error occurred.
1829 * This operation is implemented in terms of zero or more calls to the stream's
1830 * async_read_some function, and is known as a <em>composed operation</em>. If
1831 * the match condition function object already indicates a match, this
1832 * asynchronous operation completes immediately. The program must ensure that
1833 * the stream performs no other read operations (such as async_read,
1834 * async_read_until, the stream's async_read_some function, or any other
1835 * composed operations that perform reads) until this operation completes.
1837 * @param s The stream from which the data is to be read. The type must support
1838 * the AsyncReadStream concept.
1840 * @param buffers The dynamic buffer sequence into which the data will be read.
1841 * Although the buffers object may be copied as necessary, ownership of the
1842 * underlying memory blocks is retained by the caller, which must guarantee
1843 * that they remain valid until the handler is called.
1845 * @param match_condition The function object to be called to determine whether
1846 * a match exists. The signature of the function object must be:
1847 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
1849 * where @c iterator represents the type:
1850 * @code buffers_iterator<typename DynamicBuffer_v1::const_buffers_type>
1852 * The iterator parameters @c begin and @c end define the range of bytes to be
1853 * scanned to determine whether there is a match. The @c first member of the
1854 * return value is an iterator marking one-past-the-end of the bytes that have
1855 * been consumed by the match function. This iterator is used to calculate the
1856 * @c begin parameter for any subsequent invocation of the match condition. The
1857 * @c second member of the return value is true if a match has been found, false
1860 * @param handler The handler to be called when the read operation completes.
1861 * Copies will be made of the handler as required. The function signature of the
1863 * @code void handler(
1864 * // Result of operation.
1865 * const boost::system::error_code& error,
1867 * // The number of bytes in the dynamic buffer sequence's
1868 * // get area that have been fully consumed by the match
1869 * // function. O if an error occurred.
1870 * std::size_t bytes_transferred
1872 * Regardless of whether the asynchronous operation completes immediately or
1873 * not, the handler will not be invoked from within this function. On
1874 * immediate completion, invocation of the handler will be performed in a
1875 * manner equivalent to using boost::asio::post().
1877 * @note After a successful async_read_until operation, the dynamic buffer
1878 * sequence may contain additional data beyond that which matched the function
1879 * object. An application will typically leave that data in the dynamic buffer
1880 * sequence for a subsequent async_read_until operation to examine.
1882 * @note The default implementation of the @c is_match_condition type trait
1883 * evaluates to true for function pointers and function objects with a
1884 * @c result_type typedef. It must be specialised for other user-defined
1888 * To asynchronously read data into a @c std::string until whitespace is
1890 * @code typedef boost::asio::buffers_iterator<
1891 * boost::asio::const_buffers_1> iterator;
1893 * std::pair<iterator, bool>
1894 * match_whitespace(iterator begin, iterator end)
1896 * iterator i = begin;
1898 * if (std::isspace(*i++))
1899 * return std::make_pair(i, true);
1900 * return std::make_pair(i, false);
1903 * void handler(const boost::system::error_code& e, std::size_t size);
1906 * boost::asio::async_read_until(s, data, match_whitespace, handler);
1909 * To asynchronously read data into a @c std::string until a matching character
1911 * @code class match_char
1914 * explicit match_char(char c) : c_(c) {}
1916 * template <typename Iterator>
1917 * std::pair<Iterator, bool> operator()(
1918 * Iterator begin, Iterator end) const
1920 * Iterator i = begin;
1923 * return std::make_pair(i, true);
1924 * return std::make_pair(i, false);
1932 * template <> struct is_match_condition<match_char>
1933 * : public boost::true_type {};
1934 * } // namespace asio
1936 * void handler(const boost::system::error_code& e, std::size_t size);
1939 * boost::asio::async_read_until(s, data, match_char('a'), handler);
1942 template <typename AsyncReadStream, typename DynamicBuffer_v1,
1943 typename MatchCondition, typename ReadHandler>
1944 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
1945 void (boost::system::error_code, std::size_t))
1946 async_read_until(AsyncReadStream& s,
1947 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
1948 MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
1950 is_match_condition<MatchCondition>::value
1951 && is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
1952 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
1955 #if !defined(BOOST_ASIO_NO_IOSTREAM)
1957 /// Start an asynchronous operation to read data into a streambuf until it
1958 /// contains a specified delimiter.
1960 * This function is used to asynchronously read data into the specified
1961 * streambuf until the streambuf's get area contains the specified delimiter.
1962 * The function call always returns immediately. The asynchronous operation
1963 * will continue until one of the following conditions is true:
1965 * @li The get area of the streambuf contains the specified delimiter.
1967 * @li An error occurred.
1969 * This operation is implemented in terms of zero or more calls to the stream's
1970 * async_read_some function, and is known as a <em>composed operation</em>. If
1971 * the streambuf's get area already contains the delimiter, this asynchronous
1972 * operation completes immediately. The program must ensure that the stream
1973 * performs no other read operations (such as async_read, async_read_until, the
1974 * stream's async_read_some function, or any other composed operations that
1975 * perform reads) until this operation completes.
1977 * @param s The stream from which the data is to be read. The type must support
1978 * the AsyncReadStream concept.
1980 * @param b A streambuf object into which the data will be read. Ownership of
1981 * the streambuf is retained by the caller, which must guarantee that it remains
1982 * valid until the handler is called.
1984 * @param delim The delimiter character.
1986 * @param handler The handler to be called when the read operation completes.
1987 * Copies will be made of the handler as required. The function signature of the
1989 * @code void handler(
1990 * // Result of operation.
1991 * const boost::system::error_code& error,
1993 * // The number of bytes in the streambuf's get
1994 * // area up to and including the delimiter.
1995 * // 0 if an error occurred.
1996 * std::size_t bytes_transferred
1998 * Regardless of whether the asynchronous operation completes immediately or
1999 * not, the handler will not be invoked from within this function. On
2000 * immediate completion, invocation of the handler will be performed in a
2001 * manner equivalent to using boost::asio::post().
2003 * @note After a successful async_read_until operation, the streambuf may
2004 * contain additional data beyond the delimiter. An application will typically
2005 * leave that data in the streambuf for a subsequent async_read_until operation
2009 * To asynchronously read data into a streambuf until a newline is encountered:
2010 * @code boost::asio::streambuf b;
2012 * void handler(const boost::system::error_code& e, std::size_t size)
2016 * std::istream is(&b);
2018 * std::getline(is, line);
2023 * boost::asio::async_read_until(s, b, '\n', handler); @endcode
2024 * After the @c async_read_until operation completes successfully, the buffer
2025 * @c b contains the delimiter:
2026 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
2027 * The call to @c std::getline then extracts the data up to and including the
2028 * newline (which is discarded), so that the string @c line contains:
2029 * @code { 'a', 'b', ..., 'c' } @endcode
2030 * The remaining data is left in the buffer @c b as follows:
2031 * @code { 'd', 'e', ... } @endcode
2032 * This data may be the start of a new line, to be extracted by a subsequent
2033 * @c async_read_until operation.
2035 template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
2036 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
2037 void (boost::system::error_code, std::size_t))
2038 async_read_until(AsyncReadStream& s,
2039 boost::asio::basic_streambuf<Allocator>& b,
2040 char delim, BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
2042 /// Start an asynchronous operation to read data into a streambuf until it
2043 /// contains a specified delimiter.
2045 * This function is used to asynchronously read data into the specified
2046 * streambuf until the streambuf's get area contains the specified delimiter.
2047 * The function call always returns immediately. The asynchronous operation
2048 * will continue until one of the following conditions is true:
2050 * @li The get area of the streambuf contains the specified delimiter.
2052 * @li An error occurred.
2054 * This operation is implemented in terms of zero or more calls to the stream's
2055 * async_read_some function, and is known as a <em>composed operation</em>. If
2056 * the streambuf's get area already contains the delimiter, this asynchronous
2057 * operation completes immediately. The program must ensure that the stream
2058 * performs no other read operations (such as async_read, async_read_until, the
2059 * stream's async_read_some function, or any other composed operations that
2060 * perform reads) until this operation completes.
2062 * @param s The stream from which the data is to be read. The type must support
2063 * the AsyncReadStream concept.
2065 * @param b A streambuf object into which the data will be read. Ownership of
2066 * the streambuf is retained by the caller, which must guarantee that it remains
2067 * valid until the handler is called.
2069 * @param delim The delimiter string.
2071 * @param handler The handler to be called when the read operation completes.
2072 * Copies will be made of the handler as required. The function signature of the
2074 * @code void handler(
2075 * // Result of operation.
2076 * const boost::system::error_code& error,
2078 * // The number of bytes in the streambuf's get
2079 * // area up to and including the delimiter.
2080 * // 0 if an error occurred.
2081 * std::size_t bytes_transferred
2083 * Regardless of whether the asynchronous operation completes immediately or
2084 * not, the handler will not be invoked from within this function. On
2085 * immediate completion, invocation of the handler will be performed in a
2086 * manner equivalent to using boost::asio::post().
2088 * @note After a successful async_read_until operation, the streambuf may
2089 * contain additional data beyond the delimiter. An application will typically
2090 * leave that data in the streambuf for a subsequent async_read_until operation
2094 * To asynchronously read data into a streambuf until a newline is encountered:
2095 * @code boost::asio::streambuf b;
2097 * void handler(const boost::system::error_code& e, std::size_t size)
2101 * std::istream is(&b);
2103 * std::getline(is, line);
2108 * boost::asio::async_read_until(s, b, "\r\n", handler); @endcode
2109 * After the @c async_read_until operation completes successfully, the buffer
2110 * @c b contains the delimiter:
2111 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
2112 * The call to @c std::getline then extracts the data up to and including the
2113 * newline (which is discarded), so that the string @c line contains:
2114 * @code { 'a', 'b', ..., 'c', '\r' } @endcode
2115 * The remaining data is left in the buffer @c b as follows:
2116 * @code { 'd', 'e', ... } @endcode
2117 * This data may be the start of a new line, to be extracted by a subsequent
2118 * @c async_read_until operation.
2120 template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
2121 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
2122 void (boost::system::error_code, std::size_t))
2123 async_read_until(AsyncReadStream& s,
2124 boost::asio::basic_streambuf<Allocator>& b,
2125 BOOST_ASIO_STRING_VIEW_PARAM delim,
2126 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
2128 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
2129 || defined(GENERATING_DOCUMENTATION)
2131 /// Start an asynchronous operation to read data into a streambuf until some
2132 /// part of its data matches a regular expression.
2134 * This function is used to asynchronously read data into the specified
2135 * streambuf until the streambuf's get area contains some data that matches a
2136 * regular expression. The function call always returns immediately. The
2137 * asynchronous operation will continue until one of the following conditions
2140 * @li A substring of the streambuf's get area matches the regular expression.
2142 * @li An error occurred.
2144 * This operation is implemented in terms of zero or more calls to the stream's
2145 * async_read_some function, and is known as a <em>composed operation</em>. If
2146 * the streambuf's get area already contains data that matches the regular
2147 * expression, this asynchronous operation completes immediately. The program
2148 * must ensure that the stream performs no other read operations (such as
2149 * async_read, async_read_until, the stream's async_read_some function, or any
2150 * other composed operations that perform reads) until this operation
2153 * @param s The stream from which the data is to be read. The type must support
2154 * the AsyncReadStream concept.
2156 * @param b A streambuf object into which the data will be read. Ownership of
2157 * the streambuf is retained by the caller, which must guarantee that it remains
2158 * valid until the handler is called.
2160 * @param expr The regular expression.
2162 * @param handler The handler to be called when the read operation completes.
2163 * Copies will be made of the handler as required. The function signature of the
2165 * @code void handler(
2166 * // Result of operation.
2167 * const boost::system::error_code& error,
2169 * // The number of bytes in the streambuf's get
2170 * // area up to and including the substring
2171 * // that matches the regular. expression.
2172 * // 0 if an error occurred.
2173 * std::size_t bytes_transferred
2175 * Regardless of whether the asynchronous operation completes immediately or
2176 * not, the handler will not be invoked from within this function. On
2177 * immediate completion, invocation of the handler will be performed in a
2178 * manner equivalent to using boost::asio::post().
2180 * @note After a successful async_read_until operation, the streambuf may
2181 * contain additional data beyond that which matched the regular expression. An
2182 * application will typically leave that data in the streambuf for a subsequent
2183 * async_read_until operation to examine.
2186 * To asynchronously read data into a streambuf until a CR-LF sequence is
2188 * @code boost::asio::streambuf b;
2190 * void handler(const boost::system::error_code& e, std::size_t size)
2194 * std::istream is(&b);
2196 * std::getline(is, line);
2201 * boost::asio::async_read_until(s, b, boost::regex("\r\n"), handler); @endcode
2202 * After the @c async_read_until operation completes successfully, the buffer
2203 * @c b contains the data which matched the regular expression:
2204 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
2205 * The call to @c std::getline then extracts the data up to and including the
2206 * newline (which is discarded), so that the string @c line contains:
2207 * @code { 'a', 'b', ..., 'c', '\r' } @endcode
2208 * The remaining data is left in the buffer @c b as follows:
2209 * @code { 'd', 'e', ... } @endcode
2210 * This data may be the start of a new line, to be extracted by a subsequent
2211 * @c async_read_until operation.
2213 template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
2214 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
2215 void (boost::system::error_code, std::size_t))
2216 async_read_until(AsyncReadStream& s,
2217 boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr,
2218 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
2220 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
2221 // || defined(GENERATING_DOCUMENTATION)
2223 /// Start an asynchronous operation to read data into a streambuf until a
2224 /// function object indicates a match.
2226 * This function is used to asynchronously read data into the specified
2227 * streambuf until a user-defined match condition function object, when applied
2228 * to the data contained in the streambuf, indicates a successful match. The
2229 * function call always returns immediately. The asynchronous operation will
2230 * continue until one of the following conditions is true:
2232 * @li The match condition function object returns a std::pair where the second
2233 * element evaluates to true.
2235 * @li An error occurred.
2237 * This operation is implemented in terms of zero or more calls to the stream's
2238 * async_read_some function, and is known as a <em>composed operation</em>. If
2239 * the match condition function object already indicates a match, this
2240 * asynchronous operation completes immediately. The program must ensure that
2241 * the stream performs no other read operations (such as async_read,
2242 * async_read_until, the stream's async_read_some function, or any other
2243 * composed operations that perform reads) until this operation completes.
2245 * @param s The stream from which the data is to be read. The type must support
2246 * the AsyncReadStream concept.
2248 * @param b A streambuf object into which the data will be read.
2250 * @param match_condition The function object to be called to determine whether
2251 * a match exists. The signature of the function object must be:
2252 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
2254 * where @c iterator represents the type:
2255 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
2257 * The iterator parameters @c begin and @c end define the range of bytes to be
2258 * scanned to determine whether there is a match. The @c first member of the
2259 * return value is an iterator marking one-past-the-end of the bytes that have
2260 * been consumed by the match function. This iterator is used to calculate the
2261 * @c begin parameter for any subsequent invocation of the match condition. The
2262 * @c second member of the return value is true if a match has been found, false
2265 * @param handler The handler to be called when the read operation completes.
2266 * Copies will be made of the handler as required. The function signature of the
2268 * @code void handler(
2269 * // Result of operation.
2270 * const boost::system::error_code& error,
2272 * // The number of bytes in the streambuf's get
2273 * // area that have been fully consumed by the
2274 * // match function. O if an error occurred.
2275 * std::size_t bytes_transferred
2277 * Regardless of whether the asynchronous operation completes immediately or
2278 * not, the handler will not be invoked from within this function. On
2279 * immediate completion, invocation of the handler will be performed in a
2280 * manner equivalent to using boost::asio::post().
2282 * @note After a successful async_read_until operation, the streambuf may
2283 * contain additional data beyond that which matched the function object. An
2284 * application will typically leave that data in the streambuf for a subsequent
2285 * async_read_until operation to examine.
2287 * @note The default implementation of the @c is_match_condition type trait
2288 * evaluates to true for function pointers and function objects with a
2289 * @c result_type typedef. It must be specialised for other user-defined
2293 * To asynchronously read data into a streambuf until whitespace is encountered:
2294 * @code typedef boost::asio::buffers_iterator<
2295 * boost::asio::streambuf::const_buffers_type> iterator;
2297 * std::pair<iterator, bool>
2298 * match_whitespace(iterator begin, iterator end)
2300 * iterator i = begin;
2302 * if (std::isspace(*i++))
2303 * return std::make_pair(i, true);
2304 * return std::make_pair(i, false);
2307 * void handler(const boost::system::error_code& e, std::size_t size);
2309 * boost::asio::streambuf b;
2310 * boost::asio::async_read_until(s, b, match_whitespace, handler);
2313 * To asynchronously read data into a streambuf until a matching character is
2315 * @code class match_char
2318 * explicit match_char(char c) : c_(c) {}
2320 * template <typename Iterator>
2321 * std::pair<Iterator, bool> operator()(
2322 * Iterator begin, Iterator end) const
2324 * Iterator i = begin;
2327 * return std::make_pair(i, true);
2328 * return std::make_pair(i, false);
2336 * template <> struct is_match_condition<match_char>
2337 * : public boost::true_type {};
2338 * } // namespace asio
2340 * void handler(const boost::system::error_code& e, std::size_t size);
2342 * boost::asio::streambuf b;
2343 * boost::asio::async_read_until(s, b, match_char('a'), handler);
2346 template <typename AsyncReadStream, typename Allocator,
2347 typename MatchCondition, typename ReadHandler>
2348 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
2349 void (boost::system::error_code, std::size_t))
2350 async_read_until(AsyncReadStream& s,
2351 boost::asio::basic_streambuf<Allocator>& b,
2352 MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
2353 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
2355 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
2356 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
2357 #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
2359 /// Start an asynchronous operation to read data into a dynamic buffer sequence
2360 /// until it contains a specified delimiter.
2362 * This function is used to asynchronously read data into the specified dynamic
2363 * buffer sequence until the dynamic buffer sequence's get area contains the
2364 * specified delimiter. The function call always returns immediately. The
2365 * asynchronous operation will continue until one of the following conditions
2368 * @li The get area of the dynamic buffer sequence contains the specified
2371 * @li An error occurred.
2373 * This operation is implemented in terms of zero or more calls to the stream's
2374 * async_read_some function, and is known as a <em>composed operation</em>. If
2375 * the dynamic buffer sequence's get area already contains the delimiter, this
2376 * asynchronous operation completes immediately. The program must ensure that
2377 * the stream performs no other read operations (such as async_read,
2378 * async_read_until, the stream's async_read_some function, or any other
2379 * composed operations that perform reads) until this operation completes.
2381 * @param s The stream from which the data is to be read. The type must support
2382 * the AsyncReadStream concept.
2384 * @param buffers The dynamic buffer sequence into which the data will be read.
2385 * Although the buffers object may be copied as necessary, ownership of the
2386 * underlying memory blocks is retained by the caller, which must guarantee
2387 * that they remain valid until the handler is called.
2389 * @param delim The delimiter character.
2391 * @param handler The handler to be called when the read operation completes.
2392 * Copies will be made of the handler as required. The function signature of the
2394 * @code void handler(
2395 * // Result of operation.
2396 * const boost::system::error_code& error,
2398 * // The number of bytes in the dynamic buffer sequence's
2399 * // get area up to and including the delimiter.
2400 * // 0 if an error occurred.
2401 * std::size_t bytes_transferred
2403 * Regardless of whether the asynchronous operation completes immediately or
2404 * not, the handler will not be invoked from within this function. On
2405 * immediate completion, invocation of the handler will be performed in a
2406 * manner equivalent to using boost::asio::post().
2408 * @note After a successful async_read_until operation, the dynamic buffer
2409 * sequence may contain additional data beyond the delimiter. An application
2410 * will typically leave that data in the dynamic buffer sequence for a
2411 * subsequent async_read_until operation to examine.
2414 * To asynchronously read data into a @c std::string until a newline is
2416 * @code std::string data;
2418 * void handler(const boost::system::error_code& e, std::size_t size)
2422 * std::string line = data.substr(0, n);
2428 * boost::asio::async_read_until(s, data, '\n', handler); @endcode
2429 * After the @c async_read_until operation completes successfully, the buffer
2430 * @c data contains the delimiter:
2431 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
2432 * The call to @c substr then extracts the data up to and including the
2433 * delimiter, so that the string @c line contains:
2434 * @code { 'a', 'b', ..., 'c', '\n' } @endcode
2435 * After the call to @c erase, the remaining data is left in the buffer @c data
2437 * @code { 'd', 'e', ... } @endcode
2438 * This data may be the start of a new line, to be extracted by a subsequent
2439 * @c async_read_until operation.
2441 template <typename AsyncReadStream,
2442 typename DynamicBuffer_v2, typename ReadHandler>
2443 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
2444 void (boost::system::error_code, std::size_t))
2445 async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers,
2446 char delim, BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
2448 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
2451 /// Start an asynchronous operation to read data into a dynamic buffer sequence
2452 /// until it contains a specified delimiter.
2454 * This function is used to asynchronously read data into the specified dynamic
2455 * buffer sequence until the dynamic buffer sequence's get area contains the
2456 * specified delimiter. The function call always returns immediately. The
2457 * asynchronous operation will continue until one of the following conditions
2460 * @li The get area of the dynamic buffer sequence contains the specified
2463 * @li An error occurred.
2465 * This operation is implemented in terms of zero or more calls to the stream's
2466 * async_read_some function, and is known as a <em>composed operation</em>. If
2467 * the dynamic buffer sequence's get area already contains the delimiter, this
2468 * asynchronous operation completes immediately. The program must ensure that
2469 * the stream performs no other read operations (such as async_read,
2470 * async_read_until, the stream's async_read_some function, or any other
2471 * composed operations that perform reads) until this operation completes.
2473 * @param s The stream from which the data is to be read. The type must support
2474 * the AsyncReadStream concept.
2476 * @param buffers The dynamic buffer sequence into which the data will be read.
2477 * Although the buffers object may be copied as necessary, ownership of the
2478 * underlying memory blocks is retained by the caller, which must guarantee
2479 * that they remain valid until the handler is called.
2481 * @param delim The delimiter string.
2483 * @param handler The handler to be called when the read operation completes.
2484 * Copies will be made of the handler as required. The function signature of the
2486 * @code void handler(
2487 * // Result of operation.
2488 * const boost::system::error_code& error,
2490 * // The number of bytes in the dynamic buffer sequence's
2491 * // get area up to and including the delimiter.
2492 * // 0 if an error occurred.
2493 * std::size_t bytes_transferred
2495 * Regardless of whether the asynchronous operation completes immediately or
2496 * not, the handler will not be invoked from within this function. On
2497 * immediate completion, invocation of the handler will be performed in a
2498 * manner equivalent to using boost::asio::post().
2500 * @note After a successful async_read_until operation, the dynamic buffer
2501 * sequence may contain additional data beyond the delimiter. An application
2502 * will typically leave that data in the dynamic buffer sequence for a
2503 * subsequent async_read_until operation to examine.
2506 * To asynchronously read data into a @c std::string until a CR-LF sequence is
2508 * @code std::string data;
2510 * void handler(const boost::system::error_code& e, std::size_t size)
2514 * std::string line = data.substr(0, n);
2520 * boost::asio::async_read_until(s, data, "\r\n", handler); @endcode
2521 * After the @c async_read_until operation completes successfully, the string
2522 * @c data contains the delimiter:
2523 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
2524 * The call to @c substr then extracts the data up to and including the
2525 * delimiter, so that the string @c line contains:
2526 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
2527 * After the call to @c erase, the remaining data is left in the string @c data
2529 * @code { 'd', 'e', ... } @endcode
2530 * This data may be the start of a new line, to be extracted by a subsequent
2531 * @c async_read_until operation.
2533 template <typename AsyncReadStream,
2534 typename DynamicBuffer_v2, typename ReadHandler>
2535 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
2536 void (boost::system::error_code, std::size_t))
2537 async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers,
2538 BOOST_ASIO_STRING_VIEW_PARAM delim,
2539 BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
2541 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
2544 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
2545 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
2546 || defined(GENERATING_DOCUMENTATION)
2548 /// Start an asynchronous operation to read data into a dynamic buffer sequence
2549 /// until some part of its data matches a regular expression.
2551 * This function is used to asynchronously read data into the specified dynamic
2552 * buffer sequence until the dynamic buffer sequence's get area contains some
2553 * data that matches a regular expression. The function call always returns
2554 * immediately. The asynchronous operation will continue until one of the
2555 * following conditions is true:
2557 * @li A substring of the dynamic buffer sequence's get area matches the regular
2560 * @li An error occurred.
2562 * This operation is implemented in terms of zero or more calls to the stream's
2563 * async_read_some function, and is known as a <em>composed operation</em>. If
2564 * the dynamic buffer sequence's get area already contains data that matches
2565 * the regular expression, this asynchronous operation completes immediately.
2566 * The program must ensure that the stream performs no other read operations
2567 * (such as async_read, async_read_until, the stream's async_read_some
2568 * function, or any other composed operations that perform reads) until this
2569 * operation completes.
2571 * @param s The stream from which the data is to be read. The type must support
2572 * the AsyncReadStream concept.
2574 * @param buffers The dynamic buffer sequence into which the data will be read.
2575 * Although the buffers object may be copied as necessary, ownership of the
2576 * underlying memory blocks is retained by the caller, which must guarantee
2577 * that they remain valid until the handler is called.
2579 * @param expr The regular expression.
2581 * @param handler The handler to be called when the read operation completes.
2582 * Copies will be made of the handler as required. The function signature of the
2584 * @code void handler(
2585 * // Result of operation.
2586 * const boost::system::error_code& error,
2588 * // The number of bytes in the dynamic buffer
2589 * // sequence's get area up to and including the
2590 * // substring that matches the regular expression.
2591 * // 0 if an error occurred.
2592 * std::size_t bytes_transferred
2594 * Regardless of whether the asynchronous operation completes immediately or
2595 * not, the handler will not be invoked from within this function. On
2596 * immediate completion, invocation of the handler will be performed in a
2597 * manner equivalent to using boost::asio::post().
2599 * @note After a successful async_read_until operation, the dynamic buffer
2600 * sequence may contain additional data beyond that which matched the regular
2601 * expression. An application will typically leave that data in the dynamic
2602 * buffer sequence for a subsequent async_read_until operation to examine.
2605 * To asynchronously read data into a @c std::string until a CR-LF sequence is
2607 * @code std::string data;
2609 * void handler(const boost::system::error_code& e, std::size_t size)
2613 * std::string line = data.substr(0, n);
2619 * boost::asio::async_read_until(s, data,
2620 * boost::regex("\r\n"), handler); @endcode
2621 * After the @c async_read_until operation completes successfully, the string
2622 * @c data contains the data which matched the regular expression:
2623 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
2624 * The call to @c substr then extracts the data up to and including the match,
2625 * so that the string @c line contains:
2626 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
2627 * After the call to @c erase, the remaining data is left in the string @c data
2629 * @code { 'd', 'e', ... } @endcode
2630 * This data may be the start of a new line, to be extracted by a subsequent
2631 * @c async_read_until operation.
2633 template <typename AsyncReadStream,
2634 typename DynamicBuffer_v2, typename ReadHandler>
2635 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
2636 void (boost::system::error_code, std::size_t))
2637 async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers,
2638 const boost::regex& expr,
2639 BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
2641 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
2644 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
2645 // || defined(GENERATING_DOCUMENTATION)
2647 /// Start an asynchronous operation to read data into a dynamic buffer sequence
2648 /// until a function object indicates a match.
2650 * This function is used to asynchronously read data into the specified dynamic
2651 * buffer sequence until a user-defined match condition function object, when
2652 * applied to the data contained in the dynamic buffer sequence, indicates a
2653 * successful match. The function call always returns immediately. The
2654 * asynchronous operation will continue until one of the following conditions
2657 * @li The match condition function object returns a std::pair where the second
2658 * element evaluates to true.
2660 * @li An error occurred.
2662 * This operation is implemented in terms of zero or more calls to the stream's
2663 * async_read_some function, and is known as a <em>composed operation</em>. If
2664 * the match condition function object already indicates a match, this
2665 * asynchronous operation completes immediately. The program must ensure that
2666 * the stream performs no other read operations (such as async_read,
2667 * async_read_until, the stream's async_read_some function, or any other
2668 * composed operations that perform reads) until this operation completes.
2670 * @param s The stream from which the data is to be read. The type must support
2671 * the AsyncReadStream concept.
2673 * @param buffers The dynamic buffer sequence into which the data will be read.
2674 * Although the buffers object may be copied as necessary, ownership of the
2675 * underlying memory blocks is retained by the caller, which must guarantee
2676 * that they remain valid until the handler is called.
2678 * @param match_condition The function object to be called to determine whether
2679 * a match exists. The signature of the function object must be:
2680 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
2682 * where @c iterator represents the type:
2683 * @code buffers_iterator<typename DynamicBuffer_v2::const_buffers_type>
2685 * The iterator parameters @c begin and @c end define the range of bytes to be
2686 * scanned to determine whether there is a match. The @c first member of the
2687 * return value is an iterator marking one-past-the-end of the bytes that have
2688 * been consumed by the match function. This iterator is used to calculate the
2689 * @c begin parameter for any subsequent invocation of the match condition. The
2690 * @c second member of the return value is true if a match has been found, false
2693 * @param handler The handler to be called when the read operation completes.
2694 * Copies will be made of the handler as required. The function signature of the
2696 * @code void handler(
2697 * // Result of operation.
2698 * const boost::system::error_code& error,
2700 * // The number of bytes in the dynamic buffer sequence's
2701 * // get area that have been fully consumed by the match
2702 * // function. O if an error occurred.
2703 * std::size_t bytes_transferred
2705 * Regardless of whether the asynchronous operation completes immediately or
2706 * not, the handler will not be invoked from within this function. On
2707 * immediate completion, invocation of the handler will be performed in a
2708 * manner equivalent to using boost::asio::post().
2710 * @note After a successful async_read_until operation, the dynamic buffer
2711 * sequence may contain additional data beyond that which matched the function
2712 * object. An application will typically leave that data in the dynamic buffer
2713 * sequence for a subsequent async_read_until operation to examine.
2715 * @note The default implementation of the @c is_match_condition type trait
2716 * evaluates to true for function pointers and function objects with a
2717 * @c result_type typedef. It must be specialised for other user-defined
2721 * To asynchronously read data into a @c std::string until whitespace is
2723 * @code typedef boost::asio::buffers_iterator<
2724 * boost::asio::const_buffers_1> iterator;
2726 * std::pair<iterator, bool>
2727 * match_whitespace(iterator begin, iterator end)
2729 * iterator i = begin;
2731 * if (std::isspace(*i++))
2732 * return std::make_pair(i, true);
2733 * return std::make_pair(i, false);
2736 * void handler(const boost::system::error_code& e, std::size_t size);
2739 * boost::asio::async_read_until(s, data, match_whitespace, handler);
2742 * To asynchronously read data into a @c std::string until a matching character
2744 * @code class match_char
2747 * explicit match_char(char c) : c_(c) {}
2749 * template <typename Iterator>
2750 * std::pair<Iterator, bool> operator()(
2751 * Iterator begin, Iterator end) const
2753 * Iterator i = begin;
2756 * return std::make_pair(i, true);
2757 * return std::make_pair(i, false);
2765 * template <> struct is_match_condition<match_char>
2766 * : public boost::true_type {};
2767 * } // namespace asio
2769 * void handler(const boost::system::error_code& e, std::size_t size);
2772 * boost::asio::async_read_until(s, data, match_char('a'), handler);
2775 template <typename AsyncReadStream, typename DynamicBuffer_v2,
2776 typename MatchCondition, typename ReadHandler>
2777 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
2778 void (boost::system::error_code, std::size_t))
2779 async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers,
2780 MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
2782 is_match_condition<MatchCondition>::value
2783 && is_dynamic_buffer_v2<DynamicBuffer_v2>::value
2786 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
2791 } // namespace boost
2793 #include <boost/asio/detail/pop_options.hpp>
2795 #include <boost/asio/impl/read_until.hpp>
2797 #endif // BOOST_ASIO_READ_UNTIL_HPP