ruby-changes:70334
From: Burdette <ko1@a...>
Date: Mon, 20 Dec 2021 13:05:00 +0900 (JST)
Subject: [ruby-changes:70334] 3bb6e4f641 (master): [DOC] Enhanced RDoc for IO (#5304)
https://git.ruby-lang.org/ruby.git/commit/?id=3bb6e4f641 From 3bb6e4f641223c8573d2735e179f6822bc79cc33 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Sun, 19 Dec 2021 22:04:47 -0600 Subject: [DOC] Enhanced RDoc for IO (#5304) Treated: ::try_convert #write #<< #flush #tell #seek #pos= #rewind #eof --- io.c | 230 ++++++++++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 136 insertions(+), 94 deletions(-) diff --git a/io.c b/io.c index b91a324d2fe..4b963ce494e 100644 --- a/io.c +++ b/io.c @@ -838,19 +838,14 @@ rb_io_set_write_io(VALUE io, VALUE w) https://github.com/ruby/ruby/blob/trunk/io.c#L838 /* * call-seq: - * IO.try_convert(obj) -> io or nil + * IO.try_convert(object) -> new_io or nil * - * Try to convert <i>obj</i> into an IO, using to_io method. - * Returns converted IO or +nil+ if <i>obj</i> cannot be converted - * for any reason. + * Attempts to convert +object+ into an \IO object via method +to_io+; + * returns the new \IO object if successful, or +nil+ otherwise: * - * IO.try_convert(STDOUT) #=> STDOUT - * IO.try_convert("STDOUT") #=> nil - * - * require 'zlib' - * f = open("/tmp/zz.gz") #=> #<File:/tmp/zz.gz> - * z = Zlib::GzipReader.open(f) #=> #<Zlib::GzipReader:0x81d8744> - * IO.try_convert(z) #=> #<File:/tmp/zz.gz> + * IO.try_convert(STDOUT) # => #<IO:<STDOUT>> + * IO.try_convert(ARGF) # => #<IO:<STDIN>> + * IO.try_convert('STDOUT') # => nil * */ static VALUE @@ -2025,20 +2020,21 @@ io_writev(int argc, const VALUE *argv, VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L2020 /* * call-seq: - * ios.write(string, ...) -> integer + * write(*objects) -> integer * - * Writes the given strings to <em>ios</em>. The stream must be opened - * for writing. Arguments that are not a string will be converted - * to a string using <code>to_s</code>. Returns the number of bytes - * written in total. + * Writes each of the given +objects+ to +self+, + * which must be opened for writing (see {Modes}[#class-IO-label-Modes]); + * returns the total number bytes written; + * each of +objects+ that is not a string is converted via method +to_s+: * - * count = $stdout.write("This is", " a test\n") - * puts "That was #{count} bytes of data" + * $stdout.write('Hello', ', ', 'World!', "\n") # => 14 + * $stdout.write('foo', :bar, 2, "\n") # => 8 * - * <em>produces:</em> + * Output: + * + * Hello, World! + * foobar2 * - * This is a test - * That was 15 bytes of data */ static VALUE @@ -2078,17 +2074,21 @@ rb_io_writev(VALUE io, int argc, const VALUE *argv) https://github.com/ruby/ruby/blob/trunk/io.c#L2074 /* * call-seq: - * ios << obj -> ios + * self << object -> self * - * String Output---Writes <i>obj</i> to <em>ios</em>. - * <i>obj</i> will be converted to a string using - * <code>to_s</code>. + * Writes the given +object+ to +self+, + * which must be opened for writing (see {Modes}[#class-IO-label-Modes]); + * returns +self+; + * if +object+ is not a string, it is converted via method +to_s+: * - * $stdout << "Hello " << "world!\n" + * $stdout << 'Hello' << ', ' << 'World!' << "\n" + * $stdout << 'foo' << :bar << 2 << "\n" * - * <em>produces:</em> + * Output: + * + * Hello, World! + * foobar2 * - * Hello world! */ @@ -2138,18 +2138,14 @@ rb_io_flush_raw(VALUE io, int sync) https://github.com/ruby/ruby/blob/trunk/io.c#L2138 /* * call-seq: - * ios.flush -> ios - * - * Flushes any buffered data within <em>ios</em> to the underlying - * operating system (note that this is Ruby internal buffering only; - * the OS may buffer the data as well). + * flush -> self * - * $stdout.print "no newline" - * $stdout.flush + * Flushes data buffered in +self+ to the operating system + * (but does not necessarily flush data buffered in the operating system): * - * <em>produces:</em> + * $stdout.print 'no newline' # Not necessarily flushed. + * $stdout.flush # Flushed. * - * no newline */ VALUE @@ -2160,15 +2156,20 @@ rb_io_flush(VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L2156 /* * call-seq: - * ios.pos -> integer - * ios.tell -> integer + * tell -> integer * - * Returns the current offset (in bytes) of <em>ios</em>. + * Returns the current position (in bytes) in +self+ + * (see {Position}[#class-IO-label-Position]): + * + * f = File.new('t.txt') + * f.tell # => 0 + * f.readline # => "This is line one.\n" + * f.tell # => 19 + * + * Related: IO#pos=, IO#seek. + * + * IO#pos is an alias for IO#tell. * - * f = File.new("testfile") - * f.pos #=> 0 - * f.gets #=> "This is line one\n" - * f.pos #=> 17 */ static VALUE @@ -2220,23 +2221,46 @@ interpret_seek_whence(VALUE vwhence) https://github.com/ruby/ruby/blob/trunk/io.c#L2221 /* * call-seq: - * ios.seek(amount, whence=IO::SEEK_SET) -> 0 + * seek(offset, whence = IO::SEEK_SET) -> 0 * - * Seeks to a given offset <i>anInteger</i> in the stream according to - * the value of <i>whence</i>: + * Seeks to the position given by integer +offset+ + * (see {Position}[#class-IO-label-Position]) + * and constant +whence+, which is one of: * - * :CUR or IO::SEEK_CUR | Seeks to _amount_ plus current position - * ----------------------+-------------------------------------------------- - * :END or IO::SEEK_END | Seeks to _amount_ plus end of stream (you - * | probably want a negative value for _amount_) - * ----------------------+-------------------------------------------------- - * :SET or IO::SEEK_SET | Seeks to the absolute location given by _amount_ + * - +:CUR+ or <tt>IO::SEEK_CUR</tt>: + * Repositions the stream to its current position plus the given +offset+: * - * Example: + * f = File.open('t.txt') + * f.tell # => 0 + * f.seek(20, :CUR) # => 0 + * f.tell # => 20 + * f.seek(-10, :CUR) # => 0 + * f.tell # => 10 + * + * - +:END+ or <tt>IO::SEEK_END</tt>: + * Repositions the stream to its end plus the given +offset+: + * + * f = File.open('t.txt') + * f.tell # => 0 + * f.seek(0, :END) # => 0 # Repositions to stream end. + * f.tell # => 70 + * f.seek(-20, :END) # => 0 + * f.tell # => 50 + * f.seek(-40, :END) # => 0 + * f.tell # => 30 + * + * - +:SET+ or <tt>IO:SEEK_SET</tt>: + * Repositions the stream to the given +offset+: + * + * f = File.open('t.txt') + * f.tell # => 0 + * f.seek(20, :SET) # => 0 + * f.tell # => 20 + * f.seek(40, :SET) # => 0 + * f.tell # => 40 + * + * Related: IO#pos=, IO#tell. * - * f = File.new("testfile") - * f.seek(-13, IO::SEEK_END) #=> 0 - * f.readline #=> "And so on...\n" */ static VALUE @@ -2254,15 +2278,18 @@ rb_io_seek_m(int argc, VALUE *argv, VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L2278 /* * call-seq: - * ios.pos = integer -> integer + * pos = new_position -> new_position * - * Seeks to the given position (in bytes) in <em>ios</em>. - * It is not guaranteed that seeking to the right position when <em>ios</em> - * is textmode. + * Seeks to the given +new_position+ (in bytes); + * see {Position}[#class-IO-label-Position]: + * + * f = File.open('t.txt') + * f.tell # => 0 + * f.pos = 20 # => 20 + * f.tell # => 20 + * + * Related: IO#seek, IO#tell. * - * f = File.new("testfile") - * f.pos = 17 - * f.gets #=> "This is line two\n" */ static VALUE @@ -2283,18 +2310,25 @@ static void clear_readconv(rb_io_t *fptr); https://github.com/ruby/ruby/blob/trunk/io.c#L2310 /* * call-seq: - * ios.rewind -> 0 + * rewind -> 0 * - * Positions <em>ios</em> to the beginning of input, resetting - * #lineno to zero. + * Repositions the stream to its beginning, + * setting both the position and the line number to zero; + * see {Position}[#class-IO-label-Position] + * and {Line Number}[#class-IO-label-Line+Number]: * - * f = File.new("testfile") - * f.readline #=> "This is line one\n" - * f.rewind #=> 0 - * f.lineno #=> 0 - * f.readline #=> "This is line one\n" + * f = File.open('t.txt') + * f.tell # => 0 + * f.lineno # => 0 + * f.readline # => "This is line one.\n" + * f.tell # => 19 + * f.lineno # => 1 + * f.rewind # => 0 + * f.tell # => 0 + * f.lineno # => 0 + * + * Note that this method cannot be used with streams such as pipes, ttys, and sockets. * - * Note that it cannot be used with streams such as pipes, ttys, and sockets. */ static VALUE @@ -2367,35 +2401,39 @@ io_fillbuf(rb_io_t *fptr) https://github.com/ruby/ruby/blob/trunk/io.c#L2401 /* * call-seq: - * ios.eof -> true or false - * ios.eof? -> true or false + * eof -> true or false * - * Returns true if <em>ios</em> is at end of file that means - * there are no more data to read. - * The stream must be opened for reading or an IOError will be - * raised. + * Returns +true+ if the stream is positioned at its end, +false+ otherwise; + * see {Position}[#class-IO-label-Position]: * - * f = File.new("testfile") - * dummy = f.readlines - * f.eof #=> true + * f = File.open('t.txt') + * f.eof # => false + * f.seek(0, :END) # => 0 + * f.eof # => true + * + * Raises an exception unless the stream is opened for reading; + * see {Mode}[#class-IO-label-Mode]. * - * If <em>ios</em> is a stream such as pipe or socket, IO#eof? - * blocks until the other end sends some data or closes it. + * If +self+ is a stream such as pipe or so (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/