[boost] [asio] read_until -- possibly misleading documentation?

From: Richard Smith (richard_at_[hidden])
Date: 2008-06-12 13:00:24

The documentation for Boost.ASIO (which is otherwise very
comprehensive) says of the boost::asio::read_until set of
overloads:

| Read data into a streambuf until a delimiter is
| encountered.

<http://www.boost.org/doc/libs/1_35_0/doc/html/boost_asio/reference/read_until.html>

What the function actually does is to read blocks of data
into the streambuf, and stop when the delimiter is found.
This means that frequently data beyond the delimiter will be
read into the streambuf.  (And this is elaborated in more
detail on the individual function's pages, if a reader looks
there.)

I appreciate that this behaviour is compatible with the
documentation, but someone less familiar with ASIO could
easily assume that the function will read as far as the
delimiter and no further.  (And I have just spent a fair
amount of time debugging a piece of code where the author
had made this assumption.)

Could we change the summary documentation to read something
like:

| Read data into a streambuf at least until a delimiter is
| encountered.  The implementation may read beyond the
| delimiter, but will not block when doing so.

While I'm on the subject of ASIO documentation, I can't see
any documentation on whether the service_name parameters to
the basic_resolver_query constructors are allowed to be port
numbers (e.g. "80") or whether they have to be symbolic
names (e.g. "http").  Port numbers work, at least on Linux,
but it's not clear whether this is something that I should
be relying on.  Similarly for IPv4 and IPv6 addresses in the
host_name parameter.

Richard Smith