5 // Copyright (c) 2003-2018 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/detail/regex_fwd.hpp>
23 #include <boost/asio/detail/string_view.hpp>
24 #include <boost/asio/detail/type_traits.hpp>
25 #include <boost/asio/error.hpp>
27 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
28 # include <boost/asio/basic_streambuf_fwd.hpp>
29 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
31 #include <boost/asio/detail/push_options.hpp>
38 char (&has_result_type_helper(...))[2];
41 char has_result_type_helper(T*, typename T::result_type* = 0);
44 struct has_result_type
46 enum { value = (sizeof((has_result_type_helper)((T*)(0))) == 1) };
50 /// Type trait used to determine whether a type can be used as a match condition
51 /// function with read_until and async_read_until.
53 struct is_match_condition
55 #if defined(GENERATING_DOCUMENTATION)
56 /// The value member is true if the type may be used as a match condition.
57 static const bool value;
61 value = boost::asio::is_function<
62 typename boost::asio::remove_pointer<T>::type>::value
63 || detail::has_result_type<T>::value
69 * @defgroup read_until boost::asio::read_until
71 * @brief Read data into a dynamic buffer sequence, or into a streambuf, until
72 * it contains a delimiter, matches a regular expression, or a function object
77 /// Read data into a dynamic buffer sequence until it contains a specified
80 * This function is used to read data into the specified dynamic buffer
81 * sequence until the dynamic buffer sequence's get area contains the specified
82 * delimiter. The call will block until one of the following conditions is
85 * @li The get area of the dynamic buffer sequence contains the specified
88 * @li An error occurred.
90 * This operation is implemented in terms of zero or more calls to the stream's
91 * read_some function. If the dynamic buffer sequence's get area already
92 * contains the delimiter, the function returns immediately.
94 * @param s The stream from which the data is to be read. The type must support
95 * the SyncReadStream concept.
97 * @param buffers The dynamic buffer sequence into which the data will be read.
99 * @param delim The delimiter character.
101 * @returns The number of bytes in the dynamic buffer sequence's get area up to
102 * and including the delimiter.
104 * @throws boost::system::system_error Thrown on failure.
106 * @note After a successful read_until operation, the dynamic buffer sequence
107 * may contain additional data beyond the delimiter. An application will
108 * typically leave that data in the dynamic buffer sequence for a subsequent
109 * read_until operation to examine.
112 * To read data into a @c std::string until a newline is encountered:
113 * @code std::string data;
114 * std::string n = boost::asio::read_until(s,
115 * boost::asio::dynamic_buffer(data), '\n');
116 * std::string line = data.substr(0, n);
117 * data.erase(0, n); @endcode
118 * After the @c read_until operation completes successfully, the string @c data
119 * contains the delimiter:
120 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
121 * The call to @c substr then extracts the data up to and including the
122 * delimiter, so that the string @c line contains:
123 * @code { 'a', 'b', ..., 'c', '\n' } @endcode
124 * After the call to @c erase, the remaining data is left in the buffer @c b as
126 * @code { 'd', 'e', ... } @endcode
127 * This data may be the start of a new line, to be extracted by a subsequent
128 * @c read_until operation.
130 template <typename SyncReadStream, typename DynamicBuffer>
131 std::size_t read_until(SyncReadStream& s,
132 BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers, char delim);
134 /// Read data into a dynamic buffer sequence until it contains a specified
137 * This function is used to read data into the specified dynamic buffer
138 * sequence until the dynamic buffer sequence's get area contains the specified
139 * delimiter. The call will block until one of the following conditions is
142 * @li The get area of the dynamic buffer sequence contains the specified
145 * @li An error occurred.
147 * This operation is implemented in terms of zero or more calls to the stream's
148 * read_some function. If the dynamic buffer sequence's get area already
149 * contains the delimiter, the function returns immediately.
151 * @param s The stream from which the data is to be read. The type must support
152 * the SyncReadStream concept.
154 * @param buffers The dynamic buffer sequence into which the data will be read.
156 * @param delim The delimiter character.
158 * @param ec Set to indicate what error occurred, if any.
160 * @returns The number of bytes in the dynamic buffer sequence's get area up to
161 * and including the delimiter. Returns 0 if an error occurred.
163 * @note After a successful read_until operation, the dynamic buffer sequence
164 * may contain additional data beyond the delimiter. An application will
165 * typically leave that data in the dynamic buffer sequence for a subsequent
166 * read_until operation to examine.
168 template <typename SyncReadStream, typename DynamicBuffer>
169 std::size_t read_until(SyncReadStream& s,
170 BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
171 char delim, boost::system::error_code& ec);
173 /// Read data into a dynamic buffer sequence until it contains a specified
176 * This function is used to read data into the specified dynamic buffer
177 * sequence until the dynamic buffer sequence's get area contains the specified
178 * delimiter. The call will block until one of the following conditions is
181 * @li The get area of the dynamic buffer sequence contains the specified
184 * @li An error occurred.
186 * This operation is implemented in terms of zero or more calls to the stream's
187 * read_some function. If the dynamic buffer sequence's get area already
188 * contains the delimiter, the function returns immediately.
190 * @param s The stream from which the data is to be read. The type must support
191 * the SyncReadStream concept.
193 * @param buffers The dynamic buffer sequence into which the data will be read.
195 * @param delim The delimiter string.
197 * @returns The number of bytes in the dynamic buffer sequence's get area up to
198 * and including the delimiter.
200 * @note After a successful read_until operation, the dynamic buffer sequence
201 * may contain additional data beyond the delimiter. An application will
202 * typically leave that data in the dynamic buffer sequence for a subsequent
203 * read_until operation to examine.
206 * To read data into a @c std::string until a CR-LF sequence is encountered:
207 * @code std::string data;
208 * std::string n = boost::asio::read_until(s,
209 * boost::asio::dynamic_buffer(data), "\r\n");
210 * std::string line = data.substr(0, n);
211 * data.erase(0, n); @endcode
212 * After the @c read_until operation completes successfully, the string @c data
213 * contains the delimiter:
214 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
215 * The call to @c substr then extracts the data up to and including the
216 * delimiter, so that the string @c line contains:
217 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
218 * After the call to @c erase, the remaining data is left in the buffer @c b as
220 * @code { 'd', 'e', ... } @endcode
221 * This data may be the start of a new line, to be extracted by a subsequent
222 * @c read_until operation.
224 template <typename SyncReadStream, typename DynamicBuffer>
225 std::size_t read_until(SyncReadStream& s,
226 BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
227 BOOST_ASIO_STRING_VIEW_PARAM delim);
229 /// Read data into a dynamic buffer sequence until it contains a specified
232 * This function is used to read data into the specified dynamic buffer
233 * sequence until the dynamic buffer sequence's get area contains the specified
234 * delimiter. The call will block until one of the following conditions is
237 * @li The get area of the dynamic buffer sequence contains the specified
240 * @li An error occurred.
242 * This operation is implemented in terms of zero or more calls to the stream's
243 * read_some function. If the dynamic buffer sequence's get area already
244 * contains the delimiter, the function returns immediately.
246 * @param s The stream from which the data is to be read. The type must support
247 * the SyncReadStream concept.
249 * @param buffers The dynamic buffer sequence into which the data will be read.
251 * @param delim The delimiter string.
253 * @param ec Set to indicate what error occurred, if any.
255 * @returns The number of bytes in the dynamic buffer sequence's get area up to
256 * and including the delimiter. Returns 0 if an error occurred.
258 * @note After a successful read_until operation, the dynamic buffer sequence
259 * may contain additional data beyond the delimiter. An application will
260 * typically leave that data in the dynamic buffer sequence for a subsequent
261 * read_until operation to examine.
263 template <typename SyncReadStream, typename DynamicBuffer>
264 std::size_t read_until(SyncReadStream& s,
265 BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
266 BOOST_ASIO_STRING_VIEW_PARAM delim,
267 boost::system::error_code& ec);
269 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
270 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
271 || defined(GENERATING_DOCUMENTATION)
273 /// Read data into a dynamic buffer sequence until some part of the data it
274 /// contains matches a regular expression.
276 * This function is used to read data into the specified dynamic buffer
277 * sequence until the dynamic buffer sequence's get area contains some data
278 * that matches a regular expression. The call will block until one of the
279 * following conditions is true:
281 * @li A substring of the dynamic buffer sequence's get area matches the
282 * regular expression.
284 * @li An error occurred.
286 * This operation is implemented in terms of zero or more calls to the stream's
287 * read_some function. If the dynamic buffer sequence's get area already
288 * contains data that matches the regular expression, the function returns
291 * @param s The stream from which the data is to be read. The type must support
292 * the SyncReadStream concept.
294 * @param buffers A dynamic buffer sequence into which the data will be read.
296 * @param expr The regular expression.
298 * @returns The number of bytes in the dynamic buffer sequence's get area up to
299 * and including the substring that matches the regular expression.
301 * @throws boost::system::system_error Thrown on failure.
303 * @note After a successful read_until operation, the dynamic buffer sequence
304 * may contain additional data beyond that which matched the regular
305 * expression. An application will typically leave that data in the dynamic
306 * buffer sequence for a subsequent read_until operation to examine.
309 * To read data into a @c std::string until a CR-LF sequence is encountered:
310 * @code std::string data;
311 * std::string n = boost::asio::read_until(s,
312 * boost::asio::dynamic_buffer(data), boost::regex("\r\n"));
313 * std::string line = data.substr(0, n);
314 * data.erase(0, n); @endcode
315 * After the @c read_until operation completes successfully, the string @c data
316 * contains the delimiter:
317 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
318 * The call to @c substr then extracts the data up to and including the
319 * delimiter, so that the string @c line contains:
320 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
321 * After the call to @c erase, the remaining data is left in the buffer @c b as
323 * @code { 'd', 'e', ... } @endcode
324 * This data may be the start of a new line, to be extracted by a subsequent
325 * @c read_until operation.
327 template <typename SyncReadStream, typename DynamicBuffer>
328 std::size_t read_until(SyncReadStream& s,
329 BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
330 const boost::regex& expr);
332 /// Read data into a dynamic buffer sequence until some part of the data it
333 /// contains matches a regular expression.
335 * This function is used to read data into the specified dynamic buffer
336 * sequence until the dynamic buffer sequence's get area contains some data
337 * that matches a regular expression. The call will block until one of the
338 * following conditions is true:
340 * @li A substring of the dynamic buffer sequence's get area matches the
341 * regular expression.
343 * @li An error occurred.
345 * This operation is implemented in terms of zero or more calls to the stream's
346 * read_some function. If the dynamic buffer sequence's get area already
347 * contains data that matches the regular expression, the function returns
350 * @param s The stream from which the data is to be read. The type must support
351 * the SyncReadStream concept.
353 * @param buffers A dynamic buffer sequence into which the data will be read.
355 * @param expr The regular expression.
357 * @param ec Set to indicate what error occurred, if any.
359 * @returns The number of bytes in the dynamic buffer sequence's get area up to
360 * and including the substring that matches the regular expression. Returns 0
361 * if an error occurred.
363 * @note After a successful read_until operation, the dynamic buffer sequence
364 * may contain additional data beyond that which matched the regular
365 * expression. An application will typically leave that data in the dynamic
366 * buffer sequence for a subsequent read_until operation to examine.
368 template <typename SyncReadStream, typename DynamicBuffer>
369 std::size_t read_until(SyncReadStream& s,
370 BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
371 const boost::regex& expr, boost::system::error_code& ec);
373 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
374 // || defined(GENERATING_DOCUMENTATION)
376 /// Read data into a dynamic buffer sequence until a function object indicates a
380 * This function is used to read data into the specified dynamic buffer
381 * sequence until a user-defined match condition function object, when applied
382 * to the data contained in the dynamic buffer sequence, indicates a successful
383 * match. The call will block until one of the following conditions is true:
385 * @li The match condition function object returns a std::pair where the second
386 * element evaluates to true.
388 * @li An error occurred.
390 * This operation is implemented in terms of zero or more calls to the stream's
391 * read_some function. If the match condition function object already indicates
392 * a match, the function returns immediately.
394 * @param s The stream from which the data is to be read. The type must support
395 * the SyncReadStream concept.
397 * @param buffers A dynamic buffer sequence into which the data will be read.
399 * @param match_condition The function object to be called to determine whether
400 * a match exists. The signature of the function object must be:
401 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
403 * where @c iterator represents the type:
404 * @code buffers_iterator<typename DynamicBuffer::const_buffers_type>
406 * The iterator parameters @c begin and @c end define the range of bytes to be
407 * scanned to determine whether there is a match. The @c first member of the
408 * return value is an iterator marking one-past-the-end of the bytes that have
409 * been consumed by the match function. This iterator is used to calculate the
410 * @c begin parameter for any subsequent invocation of the match condition. The
411 * @c second member of the return value is true if a match has been found, false
414 * @returns The number of bytes in the dynamic_buffer's get area that
415 * have been fully consumed by the match function.
417 * @throws boost::system::system_error Thrown on failure.
419 * @note After a successful read_until operation, the dynamic buffer sequence
420 * may contain additional data beyond that which matched the function object.
421 * An application will typically leave that data in the dynamic buffer sequence
422 * for a subsequent read_until operation to examine.
424 * @note The default implementation of the @c is_match_condition type trait
425 * evaluates to true for function pointers and function objects with a
426 * @c result_type typedef. It must be specialised for other user-defined
430 * To read data into a dynamic buffer sequence until whitespace is encountered:
431 * @code typedef boost::asio::buffers_iterator<
432 * boost::asio::const_buffers_1> iterator;
434 * std::pair<iterator, bool>
435 * match_whitespace(iterator begin, iterator end)
437 * iterator i = begin;
439 * if (std::isspace(*i++))
440 * return std::make_pair(i, true);
441 * return std::make_pair(i, false);
445 * boost::asio::read_until(s, data, match_whitespace);
448 * To read data into a @c std::string until a matching character is found:
449 * @code class match_char
452 * explicit match_char(char c) : c_(c) {}
454 * template <typename Iterator>
455 * std::pair<Iterator, bool> operator()(
456 * Iterator begin, Iterator end) const
458 * Iterator i = begin;
461 * return std::make_pair(i, true);
462 * return std::make_pair(i, false);
470 * template <> struct is_match_condition<match_char>
471 * : public boost::true_type {};
472 * } // namespace asio
475 * boost::asio::read_until(s, data, match_char('a'));
478 template <typename SyncReadStream,
479 typename DynamicBuffer, typename MatchCondition>
480 std::size_t read_until(SyncReadStream& s,
481 BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
482 MatchCondition match_condition,
483 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
485 /// Read data into a dynamic buffer sequence until a function object indicates a
488 * This function is used to read data into the specified dynamic buffer
489 * sequence until a user-defined match condition function object, when applied
490 * to the data contained in the dynamic buffer sequence, indicates a successful
491 * match. The call will block until one of the following conditions is true:
493 * @li The match condition function object returns a std::pair where the second
494 * element evaluates to true.
496 * @li An error occurred.
498 * This operation is implemented in terms of zero or more calls to the stream's
499 * read_some function. If the match condition function object already indicates
500 * a match, the function returns immediately.
502 * @param s The stream from which the data is to be read. The type must support
503 * the SyncReadStream concept.
505 * @param buffers A dynamic buffer sequence into which the data will be read.
507 * @param match_condition The function object to be called to determine whether
508 * a match exists. The signature of the function object must be:
509 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
511 * where @c iterator represents the type:
512 * @code buffers_iterator<DynamicBuffer::const_buffers_type>
514 * The iterator parameters @c begin and @c end define the range of bytes to be
515 * scanned to determine whether there is a match. The @c first member of the
516 * return value is an iterator marking one-past-the-end of the bytes that have
517 * been consumed by the match function. This iterator is used to calculate the
518 * @c begin parameter for any subsequent invocation of the match condition. The
519 * @c second member of the return value is true if a match has been found, false
522 * @param ec Set to indicate what error occurred, if any.
524 * @returns The number of bytes in the dynamic buffer sequence's get area that
525 * have been fully consumed by the match function. Returns 0 if an error
528 * @note After a successful read_until operation, the dynamic buffer sequence
529 * may contain additional data beyond that which matched the function object.
530 * An application will typically leave that data in the dynamic buffer sequence
531 * for a subsequent read_until operation to examine.
533 * @note The default implementation of the @c is_match_condition type trait
534 * evaluates to true for function pointers and function objects with a
535 * @c result_type typedef. It must be specialised for other user-defined
538 template <typename SyncReadStream,
539 typename DynamicBuffer, typename MatchCondition>
540 std::size_t read_until(SyncReadStream& s,
541 BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
542 MatchCondition match_condition, boost::system::error_code& ec,
543 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
545 #if !defined(BOOST_ASIO_NO_IOSTREAM)
547 /// Read data into a streambuf until it contains a specified delimiter.
549 * This function is used to read data into the specified streambuf until the
550 * streambuf's get area contains the specified delimiter. The call will block
551 * until one of the following conditions is true:
553 * @li The get area of the streambuf contains the specified delimiter.
555 * @li An error occurred.
557 * This operation is implemented in terms of zero or more calls to the stream's
558 * read_some function. If the streambuf's get area already contains the
559 * delimiter, the function returns immediately.
561 * @param s The stream from which the data is to be read. The type must support
562 * the SyncReadStream concept.
564 * @param b A streambuf object into which the data will be read.
566 * @param delim The delimiter character.
568 * @returns The number of bytes in the streambuf's get area up to and including
571 * @throws boost::system::system_error Thrown on failure.
573 * @note After a successful read_until operation, the streambuf may contain
574 * additional data beyond the delimiter. An application will typically leave
575 * that data in the streambuf for a subsequent read_until operation to examine.
578 * To read data into a streambuf until a newline is encountered:
579 * @code boost::asio::streambuf b;
580 * boost::asio::read_until(s, b, '\n');
581 * std::istream is(&b);
583 * std::getline(is, line); @endcode
584 * After the @c read_until operation completes successfully, the buffer @c b
585 * contains the delimiter:
586 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
587 * The call to @c std::getline then extracts the data up to and including the
588 * newline (which is discarded), so that the string @c line contains:
589 * @code { 'a', 'b', ..., 'c' } @endcode
590 * The remaining data is left in the buffer @c b as follows:
591 * @code { 'd', 'e', ... } @endcode
592 * This data may be the start of a new line, to be extracted by a subsequent
593 * @c read_until operation.
595 template <typename SyncReadStream, typename Allocator>
596 std::size_t read_until(SyncReadStream& s,
597 boost::asio::basic_streambuf<Allocator>& b, char delim);
599 /// Read data into a streambuf until it contains a specified delimiter.
601 * This function is used to read data into the specified streambuf until the
602 * streambuf's get area contains the specified delimiter. The call will block
603 * until one of the following conditions is true:
605 * @li The get area of the streambuf contains the specified delimiter.
607 * @li An error occurred.
609 * This operation is implemented in terms of zero or more calls to the stream's
610 * read_some function. If the streambuf's get area already contains the
611 * delimiter, the function returns immediately.
613 * @param s The stream from which the data is to be read. The type must support
614 * the SyncReadStream concept.
616 * @param b A streambuf object into which the data will be read.
618 * @param delim The delimiter character.
620 * @param ec Set to indicate what error occurred, if any.
622 * @returns The number of bytes in the streambuf's get area up to and including
623 * the delimiter. Returns 0 if an error occurred.
625 * @note After a successful read_until operation, the streambuf may contain
626 * additional data beyond the delimiter. An application will typically leave
627 * that data in the streambuf for a subsequent read_until operation to examine.
629 template <typename SyncReadStream, typename Allocator>
630 std::size_t read_until(SyncReadStream& s,
631 boost::asio::basic_streambuf<Allocator>& b, char delim,
632 boost::system::error_code& ec);
634 /// Read data into a streambuf until it contains a specified delimiter.
636 * This function is used to read data into the specified streambuf until the
637 * streambuf's get area contains the specified delimiter. The call will block
638 * until one of the following conditions is true:
640 * @li The get area of the streambuf contains the specified delimiter.
642 * @li An error occurred.
644 * This operation is implemented in terms of zero or more calls to the stream's
645 * read_some function. If the streambuf's get area already contains the
646 * delimiter, the function returns immediately.
648 * @param s The stream from which the data is to be read. The type must support
649 * the SyncReadStream concept.
651 * @param b A streambuf object into which the data will be read.
653 * @param delim The delimiter string.
655 * @returns The number of bytes in the streambuf's get area up to and including
658 * @throws boost::system::system_error Thrown on failure.
660 * @note After a successful read_until operation, the streambuf may contain
661 * additional data beyond the delimiter. An application will typically leave
662 * that data in the streambuf for a subsequent read_until operation to examine.
665 * To read data into a streambuf until a newline is encountered:
666 * @code boost::asio::streambuf b;
667 * boost::asio::read_until(s, b, "\r\n");
668 * std::istream is(&b);
670 * std::getline(is, line); @endcode
671 * After the @c read_until operation completes successfully, the buffer @c b
672 * contains the delimiter:
673 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
674 * The call to @c std::getline then extracts the data up to and including the
675 * newline (which is discarded), so that the string @c line contains:
676 * @code { 'a', 'b', ..., 'c', '\r' } @endcode
677 * The remaining data is left in the buffer @c b as follows:
678 * @code { 'd', 'e', ... } @endcode
679 * This data may be the start of a new line, to be extracted by a subsequent
680 * @c read_until operation.
682 template <typename SyncReadStream, typename Allocator>
683 std::size_t read_until(SyncReadStream& s,
684 boost::asio::basic_streambuf<Allocator>& b,
685 BOOST_ASIO_STRING_VIEW_PARAM delim);
687 /// Read data into a streambuf until it contains a specified delimiter.
689 * This function is used to read data into the specified streambuf until the
690 * streambuf's get area contains the specified delimiter. The call will block
691 * until one of the following conditions is true:
693 * @li The get area of the streambuf contains the specified delimiter.
695 * @li An error occurred.
697 * This operation is implemented in terms of zero or more calls to the stream's
698 * read_some function. If the streambuf's get area already contains the
699 * delimiter, the function returns immediately.
701 * @param s The stream from which the data is to be read. The type must support
702 * the SyncReadStream concept.
704 * @param b A streambuf object into which the data will be read.
706 * @param delim The delimiter string.
708 * @param ec Set to indicate what error occurred, if any.
710 * @returns The number of bytes in the streambuf's get area up to and including
711 * the delimiter. Returns 0 if an error occurred.
713 * @note After a successful read_until operation, the streambuf may contain
714 * additional data beyond the delimiter. An application will typically leave
715 * that data in the streambuf for a subsequent read_until operation to examine.
717 template <typename SyncReadStream, typename Allocator>
718 std::size_t read_until(SyncReadStream& s,
719 boost::asio::basic_streambuf<Allocator>& b,
720 BOOST_ASIO_STRING_VIEW_PARAM delim, boost::system::error_code& ec);
722 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
723 || defined(GENERATING_DOCUMENTATION)
725 /// Read data into a streambuf until some part of the data it contains matches
726 /// a regular expression.
728 * This function is used to read data into the specified streambuf until the
729 * streambuf's get area contains some data that matches a regular expression.
730 * The call will block until one of the following conditions is true:
732 * @li A substring of the streambuf's get area matches the regular expression.
734 * @li An error occurred.
736 * This operation is implemented in terms of zero or more calls to the stream's
737 * read_some function. If the streambuf's get area already contains data that
738 * matches the regular expression, the function returns immediately.
740 * @param s The stream from which the data is to be read. The type must support
741 * the SyncReadStream concept.
743 * @param b A streambuf object into which the data will be read.
745 * @param expr The regular expression.
747 * @returns The number of bytes in the streambuf's get area up to and including
748 * the substring that matches the regular expression.
750 * @throws boost::system::system_error Thrown on failure.
752 * @note After a successful read_until operation, the streambuf may contain
753 * additional data beyond that which matched the regular expression. An
754 * application will typically leave that data in the streambuf for a subsequent
755 * read_until operation to examine.
758 * To read data into a streambuf until a CR-LF sequence is encountered:
759 * @code boost::asio::streambuf b;
760 * boost::asio::read_until(s, b, boost::regex("\r\n"));
761 * std::istream is(&b);
763 * std::getline(is, line); @endcode
764 * After the @c read_until operation completes successfully, the buffer @c b
765 * contains the data which matched the regular expression:
766 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
767 * The call to @c std::getline then extracts the data up to and including the
768 * newline (which is discarded), so that the string @c line contains:
769 * @code { 'a', 'b', ..., 'c', '\r' } @endcode
770 * The remaining data is left in the buffer @c b as follows:
771 * @code { 'd', 'e', ... } @endcode
772 * This data may be the start of a new line, to be extracted by a subsequent
773 * @c read_until operation.
775 template <typename SyncReadStream, typename Allocator>
776 std::size_t read_until(SyncReadStream& s,
777 boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr);
779 /// Read data into a streambuf until some part of the data it contains matches
780 /// a regular expression.
782 * This function is used to read data into the specified streambuf until the
783 * streambuf's get area contains some data that matches a regular expression.
784 * The call will block until one of the following conditions is true:
786 * @li A substring of the streambuf's get area matches the regular expression.
788 * @li An error occurred.
790 * This operation is implemented in terms of zero or more calls to the stream's
791 * read_some function. If the streambuf's get area already contains data that
792 * matches the regular expression, the function returns immediately.
794 * @param s The stream from which the data is to be read. The type must support
795 * the SyncReadStream concept.
797 * @param b A streambuf object into which the data will be read.
799 * @param expr The regular expression.
801 * @param ec Set to indicate what error occurred, if any.
803 * @returns The number of bytes in the streambuf's get area up to and including
804 * the substring that matches the regular expression. Returns 0 if an error
807 * @note After a successful read_until operation, the streambuf may contain
808 * additional data beyond that which matched the regular expression. An
809 * application will typically leave that data in the streambuf for a subsequent
810 * read_until operation to examine.
812 template <typename SyncReadStream, typename Allocator>
813 std::size_t read_until(SyncReadStream& s,
814 boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr,
815 boost::system::error_code& ec);
817 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
818 // || defined(GENERATING_DOCUMENTATION)
820 /// Read data into a streambuf until a function object indicates a match.
822 * This function is used to read data into the specified streambuf until a
823 * user-defined match condition function object, when applied to the data
824 * contained in the streambuf, indicates a successful match. The call will
825 * block until one of the following conditions is true:
827 * @li The match condition function object returns a std::pair where the second
828 * element evaluates to true.
830 * @li An error occurred.
832 * This operation is implemented in terms of zero or more calls to the stream's
833 * read_some function. If the match condition function object already indicates
834 * a match, the function returns immediately.
836 * @param s The stream from which the data is to be read. The type must support
837 * the SyncReadStream concept.
839 * @param b A streambuf object into which the data will be read.
841 * @param match_condition The function object to be called to determine whether
842 * a match exists. The signature of the function object must be:
843 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
845 * where @c iterator represents the type:
846 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
848 * The iterator parameters @c begin and @c end define the range of bytes to be
849 * scanned to determine whether there is a match. The @c first member of the
850 * return value is an iterator marking one-past-the-end of the bytes that have
851 * been consumed by the match function. This iterator is used to calculate the
852 * @c begin parameter for any subsequent invocation of the match condition. The
853 * @c second member of the return value is true if a match has been found, false
856 * @returns The number of bytes in the streambuf's get area that have been fully
857 * consumed by the match function.
859 * @throws boost::system::system_error Thrown on failure.
861 * @note After a successful read_until operation, the streambuf may contain
862 * additional data beyond that which matched the function object. An application
863 * will typically leave that data in the streambuf for a subsequent read_until
864 * operation to examine.
866 * @note The default implementation of the @c is_match_condition type trait
867 * evaluates to true for function pointers and function objects with a
868 * @c result_type typedef. It must be specialised for other user-defined
872 * To read data into a streambuf until whitespace is encountered:
873 * @code typedef boost::asio::buffers_iterator<
874 * boost::asio::streambuf::const_buffers_type> iterator;
876 * std::pair<iterator, bool>
877 * match_whitespace(iterator begin, iterator end)
879 * iterator i = begin;
881 * if (std::isspace(*i++))
882 * return std::make_pair(i, true);
883 * return std::make_pair(i, false);
886 * boost::asio::streambuf b;
887 * boost::asio::read_until(s, b, match_whitespace);
890 * To read data into a streambuf until a matching character is found:
891 * @code class match_char
894 * explicit match_char(char c) : c_(c) {}
896 * template <typename Iterator>
897 * std::pair<Iterator, bool> operator()(
898 * Iterator begin, Iterator end) const
900 * Iterator i = begin;
903 * return std::make_pair(i, true);
904 * return std::make_pair(i, false);
912 * template <> struct is_match_condition<match_char>
913 * : public boost::true_type {};
914 * } // namespace asio
916 * boost::asio::streambuf b;
917 * boost::asio::read_until(s, b, match_char('a'));
920 template <typename SyncReadStream, typename Allocator, typename MatchCondition>
921 std::size_t read_until(SyncReadStream& s,
922 boost::asio::basic_streambuf<Allocator>& b, MatchCondition match_condition,
923 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
925 /// Read data into a streambuf until a function object indicates a match.
927 * This function is used to read data into the specified streambuf until a
928 * user-defined match condition function object, when applied to the data
929 * contained in the streambuf, indicates a successful match. The call will
930 * block until one of the following conditions is true:
932 * @li The match condition function object returns a std::pair where the second
933 * element evaluates to true.
935 * @li An error occurred.
937 * This operation is implemented in terms of zero or more calls to the stream's
938 * read_some function. If the match condition function object already indicates
939 * a match, the function returns immediately.
941 * @param s The stream from which the data is to be read. The type must support
942 * the SyncReadStream concept.
944 * @param b A streambuf object into which the data will be read.
946 * @param match_condition The function object to be called to determine whether
947 * a match exists. The signature of the function object must be:
948 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
950 * where @c iterator represents the type:
951 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
953 * The iterator parameters @c begin and @c end define the range of bytes to be
954 * scanned to determine whether there is a match. The @c first member of the
955 * return value is an iterator marking one-past-the-end of the bytes that have
956 * been consumed by the match function. This iterator is used to calculate the
957 * @c begin parameter for any subsequent invocation of the match condition. The
958 * @c second member of the return value is true if a match has been found, false
961 * @param ec Set to indicate what error occurred, if any.
963 * @returns The number of bytes in the streambuf's get area that have been fully
964 * consumed by the match function. Returns 0 if an error occurred.
966 * @note After a successful read_until operation, the streambuf may contain
967 * additional data beyond that which matched the function object. An application
968 * will typically leave that data in the streambuf for a subsequent read_until
969 * operation to examine.
971 * @note The default implementation of the @c is_match_condition type trait
972 * evaluates to true for function pointers and function objects with a
973 * @c result_type typedef. It must be specialised for other user-defined
976 template <typename SyncReadStream, typename Allocator, typename MatchCondition>
977 std::size_t read_until(SyncReadStream& s,
978 boost::asio::basic_streambuf<Allocator>& b,
979 MatchCondition match_condition, boost::system::error_code& ec,
980 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
982 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
983 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
987 * @defgroup async_read_until boost::asio::async_read_until
989 * @brief Start an asynchronous operation to read data into a dynamic buffer
990 * sequence, or into a streambuf, until it contains a delimiter, matches a
991 * regular expression, or a function object indicates a match.
995 /// Start an asynchronous operation to read data into a dynamic buffer sequence
996 /// until it contains a specified delimiter.
998 * This function is used to asynchronously read data into the specified dynamic
999 * buffer sequence until the dynamic buffer sequence's get area contains the
1000 * specified delimiter. The function call always returns immediately. The
1001 * asynchronous operation will continue until one of the following conditions
1004 * @li The get area of the dynamic buffer sequence contains the specified
1007 * @li An error occurred.
1009 * This operation is implemented in terms of zero or more calls to the stream's
1010 * async_read_some function, and is known as a <em>composed operation</em>. If
1011 * the dynamic buffer sequence's get area already contains the delimiter, this
1012 * asynchronous operation completes immediately. The program must ensure that
1013 * the stream performs no other read operations (such as async_read,
1014 * async_read_until, the stream's async_read_some function, or any other
1015 * composed operations that perform reads) until this operation completes.
1017 * @param s The stream from which the data is to be read. The type must support
1018 * the AsyncReadStream concept.
1020 * @param buffers The dynamic buffer sequence into which the data will be read.
1021 * Although the buffers object may be copied as necessary, ownership of the
1022 * underlying memory blocks is retained by the caller, which must guarantee
1023 * that they remain valid until the handler is called.
1025 * @param delim The delimiter character.
1027 * @param handler The handler to be called when the read operation completes.
1028 * Copies will be made of the handler as required. The function signature of the
1030 * @code void handler(
1031 * // Result of operation.
1032 * const boost::system::error_code& error,
1034 * // The number of bytes in the dynamic buffer sequence's
1035 * // get area up to and including the delimiter.
1036 * // 0 if an error occurred.
1037 * std::size_t bytes_transferred
1039 * Regardless of whether the asynchronous operation completes immediately or
1040 * not, the handler will not be invoked from within this function. Invocation of
1041 * the handler will be performed in a manner equivalent to using
1042 * boost::asio::io_context::post().
1044 * @note After a successful async_read_until operation, the dynamic buffer
1045 * sequence may contain additional data beyond the delimiter. An application
1046 * will typically leave that data in the dynamic buffer sequence for a
1047 * subsequent async_read_until operation to examine.
1050 * To asynchronously read data into a @c std::string until a newline is
1052 * @code std::string data;
1054 * void handler(const boost::system::error_code& e, std::size_t size)
1058 * std::string line = data.substr(0, n);
1064 * boost::asio::async_read_until(s, data, '\n', handler); @endcode
1065 * After the @c async_read_until operation completes successfully, the buffer
1066 * @c data contains the delimiter:
1067 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
1068 * The call to @c substr then extracts the data up to and including the
1069 * delimiter, so that the string @c line contains:
1070 * @code { 'a', 'b', ..., 'c', '\n' } @endcode
1071 * After the call to @c erase, the remaining data is left in the buffer @c data
1073 * @code { 'd', 'e', ... } @endcode
1074 * This data may be the start of a new line, to be extracted by a subsequent
1075 * @c async_read_until operation.
1077 template <typename AsyncReadStream,
1078 typename DynamicBuffer, typename ReadHandler>
1079 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
1080 void (boost::system::error_code, std::size_t))
1081 async_read_until(AsyncReadStream& s,
1082 BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
1083 char delim, BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
1085 /// Start an asynchronous operation to read data into a dynamic buffer sequence
1086 /// until it contains a specified delimiter.
1088 * This function is used to asynchronously read data into the specified dynamic
1089 * buffer sequence until the dynamic buffer sequence's get area contains the
1090 * specified delimiter. The function call always returns immediately. The
1091 * asynchronous operation will continue until one of the following conditions
1094 * @li The get area of the dynamic buffer sequence contains the specified
1097 * @li An error occurred.
1099 * This operation is implemented in terms of zero or more calls to the stream's
1100 * async_read_some function, and is known as a <em>composed operation</em>. If
1101 * the dynamic buffer sequence's get area already contains the delimiter, this
1102 * asynchronous operation completes immediately. The program must ensure that
1103 * the stream performs no other read operations (such as async_read,
1104 * async_read_until, the stream's async_read_some function, or any other
1105 * composed operations that perform reads) until this operation completes.
1107 * @param s The stream from which the data is to be read. The type must support
1108 * the AsyncReadStream concept.
1110 * @param buffers The dynamic buffer sequence into which the data will be read.
1111 * Although the buffers object may be copied as necessary, ownership of the
1112 * underlying memory blocks is retained by the caller, which must guarantee
1113 * that they remain valid until the handler is called.
1115 * @param delim The delimiter string.
1117 * @param handler The handler to be called when the read operation completes.
1118 * Copies will be made of the handler as required. The function signature of the
1120 * @code void handler(
1121 * // Result of operation.
1122 * const boost::system::error_code& error,
1124 * // The number of bytes in the dynamic buffer sequence's
1125 * // get area up to and including the delimiter.
1126 * // 0 if an error occurred.
1127 * std::size_t bytes_transferred
1129 * Regardless of whether the asynchronous operation completes immediately or
1130 * not, the handler will not be invoked from within this function. Invocation of
1131 * the handler will be performed in a manner equivalent to using
1132 * boost::asio::io_context::post().
1134 * @note After a successful async_read_until operation, the dynamic buffer
1135 * sequence may contain additional data beyond the delimiter. An application
1136 * will typically leave that data in the dynamic buffer sequence for a
1137 * subsequent async_read_until operation to examine.
1140 * To asynchronously read data into a @c std::string until a CR-LF sequence is
1142 * @code std::string data;
1144 * void handler(const boost::system::error_code& e, std::size_t size)
1148 * std::string line = data.substr(0, n);
1154 * boost::asio::async_read_until(s, data, "\r\n", handler); @endcode
1155 * After the @c async_read_until operation completes successfully, the string
1156 * @c data contains the delimiter:
1157 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
1158 * The call to @c substr then extracts the data up to and including the
1159 * delimiter, so that the string @c line contains:
1160 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
1161 * After the call to @c erase, the remaining data is left in the string @c data
1163 * @code { 'd', 'e', ... } @endcode
1164 * This data may be the start of a new line, to be extracted by a subsequent
1165 * @c async_read_until operation.
1167 template <typename AsyncReadStream,
1168 typename DynamicBuffer, typename ReadHandler>
1169 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
1170 void (boost::system::error_code, std::size_t))
1171 async_read_until(AsyncReadStream& s,
1172 BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
1173 BOOST_ASIO_STRING_VIEW_PARAM delim,
1174 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
1176 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
1177 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
1178 || defined(GENERATING_DOCUMENTATION)
1180 /// Start an asynchronous operation to read data into a dynamic buffer sequence
1181 /// until some part of its data matches a regular expression.
1183 * This function is used to asynchronously read data into the specified dynamic
1184 * buffer sequence until the dynamic buffer sequence's get area contains some
1185 * data that matches a regular expression. The function call always returns
1186 * immediately. The asynchronous operation will continue until one of the
1187 * following conditions is true:
1189 * @li A substring of the dynamic buffer sequence's get area matches the regular
1192 * @li An error occurred.
1194 * This operation is implemented in terms of zero or more calls to the stream's
1195 * async_read_some function, and is known as a <em>composed operation</em>. If
1196 * the dynamic buffer sequence's get area already contains data that matches
1197 * the regular expression, this asynchronous operation completes immediately.
1198 * The program must ensure that the stream performs no other read operations
1199 * (such as async_read, async_read_until, the stream's async_read_some
1200 * function, or any other composed operations that perform reads) until this
1201 * operation completes.
1203 * @param s The stream from which the data is to be read. The type must support
1204 * the AsyncReadStream concept.
1206 * @param buffers The dynamic buffer sequence into which the data will be read.
1207 * Although the buffers object may be copied as necessary, ownership of the
1208 * underlying memory blocks is retained by the caller, which must guarantee
1209 * that they remain valid until the handler is called.
1211 * @param expr The regular expression.
1213 * @param handler The handler to be called when the read operation completes.
1214 * Copies will be made of the handler as required. The function signature of the
1216 * @code void handler(
1217 * // Result of operation.
1218 * const boost::system::error_code& error,
1220 * // The number of bytes in the dynamic buffer
1221 * // sequence's get area up to and including the
1222 * // substring that matches the regular expression.
1223 * // 0 if an error occurred.
1224 * std::size_t bytes_transferred
1226 * Regardless of whether the asynchronous operation completes immediately or
1227 * not, the handler will not be invoked from within this function. Invocation of
1228 * the handler will be performed in a manner equivalent to using
1229 * boost::asio::io_context::post().
1231 * @note After a successful async_read_until operation, the dynamic buffer
1232 * sequence may contain additional data beyond that which matched the regular
1233 * expression. An application will typically leave that data in the dynamic
1234 * buffer sequence for a subsequent async_read_until operation to examine.
1237 * To asynchronously read data into a @c std::string until a CR-LF sequence is
1239 * @code std::string data;
1241 * void handler(const boost::system::error_code& e, std::size_t size)
1245 * std::string line = data.substr(0, n);
1251 * boost::asio::async_read_until(s, data,
1252 * boost::regex("\r\n"), handler); @endcode
1253 * After the @c async_read_until operation completes successfully, the string
1254 * @c data contains the data which matched the regular expression:
1255 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
1256 * The call to @c substr then extracts the data up to and including the match,
1257 * so that the string @c line contains:
1258 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
1259 * After the call to @c erase, the remaining data is left in the string @c data
1261 * @code { 'd', 'e', ... } @endcode
1262 * This data may be the start of a new line, to be extracted by a subsequent
1263 * @c async_read_until operation.
1265 template <typename AsyncReadStream,
1266 typename DynamicBuffer, typename ReadHandler>
1267 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
1268 void (boost::system::error_code, std::size_t))
1269 async_read_until(AsyncReadStream& s,
1270 BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
1271 const boost::regex& expr,
1272 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
1274 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
1275 // || defined(GENERATING_DOCUMENTATION)
1277 /// Start an asynchronous operation to read data into a dynamic buffer sequence
1278 /// until a function object indicates a match.
1280 * This function is used to asynchronously read data into the specified dynamic
1281 * buffer sequence until a user-defined match condition function object, when
1282 * applied to the data contained in the dynamic buffer sequence, indicates a
1283 * successful match. The function call always returns immediately. The
1284 * asynchronous operation will continue until one of the following conditions
1287 * @li The match condition function object returns a std::pair where the second
1288 * element evaluates to true.
1290 * @li An error occurred.
1292 * This operation is implemented in terms of zero or more calls to the stream's
1293 * async_read_some function, and is known as a <em>composed operation</em>. If
1294 * the match condition function object already indicates a match, this
1295 * asynchronous operation completes immediately. The program must ensure that
1296 * the stream performs no other read operations (such as async_read,
1297 * async_read_until, the stream's async_read_some function, or any other
1298 * composed operations that perform reads) until this operation completes.
1300 * @param s The stream from which the data is to be read. The type must support
1301 * the AsyncReadStream concept.
1303 * @param buffers The dynamic buffer sequence into which the data will be read.
1304 * Although the buffers object may be copied as necessary, ownership of the
1305 * underlying memory blocks is retained by the caller, which must guarantee
1306 * that they remain valid until the handler is called.
1308 * @param match_condition The function object to be called to determine whether
1309 * a match exists. The signature of the function object must be:
1310 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
1312 * where @c iterator represents the type:
1313 * @code buffers_iterator<typename DynamicBuffer::const_buffers_type>
1315 * The iterator parameters @c begin and @c end define the range of bytes to be
1316 * scanned to determine whether there is a match. The @c first member of the
1317 * return value is an iterator marking one-past-the-end of the bytes that have
1318 * been consumed by the match function. This iterator is used to calculate the
1319 * @c begin parameter for any subsequent invocation of the match condition. The
1320 * @c second member of the return value is true if a match has been found, false
1323 * @param handler The handler to be called when the read operation completes.
1324 * Copies will be made of the handler as required. The function signature of the
1326 * @code void handler(
1327 * // Result of operation.
1328 * const boost::system::error_code& error,
1330 * // The number of bytes in the dynamic buffer sequence's
1331 * // get area that have been fully consumed by the match
1332 * // function. O if an error occurred.
1333 * std::size_t bytes_transferred
1335 * Regardless of whether the asynchronous operation completes immediately or
1336 * not, the handler will not be invoked from within this function. Invocation of
1337 * the handler will be performed in a manner equivalent to using
1338 * boost::asio::io_context::post().
1340 * @note After a successful async_read_until operation, the dynamic buffer
1341 * sequence may contain additional data beyond that which matched the function
1342 * object. An application will typically leave that data in the dynamic buffer
1343 * sequence for a subsequent async_read_until operation to examine.
1345 * @note The default implementation of the @c is_match_condition type trait
1346 * evaluates to true for function pointers and function objects with a
1347 * @c result_type typedef. It must be specialised for other user-defined
1351 * To asynchronously read data into a @c std::string until whitespace is
1353 * @code typedef boost::asio::buffers_iterator<
1354 * boost::asio::const_buffers_1> iterator;
1356 * std::pair<iterator, bool>
1357 * match_whitespace(iterator begin, iterator end)
1359 * iterator i = begin;
1361 * if (std::isspace(*i++))
1362 * return std::make_pair(i, true);
1363 * return std::make_pair(i, false);
1366 * void handler(const boost::system::error_code& e, std::size_t size);
1369 * boost::asio::async_read_until(s, data, match_whitespace, handler);
1372 * To asynchronously read data into a @c std::string until a matching character
1374 * @code class match_char
1377 * explicit match_char(char c) : c_(c) {}
1379 * template <typename Iterator>
1380 * std::pair<Iterator, bool> operator()(
1381 * Iterator begin, Iterator end) const
1383 * Iterator i = begin;
1386 * return std::make_pair(i, true);
1387 * return std::make_pair(i, false);
1395 * template <> struct is_match_condition<match_char>
1396 * : public boost::true_type {};
1397 * } // namespace asio
1399 * void handler(const boost::system::error_code& e, std::size_t size);
1402 * boost::asio::async_read_until(s, data, match_char('a'), handler);
1405 template <typename AsyncReadStream, typename DynamicBuffer,
1406 typename MatchCondition, typename ReadHandler>
1407 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
1408 void (boost::system::error_code, std::size_t))
1409 async_read_until(AsyncReadStream& s,
1410 BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
1411 MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
1412 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
1414 #if !defined(BOOST_ASIO_NO_IOSTREAM)
1416 /// Start an asynchronous operation to read data into a streambuf until it
1417 /// contains a specified delimiter.
1419 * This function is used to asynchronously read data into the specified
1420 * streambuf until the streambuf's get area contains the specified delimiter.
1421 * The function call always returns immediately. The asynchronous operation
1422 * will continue until one of the following conditions is true:
1424 * @li The get area of the streambuf contains the specified delimiter.
1426 * @li An error occurred.
1428 * This operation is implemented in terms of zero or more calls to the stream's
1429 * async_read_some function, and is known as a <em>composed operation</em>. If
1430 * the streambuf's get area already contains the delimiter, this asynchronous
1431 * operation completes immediately. The program must ensure that the stream
1432 * performs no other read operations (such as async_read, async_read_until, the
1433 * stream's async_read_some function, or any other composed operations that
1434 * perform reads) until this operation completes.
1436 * @param s The stream from which the data is to be read. The type must support
1437 * the AsyncReadStream concept.
1439 * @param b A streambuf object into which the data will be read. Ownership of
1440 * the streambuf is retained by the caller, which must guarantee that it remains
1441 * valid until the handler is called.
1443 * @param delim The delimiter character.
1445 * @param handler The handler to be called when the read operation completes.
1446 * Copies will be made of the handler as required. The function signature of the
1448 * @code void handler(
1449 * // Result of operation.
1450 * const boost::system::error_code& error,
1452 * // The number of bytes in the streambuf's get
1453 * // area up to and including the delimiter.
1454 * // 0 if an error occurred.
1455 * std::size_t bytes_transferred
1457 * Regardless of whether the asynchronous operation completes immediately or
1458 * not, the handler will not be invoked from within this function. Invocation of
1459 * the handler will be performed in a manner equivalent to using
1460 * boost::asio::io_context::post().
1462 * @note After a successful async_read_until operation, the streambuf may
1463 * contain additional data beyond the delimiter. An application will typically
1464 * leave that data in the streambuf for a subsequent async_read_until operation
1468 * To asynchronously read data into a streambuf until a newline is encountered:
1469 * @code boost::asio::streambuf b;
1471 * void handler(const boost::system::error_code& e, std::size_t size)
1475 * std::istream is(&b);
1477 * std::getline(is, line);
1482 * boost::asio::async_read_until(s, b, '\n', handler); @endcode
1483 * After the @c async_read_until operation completes successfully, the buffer
1484 * @c b contains the delimiter:
1485 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
1486 * The call to @c std::getline then extracts the data up to and including the
1487 * newline (which is discarded), so that the string @c line contains:
1488 * @code { 'a', 'b', ..., 'c' } @endcode
1489 * The remaining data is left in the buffer @c b as follows:
1490 * @code { 'd', 'e', ... } @endcode
1491 * This data may be the start of a new line, to be extracted by a subsequent
1492 * @c async_read_until operation.
1494 template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
1495 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
1496 void (boost::system::error_code, std::size_t))
1497 async_read_until(AsyncReadStream& s,
1498 boost::asio::basic_streambuf<Allocator>& b,
1499 char delim, BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
1501 /// Start an asynchronous operation to read data into a streambuf until it
1502 /// contains a specified delimiter.
1504 * This function is used to asynchronously read data into the specified
1505 * streambuf until the streambuf's get area contains the specified delimiter.
1506 * The function call always returns immediately. The asynchronous operation
1507 * will continue until one of the following conditions is true:
1509 * @li The get area of the streambuf contains the specified delimiter.
1511 * @li An error occurred.
1513 * This operation is implemented in terms of zero or more calls to the stream's
1514 * async_read_some function, and is known as a <em>composed operation</em>. If
1515 * the streambuf's get area already contains the delimiter, this asynchronous
1516 * operation completes immediately. The program must ensure that the stream
1517 * performs no other read operations (such as async_read, async_read_until, the
1518 * stream's async_read_some function, or any other composed operations that
1519 * perform reads) until this operation completes.
1521 * @param s The stream from which the data is to be read. The type must support
1522 * the AsyncReadStream concept.
1524 * @param b A streambuf object into which the data will be read. Ownership of
1525 * the streambuf is retained by the caller, which must guarantee that it remains
1526 * valid until the handler is called.
1528 * @param delim The delimiter string.
1530 * @param handler The handler to be called when the read operation completes.
1531 * Copies will be made of the handler as required. The function signature of the
1533 * @code void handler(
1534 * // Result of operation.
1535 * const boost::system::error_code& error,
1537 * // The number of bytes in the streambuf's get
1538 * // area up to and including the delimiter.
1539 * // 0 if an error occurred.
1540 * std::size_t bytes_transferred
1542 * Regardless of whether the asynchronous operation completes immediately or
1543 * not, the handler will not be invoked from within this function. Invocation of
1544 * the handler will be performed in a manner equivalent to using
1545 * boost::asio::io_context::post().
1547 * @note After a successful async_read_until operation, the streambuf may
1548 * contain additional data beyond the delimiter. An application will typically
1549 * leave that data in the streambuf for a subsequent async_read_until operation
1553 * To asynchronously read data into a streambuf until a newline is encountered:
1554 * @code boost::asio::streambuf b;
1556 * void handler(const boost::system::error_code& e, std::size_t size)
1560 * std::istream is(&b);
1562 * std::getline(is, line);
1567 * boost::asio::async_read_until(s, b, "\r\n", handler); @endcode
1568 * After the @c async_read_until operation completes successfully, the buffer
1569 * @c b contains the delimiter:
1570 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
1571 * The call to @c std::getline then extracts the data up to and including the
1572 * newline (which is discarded), so that the string @c line contains:
1573 * @code { 'a', 'b', ..., 'c', '\r' } @endcode
1574 * The remaining data is left in the buffer @c b as follows:
1575 * @code { 'd', 'e', ... } @endcode
1576 * This data may be the start of a new line, to be extracted by a subsequent
1577 * @c async_read_until operation.
1579 template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
1580 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
1581 void (boost::system::error_code, std::size_t))
1582 async_read_until(AsyncReadStream& s,
1583 boost::asio::basic_streambuf<Allocator>& b,
1584 BOOST_ASIO_STRING_VIEW_PARAM delim,
1585 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
1587 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
1588 || defined(GENERATING_DOCUMENTATION)
1590 /// Start an asynchronous operation to read data into a streambuf until some
1591 /// part of its data matches a regular expression.
1593 * This function is used to asynchronously read data into the specified
1594 * streambuf until the streambuf's get area contains some data that matches a
1595 * regular expression. The function call always returns immediately. The
1596 * asynchronous operation will continue until one of the following conditions
1599 * @li A substring of the streambuf's get area matches the regular expression.
1601 * @li An error occurred.
1603 * This operation is implemented in terms of zero or more calls to the stream's
1604 * async_read_some function, and is known as a <em>composed operation</em>. If
1605 * the streambuf's get area already contains data that matches the regular
1606 * expression, this asynchronous operation completes immediately. The program
1607 * must ensure that the stream performs no other read operations (such as
1608 * async_read, async_read_until, the stream's async_read_some function, or any
1609 * other composed operations that perform reads) until this operation
1612 * @param s The stream from which the data is to be read. The type must support
1613 * the AsyncReadStream concept.
1615 * @param b A streambuf object into which the data will be read. Ownership of
1616 * the streambuf is retained by the caller, which must guarantee that it remains
1617 * valid until the handler is called.
1619 * @param expr The regular expression.
1621 * @param handler The handler to be called when the read operation completes.
1622 * Copies will be made of the handler as required. The function signature of the
1624 * @code void handler(
1625 * // Result of operation.
1626 * const boost::system::error_code& error,
1628 * // The number of bytes in the streambuf's get
1629 * // area up to and including the substring
1630 * // that matches the regular. expression.
1631 * // 0 if an error occurred.
1632 * std::size_t bytes_transferred
1634 * Regardless of whether the asynchronous operation completes immediately or
1635 * not, the handler will not be invoked from within this function. Invocation of
1636 * the handler will be performed in a manner equivalent to using
1637 * boost::asio::io_context::post().
1639 * @note After a successful async_read_until operation, the streambuf may
1640 * contain additional data beyond that which matched the regular expression. An
1641 * application will typically leave that data in the streambuf for a subsequent
1642 * async_read_until operation to examine.
1645 * To asynchronously read data into a streambuf until a CR-LF sequence is
1647 * @code boost::asio::streambuf b;
1649 * void handler(const boost::system::error_code& e, std::size_t size)
1653 * std::istream is(&b);
1655 * std::getline(is, line);
1660 * boost::asio::async_read_until(s, b, boost::regex("\r\n"), handler); @endcode
1661 * After the @c async_read_until operation completes successfully, the buffer
1662 * @c b contains the data which matched the regular expression:
1663 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
1664 * The call to @c std::getline then extracts the data up to and including the
1665 * newline (which is discarded), so that the string @c line contains:
1666 * @code { 'a', 'b', ..., 'c', '\r' } @endcode
1667 * The remaining data is left in the buffer @c b as follows:
1668 * @code { 'd', 'e', ... } @endcode
1669 * This data may be the start of a new line, to be extracted by a subsequent
1670 * @c async_read_until operation.
1672 template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
1673 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
1674 void (boost::system::error_code, std::size_t))
1675 async_read_until(AsyncReadStream& s,
1676 boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr,
1677 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
1679 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
1680 // || defined(GENERATING_DOCUMENTATION)
1682 /// Start an asynchronous operation to read data into a streambuf until a
1683 /// function object indicates a match.
1685 * This function is used to asynchronously read data into the specified
1686 * streambuf until a user-defined match condition function object, when applied
1687 * to the data contained in the streambuf, indicates a successful match. The
1688 * function call always returns immediately. The asynchronous operation will
1689 * continue until one of the following conditions is true:
1691 * @li The match condition function object returns a std::pair where the second
1692 * element evaluates to true.
1694 * @li An error occurred.
1696 * This operation is implemented in terms of zero or more calls to the stream's
1697 * async_read_some function, and is known as a <em>composed operation</em>. If
1698 * the match condition function object already indicates a match, this
1699 * asynchronous operation completes immediately. The program must ensure that
1700 * the stream performs no other read operations (such as async_read,
1701 * async_read_until, the stream's async_read_some function, or any other
1702 * composed operations that perform reads) until this operation completes.
1704 * @param s The stream from which the data is to be read. The type must support
1705 * the AsyncReadStream concept.
1707 * @param b A streambuf object into which the data will be read.
1709 * @param match_condition The function object to be called to determine whether
1710 * a match exists. The signature of the function object must be:
1711 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
1713 * where @c iterator represents the type:
1714 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
1716 * The iterator parameters @c begin and @c end define the range of bytes to be
1717 * scanned to determine whether there is a match. The @c first member of the
1718 * return value is an iterator marking one-past-the-end of the bytes that have
1719 * been consumed by the match function. This iterator is used to calculate the
1720 * @c begin parameter for any subsequent invocation of the match condition. The
1721 * @c second member of the return value is true if a match has been found, false
1724 * @param handler The handler to be called when the read operation completes.
1725 * Copies will be made of the handler as required. The function signature of the
1727 * @code void handler(
1728 * // Result of operation.
1729 * const boost::system::error_code& error,
1731 * // The number of bytes in the streambuf's get
1732 * // area that have been fully consumed by the
1733 * // match function. O if an error occurred.
1734 * std::size_t bytes_transferred
1736 * Regardless of whether the asynchronous operation completes immediately or
1737 * not, the handler will not be invoked from within this function. Invocation of
1738 * the handler will be performed in a manner equivalent to using
1739 * boost::asio::io_context::post().
1741 * @note After a successful async_read_until operation, the streambuf may
1742 * contain additional data beyond that which matched the function object. An
1743 * application will typically leave that data in the streambuf for a subsequent
1744 * async_read_until operation to examine.
1746 * @note The default implementation of the @c is_match_condition type trait
1747 * evaluates to true for function pointers and function objects with a
1748 * @c result_type typedef. It must be specialised for other user-defined
1752 * To asynchronously read data into a streambuf until whitespace is encountered:
1753 * @code typedef boost::asio::buffers_iterator<
1754 * boost::asio::streambuf::const_buffers_type> iterator;
1756 * std::pair<iterator, bool>
1757 * match_whitespace(iterator begin, iterator end)
1759 * iterator i = begin;
1761 * if (std::isspace(*i++))
1762 * return std::make_pair(i, true);
1763 * return std::make_pair(i, false);
1766 * void handler(const boost::system::error_code& e, std::size_t size);
1768 * boost::asio::streambuf b;
1769 * boost::asio::async_read_until(s, b, match_whitespace, handler);
1772 * To asynchronously read data into a streambuf until a matching character is
1774 * @code class match_char
1777 * explicit match_char(char c) : c_(c) {}
1779 * template <typename Iterator>
1780 * std::pair<Iterator, bool> operator()(
1781 * Iterator begin, Iterator end) const
1783 * Iterator i = begin;
1786 * return std::make_pair(i, true);
1787 * return std::make_pair(i, false);
1795 * template <> struct is_match_condition<match_char>
1796 * : public boost::true_type {};
1797 * } // namespace asio
1799 * void handler(const boost::system::error_code& e, std::size_t size);
1801 * boost::asio::streambuf b;
1802 * boost::asio::async_read_until(s, b, match_char('a'), handler);
1805 template <typename AsyncReadStream, typename Allocator,
1806 typename MatchCondition, typename ReadHandler>
1807 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
1808 void (boost::system::error_code, std::size_t))
1809 async_read_until(AsyncReadStream& s,
1810 boost::asio::basic_streambuf<Allocator>& b,
1811 MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
1812 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
1814 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
1815 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
1820 } // namespace boost
1822 #include <boost/asio/detail/pop_options.hpp>
1824 #include <boost/asio/impl/read_until.hpp>
1826 #endif // BOOST_ASIO_READ_UNTIL_HPP