Issue #6285 has been updated by drbrain (Eric Hodel).

Category set to DOC
Status changed from Open to Assigned
Assignee set to drbrain (Eric Hodel)


----------------------------------------
Bug #6285: Documents of IO#read, IO#readpartial, etc. should describe how they are executed when second argument is not empty String
https://bugs.ruby-lang.org/issues/6285#change-25864

Author: nobuoka (yu nobuoka)
Status: Assigned
Priority: Normal
Assignee: drbrain (Eric Hodel)
Category: DOC
Target version: 
ruby -v: ruby 2.0.0dev (2012-04-12 trunk 35312) [x86_64-linux]


IO#read, IO#readpartial, IO#read_nonblock, and IO#sysread methods can receive a String object as second argument ((|outbuf|)).  If it is present, it will receive the data.  This is documented.

So, when I pass the empty String object to the method, it is expected that the object contains the data after the method is executed. 

 r,w = IO.pipe
 w << 'abcd'
 w.close
 r.read( 4, buf = '' )
 buf #=> 'abcd'

However, when I pass the not empty String object to the method as second argument, what happen? 

 r,w = IO.pipe
 w << 'abcd'
 w.close
 r.read( 4, buf = '012345' )
 buf #=> 'abcd'? or 'abcd45'? or '012345abcd'?

In current implementation, the ((|outbuf|)) contain only the received data after the method is executed even though it is not empty at the beginning.  I think it should be documented. 

The same applies to ARGF.read, ARGF.readpartial, StringIO#read, StringIO#readpartial, StringIO#sysread, StringIO#read_nonblock methods.

I wrote documents and tests.  Please see attached file.


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