5 // Copyright (c) 2003-2020 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, typename DynamicBuffer_v1,
1603 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1604 std::size_t)) ReadHandler
1605 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
1606 typename AsyncReadStream::executor_type)>
1607 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
1608 void (boost::system::error_code, std::size_t))
1609 async_read_until(AsyncReadStream& s,
1610 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers, char delim,
1611 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
1612 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
1613 typename AsyncReadStream::executor_type),
1615 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
1616 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
1619 /// Start an asynchronous operation to read data into a dynamic buffer sequence
1620 /// until it contains a specified delimiter.
1622 * This function is used to asynchronously read data into the specified dynamic
1623 * buffer sequence until the dynamic buffer sequence's get area contains the
1624 * specified delimiter. The function call always returns immediately. The
1625 * asynchronous operation will continue until one of the following conditions
1628 * @li The get area of the dynamic buffer sequence contains the specified
1631 * @li An error occurred.
1633 * This operation is implemented in terms of zero or more calls to the stream's
1634 * async_read_some function, and is known as a <em>composed operation</em>. If
1635 * the dynamic buffer sequence's get area already contains the delimiter, this
1636 * asynchronous operation completes immediately. The program must ensure that
1637 * the stream performs no other read operations (such as async_read,
1638 * async_read_until, the stream's async_read_some function, or any other
1639 * composed operations that perform reads) until this operation completes.
1641 * @param s The stream from which the data is to be read. The type must support
1642 * the AsyncReadStream concept.
1644 * @param buffers The dynamic buffer sequence into which the data will be read.
1645 * Although the buffers object may be copied as necessary, ownership of the
1646 * underlying memory blocks is retained by the caller, which must guarantee
1647 * that they remain valid until the handler is called.
1649 * @param delim The delimiter string.
1651 * @param handler The handler to be called when the read operation completes.
1652 * Copies will be made of the handler as required. The function signature of the
1654 * @code void handler(
1655 * // Result of operation.
1656 * const boost::system::error_code& error,
1658 * // The number of bytes in the dynamic buffer sequence's
1659 * // get area up to and including the delimiter.
1660 * // 0 if an error occurred.
1661 * std::size_t bytes_transferred
1663 * Regardless of whether the asynchronous operation completes immediately or
1664 * not, the handler will not be invoked from within this function. On
1665 * immediate completion, invocation of the handler will be performed in a
1666 * manner equivalent to using boost::asio::post().
1668 * @note After a successful async_read_until operation, the dynamic buffer
1669 * sequence may contain additional data beyond the delimiter. An application
1670 * will typically leave that data in the dynamic buffer sequence for a
1671 * subsequent async_read_until operation to examine.
1674 * To asynchronously read data into a @c std::string until a CR-LF sequence is
1676 * @code std::string data;
1678 * void handler(const boost::system::error_code& e, std::size_t size)
1682 * std::string line = data.substr(0, n);
1688 * boost::asio::async_read_until(s, data, "\r\n", handler); @endcode
1689 * After the @c async_read_until operation completes successfully, the string
1690 * @c data contains the delimiter:
1691 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
1692 * The call to @c substr then extracts the data up to and including the
1693 * delimiter, so that the string @c line contains:
1694 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
1695 * After the call to @c erase, the remaining data is left in the string @c data
1697 * @code { 'd', 'e', ... } @endcode
1698 * This data may be the start of a new line, to be extracted by a subsequent
1699 * @c async_read_until operation.
1701 template <typename AsyncReadStream, typename DynamicBuffer_v1,
1702 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1703 std::size_t)) ReadHandler
1704 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
1705 typename AsyncReadStream::executor_type)>
1706 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
1707 void (boost::system::error_code, std::size_t))
1708 async_read_until(AsyncReadStream& s,
1709 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
1710 BOOST_ASIO_STRING_VIEW_PARAM delim,
1711 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
1712 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
1713 typename AsyncReadStream::executor_type),
1715 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
1716 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
1719 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
1720 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
1721 || defined(GENERATING_DOCUMENTATION)
1723 /// Start an asynchronous operation to read data into a dynamic buffer sequence
1724 /// until some part of its data matches a regular expression.
1726 * This function is used to asynchronously read data into the specified dynamic
1727 * buffer sequence until the dynamic buffer sequence's get area contains some
1728 * data that matches a regular expression. The function call always returns
1729 * immediately. The asynchronous operation will continue until one of the
1730 * following conditions is true:
1732 * @li A substring of the dynamic buffer sequence's get area matches the regular
1735 * @li An error occurred.
1737 * This operation is implemented in terms of zero or more calls to the stream's
1738 * async_read_some function, and is known as a <em>composed operation</em>. If
1739 * the dynamic buffer sequence's get area already contains data that matches
1740 * the regular expression, this asynchronous operation completes immediately.
1741 * The program must ensure that the stream performs no other read operations
1742 * (such as async_read, async_read_until, the stream's async_read_some
1743 * function, or any other composed operations that perform reads) until this
1744 * operation completes.
1746 * @param s The stream from which the data is to be read. The type must support
1747 * the AsyncReadStream concept.
1749 * @param buffers The dynamic buffer sequence into which the data will be read.
1750 * Although the buffers object may be copied as necessary, ownership of the
1751 * underlying memory blocks is retained by the caller, which must guarantee
1752 * that they remain valid until the handler is called.
1754 * @param expr The regular expression.
1756 * @param handler The handler to be called when the read operation completes.
1757 * Copies will be made of the handler as required. The function signature of the
1759 * @code void handler(
1760 * // Result of operation.
1761 * const boost::system::error_code& error,
1763 * // The number of bytes in the dynamic buffer
1764 * // sequence's get area up to and including the
1765 * // substring that matches the regular expression.
1766 * // 0 if an error occurred.
1767 * std::size_t bytes_transferred
1769 * Regardless of whether the asynchronous operation completes immediately or
1770 * not, the handler will not be invoked from within this function. On
1771 * immediate completion, invocation of the handler will be performed in a
1772 * manner equivalent to using boost::asio::post().
1774 * @note After a successful async_read_until operation, the dynamic buffer
1775 * sequence may contain additional data beyond that which matched the regular
1776 * expression. An application will typically leave that data in the dynamic
1777 * buffer sequence for a subsequent async_read_until operation to examine.
1780 * To asynchronously read data into a @c std::string until a CR-LF sequence is
1782 * @code std::string data;
1784 * void handler(const boost::system::error_code& e, std::size_t size)
1788 * std::string line = data.substr(0, n);
1794 * boost::asio::async_read_until(s, data,
1795 * boost::regex("\r\n"), handler); @endcode
1796 * After the @c async_read_until operation completes successfully, the string
1797 * @c data contains the data which matched the regular expression:
1798 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
1799 * The call to @c substr then extracts the data up to and including the match,
1800 * so that the string @c line contains:
1801 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
1802 * After the call to @c erase, the remaining data is left in the string @c data
1804 * @code { 'd', 'e', ... } @endcode
1805 * This data may be the start of a new line, to be extracted by a subsequent
1806 * @c async_read_until operation.
1808 template <typename AsyncReadStream, typename DynamicBuffer_v1,
1809 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1810 std::size_t)) ReadHandler
1811 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
1812 typename AsyncReadStream::executor_type)>
1813 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
1814 void (boost::system::error_code, std::size_t))
1815 async_read_until(AsyncReadStream& s,
1816 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
1817 const boost::regex& expr,
1818 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
1819 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
1820 typename AsyncReadStream::executor_type),
1822 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
1823 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
1826 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
1827 // || defined(GENERATING_DOCUMENTATION)
1829 /// Start an asynchronous operation to read data into a dynamic buffer sequence
1830 /// until a function object indicates a match.
1832 * This function is used to asynchronously read data into the specified dynamic
1833 * buffer sequence until a user-defined match condition function object, when
1834 * applied to the data contained in the dynamic buffer sequence, indicates a
1835 * successful match. The function call always returns immediately. The
1836 * asynchronous operation will continue until one of the following conditions
1839 * @li The match condition function object returns a std::pair where the second
1840 * element evaluates to true.
1842 * @li An error occurred.
1844 * This operation is implemented in terms of zero or more calls to the stream's
1845 * async_read_some function, and is known as a <em>composed operation</em>. If
1846 * the match condition function object already indicates a match, this
1847 * asynchronous operation completes immediately. The program must ensure that
1848 * the stream performs no other read operations (such as async_read,
1849 * async_read_until, the stream's async_read_some function, or any other
1850 * composed operations that perform reads) until this operation completes.
1852 * @param s The stream from which the data is to be read. The type must support
1853 * the AsyncReadStream concept.
1855 * @param buffers The dynamic buffer sequence into which the data will be read.
1856 * Although the buffers object may be copied as necessary, ownership of the
1857 * underlying memory blocks is retained by the caller, which must guarantee
1858 * that they remain valid until the handler is called.
1860 * @param match_condition The function object to be called to determine whether
1861 * a match exists. The signature of the function object must be:
1862 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
1864 * where @c iterator represents the type:
1865 * @code buffers_iterator<typename DynamicBuffer_v1::const_buffers_type>
1867 * The iterator parameters @c begin and @c end define the range of bytes to be
1868 * scanned to determine whether there is a match. The @c first member of the
1869 * return value is an iterator marking one-past-the-end of the bytes that have
1870 * been consumed by the match function. This iterator is used to calculate the
1871 * @c begin parameter for any subsequent invocation of the match condition. The
1872 * @c second member of the return value is true if a match has been found, false
1875 * @param handler The handler to be called when the read operation completes.
1876 * Copies will be made of the handler as required. The function signature of the
1878 * @code void handler(
1879 * // Result of operation.
1880 * const boost::system::error_code& error,
1882 * // The number of bytes in the dynamic buffer sequence's
1883 * // get area that have been fully consumed by the match
1884 * // function. O if an error occurred.
1885 * std::size_t bytes_transferred
1887 * Regardless of whether the asynchronous operation completes immediately or
1888 * not, the handler will not be invoked from within this function. On
1889 * immediate completion, invocation of the handler will be performed in a
1890 * manner equivalent to using boost::asio::post().
1892 * @note After a successful async_read_until operation, the dynamic buffer
1893 * sequence may contain additional data beyond that which matched the function
1894 * object. An application will typically leave that data in the dynamic buffer
1895 * sequence for a subsequent async_read_until operation to examine.
1897 * @note The default implementation of the @c is_match_condition type trait
1898 * evaluates to true for function pointers and function objects with a
1899 * @c result_type typedef. It must be specialised for other user-defined
1903 * To asynchronously read data into a @c std::string until whitespace is
1905 * @code typedef boost::asio::buffers_iterator<
1906 * boost::asio::const_buffers_1> iterator;
1908 * std::pair<iterator, bool>
1909 * match_whitespace(iterator begin, iterator end)
1911 * iterator i = begin;
1913 * if (std::isspace(*i++))
1914 * return std::make_pair(i, true);
1915 * return std::make_pair(i, false);
1918 * void handler(const boost::system::error_code& e, std::size_t size);
1921 * boost::asio::async_read_until(s, data, match_whitespace, handler);
1924 * To asynchronously read data into a @c std::string until a matching character
1926 * @code class match_char
1929 * explicit match_char(char c) : c_(c) {}
1931 * template <typename Iterator>
1932 * std::pair<Iterator, bool> operator()(
1933 * Iterator begin, Iterator end) const
1935 * Iterator i = begin;
1938 * return std::make_pair(i, true);
1939 * return std::make_pair(i, false);
1947 * template <> struct is_match_condition<match_char>
1948 * : public boost::true_type {};
1949 * } // namespace asio
1951 * void handler(const boost::system::error_code& e, std::size_t size);
1954 * boost::asio::async_read_until(s, data, match_char('a'), handler);
1957 template <typename AsyncReadStream,
1958 typename DynamicBuffer_v1, typename MatchCondition,
1959 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1960 std::size_t)) ReadHandler
1961 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
1962 typename AsyncReadStream::executor_type)>
1963 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
1964 void (boost::system::error_code, std::size_t))
1965 async_read_until(AsyncReadStream& s,
1966 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
1967 MatchCondition match_condition,
1968 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
1969 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
1970 typename AsyncReadStream::executor_type),
1972 is_match_condition<MatchCondition>::value
1973 && is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
1974 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
1977 #if !defined(BOOST_ASIO_NO_IOSTREAM)
1979 /// Start an asynchronous operation to read data into a streambuf until it
1980 /// contains a specified delimiter.
1982 * This function is used to asynchronously read data into the specified
1983 * streambuf until the streambuf's get area contains the specified delimiter.
1984 * The function call always returns immediately. The asynchronous operation
1985 * will continue until one of the following conditions is true:
1987 * @li The get area of the streambuf contains the specified delimiter.
1989 * @li An error occurred.
1991 * This operation is implemented in terms of zero or more calls to the stream's
1992 * async_read_some function, and is known as a <em>composed operation</em>. If
1993 * the streambuf's get area already contains the delimiter, this asynchronous
1994 * operation completes immediately. The program must ensure that the stream
1995 * performs no other read operations (such as async_read, async_read_until, the
1996 * stream's async_read_some function, or any other composed operations that
1997 * perform reads) until this operation completes.
1999 * @param s The stream from which the data is to be read. The type must support
2000 * the AsyncReadStream concept.
2002 * @param b A streambuf object into which the data will be read. Ownership of
2003 * the streambuf is retained by the caller, which must guarantee that it remains
2004 * valid until the handler is called.
2006 * @param delim The delimiter character.
2008 * @param handler The handler to be called when the read operation completes.
2009 * Copies will be made of the handler as required. The function signature of the
2011 * @code void handler(
2012 * // Result of operation.
2013 * const boost::system::error_code& error,
2015 * // The number of bytes in the streambuf's get
2016 * // area up to and including the delimiter.
2017 * // 0 if an error occurred.
2018 * std::size_t bytes_transferred
2020 * Regardless of whether the asynchronous operation completes immediately or
2021 * not, the handler will not be invoked from within this function. On
2022 * immediate completion, invocation of the handler will be performed in a
2023 * manner equivalent to using boost::asio::post().
2025 * @note After a successful async_read_until operation, the streambuf may
2026 * contain additional data beyond the delimiter. An application will typically
2027 * leave that data in the streambuf for a subsequent async_read_until operation
2031 * To asynchronously read data into a streambuf until a newline is encountered:
2032 * @code boost::asio::streambuf b;
2034 * void handler(const boost::system::error_code& e, std::size_t size)
2038 * std::istream is(&b);
2040 * std::getline(is, line);
2045 * boost::asio::async_read_until(s, b, '\n', handler); @endcode
2046 * After the @c async_read_until operation completes successfully, the buffer
2047 * @c b contains the delimiter:
2048 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
2049 * The call to @c std::getline then extracts the data up to and including the
2050 * newline (which is discarded), so that the string @c line contains:
2051 * @code { 'a', 'b', ..., 'c' } @endcode
2052 * The remaining data is left in the buffer @c b as follows:
2053 * @code { 'd', 'e', ... } @endcode
2054 * This data may be the start of a new line, to be extracted by a subsequent
2055 * @c async_read_until operation.
2057 template <typename AsyncReadStream, typename Allocator,
2058 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2059 std::size_t)) ReadHandler
2060 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
2061 typename AsyncReadStream::executor_type)>
2062 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
2063 void (boost::system::error_code, std::size_t))
2064 async_read_until(AsyncReadStream& s,
2065 boost::asio::basic_streambuf<Allocator>& b, char delim,
2066 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
2067 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
2068 typename AsyncReadStream::executor_type));
2070 /// Start an asynchronous operation to read data into a streambuf until it
2071 /// contains a specified delimiter.
2073 * This function is used to asynchronously read data into the specified
2074 * streambuf until the streambuf's get area contains the specified delimiter.
2075 * The function call always returns immediately. The asynchronous operation
2076 * will continue until one of the following conditions is true:
2078 * @li The get area of the streambuf contains the specified delimiter.
2080 * @li An error occurred.
2082 * This operation is implemented in terms of zero or more calls to the stream's
2083 * async_read_some function, and is known as a <em>composed operation</em>. If
2084 * the streambuf's get area already contains the delimiter, this asynchronous
2085 * operation completes immediately. The program must ensure that the stream
2086 * performs no other read operations (such as async_read, async_read_until, the
2087 * stream's async_read_some function, or any other composed operations that
2088 * perform reads) until this operation completes.
2090 * @param s The stream from which the data is to be read. The type must support
2091 * the AsyncReadStream concept.
2093 * @param b A streambuf object into which the data will be read. Ownership of
2094 * the streambuf is retained by the caller, which must guarantee that it remains
2095 * valid until the handler is called.
2097 * @param delim The delimiter string.
2099 * @param handler The handler to be called when the read operation completes.
2100 * Copies will be made of the handler as required. The function signature of the
2102 * @code void handler(
2103 * // Result of operation.
2104 * const boost::system::error_code& error,
2106 * // The number of bytes in the streambuf's get
2107 * // area up to and including the delimiter.
2108 * // 0 if an error occurred.
2109 * std::size_t bytes_transferred
2111 * Regardless of whether the asynchronous operation completes immediately or
2112 * not, the handler will not be invoked from within this function. On
2113 * immediate completion, invocation of the handler will be performed in a
2114 * manner equivalent to using boost::asio::post().
2116 * @note After a successful async_read_until operation, the streambuf may
2117 * contain additional data beyond the delimiter. An application will typically
2118 * leave that data in the streambuf for a subsequent async_read_until operation
2122 * To asynchronously read data into a streambuf until a newline is encountered:
2123 * @code boost::asio::streambuf b;
2125 * void handler(const boost::system::error_code& e, std::size_t size)
2129 * std::istream is(&b);
2131 * std::getline(is, line);
2136 * boost::asio::async_read_until(s, b, "\r\n", handler); @endcode
2137 * After the @c async_read_until operation completes successfully, the buffer
2138 * @c b contains the delimiter:
2139 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
2140 * The call to @c std::getline then extracts the data up to and including the
2141 * newline (which is discarded), so that the string @c line contains:
2142 * @code { 'a', 'b', ..., 'c', '\r' } @endcode
2143 * The remaining data is left in the buffer @c b as follows:
2144 * @code { 'd', 'e', ... } @endcode
2145 * This data may be the start of a new line, to be extracted by a subsequent
2146 * @c async_read_until operation.
2148 template <typename AsyncReadStream, typename Allocator,
2149 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2150 std::size_t)) ReadHandler
2151 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
2152 typename AsyncReadStream::executor_type)>
2153 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
2154 void (boost::system::error_code, std::size_t))
2155 async_read_until(AsyncReadStream& s,
2156 boost::asio::basic_streambuf<Allocator>& b,
2157 BOOST_ASIO_STRING_VIEW_PARAM delim,
2158 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
2159 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
2160 typename AsyncReadStream::executor_type));
2162 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
2163 || defined(GENERATING_DOCUMENTATION)
2165 /// Start an asynchronous operation to read data into a streambuf until some
2166 /// part of its data matches a regular expression.
2168 * This function is used to asynchronously read data into the specified
2169 * streambuf until the streambuf's get area contains some data that matches a
2170 * regular expression. The function call always returns immediately. The
2171 * asynchronous operation will continue until one of the following conditions
2174 * @li A substring of the streambuf's get area matches the regular expression.
2176 * @li An error occurred.
2178 * This operation is implemented in terms of zero or more calls to the stream's
2179 * async_read_some function, and is known as a <em>composed operation</em>. If
2180 * the streambuf's get area already contains data that matches the regular
2181 * expression, this asynchronous operation completes immediately. The program
2182 * must ensure that the stream performs no other read operations (such as
2183 * async_read, async_read_until, the stream's async_read_some function, or any
2184 * other composed operations that perform reads) until this operation
2187 * @param s The stream from which the data is to be read. The type must support
2188 * the AsyncReadStream concept.
2190 * @param b A streambuf object into which the data will be read. Ownership of
2191 * the streambuf is retained by the caller, which must guarantee that it remains
2192 * valid until the handler is called.
2194 * @param expr The regular expression.
2196 * @param handler The handler to be called when the read operation completes.
2197 * Copies will be made of the handler as required. The function signature of the
2199 * @code void handler(
2200 * // Result of operation.
2201 * const boost::system::error_code& error,
2203 * // The number of bytes in the streambuf's get
2204 * // area up to and including the substring
2205 * // that matches the regular. expression.
2206 * // 0 if an error occurred.
2207 * std::size_t bytes_transferred
2209 * Regardless of whether the asynchronous operation completes immediately or
2210 * not, the handler will not be invoked from within this function. On
2211 * immediate completion, invocation of the handler will be performed in a
2212 * manner equivalent to using boost::asio::post().
2214 * @note After a successful async_read_until operation, the streambuf may
2215 * contain additional data beyond that which matched the regular expression. An
2216 * application will typically leave that data in the streambuf for a subsequent
2217 * async_read_until operation to examine.
2220 * To asynchronously read data into a streambuf until a CR-LF sequence is
2222 * @code boost::asio::streambuf b;
2224 * void handler(const boost::system::error_code& e, std::size_t size)
2228 * std::istream is(&b);
2230 * std::getline(is, line);
2235 * boost::asio::async_read_until(s, b, boost::regex("\r\n"), handler); @endcode
2236 * After the @c async_read_until operation completes successfully, the buffer
2237 * @c b contains the data which matched the regular expression:
2238 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
2239 * The call to @c std::getline then extracts the data up to and including the
2240 * newline (which is discarded), so that the string @c line contains:
2241 * @code { 'a', 'b', ..., 'c', '\r' } @endcode
2242 * The remaining data is left in the buffer @c b as follows:
2243 * @code { 'd', 'e', ... } @endcode
2244 * This data may be the start of a new line, to be extracted by a subsequent
2245 * @c async_read_until operation.
2247 template <typename AsyncReadStream, typename Allocator,
2248 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2249 std::size_t)) ReadHandler
2250 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
2251 typename AsyncReadStream::executor_type)>
2252 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
2253 void (boost::system::error_code, std::size_t))
2254 async_read_until(AsyncReadStream& s,
2255 boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr,
2256 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
2257 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
2258 typename AsyncReadStream::executor_type));
2260 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
2261 // || defined(GENERATING_DOCUMENTATION)
2263 /// Start an asynchronous operation to read data into a streambuf until a
2264 /// function object indicates a match.
2266 * This function is used to asynchronously read data into the specified
2267 * streambuf until a user-defined match condition function object, when applied
2268 * to the data contained in the streambuf, indicates a successful match. The
2269 * function call always returns immediately. The asynchronous operation will
2270 * continue until one of the following conditions is true:
2272 * @li The match condition function object returns a std::pair where the second
2273 * element evaluates to true.
2275 * @li An error occurred.
2277 * This operation is implemented in terms of zero or more calls to the stream's
2278 * async_read_some function, and is known as a <em>composed operation</em>. If
2279 * the match condition function object already indicates a match, this
2280 * asynchronous operation completes immediately. The program must ensure that
2281 * the stream performs no other read operations (such as async_read,
2282 * async_read_until, the stream's async_read_some function, or any other
2283 * composed operations that perform reads) until this operation completes.
2285 * @param s The stream from which the data is to be read. The type must support
2286 * the AsyncReadStream concept.
2288 * @param b A streambuf object into which the data will be read.
2290 * @param match_condition The function object to be called to determine whether
2291 * a match exists. The signature of the function object must be:
2292 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
2294 * where @c iterator represents the type:
2295 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
2297 * The iterator parameters @c begin and @c end define the range of bytes to be
2298 * scanned to determine whether there is a match. The @c first member of the
2299 * return value is an iterator marking one-past-the-end of the bytes that have
2300 * been consumed by the match function. This iterator is used to calculate the
2301 * @c begin parameter for any subsequent invocation of the match condition. The
2302 * @c second member of the return value is true if a match has been found, false
2305 * @param handler The handler to be called when the read operation completes.
2306 * Copies will be made of the handler as required. The function signature of the
2308 * @code void handler(
2309 * // Result of operation.
2310 * const boost::system::error_code& error,
2312 * // The number of bytes in the streambuf's get
2313 * // area that have been fully consumed by the
2314 * // match function. O if an error occurred.
2315 * std::size_t bytes_transferred
2317 * Regardless of whether the asynchronous operation completes immediately or
2318 * not, the handler will not be invoked from within this function. On
2319 * immediate completion, invocation of the handler will be performed in a
2320 * manner equivalent to using boost::asio::post().
2322 * @note After a successful async_read_until operation, the streambuf may
2323 * contain additional data beyond that which matched the function object. An
2324 * application will typically leave that data in the streambuf for a subsequent
2325 * async_read_until operation to examine.
2327 * @note The default implementation of the @c is_match_condition type trait
2328 * evaluates to true for function pointers and function objects with a
2329 * @c result_type typedef. It must be specialised for other user-defined
2333 * To asynchronously read data into a streambuf until whitespace is encountered:
2334 * @code typedef boost::asio::buffers_iterator<
2335 * boost::asio::streambuf::const_buffers_type> iterator;
2337 * std::pair<iterator, bool>
2338 * match_whitespace(iterator begin, iterator end)
2340 * iterator i = begin;
2342 * if (std::isspace(*i++))
2343 * return std::make_pair(i, true);
2344 * return std::make_pair(i, false);
2347 * void handler(const boost::system::error_code& e, std::size_t size);
2349 * boost::asio::streambuf b;
2350 * boost::asio::async_read_until(s, b, match_whitespace, handler);
2353 * To asynchronously read data into a streambuf until a matching character is
2355 * @code class match_char
2358 * explicit match_char(char c) : c_(c) {}
2360 * template <typename Iterator>
2361 * std::pair<Iterator, bool> operator()(
2362 * Iterator begin, Iterator end) const
2364 * Iterator i = begin;
2367 * return std::make_pair(i, true);
2368 * return std::make_pair(i, false);
2376 * template <> struct is_match_condition<match_char>
2377 * : public boost::true_type {};
2378 * } // namespace asio
2380 * void handler(const boost::system::error_code& e, std::size_t size);
2382 * boost::asio::streambuf b;
2383 * boost::asio::async_read_until(s, b, match_char('a'), handler);
2386 template <typename AsyncReadStream, typename Allocator, typename MatchCondition,
2387 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2388 std::size_t)) ReadHandler
2389 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
2390 typename AsyncReadStream::executor_type)>
2391 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
2392 void (boost::system::error_code, std::size_t))
2393 async_read_until(AsyncReadStream& s,
2394 boost::asio::basic_streambuf<Allocator>& b,
2395 MatchCondition match_condition,
2396 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
2397 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
2398 typename AsyncReadStream::executor_type),
2399 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
2401 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
2402 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
2403 #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
2405 /// Start an asynchronous operation to read data into a dynamic buffer sequence
2406 /// until it contains a specified delimiter.
2408 * This function is used to asynchronously read data into the specified dynamic
2409 * buffer sequence until the dynamic buffer sequence's get area contains the
2410 * specified delimiter. The function call always returns immediately. The
2411 * asynchronous operation will continue until one of the following conditions
2414 * @li The get area of the dynamic buffer sequence contains the specified
2417 * @li An error occurred.
2419 * This operation is implemented in terms of zero or more calls to the stream's
2420 * async_read_some function, and is known as a <em>composed operation</em>. If
2421 * the dynamic buffer sequence's get area already contains the delimiter, this
2422 * asynchronous operation completes immediately. The program must ensure that
2423 * the stream performs no other read operations (such as async_read,
2424 * async_read_until, the stream's async_read_some function, or any other
2425 * composed operations that perform reads) until this operation completes.
2427 * @param s The stream from which the data is to be read. The type must support
2428 * the AsyncReadStream concept.
2430 * @param buffers The dynamic buffer sequence into which the data will be read.
2431 * Although the buffers object may be copied as necessary, ownership of the
2432 * underlying memory blocks is retained by the caller, which must guarantee
2433 * that they remain valid until the handler is called.
2435 * @param delim The delimiter character.
2437 * @param handler The handler to be called when the read operation completes.
2438 * Copies will be made of the handler as required. The function signature of the
2440 * @code void handler(
2441 * // Result of operation.
2442 * const boost::system::error_code& error,
2444 * // The number of bytes in the dynamic buffer sequence's
2445 * // get area up to and including the delimiter.
2446 * // 0 if an error occurred.
2447 * std::size_t bytes_transferred
2449 * Regardless of whether the asynchronous operation completes immediately or
2450 * not, the handler will not be invoked from within this function. On
2451 * immediate completion, invocation of the handler will be performed in a
2452 * manner equivalent to using boost::asio::post().
2454 * @note After a successful async_read_until operation, the dynamic buffer
2455 * sequence may contain additional data beyond the delimiter. An application
2456 * will typically leave that data in the dynamic buffer sequence for a
2457 * subsequent async_read_until operation to examine.
2460 * To asynchronously read data into a @c std::string until a newline is
2462 * @code std::string data;
2464 * void handler(const boost::system::error_code& e, std::size_t size)
2468 * std::string line = data.substr(0, n);
2474 * boost::asio::async_read_until(s, data, '\n', handler); @endcode
2475 * After the @c async_read_until operation completes successfully, the buffer
2476 * @c data contains the delimiter:
2477 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
2478 * The call to @c substr then extracts the data up to and including the
2479 * delimiter, so that the string @c line contains:
2480 * @code { 'a', 'b', ..., 'c', '\n' } @endcode
2481 * After the call to @c erase, the remaining data is left in the buffer @c data
2483 * @code { 'd', 'e', ... } @endcode
2484 * This data may be the start of a new line, to be extracted by a subsequent
2485 * @c async_read_until operation.
2487 template <typename AsyncReadStream, typename DynamicBuffer_v2,
2488 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2489 std::size_t)) ReadHandler
2490 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
2491 typename AsyncReadStream::executor_type)>
2492 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
2493 void (boost::system::error_code, std::size_t))
2494 async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, char delim,
2495 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
2496 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
2497 typename AsyncReadStream::executor_type),
2499 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
2502 /// Start an asynchronous operation to read data into a dynamic buffer sequence
2503 /// until it contains a specified delimiter.
2505 * This function is used to asynchronously read data into the specified dynamic
2506 * buffer sequence until the dynamic buffer sequence's get area contains the
2507 * specified delimiter. The function call always returns immediately. The
2508 * asynchronous operation will continue until one of the following conditions
2511 * @li The get area of the dynamic buffer sequence contains the specified
2514 * @li An error occurred.
2516 * This operation is implemented in terms of zero or more calls to the stream's
2517 * async_read_some function, and is known as a <em>composed operation</em>. If
2518 * the dynamic buffer sequence's get area already contains the delimiter, this
2519 * asynchronous operation completes immediately. The program must ensure that
2520 * the stream performs no other read operations (such as async_read,
2521 * async_read_until, the stream's async_read_some function, or any other
2522 * composed operations that perform reads) until this operation completes.
2524 * @param s The stream from which the data is to be read. The type must support
2525 * the AsyncReadStream concept.
2527 * @param buffers The dynamic buffer sequence into which the data will be read.
2528 * Although the buffers object may be copied as necessary, ownership of the
2529 * underlying memory blocks is retained by the caller, which must guarantee
2530 * that they remain valid until the handler is called.
2532 * @param delim The delimiter string.
2534 * @param handler The handler to be called when the read operation completes.
2535 * Copies will be made of the handler as required. The function signature of the
2537 * @code void handler(
2538 * // Result of operation.
2539 * const boost::system::error_code& error,
2541 * // The number of bytes in the dynamic buffer sequence's
2542 * // get area up to and including the delimiter.
2543 * // 0 if an error occurred.
2544 * std::size_t bytes_transferred
2546 * Regardless of whether the asynchronous operation completes immediately or
2547 * not, the handler will not be invoked from within this function. On
2548 * immediate completion, invocation of the handler will be performed in a
2549 * manner equivalent to using boost::asio::post().
2551 * @note After a successful async_read_until operation, the dynamic buffer
2552 * sequence may contain additional data beyond the delimiter. An application
2553 * will typically leave that data in the dynamic buffer sequence for a
2554 * subsequent async_read_until operation to examine.
2557 * To asynchronously read data into a @c std::string until a CR-LF sequence is
2559 * @code std::string data;
2561 * void handler(const boost::system::error_code& e, std::size_t size)
2565 * std::string line = data.substr(0, n);
2571 * boost::asio::async_read_until(s, data, "\r\n", handler); @endcode
2572 * After the @c async_read_until operation completes successfully, the string
2573 * @c data contains the delimiter:
2574 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
2575 * The call to @c substr then extracts the data up to and including the
2576 * delimiter, so that the string @c line contains:
2577 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
2578 * After the call to @c erase, the remaining data is left in the string @c data
2580 * @code { 'd', 'e', ... } @endcode
2581 * This data may be the start of a new line, to be extracted by a subsequent
2582 * @c async_read_until operation.
2584 template <typename AsyncReadStream, typename DynamicBuffer_v2,
2585 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2586 std::size_t)) ReadHandler
2587 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
2588 typename AsyncReadStream::executor_type)>
2589 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
2590 void (boost::system::error_code, std::size_t))
2591 async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers,
2592 BOOST_ASIO_STRING_VIEW_PARAM delim,
2593 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
2594 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
2595 typename AsyncReadStream::executor_type),
2597 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
2600 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
2601 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
2602 || defined(GENERATING_DOCUMENTATION)
2604 /// Start an asynchronous operation to read data into a dynamic buffer sequence
2605 /// until some part of its data matches a regular expression.
2607 * This function is used to asynchronously read data into the specified dynamic
2608 * buffer sequence until the dynamic buffer sequence's get area contains some
2609 * data that matches a regular expression. The function call always returns
2610 * immediately. The asynchronous operation will continue until one of the
2611 * following conditions is true:
2613 * @li A substring of the dynamic buffer sequence's get area matches the regular
2616 * @li An error occurred.
2618 * This operation is implemented in terms of zero or more calls to the stream's
2619 * async_read_some function, and is known as a <em>composed operation</em>. If
2620 * the dynamic buffer sequence's get area already contains data that matches
2621 * the regular expression, this asynchronous operation completes immediately.
2622 * The program must ensure that the stream performs no other read operations
2623 * (such as async_read, async_read_until, the stream's async_read_some
2624 * function, or any other composed operations that perform reads) until this
2625 * operation completes.
2627 * @param s The stream from which the data is to be read. The type must support
2628 * the AsyncReadStream concept.
2630 * @param buffers The dynamic buffer sequence into which the data will be read.
2631 * Although the buffers object may be copied as necessary, ownership of the
2632 * underlying memory blocks is retained by the caller, which must guarantee
2633 * that they remain valid until the handler is called.
2635 * @param expr The regular expression.
2637 * @param handler The handler to be called when the read operation completes.
2638 * Copies will be made of the handler as required. The function signature of the
2640 * @code void handler(
2641 * // Result of operation.
2642 * const boost::system::error_code& error,
2644 * // The number of bytes in the dynamic buffer
2645 * // sequence's get area up to and including the
2646 * // substring that matches the regular expression.
2647 * // 0 if an error occurred.
2648 * std::size_t bytes_transferred
2650 * Regardless of whether the asynchronous operation completes immediately or
2651 * not, the handler will not be invoked from within this function. On
2652 * immediate completion, invocation of the handler will be performed in a
2653 * manner equivalent to using boost::asio::post().
2655 * @note After a successful async_read_until operation, the dynamic buffer
2656 * sequence may contain additional data beyond that which matched the regular
2657 * expression. An application will typically leave that data in the dynamic
2658 * buffer sequence for a subsequent async_read_until operation to examine.
2661 * To asynchronously read data into a @c std::string until a CR-LF sequence is
2663 * @code std::string data;
2665 * void handler(const boost::system::error_code& e, std::size_t size)
2669 * std::string line = data.substr(0, n);
2675 * boost::asio::async_read_until(s, data,
2676 * boost::regex("\r\n"), handler); @endcode
2677 * After the @c async_read_until operation completes successfully, the string
2678 * @c data contains the data which matched the regular expression:
2679 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
2680 * The call to @c substr then extracts the data up to and including the match,
2681 * so that the string @c line contains:
2682 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
2683 * After the call to @c erase, the remaining data is left in the string @c data
2685 * @code { 'd', 'e', ... } @endcode
2686 * This data may be the start of a new line, to be extracted by a subsequent
2687 * @c async_read_until operation.
2689 template <typename AsyncReadStream, typename DynamicBuffer_v2,
2690 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2691 std::size_t)) ReadHandler
2692 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
2693 typename AsyncReadStream::executor_type)>
2694 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
2695 void (boost::system::error_code, std::size_t))
2696 async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers,
2697 const boost::regex& expr,
2698 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
2699 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
2700 typename AsyncReadStream::executor_type),
2702 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
2705 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
2706 // || defined(GENERATING_DOCUMENTATION)
2708 /// Start an asynchronous operation to read data into a dynamic buffer sequence
2709 /// until a function object indicates a match.
2711 * This function is used to asynchronously read data into the specified dynamic
2712 * buffer sequence until a user-defined match condition function object, when
2713 * applied to the data contained in the dynamic buffer sequence, indicates a
2714 * successful match. The function call always returns immediately. The
2715 * asynchronous operation will continue until one of the following conditions
2718 * @li The match condition function object returns a std::pair where the second
2719 * element evaluates to true.
2721 * @li An error occurred.
2723 * This operation is implemented in terms of zero or more calls to the stream's
2724 * async_read_some function, and is known as a <em>composed operation</em>. If
2725 * the match condition function object already indicates a match, this
2726 * asynchronous operation completes immediately. The program must ensure that
2727 * the stream performs no other read operations (such as async_read,
2728 * async_read_until, the stream's async_read_some function, or any other
2729 * composed operations that perform reads) until this operation completes.
2731 * @param s The stream from which the data is to be read. The type must support
2732 * the AsyncReadStream concept.
2734 * @param buffers The dynamic buffer sequence into which the data will be read.
2735 * Although the buffers object may be copied as necessary, ownership of the
2736 * underlying memory blocks is retained by the caller, which must guarantee
2737 * that they remain valid until the handler is called.
2739 * @param match_condition The function object to be called to determine whether
2740 * a match exists. The signature of the function object must be:
2741 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
2743 * where @c iterator represents the type:
2744 * @code buffers_iterator<typename DynamicBuffer_v2::const_buffers_type>
2746 * The iterator parameters @c begin and @c end define the range of bytes to be
2747 * scanned to determine whether there is a match. The @c first member of the
2748 * return value is an iterator marking one-past-the-end of the bytes that have
2749 * been consumed by the match function. This iterator is used to calculate the
2750 * @c begin parameter for any subsequent invocation of the match condition. The
2751 * @c second member of the return value is true if a match has been found, false
2754 * @param handler The handler to be called when the read operation completes.
2755 * Copies will be made of the handler as required. The function signature of the
2757 * @code void handler(
2758 * // Result of operation.
2759 * const boost::system::error_code& error,
2761 * // The number of bytes in the dynamic buffer sequence's
2762 * // get area that have been fully consumed by the match
2763 * // function. O if an error occurred.
2764 * std::size_t bytes_transferred
2766 * Regardless of whether the asynchronous operation completes immediately or
2767 * not, the handler will not be invoked from within this function. On
2768 * immediate completion, invocation of the handler will be performed in a
2769 * manner equivalent to using boost::asio::post().
2771 * @note After a successful async_read_until operation, the dynamic buffer
2772 * sequence may contain additional data beyond that which matched the function
2773 * object. An application will typically leave that data in the dynamic buffer
2774 * sequence for a subsequent async_read_until operation to examine.
2776 * @note The default implementation of the @c is_match_condition type trait
2777 * evaluates to true for function pointers and function objects with a
2778 * @c result_type typedef. It must be specialised for other user-defined
2782 * To asynchronously read data into a @c std::string until whitespace is
2784 * @code typedef boost::asio::buffers_iterator<
2785 * boost::asio::const_buffers_1> iterator;
2787 * std::pair<iterator, bool>
2788 * match_whitespace(iterator begin, iterator end)
2790 * iterator i = begin;
2792 * if (std::isspace(*i++))
2793 * return std::make_pair(i, true);
2794 * return std::make_pair(i, false);
2797 * void handler(const boost::system::error_code& e, std::size_t size);
2800 * boost::asio::async_read_until(s, data, match_whitespace, handler);
2803 * To asynchronously read data into a @c std::string until a matching character
2805 * @code class match_char
2808 * explicit match_char(char c) : c_(c) {}
2810 * template <typename Iterator>
2811 * std::pair<Iterator, bool> operator()(
2812 * Iterator begin, Iterator end) const
2814 * Iterator i = begin;
2817 * return std::make_pair(i, true);
2818 * return std::make_pair(i, false);
2826 * template <> struct is_match_condition<match_char>
2827 * : public boost::true_type {};
2828 * } // namespace asio
2830 * void handler(const boost::system::error_code& e, std::size_t size);
2833 * boost::asio::async_read_until(s, data, match_char('a'), handler);
2836 template <typename AsyncReadStream,
2837 typename DynamicBuffer_v2, typename MatchCondition,
2838 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2839 std::size_t)) ReadHandler
2840 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
2841 typename AsyncReadStream::executor_type)>
2842 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
2843 void (boost::system::error_code, std::size_t))
2844 async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers,
2845 MatchCondition match_condition,
2846 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
2847 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
2848 typename AsyncReadStream::executor_type),
2850 is_match_condition<MatchCondition>::value
2851 && is_dynamic_buffer_v2<DynamicBuffer_v2>::value
2854 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
2859 } // namespace boost
2861 #include <boost/asio/detail/pop_options.hpp>
2863 #include <boost/asio/impl/read_until.hpp>
2865 #endif // BOOST_ASIO_READ_UNTIL_HPP