1//
2// read_until.hpp
3// ~~~~~~~~~~~~~~
4//
5// Copyright (c) 2003-2024 Christopher M. Kohlhoff (chris at kohlhoff dot com)
6//
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)
9//
10
11#ifndef BOOST_ASIO_READ_UNTIL_HPP
12#define BOOST_ASIO_READ_UNTIL_HPP
13
14#if defined(_MSC_VER) && (_MSC_VER >= 1200)
15# pragma once
16#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
17
18#include <boost/asio/detail/config.hpp>
19#include <cstddef>
20#include <string>
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>
27
28#if !defined(BOOST_ASIO_NO_EXTENSIONS)
29# include <boost/asio/basic_streambuf_fwd.hpp>
30#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
31
32#include <boost/asio/detail/push_options.hpp>
33
34namespace boost {
35namespace asio {
36namespace detail {
37
38char (&has_result_type_helper(...))[2];
39
40template <typename T>
41char has_result_type_helper(T*, typename T::result_type* = 0);
42
43template <typename T>
44struct has_result_type
45{
46 enum { value = (sizeof((has_result_type_helper)((T*)(0))) == 1) };
47};
48
49#if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
50template <typename> class initiate_async_read_until_delim_v1;
51template <typename> class initiate_async_read_until_delim_string_v1;
52#if defined(BOOST_ASIO_HAS_BOOST_REGEX)
53template <typename> class initiate_async_read_until_expr_v1;
54#endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
55template <typename> class initiate_async_read_until_match_v1;
56#endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
57template <typename> class initiate_async_read_until_delim_v2;
58template <typename> class initiate_async_read_until_delim_string_v2;
59#if defined(BOOST_ASIO_HAS_BOOST_REGEX)
60template <typename> class initiate_async_read_until_expr_v2;
61#endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
62template <typename> class initiate_async_read_until_match_v2;
63
64} // namespace detail
65
66/// Type trait used to determine whether a type can be used as a match condition
67/// function with read_until and async_read_until.
68template <typename T>
69struct is_match_condition
70{
71#if defined(GENERATING_DOCUMENTATION)
72 /// The value member is true if the type may be used as a match condition.
73 static const bool value;
74#else
75 enum
76 {
77 value = boost::asio::is_function<remove_pointer_t<T>>::value
78 || detail::has_result_type<T>::value
79 };
80#endif
81};
82
83/**
84 * @defgroup read_until boost::asio::read_until
85 *
86 * @brief The @c read_until function is a composed operation that reads data
87 * into a dynamic buffer sequence, or into a streambuf, until it contains a
88 * delimiter, matches a regular expression, or a function object indicates a
89 * match.
90 */
91/*@{*/
92
93#if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
94
95/// Read data into a dynamic buffer sequence until it contains a specified
96/// delimiter.
97/**
98 * This function is used to read data into the specified dynamic buffer
99 * sequence until the dynamic buffer sequence's get area contains the specified
100 * delimiter. The call will block until one of the following conditions is
101 * true:
102 *
103 * @li The get area of the dynamic buffer sequence contains the specified
104 * delimiter.
105 *
106 * @li An error occurred.
107 *
108 * This operation is implemented in terms of zero or more calls to the stream's
109 * read_some function. If the dynamic buffer sequence's get area already
110 * contains the delimiter, the function returns immediately.
111 *
112 * @param s The stream from which the data is to be read. The type must support
113 * the SyncReadStream concept.
114 *
115 * @param buffers The dynamic buffer sequence into which the data will be read.
116 *
117 * @param delim The delimiter character.
118 *
119 * @returns The number of bytes in the dynamic buffer sequence's get area up to
120 * and including the delimiter.
121 *
122 * @throws boost::system::system_error Thrown on failure.
123 *
124 * @note After a successful read_until operation, the dynamic buffer sequence
125 * may contain additional data beyond the delimiter. An application will
126 * typically leave that data in the dynamic buffer sequence for a subsequent
127 * read_until operation to examine.
128 *
129 * @par Example
130 * To read data into a @c std::string until a newline is encountered:
131 * @code std::string data;
132 * std::size_t n = boost::asio::read_until(s,
133 * boost::asio::dynamic_buffer(data), '\n');
134 * std::string line = data.substr(0, n);
135 * data.erase(0, n); @endcode
136 * After the @c read_until operation completes successfully, the string @c data
137 * contains the delimiter:
138 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
139 * The call to @c substr then extracts the data up to and including the
140 * delimiter, so that the string @c line contains:
141 * @code { 'a', 'b', ..., 'c', '\n' } @endcode
142 * After the call to @c erase, the remaining data is left in the buffer @c b as
143 * follows:
144 * @code { 'd', 'e', ... } @endcode
145 * This data may be the start of a new line, to be extracted by a subsequent
146 * @c read_until operation.
147 */
148template <typename SyncReadStream, typename DynamicBuffer_v1>
149std::size_t read_until(SyncReadStream& s,
150 DynamicBuffer_v1&& buffers, char delim,
151 constraint_t<
152 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
153 > = 0,
154 constraint_t<
155 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
156 > = 0);
157
158/// Read data into a dynamic buffer sequence until it contains a specified
159/// delimiter.
160/**
161 * This function is used to read data into the specified dynamic buffer
162 * sequence until the dynamic buffer sequence's get area contains the specified
163 * delimiter. The call will block until one of the following conditions is
164 * true:
165 *
166 * @li The get area of the dynamic buffer sequence contains the specified
167 * delimiter.
168 *
169 * @li An error occurred.
170 *
171 * This operation is implemented in terms of zero or more calls to the stream's
172 * read_some function. If the dynamic buffer sequence's get area already
173 * contains the delimiter, the function returns immediately.
174 *
175 * @param s The stream from which the data is to be read. The type must support
176 * the SyncReadStream concept.
177 *
178 * @param buffers The dynamic buffer sequence into which the data will be read.
179 *
180 * @param delim The delimiter character.
181 *
182 * @param ec Set to indicate what error occurred, if any.
183 *
184 * @returns The number of bytes in the dynamic buffer sequence's get area up to
185 * and including the delimiter. Returns 0 if an error occurred.
186 *
187 * @note After a successful read_until operation, the dynamic buffer sequence
188 * may contain additional data beyond the delimiter. An application will
189 * typically leave that data in the dynamic buffer sequence for a subsequent
190 * read_until operation to examine.
191 */
192template <typename SyncReadStream, typename DynamicBuffer_v1>
193std::size_t read_until(SyncReadStream& s,
194 DynamicBuffer_v1&& buffers,
195 char delim, boost::system::error_code& ec,
196 constraint_t<
197 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
198 > = 0,
199 constraint_t<
200 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
201 > = 0);
202
203/// Read data into a dynamic buffer sequence until it contains a specified
204/// delimiter.
205/**
206 * This function is used to read data into the specified dynamic buffer
207 * sequence until the dynamic buffer sequence's get area contains the specified
208 * delimiter. The call will block until one of the following conditions is
209 * true:
210 *
211 * @li The get area of the dynamic buffer sequence contains the specified
212 * delimiter.
213 *
214 * @li An error occurred.
215 *
216 * This operation is implemented in terms of zero or more calls to the stream's
217 * read_some function. If the dynamic buffer sequence's get area already
218 * contains the delimiter, the function returns immediately.
219 *
220 * @param s The stream from which the data is to be read. The type must support
221 * the SyncReadStream concept.
222 *
223 * @param buffers The dynamic buffer sequence into which the data will be read.
224 *
225 * @param delim The delimiter string.
226 *
227 * @returns The number of bytes in the dynamic buffer sequence's get area up to
228 * and including the delimiter.
229 *
230 * @note After a successful read_until operation, the dynamic buffer sequence
231 * may contain additional data beyond the delimiter. An application will
232 * typically leave that data in the dynamic buffer sequence for a subsequent
233 * read_until operation to examine.
234 *
235 * @par Example
236 * To read data into a @c std::string until a CR-LF sequence is encountered:
237 * @code std::string data;
238 * std::size_t n = boost::asio::read_until(s,
239 * boost::asio::dynamic_buffer(data), "\r\n");
240 * std::string line = data.substr(0, n);
241 * data.erase(0, n); @endcode
242 * After the @c read_until operation completes successfully, the string @c data
243 * contains the delimiter:
244 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
245 * The call to @c substr then extracts the data up to and including the
246 * delimiter, so that the string @c line contains:
247 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
248 * After the call to @c erase, the remaining data is left in the buffer @c b as
249 * follows:
250 * @code { 'd', 'e', ... } @endcode
251 * This data may be the start of a new line, to be extracted by a subsequent
252 * @c read_until operation.
253 */
254template <typename SyncReadStream, typename DynamicBuffer_v1>
255std::size_t read_until(SyncReadStream& s,
256 DynamicBuffer_v1&& buffers,
257 BOOST_ASIO_STRING_VIEW_PARAM delim,
258 constraint_t<
259 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
260 > = 0,
261 constraint_t<
262 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
263 > = 0);
264
265/// Read data into a dynamic buffer sequence until it contains a specified
266/// delimiter.
267/**
268 * This function is used to read data into the specified dynamic buffer
269 * sequence until the dynamic buffer sequence's get area contains the specified
270 * delimiter. The call will block until one of the following conditions is
271 * true:
272 *
273 * @li The get area of the dynamic buffer sequence contains the specified
274 * delimiter.
275 *
276 * @li An error occurred.
277 *
278 * This operation is implemented in terms of zero or more calls to the stream's
279 * read_some function. If the dynamic buffer sequence's get area already
280 * contains the delimiter, the function returns immediately.
281 *
282 * @param s The stream from which the data is to be read. The type must support
283 * the SyncReadStream concept.
284 *
285 * @param buffers The dynamic buffer sequence into which the data will be read.
286 *
287 * @param delim The delimiter string.
288 *
289 * @param ec Set to indicate what error occurred, if any.
290 *
291 * @returns The number of bytes in the dynamic buffer sequence's get area up to
292 * and including the delimiter. Returns 0 if an error occurred.
293 *
294 * @note After a successful read_until operation, the dynamic buffer sequence
295 * may contain additional data beyond the delimiter. An application will
296 * typically leave that data in the dynamic buffer sequence for a subsequent
297 * read_until operation to examine.
298 */
299template <typename SyncReadStream, typename DynamicBuffer_v1>
300std::size_t read_until(SyncReadStream& s,
301 DynamicBuffer_v1&& buffers,
302 BOOST_ASIO_STRING_VIEW_PARAM delim,
303 boost::system::error_code& ec,
304 constraint_t<
305 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
306 > = 0,
307 constraint_t<
308 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
309 > = 0);
310
311#if !defined(BOOST_ASIO_NO_EXTENSIONS)
312#if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
313 || defined(GENERATING_DOCUMENTATION)
314
315/// Read data into a dynamic buffer sequence until some part of the data it
316/// contains matches a regular expression.
317/**
318 * This function is used to read data into the specified dynamic buffer
319 * sequence until the dynamic buffer sequence's get area contains some data
320 * that matches a regular expression. The call will block until one of the
321 * following conditions is true:
322 *
323 * @li A substring of the dynamic buffer sequence's get area matches the
324 * regular expression.
325 *
326 * @li An error occurred.
327 *
328 * This operation is implemented in terms of zero or more calls to the stream's
329 * read_some function. If the dynamic buffer sequence's get area already
330 * contains data that matches the regular expression, the function returns
331 * immediately.
332 *
333 * @param s The stream from which the data is to be read. The type must support
334 * the SyncReadStream concept.
335 *
336 * @param buffers A dynamic buffer sequence into which the data will be read.
337 *
338 * @param expr The regular expression.
339 *
340 * @returns The number of bytes in the dynamic buffer sequence's get area up to
341 * and including the substring that matches the regular expression.
342 *
343 * @throws boost::system::system_error Thrown on failure.
344 *
345 * @note After a successful read_until operation, the dynamic buffer sequence
346 * may contain additional data beyond that which matched the regular
347 * expression. An application will typically leave that data in the dynamic
348 * buffer sequence for a subsequent read_until operation to examine.
349 *
350 * @par Example
351 * To read data into a @c std::string until a CR-LF sequence is encountered:
352 * @code std::string data;
353 * std::size_t n = boost::asio::read_until(s,
354 * boost::asio::dynamic_buffer(data), boost::regex("\r\n"));
355 * std::string line = data.substr(0, n);
356 * data.erase(0, n); @endcode
357 * After the @c read_until operation completes successfully, the string @c data
358 * contains the delimiter:
359 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
360 * The call to @c substr then extracts the data up to and including the
361 * delimiter, so that the string @c line contains:
362 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
363 * After the call to @c erase, the remaining data is left in the buffer @c b as
364 * follows:
365 * @code { 'd', 'e', ... } @endcode
366 * This data may be the start of a new line, to be extracted by a subsequent
367 * @c read_until operation.
368 */
369template <typename SyncReadStream, typename DynamicBuffer_v1, typename Traits>
370std::size_t read_until(SyncReadStream& s, DynamicBuffer_v1&& buffers,
371 const boost::basic_regex<char, Traits>& expr,
372 constraint_t<
373 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
374 > = 0,
375 constraint_t<
376 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
377 > = 0);
378
379/// Read data into a dynamic buffer sequence until some part of the data it
380/// contains matches a regular expression.
381/**
382 * This function is used to read data into the specified dynamic buffer
383 * sequence until the dynamic buffer sequence's get area contains some data
384 * that matches a regular expression. The call will block until one of the
385 * following conditions is true:
386 *
387 * @li A substring of the dynamic buffer sequence's get area matches the
388 * regular expression.
389 *
390 * @li An error occurred.
391 *
392 * This operation is implemented in terms of zero or more calls to the stream's
393 * read_some function. If the dynamic buffer sequence's get area already
394 * contains data that matches the regular expression, the function returns
395 * immediately.
396 *
397 * @param s The stream from which the data is to be read. The type must support
398 * the SyncReadStream concept.
399 *
400 * @param buffers A dynamic buffer sequence into which the data will be read.
401 *
402 * @param expr The regular expression.
403 *
404 * @param ec Set to indicate what error occurred, if any.
405 *
406 * @returns The number of bytes in the dynamic buffer sequence's get area up to
407 * and including the substring that matches the regular expression. Returns 0
408 * if an error occurred.
409 *
410 * @note After a successful read_until operation, the dynamic buffer sequence
411 * may contain additional data beyond that which matched the regular
412 * expression. An application will typically leave that data in the dynamic
413 * buffer sequence for a subsequent read_until operation to examine.
414 */
415template <typename SyncReadStream, typename DynamicBuffer_v1, typename Traits>
416std::size_t read_until(SyncReadStream& s, DynamicBuffer_v1&& buffers,
417 const boost::basic_regex<char, Traits>& expr, boost::system::error_code& ec,
418 constraint_t<
419 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
420 > = 0,
421 constraint_t<
422 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
423 > = 0);
424
425#endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
426 // || defined(GENERATING_DOCUMENTATION)
427
428/// Read data into a dynamic buffer sequence until a function object indicates a
429/// match.
430
431/**
432 * This function is used to read data into the specified dynamic buffer
433 * sequence until a user-defined match condition function object, when applied
434 * to the data contained in the dynamic buffer sequence, indicates a successful
435 * match. The call will block until one of the following conditions is true:
436 *
437 * @li The match condition function object returns a std::pair where the second
438 * element evaluates to true.
439 *
440 * @li An error occurred.
441 *
442 * This operation is implemented in terms of zero or more calls to the stream's
443 * read_some function. If the match condition function object already indicates
444 * a match, the function returns immediately.
445 *
446 * @param s The stream from which the data is to be read. The type must support
447 * the SyncReadStream concept.
448 *
449 * @param buffers A dynamic buffer sequence into which the data will be read.
450 *
451 * @param match_condition The function object to be called to determine whether
452 * a match exists. The signature of the function object must be:
453 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
454 * @endcode
455 * where @c iterator represents the type:
456 * @code buffers_iterator<typename DynamicBuffer_v1::const_buffers_type>
457 * @endcode
458 * The iterator parameters @c begin and @c end define the range of bytes to be
459 * scanned to determine whether there is a match. The @c first member of the
460 * return value is an iterator marking one-past-the-end of the bytes that have
461 * been consumed by the match function. This iterator is used to calculate the
462 * @c begin parameter for any subsequent invocation of the match condition. The
463 * @c second member of the return value is true if a match has been found, false
464 * otherwise.
465 *
466 * @returns The number of bytes in the dynamic_buffer's get area that
467 * have been fully consumed by the match function.
468 *
469 * @throws boost::system::system_error Thrown on failure.
470 *
471 * @note After a successful read_until operation, the dynamic buffer sequence
472 * may contain additional data beyond that which matched the function object.
473 * An application will typically leave that data in the dynamic buffer sequence
474 * for a subsequent read_until operation to examine.
475
476 * @note The default implementation of the @c is_match_condition type trait
477 * evaluates to true for function pointers and function objects with a
478 * @c result_type typedef. It must be specialised for other user-defined
479 * function objects.
480 *
481 * @par Examples
482 * To read data into a dynamic buffer sequence until whitespace is encountered:
483 * @code typedef boost::asio::buffers_iterator<
484 * boost::asio::const_buffers_1> iterator;
485 *
486 * std::pair<iterator, bool>
487 * match_whitespace(iterator begin, iterator end)
488 * {
489 * iterator i = begin;
490 * while (i != end)
491 * if (std::isspace(*i++))
492 * return std::make_pair(i, true);
493 * return std::make_pair(i, false);
494 * }
495 * ...
496 * std::string data;
497 * boost::asio::read_until(s, data, match_whitespace);
498 * @endcode
499 *
500 * To read data into a @c std::string until a matching character is found:
501 * @code class match_char
502 * {
503 * public:
504 * explicit match_char(char c) : c_(c) {}
505 *
506 * template <typename Iterator>
507 * std::pair<Iterator, bool> operator()(
508 * Iterator begin, Iterator end) const
509 * {
510 * Iterator i = begin;
511 * while (i != end)
512 * if (c_ == *i++)
513 * return std::make_pair(i, true);
514 * return std::make_pair(i, false);
515 * }
516 *
517 * private:
518 * char c_;
519 * };
520 *
521 * namespace asio {
522 * template <> struct is_match_condition<match_char>
523 * : public boost::true_type {};
524 * } // namespace asio
525 * ...
526 * std::string data;
527 * boost::asio::read_until(s, data, match_char('a'));
528 * @endcode
529 */
530template <typename SyncReadStream,
531 typename DynamicBuffer_v1, typename MatchCondition>
532std::size_t read_until(SyncReadStream& s,
533 DynamicBuffer_v1&& buffers,
534 MatchCondition match_condition,
535 constraint_t<
536 is_match_condition<MatchCondition>::value
537 > = 0,
538 constraint_t<
539 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
540 > = 0,
541 constraint_t<
542 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
543 > = 0);
544
545/// Read data into a dynamic buffer sequence until a function object indicates a
546/// match.
547/**
548 * This function is used to read data into the specified dynamic buffer
549 * sequence until a user-defined match condition function object, when applied
550 * to the data contained in the dynamic buffer sequence, indicates a successful
551 * match. The call will block until one of the following conditions is true:
552 *
553 * @li The match condition function object returns a std::pair where the second
554 * element evaluates to true.
555 *
556 * @li An error occurred.
557 *
558 * This operation is implemented in terms of zero or more calls to the stream's
559 * read_some function. If the match condition function object already indicates
560 * a match, the function returns immediately.
561 *
562 * @param s The stream from which the data is to be read. The type must support
563 * the SyncReadStream concept.
564 *
565 * @param buffers A dynamic buffer sequence into which the data will be read.
566 *
567 * @param match_condition The function object to be called to determine whether
568 * a match exists. The signature of the function object must be:
569 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
570 * @endcode
571 * where @c iterator represents the type:
572 * @code buffers_iterator<DynamicBuffer_v1::const_buffers_type>
573 * @endcode
574 * The iterator parameters @c begin and @c end define the range of bytes to be
575 * scanned to determine whether there is a match. The @c first member of the
576 * return value is an iterator marking one-past-the-end of the bytes that have
577 * been consumed by the match function. This iterator is used to calculate the
578 * @c begin parameter for any subsequent invocation of the match condition. The
579 * @c second member of the return value is true if a match has been found, false
580 * otherwise.
581 *
582 * @param ec Set to indicate what error occurred, if any.
583 *
584 * @returns The number of bytes in the dynamic buffer sequence's get area that
585 * have been fully consumed by the match function. Returns 0 if an error
586 * occurred.
587 *
588 * @note After a successful read_until operation, the dynamic buffer sequence
589 * may contain additional data beyond that which matched the function object.
590 * An application will typically leave that data in the dynamic buffer sequence
591 * for a subsequent read_until operation to examine.
592 *
593 * @note The default implementation of the @c is_match_condition type trait
594 * evaluates to true for function pointers and function objects with a
595 * @c result_type typedef. It must be specialised for other user-defined
596 * function objects.
597 */
598template <typename SyncReadStream,
599 typename DynamicBuffer_v1, typename MatchCondition>
600std::size_t read_until(SyncReadStream& s,
601 DynamicBuffer_v1&& buffers,
602 MatchCondition match_condition, boost::system::error_code& ec,
603 constraint_t<
604 is_match_condition<MatchCondition>::value
605 > = 0,
606 constraint_t<
607 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
608 > = 0,
609 constraint_t<
610 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
611 > = 0);
612
613#if !defined(BOOST_ASIO_NO_IOSTREAM)
614
615/// Read data into a streambuf until it contains a specified delimiter.
616/**
617 * This function is used to read data into the specified streambuf until the
618 * streambuf's get area contains the specified delimiter. The call will block
619 * until one of the following conditions is true:
620 *
621 * @li The get area of the streambuf contains the specified delimiter.
622 *
623 * @li An error occurred.
624 *
625 * This operation is implemented in terms of zero or more calls to the stream's
626 * read_some function. If the streambuf's get area already contains the
627 * delimiter, the function returns immediately.
628 *
629 * @param s The stream from which the data is to be read. The type must support
630 * the SyncReadStream concept.
631 *
632 * @param b A streambuf object into which the data will be read.
633 *
634 * @param delim The delimiter character.
635 *
636 * @returns The number of bytes in the streambuf's get area up to and including
637 * the delimiter.
638 *
639 * @throws boost::system::system_error Thrown on failure.
640 *
641 * @note After a successful read_until operation, the streambuf may contain
642 * additional data beyond the delimiter. An application will typically leave
643 * that data in the streambuf for a subsequent read_until operation to examine.
644 *
645 * @par Example
646 * To read data into a streambuf until a newline is encountered:
647 * @code boost::asio::streambuf b;
648 * boost::asio::read_until(s, b, '\n');
649 * std::istream is(&b);
650 * std::string line;
651 * std::getline(is, line); @endcode
652 * After the @c read_until operation completes successfully, the buffer @c b
653 * contains the delimiter:
654 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
655 * The call to @c std::getline then extracts the data up to and including the
656 * newline (which is discarded), so that the string @c line contains:
657 * @code { 'a', 'b', ..., 'c' } @endcode
658 * The remaining data is left in the buffer @c b as follows:
659 * @code { 'd', 'e', ... } @endcode
660 * This data may be the start of a new line, to be extracted by a subsequent
661 * @c read_until operation.
662 */
663template <typename SyncReadStream, typename Allocator>
664std::size_t read_until(SyncReadStream& s,
665 boost::asio::basic_streambuf<Allocator>& b, char delim);
666
667/// Read data into a streambuf until it contains a specified delimiter.
668/**
669 * This function is used to read data into the specified streambuf until the
670 * streambuf's get area contains the specified delimiter. The call will block
671 * until one of the following conditions is true:
672 *
673 * @li The get area of the streambuf contains the specified delimiter.
674 *
675 * @li An error occurred.
676 *
677 * This operation is implemented in terms of zero or more calls to the stream's
678 * read_some function. If the streambuf's get area already contains the
679 * delimiter, the function returns immediately.
680 *
681 * @param s The stream from which the data is to be read. The type must support
682 * the SyncReadStream concept.
683 *
684 * @param b A streambuf object into which the data will be read.
685 *
686 * @param delim The delimiter character.
687 *
688 * @param ec Set to indicate what error occurred, if any.
689 *
690 * @returns The number of bytes in the streambuf's get area up to and including
691 * the delimiter. Returns 0 if an error occurred.
692 *
693 * @note After a successful read_until operation, the streambuf may contain
694 * additional data beyond the delimiter. An application will typically leave
695 * that data in the streambuf for a subsequent read_until operation to examine.
696 */
697template <typename SyncReadStream, typename Allocator>
698std::size_t read_until(SyncReadStream& s,
699 boost::asio::basic_streambuf<Allocator>& b, char delim,
700 boost::system::error_code& ec);
701
702/// Read data into a streambuf until it contains a specified delimiter.
703/**
704 * This function is used to read data into the specified streambuf until the
705 * streambuf's get area contains the specified delimiter. The call will block
706 * until one of the following conditions is true:
707 *
708 * @li The get area of the streambuf contains the specified delimiter.
709 *
710 * @li An error occurred.
711 *
712 * This operation is implemented in terms of zero or more calls to the stream's
713 * read_some function. If the streambuf's get area already contains the
714 * delimiter, the function returns immediately.
715 *
716 * @param s The stream from which the data is to be read. The type must support
717 * the SyncReadStream concept.
718 *
719 * @param b A streambuf object into which the data will be read.
720 *
721 * @param delim The delimiter string.
722 *
723 * @returns The number of bytes in the streambuf's get area up to and including
724 * the delimiter.
725 *
726 * @throws boost::system::system_error Thrown on failure.
727 *
728 * @note After a successful read_until operation, the streambuf may contain
729 * additional data beyond the delimiter. An application will typically leave
730 * that data in the streambuf for a subsequent read_until operation to examine.
731 *
732 * @par Example
733 * To read data into a streambuf until a newline is encountered:
734 * @code boost::asio::streambuf b;
735 * boost::asio::read_until(s, b, "\r\n");
736 * std::istream is(&b);
737 * std::string line;
738 * std::getline(is, line); @endcode
739 * After the @c read_until operation completes successfully, the buffer @c b
740 * contains the delimiter:
741 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
742 * The call to @c std::getline then extracts the data up to and including the
743 * newline (which is discarded), so that the string @c line contains:
744 * @code { 'a', 'b', ..., 'c', '\r' } @endcode
745 * The remaining data is left in the buffer @c b as follows:
746 * @code { 'd', 'e', ... } @endcode
747 * This data may be the start of a new line, to be extracted by a subsequent
748 * @c read_until operation.
749 */
750template <typename SyncReadStream, typename Allocator>
751std::size_t read_until(SyncReadStream& s,
752 boost::asio::basic_streambuf<Allocator>& b,
753 BOOST_ASIO_STRING_VIEW_PARAM delim);
754
755/// Read data into a streambuf until it contains a specified delimiter.
756/**
757 * This function is used to read data into the specified streambuf until the
758 * streambuf's get area contains the specified delimiter. The call will block
759 * until one of the following conditions is true:
760 *
761 * @li The get area of the streambuf contains the specified delimiter.
762 *
763 * @li An error occurred.
764 *
765 * This operation is implemented in terms of zero or more calls to the stream's
766 * read_some function. If the streambuf's get area already contains the
767 * delimiter, the function returns immediately.
768 *
769 * @param s The stream from which the data is to be read. The type must support
770 * the SyncReadStream concept.
771 *
772 * @param b A streambuf object into which the data will be read.
773 *
774 * @param delim The delimiter string.
775 *
776 * @param ec Set to indicate what error occurred, if any.
777 *
778 * @returns The number of bytes in the streambuf's get area up to and including
779 * the delimiter. Returns 0 if an error occurred.
780 *
781 * @note After a successful read_until operation, the streambuf may contain
782 * additional data beyond the delimiter. An application will typically leave
783 * that data in the streambuf for a subsequent read_until operation to examine.
784 */
785template <typename SyncReadStream, typename Allocator>
786std::size_t read_until(SyncReadStream& s,
787 boost::asio::basic_streambuf<Allocator>& b,
788 BOOST_ASIO_STRING_VIEW_PARAM delim, boost::system::error_code& ec);
789
790#if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
791 || defined(GENERATING_DOCUMENTATION)
792
793/// Read data into a streambuf until some part of the data it contains matches
794/// a regular expression.
795/**
796 * This function is used to read data into the specified streambuf until the
797 * streambuf's get area contains some data that matches a regular expression.
798 * The call will block until one of the following conditions is true:
799 *
800 * @li A substring of the streambuf's get area matches the regular expression.
801 *
802 * @li An error occurred.
803 *
804 * This operation is implemented in terms of zero or more calls to the stream's
805 * read_some function. If the streambuf's get area already contains data that
806 * matches the regular expression, the function returns immediately.
807 *
808 * @param s The stream from which the data is to be read. The type must support
809 * the SyncReadStream concept.
810 *
811 * @param b A streambuf object into which the data will be read.
812 *
813 * @param expr The regular expression.
814 *
815 * @returns The number of bytes in the streambuf's get area up to and including
816 * the substring that matches the regular expression.
817 *
818 * @throws boost::system::system_error Thrown on failure.
819 *
820 * @note After a successful read_until operation, the streambuf may contain
821 * additional data beyond that which matched the regular expression. An
822 * application will typically leave that data in the streambuf for a subsequent
823 * read_until operation to examine.
824 *
825 * @par Example
826 * To read data into a streambuf until a CR-LF sequence is encountered:
827 * @code boost::asio::streambuf b;
828 * boost::asio::read_until(s, b, boost::regex("\r\n"));
829 * std::istream is(&b);
830 * std::string line;
831 * std::getline(is, line); @endcode
832 * After the @c read_until operation completes successfully, the buffer @c b
833 * contains the data which matched the regular expression:
834 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
835 * The call to @c std::getline then extracts the data up to and including the
836 * newline (which is discarded), so that the string @c line contains:
837 * @code { 'a', 'b', ..., 'c', '\r' } @endcode
838 * The remaining data is left in the buffer @c b as follows:
839 * @code { 'd', 'e', ... } @endcode
840 * This data may be the start of a new line, to be extracted by a subsequent
841 * @c read_until operation.
842 */
843template <typename SyncReadStream, typename Allocator, typename Traits>
844std::size_t read_until(SyncReadStream& s,
845 boost::asio::basic_streambuf<Allocator>& b,
846 const boost::basic_regex<char, Traits>& expr);
847
848/// Read data into a streambuf until some part of the data it contains matches
849/// a regular expression.
850/**
851 * This function is used to read data into the specified streambuf until the
852 * streambuf's get area contains some data that matches a regular expression.
853 * The call will block until one of the following conditions is true:
854 *
855 * @li A substring of the streambuf's get area matches the regular expression.
856 *
857 * @li An error occurred.
858 *
859 * This operation is implemented in terms of zero or more calls to the stream's
860 * read_some function. If the streambuf's get area already contains data that
861 * matches the regular expression, the function returns immediately.
862 *
863 * @param s The stream from which the data is to be read. The type must support
864 * the SyncReadStream concept.
865 *
866 * @param b A streambuf object into which the data will be read.
867 *
868 * @param expr The regular expression.
869 *
870 * @param ec Set to indicate what error occurred, if any.
871 *
872 * @returns The number of bytes in the streambuf's get area up to and including
873 * the substring that matches the regular expression. Returns 0 if an error
874 * occurred.
875 *
876 * @note After a successful read_until operation, the streambuf may contain
877 * additional data beyond that which matched the regular expression. An
878 * application will typically leave that data in the streambuf for a subsequent
879 * read_until operation to examine.
880 */
881template <typename SyncReadStream, typename Allocator, typename Traits>
882std::size_t read_until(SyncReadStream& s,
883 boost::asio::basic_streambuf<Allocator>& b,
884 const boost::basic_regex<char, Traits>& expr,
885 boost::system::error_code& ec);
886
887#endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
888 // || defined(GENERATING_DOCUMENTATION)
889
890/// Read data into a streambuf until a function object indicates a match.
891/**
892 * This function is used to read data into the specified streambuf until a
893 * user-defined match condition function object, when applied to the data
894 * contained in the streambuf, indicates a successful match. The call will
895 * block until one of the following conditions is true:
896 *
897 * @li The match condition function object returns a std::pair where the second
898 * element evaluates to true.
899 *
900 * @li An error occurred.
901 *
902 * This operation is implemented in terms of zero or more calls to the stream's
903 * read_some function. If the match condition function object already indicates
904 * a match, the function returns immediately.
905 *
906 * @param s The stream from which the data is to be read. The type must support
907 * the SyncReadStream concept.
908 *
909 * @param b A streambuf object into which the data will be read.
910 *
911 * @param match_condition The function object to be called to determine whether
912 * a match exists. The signature of the function object must be:
913 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
914 * @endcode
915 * where @c iterator represents the type:
916 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
917 * @endcode
918 * The iterator parameters @c begin and @c end define the range of bytes to be
919 * scanned to determine whether there is a match. The @c first member of the
920 * return value is an iterator marking one-past-the-end of the bytes that have
921 * been consumed by the match function. This iterator is used to calculate the
922 * @c begin parameter for any subsequent invocation of the match condition. The
923 * @c second member of the return value is true if a match has been found, false
924 * otherwise.
925 *
926 * @returns The number of bytes in the streambuf's get area that have been fully
927 * consumed by the match function.
928 *
929 * @throws boost::system::system_error Thrown on failure.
930 *
931 * @note After a successful read_until operation, the streambuf may contain
932 * additional data beyond that which matched the function object. An application
933 * will typically leave that data in the streambuf for a subsequent read_until
934 * operation to examine.
935 *
936 * @note The default implementation of the @c is_match_condition type trait
937 * evaluates to true for function pointers and function objects with a
938 * @c result_type typedef. It must be specialised for other user-defined
939 * function objects.
940 *
941 * @par Examples
942 * To read data into a streambuf until whitespace is encountered:
943 * @code typedef boost::asio::buffers_iterator<
944 * boost::asio::streambuf::const_buffers_type> iterator;
945 *
946 * std::pair<iterator, bool>
947 * match_whitespace(iterator begin, iterator end)
948 * {
949 * iterator i = begin;
950 * while (i != end)
951 * if (std::isspace(*i++))
952 * return std::make_pair(i, true);
953 * return std::make_pair(i, false);
954 * }
955 * ...
956 * boost::asio::streambuf b;
957 * boost::asio::read_until(s, b, match_whitespace);
958 * @endcode
959 *
960 * To read data into a streambuf until a matching character is found:
961 * @code class match_char
962 * {
963 * public:
964 * explicit match_char(char c) : c_(c) {}
965 *
966 * template <typename Iterator>
967 * std::pair<Iterator, bool> operator()(
968 * Iterator begin, Iterator end) const
969 * {
970 * Iterator i = begin;
971 * while (i != end)
972 * if (c_ == *i++)
973 * return std::make_pair(i, true);
974 * return std::make_pair(i, false);
975 * }
976 *
977 * private:
978 * char c_;
979 * };
980 *
981 * namespace asio {
982 * template <> struct is_match_condition<match_char>
983 * : public boost::true_type {};
984 * } // namespace asio
985 * ...
986 * boost::asio::streambuf b;
987 * boost::asio::read_until(s, b, match_char('a'));
988 * @endcode
989 */
990template <typename SyncReadStream, typename Allocator, typename MatchCondition>
991std::size_t read_until(SyncReadStream& s,
992 boost::asio::basic_streambuf<Allocator>& b, MatchCondition match_condition,
993 constraint_t<is_match_condition<MatchCondition>::value> = 0);
994
995/// Read data into a streambuf until a function object indicates a match.
996/**
997 * This function is used to read data into the specified streambuf until a
998 * user-defined match condition function object, when applied to the data
999 * contained in the streambuf, indicates a successful match. The call will
1000 * block until one of the following conditions is true:
1001 *
1002 * @li The match condition function object returns a std::pair where the second
1003 * element evaluates to true.
1004 *
1005 * @li An error occurred.
1006 *
1007 * This operation is implemented in terms of zero or more calls to the stream's
1008 * read_some function. If the match condition function object already indicates
1009 * a match, the function returns immediately.
1010 *
1011 * @param s The stream from which the data is to be read. The type must support
1012 * the SyncReadStream concept.
1013 *
1014 * @param b A streambuf object into which the data will be read.
1015 *
1016 * @param match_condition The function object to be called to determine whether
1017 * a match exists. The signature of the function object must be:
1018 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
1019 * @endcode
1020 * where @c iterator represents the type:
1021 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
1022 * @endcode
1023 * The iterator parameters @c begin and @c end define the range of bytes to be
1024 * scanned to determine whether there is a match. The @c first member of the
1025 * return value is an iterator marking one-past-the-end of the bytes that have
1026 * been consumed by the match function. This iterator is used to calculate the
1027 * @c begin parameter for any subsequent invocation of the match condition. The
1028 * @c second member of the return value is true if a match has been found, false
1029 * otherwise.
1030 *
1031 * @param ec Set to indicate what error occurred, if any.
1032 *
1033 * @returns The number of bytes in the streambuf's get area that have been fully
1034 * consumed by the match function. Returns 0 if an error occurred.
1035 *
1036 * @note After a successful read_until operation, the streambuf may contain
1037 * additional data beyond that which matched the function object. An application
1038 * will typically leave that data in the streambuf for a subsequent read_until
1039 * operation to examine.
1040 *
1041 * @note The default implementation of the @c is_match_condition type trait
1042 * evaluates to true for function pointers and function objects with a
1043 * @c result_type typedef. It must be specialised for other user-defined
1044 * function objects.
1045 */
1046template <typename SyncReadStream, typename Allocator, typename MatchCondition>
1047std::size_t read_until(SyncReadStream& s,
1048 boost::asio::basic_streambuf<Allocator>& b,
1049 MatchCondition match_condition, boost::system::error_code& ec,
1050 constraint_t<is_match_condition<MatchCondition>::value> = 0);
1051
1052#endif // !defined(BOOST_ASIO_NO_IOSTREAM)
1053#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
1054#endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
1055
1056/// Read data into a dynamic buffer sequence until it contains a specified
1057/// delimiter.
1058/**
1059 * This function is used to read data into the specified dynamic buffer
1060 * sequence until the dynamic buffer sequence's get area contains the specified
1061 * delimiter. The call will block until one of the following conditions is
1062 * true:
1063 *
1064 * @li The get area of the dynamic buffer sequence contains the specified
1065 * delimiter.
1066 *
1067 * @li An error occurred.
1068 *
1069 * This operation is implemented in terms of zero or more calls to the stream's
1070 * read_some function. If the dynamic buffer sequence's get area already
1071 * contains the delimiter, the function returns immediately.
1072 *
1073 * @param s The stream from which the data is to be read. The type must support
1074 * the SyncReadStream concept.
1075 *
1076 * @param buffers The dynamic buffer sequence into which the data will be read.
1077 *
1078 * @param delim The delimiter character.
1079 *
1080 * @returns The number of bytes in the dynamic buffer sequence's get area up to
1081 * and including the delimiter.
1082 *
1083 * @throws boost::system::system_error Thrown on failure.
1084 *
1085 * @note After a successful read_until operation, the dynamic buffer sequence
1086 * may contain additional data beyond the delimiter. An application will
1087 * typically leave that data in the dynamic buffer sequence for a subsequent
1088 * read_until operation to examine.
1089 *
1090 * @par Example
1091 * To read data into a @c std::string until a newline is encountered:
1092 * @code std::string data;
1093 * std::size_t n = boost::asio::read_until(s,
1094 * boost::asio::dynamic_buffer(data), '\n');
1095 * std::string line = data.substr(0, n);
1096 * data.erase(0, n); @endcode
1097 * After the @c read_until operation completes successfully, the string @c data
1098 * contains the delimiter:
1099 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
1100 * The call to @c substr then extracts the data up to and including the
1101 * delimiter, so that the string @c line contains:
1102 * @code { 'a', 'b', ..., 'c', '\n' } @endcode
1103 * After the call to @c erase, the remaining data is left in the buffer @c b as
1104 * follows:
1105 * @code { 'd', 'e', ... } @endcode
1106 * This data may be the start of a new line, to be extracted by a subsequent
1107 * @c read_until operation.
1108 */
1109template <typename SyncReadStream, typename DynamicBuffer_v2>
1110std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers, char delim,
1111 constraint_t<
1112 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1113 > = 0);
1114
1115/// Read data into a dynamic buffer sequence until it contains a specified
1116/// delimiter.
1117/**
1118 * This function is used to read data into the specified dynamic buffer
1119 * sequence until the dynamic buffer sequence's get area contains the specified
1120 * delimiter. The call will block until one of the following conditions is
1121 * true:
1122 *
1123 * @li The get area of the dynamic buffer sequence contains the specified
1124 * delimiter.
1125 *
1126 * @li An error occurred.
1127 *
1128 * This operation is implemented in terms of zero or more calls to the stream's
1129 * read_some function. If the dynamic buffer sequence's get area already
1130 * contains the delimiter, the function returns immediately.
1131 *
1132 * @param s The stream from which the data is to be read. The type must support
1133 * the SyncReadStream concept.
1134 *
1135 * @param buffers The dynamic buffer sequence into which the data will be read.
1136 *
1137 * @param delim The delimiter character.
1138 *
1139 * @param ec Set to indicate what error occurred, if any.
1140 *
1141 * @returns The number of bytes in the dynamic buffer sequence's get area up to
1142 * and including the delimiter. Returns 0 if an error occurred.
1143 *
1144 * @note After a successful read_until operation, the dynamic buffer sequence
1145 * may contain additional data beyond the delimiter. An application will
1146 * typically leave that data in the dynamic buffer sequence for a subsequent
1147 * read_until operation to examine.
1148 */
1149template <typename SyncReadStream, typename DynamicBuffer_v2>
1150std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
1151 char delim, boost::system::error_code& ec,
1152 constraint_t<
1153 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1154 > = 0);
1155
1156/// Read data into a dynamic buffer sequence until it contains a specified
1157/// delimiter.
1158/**
1159 * This function is used to read data into the specified dynamic buffer
1160 * sequence until the dynamic buffer sequence's get area contains the specified
1161 * delimiter. The call will block until one of the following conditions is
1162 * true:
1163 *
1164 * @li The get area of the dynamic buffer sequence contains the specified
1165 * delimiter.
1166 *
1167 * @li An error occurred.
1168 *
1169 * This operation is implemented in terms of zero or more calls to the stream's
1170 * read_some function. If the dynamic buffer sequence's get area already
1171 * contains the delimiter, the function returns immediately.
1172 *
1173 * @param s The stream from which the data is to be read. The type must support
1174 * the SyncReadStream concept.
1175 *
1176 * @param buffers The dynamic buffer sequence into which the data will be read.
1177 *
1178 * @param delim The delimiter string.
1179 *
1180 * @returns The number of bytes in the dynamic buffer sequence's get area up to
1181 * and including the delimiter.
1182 *
1183 * @note After a successful read_until operation, the dynamic buffer sequence
1184 * may contain additional data beyond the delimiter. An application will
1185 * typically leave that data in the dynamic buffer sequence for a subsequent
1186 * read_until operation to examine.
1187 *
1188 * @par Example
1189 * To read data into a @c std::string until a CR-LF sequence is encountered:
1190 * @code std::string data;
1191 * std::size_t n = boost::asio::read_until(s,
1192 * boost::asio::dynamic_buffer(data), "\r\n");
1193 * std::string line = data.substr(0, n);
1194 * data.erase(0, n); @endcode
1195 * After the @c read_until operation completes successfully, the string @c data
1196 * contains the delimiter:
1197 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
1198 * The call to @c substr then extracts the data up to and including the
1199 * delimiter, so that the string @c line contains:
1200 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
1201 * After the call to @c erase, the remaining data is left in the buffer @c b as
1202 * follows:
1203 * @code { 'd', 'e', ... } @endcode
1204 * This data may be the start of a new line, to be extracted by a subsequent
1205 * @c read_until operation.
1206 */
1207template <typename SyncReadStream, typename DynamicBuffer_v2>
1208std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
1209 BOOST_ASIO_STRING_VIEW_PARAM delim,
1210 constraint_t<
1211 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1212 > = 0);
1213
1214/// Read data into a dynamic buffer sequence until it contains a specified
1215/// delimiter.
1216/**
1217 * This function is used to read data into the specified dynamic buffer
1218 * sequence until the dynamic buffer sequence's get area contains the specified
1219 * delimiter. The call will block until one of the following conditions is
1220 * true:
1221 *
1222 * @li The get area of the dynamic buffer sequence contains the specified
1223 * delimiter.
1224 *
1225 * @li An error occurred.
1226 *
1227 * This operation is implemented in terms of zero or more calls to the stream's
1228 * read_some function. If the dynamic buffer sequence's get area already
1229 * contains the delimiter, the function returns immediately.
1230 *
1231 * @param s The stream from which the data is to be read. The type must support
1232 * the SyncReadStream concept.
1233 *
1234 * @param buffers The dynamic buffer sequence into which the data will be read.
1235 *
1236 * @param delim The delimiter string.
1237 *
1238 * @param ec Set to indicate what error occurred, if any.
1239 *
1240 * @returns The number of bytes in the dynamic buffer sequence's get area up to
1241 * and including the delimiter. Returns 0 if an error occurred.
1242 *
1243 * @note After a successful read_until operation, the dynamic buffer sequence
1244 * may contain additional data beyond the delimiter. An application will
1245 * typically leave that data in the dynamic buffer sequence for a subsequent
1246 * read_until operation to examine.
1247 */
1248template <typename SyncReadStream, typename DynamicBuffer_v2>
1249std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
1250 BOOST_ASIO_STRING_VIEW_PARAM delim, boost::system::error_code& ec,
1251 constraint_t<
1252 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1253 > = 0);
1254
1255#if !defined(BOOST_ASIO_NO_EXTENSIONS)
1256#if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
1257 || defined(GENERATING_DOCUMENTATION)
1258
1259/// Read data into a dynamic buffer sequence until some part of the data it
1260/// contains matches a regular expression.
1261/**
1262 * This function is used to read data into the specified dynamic buffer
1263 * sequence until the dynamic buffer sequence's get area contains some data
1264 * that matches a regular expression. The call will block until one of the
1265 * following conditions is true:
1266 *
1267 * @li A substring of the dynamic buffer sequence's get area matches the
1268 * regular expression.
1269 *
1270 * @li An error occurred.
1271 *
1272 * This operation is implemented in terms of zero or more calls to the stream's
1273 * read_some function. If the dynamic buffer sequence's get area already
1274 * contains data that matches the regular expression, the function returns
1275 * immediately.
1276 *
1277 * @param s The stream from which the data is to be read. The type must support
1278 * the SyncReadStream concept.
1279 *
1280 * @param buffers A dynamic buffer sequence into which the data will be read.
1281 *
1282 * @param expr The regular expression.
1283 *
1284 * @returns The number of bytes in the dynamic buffer sequence's get area up to
1285 * and including the substring that matches the regular expression.
1286 *
1287 * @throws boost::system::system_error Thrown on failure.
1288 *
1289 * @note After a successful read_until operation, the dynamic buffer sequence
1290 * may contain additional data beyond that which matched the regular
1291 * expression. An application will typically leave that data in the dynamic
1292 * buffer sequence for a subsequent read_until operation to examine.
1293 *
1294 * @par Example
1295 * To read data into a @c std::string until a CR-LF sequence is encountered:
1296 * @code std::string data;
1297 * std::size_t n = boost::asio::read_until(s,
1298 * boost::asio::dynamic_buffer(data), boost::regex("\r\n"));
1299 * std::string line = data.substr(0, n);
1300 * data.erase(0, n); @endcode
1301 * After the @c read_until operation completes successfully, the string @c data
1302 * contains the delimiter:
1303 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
1304 * The call to @c substr then extracts the data up to and including the
1305 * delimiter, so that the string @c line contains:
1306 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
1307 * After the call to @c erase, the remaining data is left in the buffer @c b as
1308 * follows:
1309 * @code { 'd', 'e', ... } @endcode
1310 * This data may be the start of a new line, to be extracted by a subsequent
1311 * @c read_until operation.
1312 */
1313template <typename SyncReadStream, typename DynamicBuffer_v2, typename Traits>
1314std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
1315 const boost::basic_regex<char, Traits>& expr,
1316 constraint_t<
1317 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1318 > = 0);
1319
1320/// Read data into a dynamic buffer sequence until some part of the data it
1321/// contains matches a regular expression.
1322/**
1323 * This function is used to read data into the specified dynamic buffer
1324 * sequence until the dynamic buffer sequence's get area contains some data
1325 * that matches a regular expression. The call will block until one of the
1326 * following conditions is true:
1327 *
1328 * @li A substring of the dynamic buffer sequence's get area matches the
1329 * regular expression.
1330 *
1331 * @li An error occurred.
1332 *
1333 * This operation is implemented in terms of zero or more calls to the stream's
1334 * read_some function. If the dynamic buffer sequence's get area already
1335 * contains data that matches the regular expression, the function returns
1336 * immediately.
1337 *
1338 * @param s The stream from which the data is to be read. The type must support
1339 * the SyncReadStream concept.
1340 *
1341 * @param buffers A dynamic buffer sequence into which the data will be read.
1342 *
1343 * @param expr The regular expression.
1344 *
1345 * @param ec Set to indicate what error occurred, if any.
1346 *
1347 * @returns The number of bytes in the dynamic buffer sequence's get area up to
1348 * and including the substring that matches the regular expression. Returns 0
1349 * if an error occurred.
1350 *
1351 * @note After a successful read_until operation, the dynamic buffer sequence
1352 * may contain additional data beyond that which matched the regular
1353 * expression. An application will typically leave that data in the dynamic
1354 * buffer sequence for a subsequent read_until operation to examine.
1355 */
1356template <typename SyncReadStream, typename DynamicBuffer_v2, typename Traits>
1357std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
1358 const boost::basic_regex<char, Traits>& expr, boost::system::error_code& ec,
1359 constraint_t<
1360 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1361 > = 0);
1362
1363#endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
1364 // || defined(GENERATING_DOCUMENTATION)
1365
1366/// Read data into a dynamic buffer sequence until a function object indicates a
1367/// match.
1368
1369/**
1370 * This function is used to read data into the specified dynamic buffer
1371 * sequence until a user-defined match condition function object, when applied
1372 * to the data contained in the dynamic buffer sequence, indicates a successful
1373 * match. The call will block until one of the following conditions is true:
1374 *
1375 * @li The match condition function object returns a std::pair where the second
1376 * element evaluates to true.
1377 *
1378 * @li An error occurred.
1379 *
1380 * This operation is implemented in terms of zero or more calls to the stream's
1381 * read_some function. If the match condition function object already indicates
1382 * a match, the function returns immediately.
1383 *
1384 * @param s The stream from which the data is to be read. The type must support
1385 * the SyncReadStream concept.
1386 *
1387 * @param buffers A dynamic buffer sequence into which the data will be read.
1388 *
1389 * @param match_condition The function object to be called to determine whether
1390 * a match exists. The signature of the function object must be:
1391 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
1392 * @endcode
1393 * where @c iterator represents the type:
1394 * @code buffers_iterator<typename DynamicBuffer_v2::const_buffers_type>
1395 * @endcode
1396 * The iterator parameters @c begin and @c end define the range of bytes to be
1397 * scanned to determine whether there is a match. The @c first member of the
1398 * return value is an iterator marking one-past-the-end of the bytes that have
1399 * been consumed by the match function. This iterator is used to calculate the
1400 * @c begin parameter for any subsequent invocation of the match condition. The
1401 * @c second member of the return value is true if a match has been found, false
1402 * otherwise.
1403 *
1404 * @returns The number of bytes in the dynamic_buffer's get area that
1405 * have been fully consumed by the match function.
1406 *
1407 * @throws boost::system::system_error Thrown on failure.
1408 *
1409 * @note After a successful read_until operation, the dynamic buffer sequence
1410 * may contain additional data beyond that which matched the function object.
1411 * An application will typically leave that data in the dynamic buffer sequence
1412 * for a subsequent read_until operation to examine.
1413
1414 * @note The default implementation of the @c is_match_condition type trait
1415 * evaluates to true for function pointers and function objects with a
1416 * @c result_type typedef. It must be specialised for other user-defined
1417 * function objects.
1418 *
1419 * @par Examples
1420 * To read data into a dynamic buffer sequence until whitespace is encountered:
1421 * @code typedef boost::asio::buffers_iterator<
1422 * boost::asio::const_buffers_1> iterator;
1423 *
1424 * std::pair<iterator, bool>
1425 * match_whitespace(iterator begin, iterator end)
1426 * {
1427 * iterator i = begin;
1428 * while (i != end)
1429 * if (std::isspace(*i++))
1430 * return std::make_pair(i, true);
1431 * return std::make_pair(i, false);
1432 * }
1433 * ...
1434 * std::string data;
1435 * boost::asio::read_until(s, data, match_whitespace);
1436 * @endcode
1437 *
1438 * To read data into a @c std::string until a matching character is found:
1439 * @code class match_char
1440 * {
1441 * public:
1442 * explicit match_char(char c) : c_(c) {}
1443 *
1444 * template <typename Iterator>
1445 * std::pair<Iterator, bool> operator()(
1446 * Iterator begin, Iterator end) const
1447 * {
1448 * Iterator i = begin;
1449 * while (i != end)
1450 * if (c_ == *i++)
1451 * return std::make_pair(i, true);
1452 * return std::make_pair(i, false);
1453 * }
1454 *
1455 * private:
1456 * char c_;
1457 * };
1458 *
1459 * namespace asio {
1460 * template <> struct is_match_condition<match_char>
1461 * : public boost::true_type {};
1462 * } // namespace asio
1463 * ...
1464 * std::string data;
1465 * boost::asio::read_until(s, data, match_char('a'));
1466 * @endcode
1467 */
1468template <typename SyncReadStream,
1469 typename DynamicBuffer_v2, typename MatchCondition>
1470std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
1471 MatchCondition match_condition,
1472 constraint_t<
1473 is_match_condition<MatchCondition>::value
1474 > = 0,
1475 constraint_t<
1476 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1477 > = 0);
1478
1479/// Read data into a dynamic buffer sequence until a function object indicates a
1480/// match.
1481/**
1482 * This function is used to read data into the specified dynamic buffer
1483 * sequence until a user-defined match condition function object, when applied
1484 * to the data contained in the dynamic buffer sequence, indicates a successful
1485 * match. The call will block until one of the following conditions is true:
1486 *
1487 * @li The match condition function object returns a std::pair where the second
1488 * element evaluates to true.
1489 *
1490 * @li An error occurred.
1491 *
1492 * This operation is implemented in terms of zero or more calls to the stream's
1493 * read_some function. If the match condition function object already indicates
1494 * a match, the function returns immediately.
1495 *
1496 * @param s The stream from which the data is to be read. The type must support
1497 * the SyncReadStream concept.
1498 *
1499 * @param buffers A dynamic buffer sequence into which the data will be read.
1500 *
1501 * @param match_condition The function object to be called to determine whether
1502 * a match exists. The signature of the function object must be:
1503 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
1504 * @endcode
1505 * where @c iterator represents the type:
1506 * @code buffers_iterator<DynamicBuffer_v2::const_buffers_type>
1507 * @endcode
1508 * The iterator parameters @c begin and @c end define the range of bytes to be
1509 * scanned to determine whether there is a match. The @c first member of the
1510 * return value is an iterator marking one-past-the-end of the bytes that have
1511 * been consumed by the match function. This iterator is used to calculate the
1512 * @c begin parameter for any subsequent invocation of the match condition. The
1513 * @c second member of the return value is true if a match has been found, false
1514 * otherwise.
1515 *
1516 * @param ec Set to indicate what error occurred, if any.
1517 *
1518 * @returns The number of bytes in the dynamic buffer sequence's get area that
1519 * have been fully consumed by the match function. Returns 0 if an error
1520 * occurred.
1521 *
1522 * @note After a successful read_until operation, the dynamic buffer sequence
1523 * may contain additional data beyond that which matched the function object.
1524 * An application will typically leave that data in the dynamic buffer sequence
1525 * for a subsequent read_until operation to examine.
1526 *
1527 * @note The default implementation of the @c is_match_condition type trait
1528 * evaluates to true for function pointers and function objects with a
1529 * @c result_type typedef. It must be specialised for other user-defined
1530 * function objects.
1531 */
1532template <typename SyncReadStream,
1533 typename DynamicBuffer_v2, typename MatchCondition>
1534std::size_t read_until(SyncReadStream& s, DynamicBuffer_v2 buffers,
1535 MatchCondition match_condition, boost::system::error_code& ec,
1536 constraint_t<
1537 is_match_condition<MatchCondition>::value
1538 > = 0,
1539 constraint_t<
1540 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1541 > = 0);
1542
1543#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
1544
1545/*@}*/
1546/**
1547 * @defgroup async_read_until boost::asio::async_read_until
1548 *
1549 * @brief The @c async_read_until function is a composed asynchronous operation
1550 * that reads data into a dynamic buffer sequence, or into a streambuf, until
1551 * it contains a delimiter, matches a regular expression, or a function object
1552 * indicates a match.
1553 */
1554/*@{*/
1555
1556#if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
1557
1558/// Start an asynchronous operation to read data into a dynamic buffer sequence
1559/// until it contains a specified delimiter.
1560/**
1561 * This function is used to asynchronously read data into the specified dynamic
1562 * buffer sequence until the dynamic buffer sequence's get area contains the
1563 * specified delimiter. It is an initiating function for an @ref
1564 * asynchronous_operation, and always returns immediately. The asynchronous
1565 * operation will continue until one of the following conditions is true:
1566 *
1567 * @li The get area of the dynamic buffer sequence contains the specified
1568 * delimiter.
1569 *
1570 * @li An error occurred.
1571 *
1572 * This operation is implemented in terms of zero or more calls to the stream's
1573 * async_read_some function, and is known as a <em>composed operation</em>. If
1574 * the dynamic buffer sequence's get area already contains the delimiter, this
1575 * asynchronous operation completes immediately. The program must ensure that
1576 * the stream performs no other read operations (such as async_read,
1577 * async_read_until, the stream's async_read_some function, or any other
1578 * composed operations that perform reads) until this operation completes.
1579 *
1580 * @param s The stream from which the data is to be read. The type must support
1581 * the AsyncReadStream concept.
1582 *
1583 * @param buffers The dynamic buffer sequence into which the data will be read.
1584 * Although the buffers object may be copied as necessary, ownership of the
1585 * underlying memory blocks is retained by the caller, which must guarantee
1586 * that they remain valid until the completion handler is called.
1587 *
1588 * @param delim The delimiter character.
1589 *
1590 * @param token The @ref completion_token that will be used to produce a
1591 * completion handler, which will be called when the read completes.
1592 * Potential completion tokens include @ref use_future, @ref use_awaitable,
1593 * @ref yield_context, or a function object with the correct completion
1594 * signature. The function signature of the completion handler must be:
1595 * @code void handler(
1596 * // Result of operation.
1597 * const boost::system::error_code& error,
1598 *
1599 * // The number of bytes in the dynamic buffer sequence's
1600 * // get area up to and including the delimiter.
1601 * std::size_t bytes_transferred
1602 * ); @endcode
1603 * Regardless of whether the asynchronous operation completes immediately or
1604 * not, the completion handler will not be invoked from within this function.
1605 * On immediate completion, invocation of the handler will be performed in a
1606 * manner equivalent to using boost::asio::post().
1607 *
1608 * @par Completion Signature
1609 * @code void(boost::system::error_code, std::size_t) @endcode
1610 *
1611 * @note After a successful async_read_until operation, the dynamic buffer
1612 * sequence may contain additional data beyond the delimiter. An application
1613 * will typically leave that data in the dynamic buffer sequence for a
1614 * subsequent async_read_until operation to examine.
1615 *
1616 * @par Example
1617 * To asynchronously read data into a @c std::string until a newline is
1618 * encountered:
1619 * @code std::string data;
1620 * ...
1621 * void handler(const boost::system::error_code& e, std::size_t size)
1622 * {
1623 * if (!e)
1624 * {
1625 * std::string line = data.substr(0, n);
1626 * data.erase(0, n);
1627 * ...
1628 * }
1629 * }
1630 * ...
1631 * boost::asio::async_read_until(s, data, '\n', handler); @endcode
1632 * After the @c async_read_until operation completes successfully, the buffer
1633 * @c data contains the delimiter:
1634 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
1635 * The call to @c substr then extracts the data up to and including the
1636 * delimiter, so that the string @c line contains:
1637 * @code { 'a', 'b', ..., 'c', '\n' } @endcode
1638 * After the call to @c erase, the remaining data is left in the buffer @c data
1639 * as follows:
1640 * @code { 'd', 'e', ... } @endcode
1641 * This data may be the start of a new line, to be extracted by a subsequent
1642 * @c async_read_until operation.
1643 *
1644 * @par Per-Operation Cancellation
1645 * This asynchronous operation supports cancellation for the following
1646 * boost::asio::cancellation_type values:
1647 *
1648 * @li @c cancellation_type::terminal
1649 *
1650 * @li @c cancellation_type::partial
1651 *
1652 * if they are also supported by the @c AsyncReadStream type's
1653 * @c async_read_some operation.
1654 */
1655template <typename AsyncReadStream, typename DynamicBuffer_v1,
1656 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1657 std::size_t)) ReadToken = default_completion_token_t<
1658 typename AsyncReadStream::executor_type>>
1659auto async_read_until(AsyncReadStream& s,
1660 DynamicBuffer_v1&& buffers, char delim,
1661 ReadToken&& token = default_completion_token_t<
1662 typename AsyncReadStream::executor_type>(),
1663 constraint_t<
1664 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
1665 > = 0,
1666 constraint_t<
1667 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
1668 > = 0)
1669 -> decltype(
1670 async_initiate<ReadToken,
1671 void (boost::system::error_code, std::size_t)>(
1672 declval<detail::initiate_async_read_until_delim_v1<AsyncReadStream>>(),
1673 token, static_cast<DynamicBuffer_v1&&>(buffers), delim));
1674
1675/// Start an asynchronous operation to read data into a dynamic buffer sequence
1676/// until it contains a specified delimiter.
1677/**
1678 * This function is used to asynchronously read data into the specified dynamic
1679 * buffer sequence until the dynamic buffer sequence's get area contains the
1680 * specified delimiter. It is an initiating function for an @ref
1681 * asynchronous_operation, and always returns immediately. The asynchronous
1682 * operation will continue until one of the following conditions is true:
1683 *
1684 * @li The get area of the dynamic buffer sequence contains the specified
1685 * delimiter.
1686 *
1687 * @li An error occurred.
1688 *
1689 * This operation is implemented in terms of zero or more calls to the stream's
1690 * async_read_some function, and is known as a <em>composed operation</em>. If
1691 * the dynamic buffer sequence's get area already contains the delimiter, this
1692 * asynchronous operation completes immediately. The program must ensure that
1693 * the stream performs no other read operations (such as async_read,
1694 * async_read_until, the stream's async_read_some function, or any other
1695 * composed operations that perform reads) until this operation completes.
1696 *
1697 * @param s The stream from which the data is to be read. The type must support
1698 * the AsyncReadStream concept.
1699 *
1700 * @param buffers The dynamic buffer sequence into which the data will be read.
1701 * Although the buffers object may be copied as necessary, ownership of the
1702 * underlying memory blocks is retained by the caller, which must guarantee
1703 * that they remain valid until the completion handler is called.
1704 *
1705 * @param delim The delimiter string.
1706 *
1707 * @param token The @ref completion_token that will be used to produce a
1708 * completion handler, which will be called when the read completes.
1709 * Potential completion tokens include @ref use_future, @ref use_awaitable,
1710 * @ref yield_context, or a function object with the correct completion
1711 * signature. The function signature of the completion handler must be:
1712 * @code void handler(
1713 * // Result of operation.
1714 * const boost::system::error_code& error,
1715 *
1716 * // The number of bytes in the dynamic buffer sequence's
1717 * // get area up to and including the delimiter.
1718 * std::size_t bytes_transferred
1719 * ); @endcode
1720 * Regardless of whether the asynchronous operation completes immediately or
1721 * not, the completion handler will not be invoked from within this function.
1722 * On immediate completion, invocation of the handler will be performed in a
1723 * manner equivalent to using boost::asio::post().
1724 *
1725 * @par Completion Signature
1726 * @code void(boost::system::error_code, std::size_t) @endcode
1727 *
1728 * @note After a successful async_read_until operation, the dynamic buffer
1729 * sequence may contain additional data beyond the delimiter. An application
1730 * will typically leave that data in the dynamic buffer sequence for a
1731 * subsequent async_read_until operation to examine.
1732 *
1733 * @par Example
1734 * To asynchronously read data into a @c std::string until a CR-LF sequence is
1735 * encountered:
1736 * @code std::string data;
1737 * ...
1738 * void handler(const boost::system::error_code& e, std::size_t size)
1739 * {
1740 * if (!e)
1741 * {
1742 * std::string line = data.substr(0, n);
1743 * data.erase(0, n);
1744 * ...
1745 * }
1746 * }
1747 * ...
1748 * boost::asio::async_read_until(s, data, "\r\n", handler); @endcode
1749 * After the @c async_read_until operation completes successfully, the string
1750 * @c data contains the delimiter:
1751 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
1752 * The call to @c substr then extracts the data up to and including the
1753 * delimiter, so that the string @c line contains:
1754 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
1755 * After the call to @c erase, the remaining data is left in the string @c data
1756 * as follows:
1757 * @code { 'd', 'e', ... } @endcode
1758 * This data may be the start of a new line, to be extracted by a subsequent
1759 * @c async_read_until operation.
1760 *
1761 * @par Per-Operation Cancellation
1762 * This asynchronous operation supports cancellation for the following
1763 * boost::asio::cancellation_type values:
1764 *
1765 * @li @c cancellation_type::terminal
1766 *
1767 * @li @c cancellation_type::partial
1768 *
1769 * if they are also supported by the @c AsyncReadStream type's
1770 * @c async_read_some operation.
1771 */
1772template <typename AsyncReadStream, typename DynamicBuffer_v1,
1773 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1774 std::size_t)) ReadToken = default_completion_token_t<
1775 typename AsyncReadStream::executor_type>>
1776auto async_read_until(AsyncReadStream& s,
1777 DynamicBuffer_v1&& buffers,
1778 BOOST_ASIO_STRING_VIEW_PARAM delim,
1779 ReadToken&& token = default_completion_token_t<
1780 typename AsyncReadStream::executor_type>(),
1781 constraint_t<
1782 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
1783 > = 0,
1784 constraint_t<
1785 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
1786 > = 0)
1787 -> decltype(
1788 async_initiate<ReadToken,
1789 void (boost::system::error_code, std::size_t)>(
1790 declval<detail::initiate_async_read_until_delim_string_v1<
1791 AsyncReadStream>>(),
1792 token, static_cast<DynamicBuffer_v1&&>(buffers),
1793 static_cast<std::string>(delim)));
1794
1795#if !defined(BOOST_ASIO_NO_EXTENSIONS)
1796#if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
1797 || defined(GENERATING_DOCUMENTATION)
1798
1799/// Start an asynchronous operation to read data into a dynamic buffer sequence
1800/// until some part of its data matches a regular expression.
1801/**
1802 * This function is used to asynchronously read data into the specified dynamic
1803 * buffer sequence until the dynamic buffer sequence's get area contains some
1804 * data that matches a regular expression. It is an initiating function for an
1805 * @ref asynchronous_operation, and always returns immediately. The
1806 * asynchronous operation will continue until one of the following conditions
1807 * is true:
1808 *
1809 * @li A substring of the dynamic buffer sequence's get area matches the regular
1810 * expression.
1811 *
1812 * @li An error occurred.
1813 *
1814 * This operation is implemented in terms of zero or more calls to the stream's
1815 * async_read_some function, and is known as a <em>composed operation</em>. If
1816 * the dynamic buffer sequence's get area already contains data that matches
1817 * the regular expression, this asynchronous operation completes immediately.
1818 * The program must ensure that the stream performs no other read operations
1819 * (such as async_read, async_read_until, the stream's async_read_some
1820 * function, or any other composed operations that perform reads) until this
1821 * operation completes.
1822 *
1823 * @param s The stream from which the data is to be read. The type must support
1824 * the AsyncReadStream concept.
1825 *
1826 * @param buffers The dynamic buffer sequence into which the data will be read.
1827 * Although the buffers object may be copied as necessary, ownership of the
1828 * underlying memory blocks is retained by the caller, which must guarantee
1829 * that they remain valid until the completion handler is called.
1830 *
1831 * @param expr The regular expression.
1832 *
1833 * @param token The @ref completion_token that will be used to produce a
1834 * completion handler, which will be called when the read completes.
1835 * Potential completion tokens include @ref use_future, @ref use_awaitable,
1836 * @ref yield_context, or a function object with the correct completion
1837 * signature. The function signature of the completion handler must be:
1838 * @code void handler(
1839 * // Result of operation.
1840 * const boost::system::error_code& error,
1841 *
1842 * // The number of bytes in the dynamic buffer
1843 * // sequence's get area up to and including the
1844 * // substring that matches the regular expression.
1845 * // 0 if an error occurred.
1846 * std::size_t bytes_transferred
1847 * ); @endcode
1848 * Regardless of whether the asynchronous operation completes immediately or
1849 * not, the completion handler will not be invoked from within this function.
1850 * On immediate completion, invocation of the handler will be performed in a
1851 * manner equivalent to using boost::asio::post().
1852 *
1853 * @par Completion Signature
1854 * @code void(boost::system::error_code, std::size_t) @endcode
1855 *
1856 * @note After a successful async_read_until operation, the dynamic buffer
1857 * sequence may contain additional data beyond that which matched the regular
1858 * expression. An application will typically leave that data in the dynamic
1859 * buffer sequence for a subsequent async_read_until operation to examine.
1860 *
1861 * @par Example
1862 * To asynchronously read data into a @c std::string until a CR-LF sequence is
1863 * encountered:
1864 * @code std::string data;
1865 * ...
1866 * void handler(const boost::system::error_code& e, std::size_t size)
1867 * {
1868 * if (!e)
1869 * {
1870 * std::string line = data.substr(0, n);
1871 * data.erase(0, n);
1872 * ...
1873 * }
1874 * }
1875 * ...
1876 * boost::asio::async_read_until(s, data,
1877 * boost::regex("\r\n"), handler); @endcode
1878 * After the @c async_read_until operation completes successfully, the string
1879 * @c data contains the data which matched the regular expression:
1880 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
1881 * The call to @c substr then extracts the data up to and including the match,
1882 * so that the string @c line contains:
1883 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
1884 * After the call to @c erase, the remaining data is left in the string @c data
1885 * as follows:
1886 * @code { 'd', 'e', ... } @endcode
1887 * This data may be the start of a new line, to be extracted by a subsequent
1888 * @c async_read_until operation.
1889 *
1890 * @par Per-Operation Cancellation
1891 * This asynchronous operation supports cancellation for the following
1892 * boost::asio::cancellation_type values:
1893 *
1894 * @li @c cancellation_type::terminal
1895 *
1896 * @li @c cancellation_type::partial
1897 *
1898 * if they are also supported by the @c AsyncReadStream type's
1899 * @c async_read_some operation.
1900 */
1901template <typename AsyncReadStream, typename DynamicBuffer_v1, typename Traits,
1902 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1903 std::size_t)) ReadToken = default_completion_token_t<
1904 typename AsyncReadStream::executor_type>>
1905auto async_read_until(AsyncReadStream& s, DynamicBuffer_v1&& buffers,
1906 const boost::basic_regex<char, Traits>& expr,
1907 ReadToken&& token = default_completion_token_t<
1908 typename AsyncReadStream::executor_type>(),
1909 constraint_t<
1910 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
1911 > = 0,
1912 constraint_t<
1913 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
1914 > = 0)
1915 -> decltype(
1916 async_initiate<ReadToken,
1917 void (boost::system::error_code, std::size_t)>(
1918 declval<detail::initiate_async_read_until_expr_v1<AsyncReadStream>>(),
1919 token, static_cast<DynamicBuffer_v1&&>(buffers), expr));
1920
1921#endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
1922 // || defined(GENERATING_DOCUMENTATION)
1923
1924/// Start an asynchronous operation to read data into a dynamic buffer sequence
1925/// until a function object indicates a match.
1926/**
1927 * This function is used to asynchronously read data into the specified dynamic
1928 * buffer sequence until a user-defined match condition function object, when
1929 * applied to the data contained in the dynamic buffer sequence, indicates a
1930 * successful match. It is an initiating function for an @ref
1931 * asynchronous_operation, and always returns immediately. The asynchronous
1932 * operation will continue until one of the following conditions is true:
1933 *
1934 * @li The match condition function object returns a std::pair where the second
1935 * element evaluates to true.
1936 *
1937 * @li An error occurred.
1938 *
1939 * This operation is implemented in terms of zero or more calls to the stream's
1940 * async_read_some function, and is known as a <em>composed operation</em>. If
1941 * the match condition function object already indicates a match, this
1942 * asynchronous operation completes immediately. The program must ensure that
1943 * the stream performs no other read operations (such as async_read,
1944 * async_read_until, the stream's async_read_some function, or any other
1945 * composed operations that perform reads) until this operation completes.
1946 *
1947 * @param s The stream from which the data is to be read. The type must support
1948 * the AsyncReadStream concept.
1949 *
1950 * @param buffers The dynamic buffer sequence into which the data will be read.
1951 * Although the buffers object may be copied as necessary, ownership of the
1952 * underlying memory blocks is retained by the caller, which must guarantee
1953 * that they remain valid until the completion handler is called.
1954 *
1955 * @param match_condition The function object to be called to determine whether
1956 * a match exists. The signature of the function object must be:
1957 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
1958 * @endcode
1959 * where @c iterator represents the type:
1960 * @code buffers_iterator<typename DynamicBuffer_v1::const_buffers_type>
1961 * @endcode
1962 * The iterator parameters @c begin and @c end define the range of bytes to be
1963 * scanned to determine whether there is a match. The @c first member of the
1964 * return value is an iterator marking one-past-the-end of the bytes that have
1965 * been consumed by the match function. This iterator is used to calculate the
1966 * @c begin parameter for any subsequent invocation of the match condition. The
1967 * @c second member of the return value is true if a match has been found, false
1968 * otherwise.
1969 *
1970 * @param token The @ref completion_token that will be used to produce a
1971 * completion handler, which will be called when the read completes.
1972 * Potential completion tokens include @ref use_future, @ref use_awaitable,
1973 * @ref yield_context, or a function object with the correct completion
1974 * signature. The function signature of the completion handler must be:
1975 * @code void handler(
1976 * // Result of operation.
1977 * const boost::system::error_code& error,
1978 *
1979 * // The number of bytes in the dynamic buffer sequence's
1980 * // get area that have been fully consumed by the match
1981 * // function. O if an error occurred.
1982 * std::size_t bytes_transferred
1983 * ); @endcode
1984 * Regardless of whether the asynchronous operation completes immediately or
1985 * not, the completion handler will not be invoked from within this function.
1986 * On immediate completion, invocation of the handler will be performed in a
1987 * manner equivalent to using boost::asio::post().
1988 *
1989 * @note After a successful async_read_until operation, the dynamic buffer
1990 * sequence may contain additional data beyond that which matched the function
1991 * object. An application will typically leave that data in the dynamic buffer
1992 * sequence for a subsequent async_read_until operation to examine.
1993 *
1994 * @par Completion Signature
1995 * @code void(boost::system::error_code, std::size_t) @endcode
1996 *
1997 * @note The default implementation of the @c is_match_condition type trait
1998 * evaluates to true for function pointers and function objects with a
1999 * @c result_type typedef. It must be specialised for other user-defined
2000 * function objects.
2001 *
2002 * @par Examples
2003 * To asynchronously read data into a @c std::string until whitespace is
2004 * encountered:
2005 * @code typedef boost::asio::buffers_iterator<
2006 * boost::asio::const_buffers_1> iterator;
2007 *
2008 * std::pair<iterator, bool>
2009 * match_whitespace(iterator begin, iterator end)
2010 * {
2011 * iterator i = begin;
2012 * while (i != end)
2013 * if (std::isspace(*i++))
2014 * return std::make_pair(i, true);
2015 * return std::make_pair(i, false);
2016 * }
2017 * ...
2018 * void handler(const boost::system::error_code& e, std::size_t size);
2019 * ...
2020 * std::string data;
2021 * boost::asio::async_read_until(s, data, match_whitespace, handler);
2022 * @endcode
2023 *
2024 * To asynchronously read data into a @c std::string until a matching character
2025 * is found:
2026 * @code class match_char
2027 * {
2028 * public:
2029 * explicit match_char(char c) : c_(c) {}
2030 *
2031 * template <typename Iterator>
2032 * std::pair<Iterator, bool> operator()(
2033 * Iterator begin, Iterator end) const
2034 * {
2035 * Iterator i = begin;
2036 * while (i != end)
2037 * if (c_ == *i++)
2038 * return std::make_pair(i, true);
2039 * return std::make_pair(i, false);
2040 * }
2041 *
2042 * private:
2043 * char c_;
2044 * };
2045 *
2046 * namespace asio {
2047 * template <> struct is_match_condition<match_char>
2048 * : public boost::true_type {};
2049 * } // namespace asio
2050 * ...
2051 * void handler(const boost::system::error_code& e, std::size_t size);
2052 * ...
2053 * std::string data;
2054 * boost::asio::async_read_until(s, data, match_char('a'), handler);
2055 * @endcode
2056 *
2057 * @par Per-Operation Cancellation
2058 * This asynchronous operation supports cancellation for the following
2059 * boost::asio::cancellation_type values:
2060 *
2061 * @li @c cancellation_type::terminal
2062 *
2063 * @li @c cancellation_type::partial
2064 *
2065 * if they are also supported by the @c AsyncReadStream type's
2066 * @c async_read_some operation.
2067 */
2068template <typename AsyncReadStream,
2069 typename DynamicBuffer_v1, typename MatchCondition,
2070 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2071 std::size_t)) ReadToken = default_completion_token_t<
2072 typename AsyncReadStream::executor_type>>
2073auto async_read_until(AsyncReadStream& s,
2074 DynamicBuffer_v1&& buffers, MatchCondition match_condition,
2075 ReadToken&& token = default_completion_token_t<
2076 typename AsyncReadStream::executor_type>(),
2077 constraint_t<
2078 is_match_condition<MatchCondition>::value
2079 > = 0,
2080 constraint_t<
2081 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
2082 > = 0,
2083 constraint_t<
2084 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
2085 > = 0)
2086 -> decltype(
2087 async_initiate<ReadToken,
2088 void (boost::system::error_code, std::size_t)>(
2089 declval<detail::initiate_async_read_until_match_v1<AsyncReadStream>>(),
2090 token, static_cast<DynamicBuffer_v1&&>(buffers),
2091 match_condition));
2092
2093#if !defined(BOOST_ASIO_NO_IOSTREAM)
2094
2095/// Start an asynchronous operation to read data into a streambuf until it
2096/// contains a specified delimiter.
2097/**
2098 * This function is used to asynchronously read data into the specified
2099 * streambuf until the streambuf's get area contains the specified delimiter.
2100 * It is an initiating function for an @ref asynchronous_operation, and always
2101 * returns immediately. The asynchronous operation will continue until one of
2102 * the following conditions is true:
2103 *
2104 * @li The get area of the streambuf contains the specified delimiter.
2105 *
2106 * @li An error occurred.
2107 *
2108 * This operation is implemented in terms of zero or more calls to the stream's
2109 * async_read_some function, and is known as a <em>composed operation</em>. If
2110 * the streambuf's get area already contains the delimiter, this asynchronous
2111 * operation completes immediately. The program must ensure that the stream
2112 * performs no other read operations (such as async_read, async_read_until, the
2113 * stream's async_read_some function, or any other composed operations that
2114 * perform reads) until this operation completes.
2115 *
2116 * @param s The stream from which the data is to be read. The type must support
2117 * the AsyncReadStream concept.
2118 *
2119 * @param b A streambuf object into which the data will be read. Ownership of
2120 * the streambuf is retained by the caller, which must guarantee that it remains
2121 * valid until the completion handler is called.
2122 *
2123 * @param delim The delimiter character.
2124 *
2125 * @param token The @ref completion_token that will be used to produce a
2126 * completion handler, which will be called when the read completes.
2127 * Potential completion tokens include @ref use_future, @ref use_awaitable,
2128 * @ref yield_context, or a function object with the correct completion
2129 * signature. The function signature of the completion handler must be:
2130 * @code void handler(
2131 * // Result of operation.
2132 * const boost::system::error_code& error,
2133 *
2134 * // The number of bytes in the streambuf's get
2135 * // area up to and including the delimiter.
2136 * // 0 if an error occurred.
2137 * std::size_t bytes_transferred
2138 * ); @endcode
2139 * Regardless of whether the asynchronous operation completes immediately or
2140 * not, the completion handler will not be invoked from within this function.
2141 * On immediate completion, invocation of the handler will be performed in a
2142 * manner equivalent to using boost::asio::post().
2143 *
2144 * @par Completion Signature
2145 * @code void(boost::system::error_code, std::size_t) @endcode
2146 *
2147 * @note After a successful async_read_until operation, the streambuf may
2148 * contain additional data beyond the delimiter. An application will typically
2149 * leave that data in the streambuf for a subsequent async_read_until operation
2150 * to examine.
2151 *
2152 * @par Example
2153 * To asynchronously read data into a streambuf until a newline is encountered:
2154 * @code boost::asio::streambuf b;
2155 * ...
2156 * void handler(const boost::system::error_code& e, std::size_t size)
2157 * {
2158 * if (!e)
2159 * {
2160 * std::istream is(&b);
2161 * std::string line;
2162 * std::getline(is, line);
2163 * ...
2164 * }
2165 * }
2166 * ...
2167 * boost::asio::async_read_until(s, b, '\n', handler); @endcode
2168 * After the @c async_read_until operation completes successfully, the buffer
2169 * @c b contains the delimiter:
2170 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
2171 * The call to @c std::getline then extracts the data up to and including the
2172 * newline (which is discarded), so that the string @c line contains:
2173 * @code { 'a', 'b', ..., 'c' } @endcode
2174 * The remaining data is left in the buffer @c b as follows:
2175 * @code { 'd', 'e', ... } @endcode
2176 * This data may be the start of a new line, to be extracted by a subsequent
2177 * @c async_read_until operation.
2178 *
2179 * @par Per-Operation Cancellation
2180 * This asynchronous operation supports cancellation for the following
2181 * boost::asio::cancellation_type values:
2182 *
2183 * @li @c cancellation_type::terminal
2184 *
2185 * @li @c cancellation_type::partial
2186 *
2187 * if they are also supported by the @c AsyncReadStream type's
2188 * @c async_read_some operation.
2189 */
2190template <typename AsyncReadStream, typename Allocator,
2191 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2192 std::size_t)) ReadToken = default_completion_token_t<
2193 typename AsyncReadStream::executor_type>>
2194auto async_read_until(AsyncReadStream& s,
2195 boost::asio::basic_streambuf<Allocator>& b, char delim,
2196 ReadToken&& token = default_completion_token_t<
2197 typename AsyncReadStream::executor_type>())
2198 -> decltype(
2199 async_initiate<ReadToken,
2200 void (boost::system::error_code, std::size_t)>(
2201 declval<detail::initiate_async_read_until_delim_v1<AsyncReadStream>>(),
2202 token, basic_streambuf_ref<Allocator>(b), delim));
2203
2204/// Start an asynchronous operation to read data into a streambuf until it
2205/// contains a specified delimiter.
2206/**
2207 * This function is used to asynchronously read data into the specified
2208 * streambuf until the streambuf's get area contains the specified delimiter.
2209 * It is an initiating function for an @ref asynchronous_operation, and always
2210 * returns immediately. The asynchronous operation will continue until one of
2211 * the following conditions is true:
2212 *
2213 * @li The get area of the streambuf contains the specified delimiter.
2214 *
2215 * @li An error occurred.
2216 *
2217 * This operation is implemented in terms of zero or more calls to the stream's
2218 * async_read_some function, and is known as a <em>composed operation</em>. If
2219 * the streambuf's get area already contains the delimiter, this asynchronous
2220 * operation completes immediately. The program must ensure that the stream
2221 * performs no other read operations (such as async_read, async_read_until, the
2222 * stream's async_read_some function, or any other composed operations that
2223 * perform reads) until this operation completes.
2224 *
2225 * @param s The stream from which the data is to be read. The type must support
2226 * the AsyncReadStream concept.
2227 *
2228 * @param b A streambuf object into which the data will be read. Ownership of
2229 * the streambuf is retained by the caller, which must guarantee that it remains
2230 * valid until the completion handler is called.
2231 *
2232 * @param delim The delimiter string.
2233 *
2234 * @param token The @ref completion_token that will be used to produce a
2235 * completion handler, which will be called when the read completes.
2236 * Potential completion tokens include @ref use_future, @ref use_awaitable,
2237 * @ref yield_context, or a function object with the correct completion
2238 * signature. The function signature of the completion handler must be:
2239 * @code void handler(
2240 * // Result of operation.
2241 * const boost::system::error_code& error,
2242 *
2243 * // The number of bytes in the streambuf's get
2244 * // area up to and including the delimiter.
2245 * // 0 if an error occurred.
2246 * std::size_t bytes_transferred
2247 * ); @endcode
2248 * Regardless of whether the asynchronous operation completes immediately or
2249 * not, the completion handler will not be invoked from within this function.
2250 * On immediate completion, invocation of the handler will be performed in a
2251 * manner equivalent to using boost::asio::post().
2252 *
2253 * @par Completion Signature
2254 * @code void(boost::system::error_code, std::size_t) @endcode
2255 *
2256 * @note After a successful async_read_until operation, the streambuf may
2257 * contain additional data beyond the delimiter. An application will typically
2258 * leave that data in the streambuf for a subsequent async_read_until operation
2259 * to examine.
2260 *
2261 * @par Example
2262 * To asynchronously read data into a streambuf until a newline is encountered:
2263 * @code boost::asio::streambuf b;
2264 * ...
2265 * void handler(const boost::system::error_code& e, std::size_t size)
2266 * {
2267 * if (!e)
2268 * {
2269 * std::istream is(&b);
2270 * std::string line;
2271 * std::getline(is, line);
2272 * ...
2273 * }
2274 * }
2275 * ...
2276 * boost::asio::async_read_until(s, b, "\r\n", handler); @endcode
2277 * After the @c async_read_until operation completes successfully, the buffer
2278 * @c b contains the delimiter:
2279 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
2280 * The call to @c std::getline then extracts the data up to and including the
2281 * newline (which is discarded), so that the string @c line contains:
2282 * @code { 'a', 'b', ..., 'c', '\r' } @endcode
2283 * The remaining data is left in the buffer @c b as follows:
2284 * @code { 'd', 'e', ... } @endcode
2285 * This data may be the start of a new line, to be extracted by a subsequent
2286 * @c async_read_until operation.
2287 *
2288 * @par Per-Operation Cancellation
2289 * This asynchronous operation supports cancellation for the following
2290 * boost::asio::cancellation_type values:
2291 *
2292 * @li @c cancellation_type::terminal
2293 *
2294 * @li @c cancellation_type::partial
2295 *
2296 * if they are also supported by the @c AsyncReadStream type's
2297 * @c async_read_some operation.
2298 */
2299template <typename AsyncReadStream, typename Allocator,
2300 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2301 std::size_t)) ReadToken = default_completion_token_t<
2302 typename AsyncReadStream::executor_type>>
2303auto async_read_until(AsyncReadStream& s,
2304 boost::asio::basic_streambuf<Allocator>& b,
2305 BOOST_ASIO_STRING_VIEW_PARAM delim,
2306 ReadToken&& token = default_completion_token_t<
2307 typename AsyncReadStream::executor_type>())
2308 -> decltype(
2309 async_initiate<ReadToken,
2310 void (boost::system::error_code, std::size_t)>(
2311 declval<detail::initiate_async_read_until_delim_string_v1<
2312 AsyncReadStream>>(),
2313 token, basic_streambuf_ref<Allocator>(b),
2314 static_cast<std::string>(delim)));
2315
2316#if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
2317 || defined(GENERATING_DOCUMENTATION)
2318
2319/// Start an asynchronous operation to read data into a streambuf until some
2320/// part of its data matches a regular expression.
2321/**
2322 * This function is used to asynchronously read data into the specified
2323 * streambuf until the streambuf's get area contains some data that matches a
2324 * regular expression. It is an initiating function for an @ref
2325 * asynchronous_operation, and always returns immediately. The asynchronous
2326 * operation will continue until one of the following conditions is true:
2327 *
2328 * @li A substring of the streambuf's get area matches the regular expression.
2329 *
2330 * @li An error occurred.
2331 *
2332 * This operation is implemented in terms of zero or more calls to the stream's
2333 * async_read_some function, and is known as a <em>composed operation</em>. If
2334 * the streambuf's get area already contains data that matches the regular
2335 * expression, this asynchronous operation completes immediately. The program
2336 * must ensure that the stream performs no other read operations (such as
2337 * async_read, async_read_until, the stream's async_read_some function, or any
2338 * other composed operations that perform reads) until this operation
2339 * completes.
2340 *
2341 * @param s The stream from which the data is to be read. The type must support
2342 * the AsyncReadStream concept.
2343 *
2344 * @param b A streambuf object into which the data will be read. Ownership of
2345 * the streambuf is retained by the caller, which must guarantee that it remains
2346 * valid until the completion handler is called.
2347 *
2348 * @param expr The regular expression.
2349 *
2350 * @param token The @ref completion_token that will be used to produce a
2351 * completion handler, which will be called when the read completes.
2352 * Potential completion tokens include @ref use_future, @ref use_awaitable,
2353 * @ref yield_context, or a function object with the correct completion
2354 * signature. The function signature of the completion handler must be:
2355 * @code void handler(
2356 * // Result of operation.
2357 * const boost::system::error_code& error,
2358 *
2359 * // The number of bytes in the streambuf's get
2360 * // area up to and including the substring
2361 * // that matches the regular. expression.
2362 * // 0 if an error occurred.
2363 * std::size_t bytes_transferred
2364 * ); @endcode
2365 * Regardless of whether the asynchronous operation completes immediately or
2366 * not, the completion handler will not be invoked from within this function.
2367 * On immediate completion, invocation of the handler will be performed in a
2368 * manner equivalent to using boost::asio::post().
2369 *
2370 * @par Completion Signature
2371 * @code void(boost::system::error_code, std::size_t) @endcode
2372 *
2373 * @note After a successful async_read_until operation, the streambuf may
2374 * contain additional data beyond that which matched the regular expression. An
2375 * application will typically leave that data in the streambuf for a subsequent
2376 * async_read_until operation to examine.
2377 *
2378 * @par Example
2379 * To asynchronously read data into a streambuf until a CR-LF sequence is
2380 * encountered:
2381 * @code boost::asio::streambuf b;
2382 * ...
2383 * void handler(const boost::system::error_code& e, std::size_t size)
2384 * {
2385 * if (!e)
2386 * {
2387 * std::istream is(&b);
2388 * std::string line;
2389 * std::getline(is, line);
2390 * ...
2391 * }
2392 * }
2393 * ...
2394 * boost::asio::async_read_until(s, b, boost::regex("\r\n"), handler); @endcode
2395 * After the @c async_read_until operation completes successfully, the buffer
2396 * @c b contains the data which matched the regular expression:
2397 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
2398 * The call to @c std::getline then extracts the data up to and including the
2399 * newline (which is discarded), so that the string @c line contains:
2400 * @code { 'a', 'b', ..., 'c', '\r' } @endcode
2401 * The remaining data is left in the buffer @c b as follows:
2402 * @code { 'd', 'e', ... } @endcode
2403 * This data may be the start of a new line, to be extracted by a subsequent
2404 * @c async_read_until operation.
2405 *
2406 * @par Per-Operation Cancellation
2407 * This asynchronous operation supports cancellation for the following
2408 * boost::asio::cancellation_type values:
2409 *
2410 * @li @c cancellation_type::terminal
2411 *
2412 * @li @c cancellation_type::partial
2413 *
2414 * if they are also supported by the @c AsyncReadStream type's
2415 * @c async_read_some operation.
2416 */
2417template <typename AsyncReadStream, typename Allocator, typename Traits,
2418 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2419 std::size_t)) ReadToken = default_completion_token_t<
2420 typename AsyncReadStream::executor_type>>
2421auto async_read_until(AsyncReadStream& s,
2422 boost::asio::basic_streambuf<Allocator>& b,
2423 const boost::basic_regex<char, Traits>& expr,
2424 ReadToken&& token = default_completion_token_t<
2425 typename AsyncReadStream::executor_type>())
2426 -> decltype(
2427 async_initiate<ReadToken,
2428 void (boost::system::error_code, std::size_t)>(
2429 declval<detail::initiate_async_read_until_expr_v1<AsyncReadStream>>(),
2430 token, basic_streambuf_ref<Allocator>(b), expr));
2431
2432#endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
2433 // || defined(GENERATING_DOCUMENTATION)
2434
2435/// Start an asynchronous operation to read data into a streambuf until a
2436/// function object indicates a match.
2437/**
2438 * This function is used to asynchronously read data into the specified
2439 * streambuf until a user-defined match condition function object, when applied
2440 * to the data contained in the streambuf, indicates a successful match. It is
2441 * an initiating function for an @ref asynchronous_operation, and always
2442 * returns immediately. The asynchronous operation will continue until one of
2443 * the following conditions is true:
2444 *
2445 * @li The match condition function object returns a std::pair where the second
2446 * element evaluates to true.
2447 *
2448 * @li An error occurred.
2449 *
2450 * This operation is implemented in terms of zero or more calls to the stream's
2451 * async_read_some function, and is known as a <em>composed operation</em>. If
2452 * the match condition function object already indicates a match, this
2453 * asynchronous operation completes immediately. The program must ensure that
2454 * the stream performs no other read operations (such as async_read,
2455 * async_read_until, the stream's async_read_some function, or any other
2456 * composed operations that perform reads) until this operation completes.
2457 *
2458 * @param s The stream from which the data is to be read. The type must support
2459 * the AsyncReadStream concept.
2460 *
2461 * @param b A streambuf object into which the data will be read.
2462 *
2463 * @param match_condition The function object to be called to determine whether
2464 * a match exists. The signature of the function object must be:
2465 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
2466 * @endcode
2467 * where @c iterator represents the type:
2468 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
2469 * @endcode
2470 * The iterator parameters @c begin and @c end define the range of bytes to be
2471 * scanned to determine whether there is a match. The @c first member of the
2472 * return value is an iterator marking one-past-the-end of the bytes that have
2473 * been consumed by the match function. This iterator is used to calculate the
2474 * @c begin parameter for any subsequent invocation of the match condition. The
2475 * @c second member of the return value is true if a match has been found, false
2476 * otherwise.
2477 *
2478 * @param token The @ref completion_token that will be used to produce a
2479 * completion handler, which will be called when the read completes.
2480 * Potential completion tokens include @ref use_future, @ref use_awaitable,
2481 * @ref yield_context, or a function object with the correct completion
2482 * signature. The function signature of the completion handler must be:
2483 * @code void handler(
2484 * // Result of operation.
2485 * const boost::system::error_code& error,
2486 *
2487 * // The number of bytes in the streambuf's get
2488 * // area that have been fully consumed by the
2489 * // match function. O if an error occurred.
2490 * std::size_t bytes_transferred
2491 * ); @endcode
2492 * Regardless of whether the asynchronous operation completes immediately or
2493 * not, the completion handler will not be invoked from within this function.
2494 * On immediate completion, invocation of the handler will be performed in a
2495 * manner equivalent to using boost::asio::post().
2496 *
2497 * @note After a successful async_read_until operation, the streambuf may
2498 * contain additional data beyond that which matched the function object. An
2499 * application will typically leave that data in the streambuf for a subsequent
2500 * async_read_until operation to examine.
2501 *
2502 * @par Completion Signature
2503 * @code void(boost::system::error_code, std::size_t) @endcode
2504 *
2505 * @note The default implementation of the @c is_match_condition type trait
2506 * evaluates to true for function pointers and function objects with a
2507 * @c result_type typedef. It must be specialised for other user-defined
2508 * function objects.
2509 *
2510 * @par Examples
2511 * To asynchronously read data into a streambuf until whitespace is encountered:
2512 * @code typedef boost::asio::buffers_iterator<
2513 * boost::asio::streambuf::const_buffers_type> iterator;
2514 *
2515 * std::pair<iterator, bool>
2516 * match_whitespace(iterator begin, iterator end)
2517 * {
2518 * iterator i = begin;
2519 * while (i != end)
2520 * if (std::isspace(*i++))
2521 * return std::make_pair(i, true);
2522 * return std::make_pair(i, false);
2523 * }
2524 * ...
2525 * void handler(const boost::system::error_code& e, std::size_t size);
2526 * ...
2527 * boost::asio::streambuf b;
2528 * boost::asio::async_read_until(s, b, match_whitespace, handler);
2529 * @endcode
2530 *
2531 * To asynchronously read data into a streambuf until a matching character is
2532 * found:
2533 * @code class match_char
2534 * {
2535 * public:
2536 * explicit match_char(char c) : c_(c) {}
2537 *
2538 * template <typename Iterator>
2539 * std::pair<Iterator, bool> operator()(
2540 * Iterator begin, Iterator end) const
2541 * {
2542 * Iterator i = begin;
2543 * while (i != end)
2544 * if (c_ == *i++)
2545 * return std::make_pair(i, true);
2546 * return std::make_pair(i, false);
2547 * }
2548 *
2549 * private:
2550 * char c_;
2551 * };
2552 *
2553 * namespace asio {
2554 * template <> struct is_match_condition<match_char>
2555 * : public boost::true_type {};
2556 * } // namespace asio
2557 * ...
2558 * void handler(const boost::system::error_code& e, std::size_t size);
2559 * ...
2560 * boost::asio::streambuf b;
2561 * boost::asio::async_read_until(s, b, match_char('a'), handler);
2562 * @endcode
2563 *
2564 * @par Per-Operation Cancellation
2565 * This asynchronous operation supports cancellation for the following
2566 * boost::asio::cancellation_type values:
2567 *
2568 * @li @c cancellation_type::terminal
2569 *
2570 * @li @c cancellation_type::partial
2571 *
2572 * if they are also supported by the @c AsyncReadStream type's
2573 * @c async_read_some operation.
2574 */
2575template <typename AsyncReadStream, typename Allocator, typename MatchCondition,
2576 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2577 std::size_t)) ReadToken = default_completion_token_t<
2578 typename AsyncReadStream::executor_type>>
2579auto async_read_until(AsyncReadStream& s,
2580 boost::asio::basic_streambuf<Allocator>& b, MatchCondition match_condition,
2581 ReadToken&& token = default_completion_token_t<
2582 typename AsyncReadStream::executor_type>(),
2583 constraint_t<is_match_condition<MatchCondition>::value> = 0)
2584 -> decltype(
2585 async_initiate<ReadToken,
2586 void (boost::system::error_code, std::size_t)>(
2587 declval<detail::initiate_async_read_until_match_v1<AsyncReadStream>>(),
2588 token, basic_streambuf_ref<Allocator>(b), match_condition));
2589
2590#endif // !defined(BOOST_ASIO_NO_IOSTREAM)
2591#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
2592#endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
2593
2594/// Start an asynchronous operation to read data into a dynamic buffer sequence
2595/// until it contains a specified delimiter.
2596/**
2597 * This function is used to asynchronously read data into the specified dynamic
2598 * buffer sequence until the dynamic buffer sequence's get area contains the
2599 * specified delimiter. It is an initiating function for an @ref
2600 * asynchronous_operation, and always returns immediately. The asynchronous
2601 * operation will continue until one of the following conditions is true:
2602 *
2603 * @li The get area of the dynamic buffer sequence contains the specified
2604 * delimiter.
2605 *
2606 * @li An error occurred.
2607 *
2608 * This operation is implemented in terms of zero or more calls to the stream's
2609 * async_read_some function, and is known as a <em>composed operation</em>. If
2610 * the dynamic buffer sequence's get area already contains the delimiter, this
2611 * asynchronous operation completes immediately. The program must ensure that
2612 * the stream performs no other read operations (such as async_read,
2613 * async_read_until, the stream's async_read_some function, or any other
2614 * composed operations that perform reads) until this operation completes.
2615 *
2616 * @param s The stream from which the data is to be read. The type must support
2617 * the AsyncReadStream concept.
2618 *
2619 * @param buffers The dynamic buffer sequence into which the data will be read.
2620 * Although the buffers object may be copied as necessary, ownership of the
2621 * underlying memory blocks is retained by the caller, which must guarantee
2622 * that they remain valid until the completion handler is called.
2623 *
2624 * @param delim The delimiter character.
2625 *
2626 * @param token The @ref completion_token that will be used to produce a
2627 * completion handler, which will be called when the read completes.
2628 * Potential completion tokens include @ref use_future, @ref use_awaitable,
2629 * @ref yield_context, or a function object with the correct completion
2630 * signature. The function signature of the completion handler must be:
2631 * @code void handler(
2632 * // Result of operation.
2633 * const boost::system::error_code& error,
2634 *
2635 * // The number of bytes in the dynamic buffer sequence's
2636 * // get area up to and including the delimiter.
2637 * // 0 if an error occurred.
2638 * std::size_t bytes_transferred
2639 * ); @endcode
2640 * Regardless of whether the asynchronous operation completes immediately or
2641 * not, the completion handler will not be invoked from within this function.
2642 * On immediate completion, invocation of the handler will be performed in a
2643 * manner equivalent to using boost::asio::post().
2644 *
2645 * @par Completion Signature
2646 * @code void(boost::system::error_code, std::size_t) @endcode
2647 *
2648 * @note After a successful async_read_until operation, the dynamic buffer
2649 * sequence may contain additional data beyond the delimiter. An application
2650 * will typically leave that data in the dynamic buffer sequence for a
2651 * subsequent async_read_until operation to examine.
2652 *
2653 * @par Example
2654 * To asynchronously read data into a @c std::string until a newline is
2655 * encountered:
2656 * @code std::string data;
2657 * ...
2658 * void handler(const boost::system::error_code& e, std::size_t size)
2659 * {
2660 * if (!e)
2661 * {
2662 * std::string line = data.substr(0, n);
2663 * data.erase(0, n);
2664 * ...
2665 * }
2666 * }
2667 * ...
2668 * boost::asio::async_read_until(s, data, '\n', handler); @endcode
2669 * After the @c async_read_until operation completes successfully, the buffer
2670 * @c data contains the delimiter:
2671 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
2672 * The call to @c substr then extracts the data up to and including the
2673 * delimiter, so that the string @c line contains:
2674 * @code { 'a', 'b', ..., 'c', '\n' } @endcode
2675 * After the call to @c erase, the remaining data is left in the buffer @c data
2676 * as follows:
2677 * @code { 'd', 'e', ... } @endcode
2678 * This data may be the start of a new line, to be extracted by a subsequent
2679 * @c async_read_until operation.
2680 *
2681 * @par Per-Operation Cancellation
2682 * This asynchronous operation supports cancellation for the following
2683 * boost::asio::cancellation_type values:
2684 *
2685 * @li @c cancellation_type::terminal
2686 *
2687 * @li @c cancellation_type::partial
2688 *
2689 * if they are also supported by the @c AsyncReadStream type's
2690 * @c async_read_some operation.
2691 */
2692template <typename AsyncReadStream, typename DynamicBuffer_v2,
2693 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2694 std::size_t)) ReadToken = default_completion_token_t<
2695 typename AsyncReadStream::executor_type>>
2696auto async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers, char delim,
2697 ReadToken&& token = default_completion_token_t<
2698 typename AsyncReadStream::executor_type>(),
2699 constraint_t<
2700 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
2701 > = 0)
2702 -> decltype(
2703 async_initiate<ReadToken,
2704 void (boost::system::error_code, std::size_t)>(
2705 declval<detail::initiate_async_read_until_delim_v2<AsyncReadStream>>(),
2706 token, static_cast<DynamicBuffer_v2&&>(buffers), delim));
2707
2708/// Start an asynchronous operation to read data into a dynamic buffer sequence
2709/// until it contains a specified delimiter.
2710/**
2711 * This function is used to asynchronously read data into the specified dynamic
2712 * buffer sequence until the dynamic buffer sequence's get area contains the
2713 * specified delimiter. It is an initiating function for an @ref
2714 * asynchronous_operation, and always returns immediately. The asynchronous
2715 * operation will continue until one of the following conditions is true:
2716 *
2717 * @li The get area of the dynamic buffer sequence contains the specified
2718 * delimiter.
2719 *
2720 * @li An error occurred.
2721 *
2722 * This operation is implemented in terms of zero or more calls to the stream's
2723 * async_read_some function, and is known as a <em>composed operation</em>. If
2724 * the dynamic buffer sequence's get area already contains the delimiter, this
2725 * asynchronous operation completes immediately. The program must ensure that
2726 * the stream performs no other read operations (such as async_read,
2727 * async_read_until, the stream's async_read_some function, or any other
2728 * composed operations that perform reads) until this operation completes.
2729 *
2730 * @param s The stream from which the data is to be read. The type must support
2731 * the AsyncReadStream concept.
2732 *
2733 * @param buffers The dynamic buffer sequence into which the data will be read.
2734 * Although the buffers object may be copied as necessary, ownership of the
2735 * underlying memory blocks is retained by the caller, which must guarantee
2736 * that they remain valid until the completion handler is called.
2737 *
2738 * @param delim The delimiter string.
2739 *
2740 * @param token The @ref completion_token that will be used to produce a
2741 * completion handler, which will be called when the read completes.
2742 * Potential completion tokens include @ref use_future, @ref use_awaitable,
2743 * @ref yield_context, or a function object with the correct completion
2744 * signature. The function signature of the completion handler must be:
2745 * @code void handler(
2746 * // Result of operation.
2747 * const boost::system::error_code& error,
2748 *
2749 * // The number of bytes in the dynamic buffer sequence's
2750 * // get area up to and including the delimiter.
2751 * std::size_t bytes_transferred
2752 * ); @endcode
2753 * Regardless of whether the asynchronous operation completes immediately or
2754 * not, the completion handler will not be invoked from within this function.
2755 * On immediate completion, invocation of the handler will be performed in a
2756 * manner equivalent to using boost::asio::post().
2757 *
2758 * @par Completion Signature
2759 * @code void(boost::system::error_code, std::size_t) @endcode
2760 *
2761 * @note After a successful async_read_until operation, the dynamic buffer
2762 * sequence may contain additional data beyond the delimiter. An application
2763 * will typically leave that data in the dynamic buffer sequence for a
2764 * subsequent async_read_until operation to examine.
2765 *
2766 * @par Example
2767 * To asynchronously read data into a @c std::string until a CR-LF sequence is
2768 * encountered:
2769 * @code std::string data;
2770 * ...
2771 * void handler(const boost::system::error_code& e, std::size_t size)
2772 * {
2773 * if (!e)
2774 * {
2775 * std::string line = data.substr(0, n);
2776 * data.erase(0, n);
2777 * ...
2778 * }
2779 * }
2780 * ...
2781 * boost::asio::async_read_until(s, data, "\r\n", handler); @endcode
2782 * After the @c async_read_until operation completes successfully, the string
2783 * @c data contains the delimiter:
2784 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
2785 * The call to @c substr then extracts the data up to and including the
2786 * delimiter, so that the string @c line contains:
2787 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
2788 * After the call to @c erase, the remaining data is left in the string @c data
2789 * as follows:
2790 * @code { 'd', 'e', ... } @endcode
2791 * This data may be the start of a new line, to be extracted by a subsequent
2792 * @c async_read_until operation.
2793 *
2794 * @par Per-Operation Cancellation
2795 * This asynchronous operation supports cancellation for the following
2796 * boost::asio::cancellation_type values:
2797 *
2798 * @li @c cancellation_type::terminal
2799 *
2800 * @li @c cancellation_type::partial
2801 *
2802 * if they are also supported by the @c AsyncReadStream type's
2803 * @c async_read_some operation.
2804 */
2805template <typename AsyncReadStream, typename DynamicBuffer_v2,
2806 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2807 std::size_t)) ReadToken = default_completion_token_t<
2808 typename AsyncReadStream::executor_type>>
2809auto async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers,
2810 BOOST_ASIO_STRING_VIEW_PARAM delim,
2811 ReadToken&& token = default_completion_token_t<
2812 typename AsyncReadStream::executor_type>(),
2813 constraint_t<
2814 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
2815 > = 0)
2816 -> decltype(
2817 async_initiate<ReadToken,
2818 void (boost::system::error_code, std::size_t)>(
2819 declval<detail::initiate_async_read_until_delim_string_v2<
2820 AsyncReadStream>>(),
2821 token, static_cast<DynamicBuffer_v2&&>(buffers),
2822 static_cast<std::string>(delim)));
2823
2824#if !defined(BOOST_ASIO_NO_EXTENSIONS)
2825#if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
2826 || defined(GENERATING_DOCUMENTATION)
2827
2828/// Start an asynchronous operation to read data into a dynamic buffer sequence
2829/// until some part of its data matches a regular expression.
2830/**
2831 * This function is used to asynchronously read data into the specified dynamic
2832 * buffer sequence until the dynamic buffer sequence's get area contains some
2833 * data that matches a regular expression. It is an initiating function for an
2834 * @ref asynchronous_operation, and always returns immediately. The
2835 * asynchronous operation will continue until one of the following conditions
2836 * is true:
2837 *
2838 * @li A substring of the dynamic buffer sequence's get area matches the regular
2839 * expression.
2840 *
2841 * @li An error occurred.
2842 *
2843 * This operation is implemented in terms of zero or more calls to the stream's
2844 * async_read_some function, and is known as a <em>composed operation</em>. If
2845 * the dynamic buffer sequence's get area already contains data that matches
2846 * the regular expression, this asynchronous operation completes immediately.
2847 * The program must ensure that the stream performs no other read operations
2848 * (such as async_read, async_read_until, the stream's async_read_some
2849 * function, or any other composed operations that perform reads) until this
2850 * operation completes.
2851 *
2852 * @param s The stream from which the data is to be read. The type must support
2853 * the AsyncReadStream concept.
2854 *
2855 * @param buffers The dynamic buffer sequence into which the data will be read.
2856 * Although the buffers object may be copied as necessary, ownership of the
2857 * underlying memory blocks is retained by the caller, which must guarantee
2858 * that they remain valid until the completion handler is called.
2859 *
2860 * @param expr The regular expression.
2861 *
2862 * @param token The @ref completion_token that will be used to produce a
2863 * completion handler, which will be called when the read completes.
2864 * Potential completion tokens include @ref use_future, @ref use_awaitable,
2865 * @ref yield_context, or a function object with the correct completion
2866 * signature. The function signature of the completion handler must be:
2867 * @code void handler(
2868 * // Result of operation.
2869 * const boost::system::error_code& error,
2870 *
2871 * // The number of bytes in the dynamic buffer
2872 * // sequence's get area up to and including the
2873 * // substring that matches the regular expression.
2874 * // 0 if an error occurred.
2875 * std::size_t bytes_transferred
2876 * ); @endcode
2877 * Regardless of whether the asynchronous operation completes immediately or
2878 * not, the completion handler will not be invoked from within this function.
2879 * On immediate completion, invocation of the handler will be performed in a
2880 * manner equivalent to using boost::asio::post().
2881 *
2882 * @par Completion Signature
2883 * @code void(boost::system::error_code, std::size_t) @endcode
2884 *
2885 * @note After a successful async_read_until operation, the dynamic buffer
2886 * sequence may contain additional data beyond that which matched the regular
2887 * expression. An application will typically leave that data in the dynamic
2888 * buffer sequence for a subsequent async_read_until operation to examine.
2889 *
2890 * @par Example
2891 * To asynchronously read data into a @c std::string until a CR-LF sequence is
2892 * encountered:
2893 * @code std::string data;
2894 * ...
2895 * void handler(const boost::system::error_code& e, std::size_t size)
2896 * {
2897 * if (!e)
2898 * {
2899 * std::string line = data.substr(0, n);
2900 * data.erase(0, n);
2901 * ...
2902 * }
2903 * }
2904 * ...
2905 * boost::asio::async_read_until(s, data,
2906 * boost::regex("\r\n"), handler); @endcode
2907 * After the @c async_read_until operation completes successfully, the string
2908 * @c data contains the data which matched the regular expression:
2909 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
2910 * The call to @c substr then extracts the data up to and including the match,
2911 * so that the string @c line contains:
2912 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
2913 * After the call to @c erase, the remaining data is left in the string @c data
2914 * as follows:
2915 * @code { 'd', 'e', ... } @endcode
2916 * This data may be the start of a new line, to be extracted by a subsequent
2917 * @c async_read_until operation.
2918 *
2919 * @par Per-Operation Cancellation
2920 * This asynchronous operation supports cancellation for the following
2921 * boost::asio::cancellation_type values:
2922 *
2923 * @li @c cancellation_type::terminal
2924 *
2925 * @li @c cancellation_type::partial
2926 *
2927 * if they are also supported by the @c AsyncReadStream type's
2928 * @c async_read_some operation.
2929 */
2930template <typename AsyncReadStream, typename DynamicBuffer_v2, typename Traits,
2931 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
2932 std::size_t)) ReadToken = default_completion_token_t<
2933 typename AsyncReadStream::executor_type>>
2934auto async_read_until(AsyncReadStream& s, DynamicBuffer_v2 buffers,
2935 const boost::basic_regex<char, Traits>& expr,
2936 ReadToken&& token = default_completion_token_t<
2937 typename AsyncReadStream::executor_type>(),
2938 constraint_t<
2939 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
2940 > = 0)
2941 -> decltype(
2942 async_initiate<ReadToken,
2943 void (boost::system::error_code, std::size_t)>(
2944 declval<detail::initiate_async_read_until_expr_v2<AsyncReadStream>>(),
2945 token, static_cast<DynamicBuffer_v2&&>(buffers), expr));
2946
2947#endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
2948 // || defined(GENERATING_DOCUMENTATION)
2949
2950/// Start an asynchronous operation to read data into a dynamic buffer sequence
2951/// until a function object indicates a match.
2952/**
2953 * This function is used to asynchronously read data into the specified dynamic
2954 * buffer sequence until a user-defined match condition function object, when
2955 * applied to the data contained in the dynamic buffer sequence, indicates a
2956 * successful match. It is an initiating function for an @ref
2957 * asynchronous_operation, and always returns immediately. The asynchronous
2958 * operation will continue until one of the following conditions is true:
2959 *
2960 * @li The match condition function object returns a std::pair where the second
2961 * element evaluates to true.
2962 *
2963 * @li An error occurred.
2964 *
2965 * This operation is implemented in terms of zero or more calls to the stream's
2966 * async_read_some function, and is known as a <em>composed operation</em>. If
2967 * the match condition function object already indicates a match, this
2968 * asynchronous operation completes immediately. The program must ensure that
2969 * the stream performs no other read operations (such as async_read,
2970 * async_read_until, the stream's async_read_some function, or any other
2971 * composed operations that perform reads) until this operation completes.
2972 *
2973 * @param s The stream from which the data is to be read. The type must support
2974 * the AsyncReadStream concept.
2975 *
2976 * @param buffers The dynamic buffer sequence into which the data will be read.
2977 * Although the buffers object may be copied as necessary, ownership of the
2978 * underlying memory blocks is retained by the caller, which must guarantee
2979 * that they remain valid until the completion handler is called.
2980 *
2981 * @param match_condition The function object to be called to determine whether
2982 * a match exists. The signature of the function object must be:
2983 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
2984 * @endcode
2985 * where @c iterator represents the type:
2986 * @code buffers_iterator<typename DynamicBuffer_v2::const_buffers_type>
2987 * @endcode
2988 * The iterator parameters @c begin and @c end define the range of bytes to be
2989 * scanned to determine whether there is a match. The @c first member of the
2990 * return value is an iterator marking one-past-the-end of the bytes that have
2991 * been consumed by the match function. This iterator is used to calculate the
2992 * @c begin parameter for any subsequent invocation of the match condition. The
2993 * @c second member of the return value is true if a match has been found, false
2994 * otherwise.
2995 *
2996 * @param token The @ref completion_token that will be used to produce a
2997 * completion handler, which will be called when the read completes.
2998 * Potential completion tokens include @ref use_future, @ref use_awaitable,
2999 * @ref yield_context, or a function object with the correct completion
3000 * signature. The function signature of the completion handler must be:
3001 * @code void handler(
3002 * // Result of operation.
3003 * const boost::system::error_code& error,
3004 *
3005 * // The number of bytes in the dynamic buffer sequence's
3006 * // get area that have been fully consumed by the match
3007 * // function. O if an error occurred.
3008 * std::size_t bytes_transferred
3009 * ); @endcode
3010 * Regardless of whether the asynchronous operation completes immediately or
3011 * not, the completion handler will not be invoked from within this function.
3012 * On immediate completion, invocation of the handler will be performed in a
3013 * manner equivalent to using boost::asio::post().
3014 *
3015 * @note After a successful async_read_until operation, the dynamic buffer
3016 * sequence may contain additional data beyond that which matched the function
3017 * object. An application will typically leave that data in the dynamic buffer
3018 * sequence for a subsequent async_read_until operation to examine.
3019 *
3020 * @par Completion Signature
3021 * @code void(boost::system::error_code, std::size_t) @endcode
3022 *
3023 * @note The default implementation of the @c is_match_condition type trait
3024 * evaluates to true for function pointers and function objects with a
3025 * @c result_type typedef. It must be specialised for other user-defined
3026 * function objects.
3027 *
3028 * @par Examples
3029 * To asynchronously read data into a @c std::string until whitespace is
3030 * encountered:
3031 * @code typedef boost::asio::buffers_iterator<
3032 * boost::asio::const_buffers_1> iterator;
3033 *
3034 * std::pair<iterator, bool>
3035 * match_whitespace(iterator begin, iterator end)
3036 * {
3037 * iterator i = begin;
3038 * while (i != end)
3039 * if (std::isspace(*i++))
3040 * return std::make_pair(i, true);
3041 * return std::make_pair(i, false);
3042 * }
3043 * ...
3044 * void handler(const boost::system::error_code& e, std::size_t size);
3045 * ...
3046 * std::string data;
3047 * boost::asio::async_read_until(s, data, match_whitespace, handler);
3048 * @endcode
3049 *
3050 * To asynchronously read data into a @c std::string until a matching character
3051 * is found:
3052 * @code class match_char
3053 * {
3054 * public:
3055 * explicit match_char(char c) : c_(c) {}
3056 *
3057 * template <typename Iterator>
3058 * std::pair<Iterator, bool> operator()(
3059 * Iterator begin, Iterator end) const
3060 * {
3061 * Iterator i = begin;
3062 * while (i != end)
3063 * if (c_ == *i++)
3064 * return std::make_pair(i, true);
3065 * return std::make_pair(i, false);
3066 * }
3067 *
3068 * private:
3069 * char c_;
3070 * };
3071 *
3072 * namespace asio {
3073 * template <> struct is_match_condition<match_char>
3074 * : public boost::true_type {};
3075 * } // namespace asio
3076 * ...
3077 * void handler(const boost::system::error_code& e, std::size_t size);
3078 * ...
3079 * std::string data;
3080 * boost::asio::async_read_until(s, data, match_char('a'), handler);
3081 * @endcode
3082 *
3083 * @par Per-Operation Cancellation
3084 * This asynchronous operation supports cancellation for the following
3085 * boost::asio::cancellation_type values:
3086 *
3087 * @li @c cancellation_type::terminal
3088 *
3089 * @li @c cancellation_type::partial
3090 *
3091 * if they are also supported by the @c AsyncReadStream type's
3092 * @c async_read_some operation.
3093 */
3094template <typename AsyncReadStream,
3095 typename DynamicBuffer_v2, typename MatchCondition,
3096 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
3097 std::size_t)) ReadToken = default_completion_token_t<
3098 typename AsyncReadStream::executor_type>>
3099auto async_read_until(AsyncReadStream& s,
3100 DynamicBuffer_v2 buffers, MatchCondition match_condition,
3101 ReadToken&& token = default_completion_token_t<
3102 typename AsyncReadStream::executor_type>(),
3103 constraint_t<
3104 is_match_condition<MatchCondition>::value
3105 > = 0,
3106 constraint_t<
3107 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
3108 > = 0)
3109 -> decltype(
3110 async_initiate<ReadToken,
3111 void (boost::system::error_code, std::size_t)>(
3112 declval<detail::initiate_async_read_until_match_v2<AsyncReadStream>>(),
3113 token, static_cast<DynamicBuffer_v2&&>(buffers), match_condition));
3114
3115#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
3116
3117/*@}*/
3118
3119} // namespace asio
3120} // namespace boost
3121
3122#include <boost/asio/detail/pop_options.hpp>
3123
3124#include <boost/asio/impl/read_until.hpp>
3125
3126#endif // BOOST_ASIO_READ_UNTIL_HPP
3127

source code of boost/libs/asio/include/boost/asio/read_until.hpp