read_until (13 of 18 overloads)

Read data into a streambuf until some part of the data it contains matches a regular expression.

template<
    typename SyncReadStream,
    typename Allocator>
std::size_t read_until(
    SyncReadStream & s,
    asio::basic_streambuf< Allocator > & b,
    const boost::regex & expr);

This function is used to read data into the specified streambuf until the streambuf's get area contains some data that matches a regular expression. The call will block until one of the following conditions is true:

A substring of the streambuf's get area matches the regular expression.
An error occurred.

This operation is implemented in terms of zero or more calls to the stream's read_some function. If the streambuf's get area already contains data that matches the regular expression, the function returns immediately.

Parameters

s: The stream from which the data is to be read. The type must support the SyncReadStream concept.
b: A streambuf object into which the data will be read.
expr: The regular expression.

Return Value

The number of bytes in the streambuf's get area up to and including the substring that matches the regular expression.

Exceptions

asio::system_error: Thrown on failure.

Remarks

After a successful read_until operation, the streambuf may contain additional data beyond that which matched the regular expression. An application will typically leave that data in the streambuf for a subsequent read_until operation to examine.

Example

To read data into a streambuf until a CR-LF sequence is encountered:

asio::streambuf b;
asio::read_until(s, b, boost::regex("\r\n"));
std::istream is(&b);
std::string line;
std::getline(is, line);

After the read_until operation completes successfully, the buffer b contains the data which matched the regular expression:

{ 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... }

The call to std::getline then extracts the data up to and including the match, so that the string line contains:

{ 'a', 'b', ..., 'c', '\r', '\n' }

The remaining data is left in the buffer b as follows:

{ 'd', 'e', ... }

This data may be the start of a new line, to be extracted by a subsequent read_until operation.