| Home | Libraries | People | FAQ | More

#### read_until (5 of 8 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,
        boost::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

boost::system::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:

    boost::asio::streambuf b;
    boost::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.