diff options
author | akr <akr@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2009-03-17 01:37:57 +0000 |
---|---|---|
committer | akr <akr@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2009-03-17 01:37:57 +0000 |
commit | e3cb6518d1c4fb3fc74737f66785be419f162ea4 (patch) | |
tree | ae124123044ea57d0231c9d9a78ede814fcdd92a /io.c | |
parent | 22cde7b682328ba195ce0ee214edb6c2feb81b23 (diff) |
rdoc update.
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@22985 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'io.c')
-rw-r--r-- | io.c | 46 |
1 files changed, 42 insertions, 4 deletions
@@ -1967,9 +1967,23 @@ rb_io_write_nonblock(VALUE io, VALUE str) * call-seq: * ios.read([length [, buffer]]) => string, buffer, or nil * - * Reads at most <i>length</i> bytes from the I/O stream, or to the - * end of file if <i>length</i> is omitted or is <code>nil</code>. + * Reads <i>length</i> bytes from the I/O stream. + * * <i>length</i> must be a non-negative integer or nil. + * + * If <i>length</i> is a positive integer, + * It reads <i>length</i> bytes and + * returns a string which is <i>length</i> bytes long. + * If EOF is met after 1 or more bytes read but before <i>length</i> bytes read, + * a shorter string is returned. + * If EOF is met at beginning, nil is returned. + * + * If <i>length</i> is omitted or is <code>nil</code>, + * it reads until EOF. + * It returns a string even if EOF is met at beginning. + * + * If <i>length</i> is zero, it returns <code>""</code>. + * * If the optional <i>buffer</i> argument is present, it must reference * a String, which will receive the data. * @@ -1979,10 +1993,34 @@ rb_io_write_nonblock(VALUE io, VALUE str) * <code><i>ios</i>.read(nil)</code> returns <code>""</code>. * <code><i>ios</i>.read(<i>positive-integer</i>)</code> returns nil. * - * <code><i>ios</i>.read(0)</code> returns <code>""</code>. - * * f = File.new("testfile") * f.read(16) #=> "This is line one" + * + * # reads whole file + * open("file") {|f| + * data = f.read # This returns a string even if the file is empty. + * ... + * } + * + * # iterate over fixed length records. + * open("fixed-record-file") {|f| + * while record = f.read(256) + * ... + * end + * } + * + * # iterate over variable length records. + * # record is prefixed by 32-bit length. + * open("variable-record-file") {|f| + * while len = f.read(4) + * len = len.unpack("N")[0] # 32-bit length + * record = f.read(len) # This returns a string even if len is 0. + * end + * } + * + * Note that this method behaves like fread function in C. + * If you need the behavior like read(2) system call, + * consider readpartial, read_nonblock and sysread. */ static VALUE |