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

Subject: Re: [boost] [asio] read_until -- possibly misleading documentation?
From: Bijan (bijan.treister_at_[hidden])
Date: 2010-04-15 11:53:50

Christopher Kohlhoff <chris <at> kohlhoff.com> writes:

> 
> Richard Smith wrote:
> > 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.
> 
> That's a bit on the long side for a brief description, but I've made
> some tweaks along those lines. Hopefully they will make the behaviour
> clearer.
> 
> > 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.
> 
> The behaviour is intended to be as-if getaddrinfo was used, and that
> function supports numbers as strings. So yes, you can rely on this
> behaviour.
> 
> Cheers,
> Chris
> 
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
> 
> 
-----------------------------------------------------------------
-----------------------------------------------------------------

As a side note - it seems the read_until documentation is still confusing.

The sample HTTP client is using read_until incorrectly and (from some actual 
testing) will over-read in certain cases and cause exceptions to be thrown due 
to end-of-file issues.

The sample is here:

http://www.boost.org/doc/libs/1_42_0/doc/html/boost_asio/examples.html#boost_asi
o.examples.http_client

and I think it will likely mislead a lot of people as to the usage. I'd fix it, 
but I ended up not using read_until at all since it really rather confusing.