17 Buffer-oriented streams [buffer.stream]

17.10 Asynchronous delimited read operations [buffer.async.read.until]

template<class AsyncReadStream, class DynamicBuffer, class CompletionToken> DEDUCED async_read_until(AsyncReadStream& s, DynamicBuffer&& b, char delim, CompletionToken&& token); template<class AsyncReadStream, class DynamicBuffer, class CompletionToken> DEDUCED async_read_until(AsyncReadStream& s, DynamicBuffer&& b, string_view delim, CompletionToken&& token);

A composed asynchronous operation ([async.reqmts.async.composed]).

Completion signature: void(error_code ec, size_t n).

Effects: Initiates an asynchronous operation to read data from the buffer-oriented asynchronous read stream ([buffer.stream.reqmts.asyncreadstream]) object stream by performing zero or more asynchronous read_some operations on the stream, until the readable bytes of the dynamic buffer ([buffer.reqmts.dynamicbuffer]) object b contain the specified delimiter delim.

Data is placed into the dynamic buffer object b. A mutable buffer sequence ([buffer.reqmts.mutablebuffersequence]) is obtained prior to each async_read_some call using b.prepare(N), where N is an unspecified value such that N <= max_size() - size(). [ Note: Implementations can use b.capacity() when determining N, to minimize the number of asynchronous read_some operations performed on the stream.  — end note ] After the completion of each asynchronous read_some operation, the implementation performs b.commit(n), where n is the value passed to the asynchronous read_some operation's completion handler.

The asynchronous read_until operation continues until:

  • the readable bytes of b contain the delimiter delim; or

  • b.size() == b.max_size(); or

  • an asynchronous read_some operation fails.

The program shall ensure the AsyncReadStream object stream is valid until the completion handler for the asynchronous operation is invoked.

If delim is of type string_view, the implementation copies the underlying sequence of characters prior to initiating an asynchronous read_some operation on the stream. [ Note: This means that the caller is not required to guarantee the validity of the delimiter string after the call to async_read_until returns.  — end note ]

On completion of the asynchronous operation, if the readable bytes of b contain the delimiter, ec is set such that !ec is true. Otherwise, if b.size() == b.max_size(), ec is set such that ec == stream_errc::not_found. If b.size() < b.max_size(), ec is the error_code from the most recent asynchronous read_some operation. n is the number of readable bytes in b up to and including the delimiter, if present, otherwise 0.