Bug #925: IO#read documentation versus usage in net/protocol.rb
http://redmine.ruby-lang.org/issues/show/925

Author: Brian Candler
Status: Open, Priority: Low

Note the last sentence here, which says that the read buffer *must* reference a String:

---------------------------------------------------------------- IO#read
     ios.read([length [, buffer]])    => string, buffer, or nil

     From Ruby 1.9.1
------------------------------------------------------------------------
     Reads at most _length_ bytes from the I/O stream, or to the end of
     file if _length_ is omitted or is +nil+. _length_ must be a
     non-negative integer or nil. If the optional _buffer_ argument is
     present, it must reference a String, which will receive the data.

However, Net::HTTP violates this by passing a ReadAdapter object (from net/protocol.rb), which maps a << call to a Proc#call for read_body. This is actually useful duck-typing behaviour of course, so if this is officially supported I suggest that IO#read should document this usage. For example:

"If the optional _buffer_ argument is present, it must be an object which implements the << method (such as a String), which will receive the data in one or more chunks"


----------------------------------------
http://redmine.ruby-lang.org