boost::capy::read_until

Asynchronously read until a match condition is satisfied.

Synopsis

Declared in <boost/capy/read_until.hpp>

template<
    ReadStream Stream,
    class B,
    MatchCondition M>
requires DynamicBufferParam<B&&>
auto
read_until(
    Stream& stream,
    B&& buffers,
    M match,
    std::size_t initial_amount = 2048);

Description

Reads data from the stream into the dynamic buffer until the match condition returns a valid position. Implemented using read_some. If the match condition is already satisfied by existing buffer data, returns immediately without I/O.

  • The operation completes when:

  • The match condition returns a valid position

  • End‐of‐stream is reached (`cond::eof`)

  • The buffer's `max_size()` is reached (`cond::not_found`)

  • An error occurs

  • The operation is cancelled

Cancellation

Supports cancellation via stop_token propagated through the IoAwaitable protocol. When cancelled, returns with cond::canceled.

  • `cond::eof` ‐ EOF before match; `n` is buffer size

  • `cond::not_found` ‐ `max_size()` reached before match

  • `cond::canceled` ‐ Operation was cancelled

Example

    task<> read_http_header( ReadStream auto& stream )
    {
        std::string header;
        auto [ec, n] = co_await read_until(
            stream,
            string_dynamic_buffer( &header ),
            []( std::string_view data, std::size_t* hint ) {
                auto pos = data.find( "\r\n\r\n" );
                if( pos != std::string_view::npos )
                    return pos + 4;
                if( hint )
hint = 3;  // partial "\r\n\r" possible
                return std::string_view::npos;
            } );
        if( ec )
            detail::throw_system_error( ec );
        // header contains data through "\r\n\r\n"
    }

Return Value

An awaitable yielding (error_code, std::size_t). On success, n is the position returned by the match condition (bytes up to and including the matched delimiter). Compare error codes to conditions:

Parameters

Name Description

stream

The stream to read from. The caller retains ownership.

buffers

The dynamic buffer to append data to. Must remain valid until the operation completes.

match

The match condition callable. Copied into the awaitable.

initial_amount

Initial bytes to read per iteration (default 2048). Grows by 1.5x when filled.

See Also

read_some, MatchCondition, DynamicBufferParam

Created with MrDocs