Bug #6285

Documents of IO#read, IO#readpartial, etc. should describe how they are executed when second argument is not empty String

Added by yu nobuoka about 2 years ago. Updated about 2 years ago.

[ruby-core:44314]
Status:Closed
Priority:Normal
Assignee:Eric Hodel
Category:doc
Target version:-
ruby -v:ruby 2.0.0dev (2012-04-12 trunk 35312) [x86_64-linux] Backport:

Description

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.

__diff__.txt Magnifier (8.03 KB) yu nobuoka, 04/13/2012 02:47 AM

Associated revisions

Revision 35391
Added by Eric Hodel about 2 years ago

  • io.c (io_readpartial): Document the output buffer parameter is overwritten with the read contents even when non-empty. Patch by yu nobuoka. [ruby-trunk - Bug #6285]
  • io.c (ioreadnonblock): ditto.
  • io.c (io_read): ditto.
  • io.c (rbiosysread): ditto.
  • io.c (argf_read): ditto.
  • io.c (argf_readpartial): ditto.
  • ext/stringio/stringio.c (strio_read): ditto.
  • test/ruby/test_argf.rb (class TestArgf): Add test for existing behavior of read outbuf.
  • test/ruby/test_io.rb (class TestIO): ditto.
  • test/stringio/test_stringio.rb (class TestStringIO): ditto.

History

#1 Updated by Eric Hodel about 2 years ago

  • Category set to doc
  • Status changed from Open to Assigned
  • Assignee set to Eric Hodel

#2 Updated by Eric Hodel about 2 years ago

  • Status changed from Assigned to Closed
  • % Done changed from 0 to 100

This issue was solved with changeset r35391.
yu, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.


  • io.c (io_readpartial): Document the output buffer parameter is overwritten with the read contents even when non-empty. Patch by yu nobuoka. [ruby-trunk - Bug #6285]
  • io.c (ioreadnonblock): ditto.
  • io.c (io_read): ditto.
  • io.c (rbiosysread): ditto.
  • io.c (argf_read): ditto.
  • io.c (argf_readpartial): ditto.
  • ext/stringio/stringio.c (strio_read): ditto.
  • test/ruby/test_argf.rb (class TestArgf): Add test for existing behavior of read outbuf.
  • test/ruby/test_io.rb (class TestIO): ditto.
  • test/stringio/test_stringio.rb (class TestStringIO): ditto.

Also available in: Atom PDF