From 2746fd5d50429994b0d66bb49c2e09089beb1b3f Mon Sep 17 00:00:00 2001 From: zverok Date: Sat, 26 Oct 2019 10:03:24 +0300 Subject: Update StringIO docs: * More explanations/examples in class docs; * Fix links to other methods (remove tag); * Fix wording of method docs (remove *stringio* receiver name, as it is not rendered by modern RDoc); * Add option mention to linereading methods (added in 2.4); * Several other small fixes. --- ext/stringio/stringio.c | 97 ++++++++++++++++++++++++++++--------------------- 1 file changed, 56 insertions(+), 41 deletions(-) diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c index 15e5cdd017..d6db112069 100644 --- a/ext/stringio/stringio.c +++ b/ext/stringio/stringio.c @@ -429,7 +429,7 @@ strio_nil(VALUE self) } /* - * Returns *strio* itself. Just for compatibility to IO. + * Returns an object itself. Just for compatibility to IO. */ static VALUE strio_self(VALUE self) @@ -505,7 +505,7 @@ strio_set_string(VALUE self, VALUE string) * call-seq: * strio.close -> nil * - * Closes strio. The *strio* is unavailable for any further data + * Closes a StringIO. The stream is unavailable for any further data * operations; an +IOError+ is raised if such an attempt is made. */ static VALUE @@ -521,7 +521,7 @@ strio_close(VALUE self) * strio.close_read -> nil * * Closes the read end of a StringIO. Will raise an +IOError+ if the - * *strio* is not readable. + * receiver is not readable. */ static VALUE strio_close_read(VALUE self) @@ -539,7 +539,7 @@ strio_close_read(VALUE self) * strio.close_write -> nil * * Closes the write end of a StringIO. Will raise an +IOError+ if the - * *strio* is not writeable. + * receiver is not writeable. */ static VALUE strio_close_write(VALUE self) @@ -556,7 +556,7 @@ strio_close_write(VALUE self) * call-seq: * strio.closed? -> true or false * - * Returns +true+ if *strio* is completely closed, +false+ otherwise. + * Returns +true+ if the stream is completely closed, +false+ otherwise. */ static VALUE strio_closed(VALUE self) @@ -570,7 +570,7 @@ strio_closed(VALUE self) * call-seq: * strio.closed_read? -> true or false * - * Returns +true+ if *strio* is not readable, +false+ otherwise. + * Returns +true+ if the stream is not readable, +false+ otherwise. */ static VALUE strio_closed_read(VALUE self) @@ -584,7 +584,7 @@ strio_closed_read(VALUE self) * call-seq: * strio.closed_write? -> true or false * - * Returns +true+ if *strio* is not writable, +false+ otherwise. + * Returns +true+ if the stream is not writable, +false+ otherwise. */ static VALUE strio_closed_write(VALUE self) @@ -599,8 +599,8 @@ strio_closed_write(VALUE self) * strio.eof -> true or false * strio.eof? -> true or false * - * Returns true if *strio* is at end of file. The stringio must be - * opened for reading or an +IOError+ will be raised. + * Returns true if the stream is at the end of the data (underlying string). + * The stream must be opened for reading or an +IOError+ will be raised. */ static VALUE strio_eof(VALUE self) @@ -634,7 +634,7 @@ strio_copy(VALUE copy, VALUE orig) * call-seq: * strio.lineno -> integer * - * Returns the current line number in *strio*. The stringio must be + * Returns the current line number. The stream must be * opened for reading. +lineno+ counts the number of times +gets+ is * called, rather than the number of newlines encountered. The two * values will differ if +gets+ is called with a separator other than @@ -660,6 +660,13 @@ strio_set_lineno(VALUE self, VALUE lineno) return lineno; } +/* + * call-seq: + * strio.binmode -> stringio + * + * Puts stream into binary mode. See IO#binmode. + * + */ static VALUE strio_binmode(VALUE self) { @@ -684,7 +691,7 @@ strio_binmode(VALUE self) * strio.reopen(other_StrIO) -> strio * strio.reopen(string, mode) -> strio * - * Reinitializes *strio* with the given other_StrIO or _string_ + * Reinitializes the stream with the given other_StrIO or _string_ * and _mode_ (see StringIO#new). */ static VALUE @@ -702,7 +709,7 @@ strio_reopen(int argc, VALUE *argv, VALUE self) * strio.pos -> integer * strio.tell -> integer * - * Returns the current offset (in bytes) of *strio*. + * Returns the current offset (in bytes). */ static VALUE strio_get_pos(VALUE self) @@ -714,7 +721,7 @@ strio_get_pos(VALUE self) * call-seq: * strio.pos = integer -> integer * - * Seeks to the given position (in bytes) in *strio*. + * Seeks to the given position (in bytes). */ static VALUE strio_set_pos(VALUE self, VALUE pos) @@ -732,7 +739,7 @@ strio_set_pos(VALUE self, VALUE pos) * call-seq: * strio.rewind -> 0 * - * Positions *strio* to the beginning of input, resetting + * Positions the stream to the beginning of input, resetting * +lineno+ to zero. */ static VALUE @@ -900,7 +907,7 @@ strio_extend(struct StringIO *ptr, long pos, long len) * call-seq: * strio.ungetc(string) -> nil * - * Pushes back one character (passed as a parameter) onto *strio* + * Pushes back one character (passed as a parameter) * such that a subsequent buffered read will return it. There is no * limitation for multiple pushbacks including pushing back behind the * beginning of the buffer string. @@ -1047,7 +1054,7 @@ strio_each_char(VALUE self) } /* - * This is a deprecated alias for each_char. + * This is a deprecated alias for #each_char. */ static VALUE strio_chars(VALUE self) @@ -1091,7 +1098,7 @@ strio_each_codepoint(VALUE self) } /* - * This is a deprecated alias for each_codepoint. + * This is a deprecated alias for #each_codepoint. */ static VALUE strio_codepoints(VALUE self) @@ -1281,9 +1288,9 @@ strio_getline(struct getline_arg *arg, struct StringIO *ptr) /* * call-seq: - * strio.gets(sep=$/) -> string or nil - * strio.gets(limit) -> string or nil - * strio.gets(sep, limit) -> string or nil + * strio.gets(sep=$/, chomp: false) -> string or nil + * strio.gets(limit, chomp: false) -> string or nil + * strio.gets(sep, limit, chomp: false) -> string or nil * * See IO#gets. */ @@ -1305,9 +1312,9 @@ strio_gets(int argc, VALUE *argv, VALUE self) /* * call-seq: - * strio.readline(sep=$/) -> string - * strio.readline(limit) -> string or nil - * strio.readline(sep, limit) -> string or nil + * strio.readline(sep=$/, chomp: false) -> string + * strio.readline(limit, chomp: false) -> string or nil + * strio.readline(sep, limit, chomp: false) -> string or nil * * See IO#readline. */ @@ -1321,15 +1328,15 @@ strio_readline(int argc, VALUE *argv, VALUE self) /* * call-seq: - * strio.each(sep=$/) {|line| block } -> strio - * strio.each(limit) {|line| block } -> strio - * strio.each(sep, limit) {|line| block } -> strio - * strio.each(...) -> anEnumerator + * strio.each(sep=$/, chomp: false) {|line| block } -> strio + * strio.each(limit, chomp: false) {|line| block } -> strio + * strio.each(sep, limit, chomp: false) {|line| block } -> strio + * strio.each(...) -> anEnumerator * - * strio.each_line(sep=$/) {|line| block } -> strio - * strio.each_line(limit) {|line| block } -> strio - * strio.each_line(sep,limit) {|line| block } -> strio - * strio.each_line(...) -> anEnumerator + * strio.each_line(sep=$/, chomp: false) {|line| block } -> strio + * strio.each_line(limit, chomp: false) {|line| block } -> strio + * strio.each_line(sep, limit, chomp: false) {|line| block } -> strio + * strio.each_line(...) -> anEnumerator * * See IO#each. */ @@ -1353,7 +1360,7 @@ strio_each(int argc, VALUE *argv, VALUE self) } /* - * This is a deprecated alias for each_line. + * This is a deprecated alias for #each_line. */ static VALUE strio_lines(int argc, VALUE *argv, VALUE self) @@ -1366,9 +1373,9 @@ strio_lines(int argc, VALUE *argv, VALUE self) /* * call-seq: - * strio.readlines(sep=$/) -> array - * strio.readlines(limit) -> array - * strio.readlines(sep,limit) -> array + * strio.readlines(sep=$/, chomp: false) -> array + * strio.readlines(limit, chomp: false) -> array + * strio.readlines(sep, limit, chomp: false) -> array * * See IO#readlines. */ @@ -1395,7 +1402,7 @@ strio_readlines(int argc, VALUE *argv, VALUE self) * strio.write(string, ...) -> integer * strio.syswrite(string) -> integer * - * Appends the given string to the underlying buffer string of *strio*. + * Appends the given string to the underlying buffer string. * The stream must be opened for writing. If the argument is not a * string, it will be converted to a string using to_s. * Returns the number of bytes written. See IO#write. @@ -1669,7 +1676,7 @@ strio_size(VALUE self) * call-seq: * strio.truncate(integer) -> 0 * - * Truncates the buffer string to at most _integer_ bytes. The *strio* + * Truncates the buffer string to at most _integer_ bytes. The stream * must be opened for writing. */ static VALUE @@ -1693,7 +1700,8 @@ strio_truncate(VALUE self, VALUE len) * strio.external_encoding => encoding * * Returns the Encoding object that represents the encoding of the file. - * If strio is write mode and no encoding is specified, returns nil. + * If the stream is write mode and no encoding is specified, returns + * +nil+. */ static VALUE @@ -1708,7 +1716,7 @@ strio_external_encoding(VALUE self) * strio.internal_encoding => encoding * * Returns the Encoding of the internal string if conversion is - * specified. Otherwise returns nil. + * specified. Otherwise returns +nil+. */ static VALUE @@ -1763,17 +1771,24 @@ strio_set_encoding_by_bom(VALUE self) } /* - * Pseudo I/O on String object. + * Pseudo I/O on String object, with interface corresponding to IO. * - * Commonly used to simulate `$stdio` or `$stderr` + * Commonly used to simulate $stdio or $stderr * * === Examples * * require 'stringio' * + * # Writing stream emulation * io = StringIO.new * io.puts "Hello World" * io.string #=> "Hello World\n" + * + * # Reading stream emulation + * io = StringIO.new "first\nsecond\nlast\n" + * io.getc #=> "f" + * io.gets #=> "irst\n" + * io.read #=> "second\nlast\n" */ void Init_stringio(void) -- cgit v1.2.3