io: soften ‘at most one write attempt’ requirement in io::Write::write
At the moment, documentation of std::io::Write::write indicates that
call to it ‘represents at most one attempt to write to any wrapped
object’. It seems that such wording was put there to contrast it with
pre-1.0 interface which attempted to write all the data (it has since
been changed in [RFC 517]).
However, the requirement puts unnecessary constraints and may
complicate adaptors which perform non-trivial transformations on the
data. For example, they may maintain an internal buffer which needs
to be written out before the write method accepts more data. It might
be natural to code the method such that it flushes the buffer and then
grabs another chunk of user data. With the current wording in the
documentation, the adaptor would be forced to return Ok(0).
This commit softens the wording such that implementations can choose
code structure which makes most sense for their particular use case.
While at it, elaborate on the meaning of `Ok(0)` return pointing out
that the write_all methods interprets it as an error.
[RFC 517]: https://rust-lang.github.io/rfcs/0517-io-os-reform.html
876f00a655