From 51ae7f6e9aa24a136115dae1853779055bbd9eb4 Mon Sep 17 00:00:00 2001 From: marcandre Date: Sun, 7 Mar 2010 10:22:05 +0000 Subject: [PATCH] * io.c: Fix documentation for each/each_line/lines, bytes/each_byte, codepoints/each_code_point [ruby-core:23948] * string.c: ditto * ext/stringio/stringio.c: ditto git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@26844 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 9 ++++ ext/stringio/stringio.c | 20 +++++++ io.c | 116 ++++++++++++++++------------------------ string.c | 75 ++++++++------------------ 4 files changed, 97 insertions(+), 123 deletions(-) diff --git a/ChangeLog b/ChangeLog index fa872f91da..b7472c829d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +Sun Mar 7 19:21:10 2010 Marc-Andre Lafortune + + * io.c: Fix documentation for each/each_line/lines, bytes/each_byte, + codepoints/each_code_point [ruby-core:23948] + + * string.c: ditto + + * ext/stringio/stringio.c: ditto + Sun Mar 7 13:49:49 2010 Tanaka Akira * file.c: add optional basedir argument for realpath/realdirpath. diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c index faf974e78d..bc02d6fece 100644 --- a/ext/stringio/stringio.c +++ b/ext/stringio/stringio.c @@ -615,7 +615,11 @@ strio_get_sync(VALUE self) /* * call-seq: + * strio.bytes {|byte| block } -> strio + * strio.bytes -> anEnumerator + * * strio.each_byte {|byte| block } -> strio + * strio.each_byte -> anEnumerator * * See IO#each_byte. */ @@ -821,7 +825,11 @@ strio_readbyte(VALUE self) /* * call-seq: + * strio.chars {|char| block } -> strio + * strio.chars -> anEnumerator + * * strio.each_char {|char| block } -> strio + * strio.each_char -> anEnumerator * * See IO#each_char. */ @@ -840,7 +848,11 @@ strio_each_char(VALUE self) /* * call-seq: + * strio.codepoints {|c| block } -> strio + * strio.codepoints -> anEnumerator + * * strio.each_codepoint {|c| block } -> strio + * strio.each_codepoint -> anEnumerator * * See IO#each_codepoint. */ @@ -1031,9 +1043,17 @@ strio_readline(int argc, VALUE *argv, VALUE self) * strio.each(sep=$/) {|line| block } -> strio * strio.each(limit) {|line| block } -> strio * strio.each(sep, limit) {|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.lines(sep=$/) {|line| block } -> strio + * strio.lines(limit) {|line| block } -> strio + * strio.lines(sep,limit) {|line| block } -> strio + * strio.lines(...) -> anEnumerator * * See IO#each. */ diff --git a/io.c b/io.c index 7f5fc3548e..b1a89b4502 100644 --- a/io.c +++ b/io.c @@ -2611,35 +2611,29 @@ rb_io_readlines(int argc, VALUE *argv, VALUE io) return ary; } -/* - * call-seq: - * ios.lines(sep=$/) => anEnumerator - * ios.lines(limit) => anEnumerator - * ios.lines(sep, limit) => anEnumerator - * - * Returns an enumerator that gives each line in ios. - * The stream must be opened for reading or an IOError - * will be raised. - * - * f = File.new("testfile") - * f.lines.to_a #=> ["foo\n", "bar\n"] - * f.rewind - * f.lines.sort #=> ["bar\n", "foo\n"] - */ - /* * call-seq: * ios.each(sep=$/) {|line| block } => ios * ios.each(limit) {|line| block } => ios * ios.each(sep,limit) {|line| block } => ios + * ios.each(...) => anEnumerator + * * ios.each_line(sep=$/) {|line| block } => ios * ios.each_line(limit) {|line| block } => ios * ios.each_line(sep,limit) {|line| block } => ios + * ios.each_line(...) => anEnumerator + * + * ios.lines(sep=$/) {|line| block } => ios + * ios.lines(limit) {|line| block } => ios + * ios.lines(sep,limit) {|line| block } => ios + * ios.lines(...) => anEnumerator * * Executes the block for every line in ios, where lines are * separated by sep. ios must be opened for * reading or an IOError will be raised. * + * If no block is given, an enumerator is returned instead. + * * f = File.new("testfile") * f.each {|line| puts "#{f.lineno}: #{line}" } * @@ -2667,26 +2661,18 @@ rb_io_each_line(int argc, VALUE *argv, VALUE io) /* * call-seq: - * ios.bytes => anEnumerator + * ios.bytes {|byte| block } => ios + * ios.bytes => anEnumerator * - * Returns an enumerator that gives each byte (0..255) in ios. - * The stream must be opened for reading or an IOError - * will be raised. - * - * f = File.new("testfile") - * f.bytes.to_a #=> [104, 101, 108, 108, 111] - * f.rewind - * f.bytes.sort #=> [101, 104, 108, 108, 111] - */ - -/* - * call-seq: * ios.each_byte {|byte| block } => ios + * ios.each_byte => anEnumerator * * Calls the given block once for each byte (0..255) in ios, * passing the byte as an argument. The stream must be opened for * reading or an IOError will be raised. * + * If no block is given, an enumerator is returned instead. + * * f = File.new("testfile") * checksum = 0 * f.each_byte {|x| checksum ^= x } #=> # @@ -2813,26 +2799,18 @@ io_getc(rb_io_t *fptr, rb_encoding *enc) /* * call-seq: - * ios.chars => anEnumerator + * ios.chars {|c| block } => ios + * ios.chars => anEnumerator * - * Returns an enumerator that gives each character in ios. - * The stream must be opened for reading or an IOError - * will be raised. - * - * f = File.new("testfile") - * f.chars.to_a #=> ["h", "e", "l", "l", "o"] - * f.rewind - * f.chars.sort #=> ["e", "h", "l", "l", "o"] - */ - -/* - * call-seq: * ios.each_char {|c| block } => ios + * ios.each_char => anEnumerator * * Calls the given block once for each character in ios, * passing the character as an argument. The stream must be opened for * reading or an IOError will be raised. * + * If no block is given, an enumerator is returned instead. + * * f = File.new("testfile") * f.each_char {|c| print c, ' ' } #=> # */ @@ -9116,24 +9094,23 @@ argf_readbyte(VALUE argf) /* * call-seq: - * ARGF.lines(sep=$/) => Enumerator - * ARGF.lines(sep=$/) {|line| } => Enumerator - * ARGF.lines(sep=$/,limit) => Enumerator - * ARGF.lines(sep=$/,limit) {|line| } => Enumerator + * ARGF.each(sep=$/) {|line| block } => ARGF + * ARGF.each(sep=$/,limit) {|line| block } => ARGF + * ARGF.each(...) => anEnumerator * - * ARGF.each_line(sep=$/) => Enumerator - * ARGF.each_line(sep=$/) {|line| } => Enumerator - * ARGF.each_line(sep=$/,limit) => Enumerator - * ARGF.each_line(sep=$/,limit) {|line| } => Enumerator - * ARGF.each(sep=$/) => Enumerator - * ARGF.each(sep=$/) {|line| } => Enumerator - * ARGF.each(sep=$/,limit) => Enumerator - * ARGF.each(sep=$/,limit) {|line| } => Enumerator + * ARGF.each_line(sep=$/) {|line| block } => ARGF + * ARGF.each_line(sep=$/,limit) {|line| block } => ARGF + * ARGF.each_line(...) => anEnumerator + * + * ARGF.lines(sep=$/) {|line| block } => ARGF + * ARGF.lines(sep=$/,limit) {|line| block } => ARGF + * ARGF.lines(...) => anEnumerator * * Returns an enumerator which iterates over each line (separated by _sep_, * which defaults to your platform's newline character) of each file in * +ARGV+. If a block is supplied, each line in turn will be yielded to the - * block. The optional _limit_ argument is a +Fixnum+ specifying the maximum + * block, otherwise an enumerator is returned. + * The optional _limit_ argument is a +Fixnum+ specifying the maximum * length of each line; longer lines will be split according to this limit. * * This method allows you to treat the files supplied on the command line as @@ -9164,15 +9141,14 @@ argf_each_line(int argc, VALUE *argv, VALUE argf) /* * call-seq: - * ARGF.bytes => Enumerator - * ARGF.bytes {|byte| } => Enumerator + * ARGF.bytes {|byte| block } => ARGF + * ARGF.bytes => anEnumerator * - * ARGF.each_byte => Enumerator - * ARGF.each_byte {|byte| } => Enumerator + * ARGF.each_byte {|byte| block } => ARGF + * ARGF.each_byte => anEnumerator * - * Returns an enumerator which iterates over each byte of each file in - * +ARGV+. If a block is supplied, each byte in turn will be yielded to the - * block. A byte is returned as a +Fixnum+ in the range 0..255. + * Iterates over each byte of each file in +ARGV+. + * A byte is returned as a +Fixnum+ in the range 0..255. * * This method allows you to treat the files supplied on the command line as * a single file consisting of the concatenation of each named file. After @@ -9180,6 +9156,8 @@ argf_each_line(int argc, VALUE *argv, VALUE argf) * second file is returned. The +ARGF.filename+ method can be used to * determine the filename of the current byte. * + * If no block is given, an enumerator is returned instead. + * * For example: * * ARGF.bytes.to_a #=> [35, 32, ... 95, 10] @@ -9198,15 +9176,13 @@ argf_each_byte(VALUE argf) /* * call-seq: - * ARGF.chars => Enumerator - * ARGF.chars {|char| } => Enumerator + * ARGF.chars {|char| block } => ARGF + * ARGF.chars => anEnumerator * - * ARGF.each_char => Enumerator - * ARGF.each_char {|char| } => Enumerator + * ARGF.each_char {|char| block } => ARGF + * ARGF.each_char => anEnumerator * - * Returns an enumerator which iterates over each character of each file in - * +ARGV+. If a block is supplied, each character in turn will be yielded to - * the block. + * Iterates over each character of each file in +ARGF+. * * This method allows you to treat the files supplied on the command line as * a single file consisting of the concatenation of each named file. After @@ -9214,6 +9190,8 @@ argf_each_byte(VALUE argf) * character of the second file is returned. The +ARGF.filename+ method can * be used to determine the name of the file in which the current character * appears. + * + * If no block is given, an enumerator is returned instead. */ static VALUE argf_each_char(VALUE argf) diff --git a/string.c b/string.c index f8a858a179..435a06d76b 100644 --- a/string.c +++ b/string.c @@ -5651,28 +5651,20 @@ rb_str_split(VALUE str, const char *sep0) /* - * Document-method: lines - * call-seq: - * str.lines(separator=$/) => anEnumerator - * str.lines(separator=$/) {|substr| block } => str - * - * Returns an enumerator that gives each line in the string. If a block is - * given, it iterates over each line in the string. - * - * "foo\nbar\n".lines.to_a #=> ["foo\n", "bar\n"] - * "foo\nb ar".lines.sort #=> ["b ar", "foo\n"] - */ - -/* - * Document-method: each_line * call-seq: * str.each_line(separator=$/) {|substr| block } => str + * str.each_line(separator=$/) => anEnumerator + * + * str.lines(separator=$/) {|substr| block } => str + * str.lines(separator=$/) => anEnumerator * * Splits str using the supplied parameter as the record separator * ($/ by default), passing each substring in turn to the supplied * block. If a zero-length record separator is supplied, the string is split * into paragraphs delimited by multiple successive newlines. * + * If no block is given, an enumerator is returned instead. + * * print "Example one\n" * "hello\nworld".each_line {|s| p s} * print "Example two\n" @@ -5794,23 +5786,15 @@ rb_str_each_line(int argc, VALUE *argv, VALUE str) /* - * Document-method: bytes * call-seq: - * str.bytes => anEnumerator - * str.bytes {|fixnum| block } => str + * str.bytes {|fixnum| block } => str + * str.bytes => anEnumerator * - * Returns an enumerator that gives each byte in the string. If a block is - * given, it iterates over each byte in the string. - * - * "hello".bytes.to_a #=> [104, 101, 108, 108, 111] - */ - -/* - * Document-method: each_byte - * call-seq: * str.each_byte {|fixnum| block } => str + * str.each_byte => anEnumerator * - * Passes each byte in str to the given block. + * Passes each byte in str to the given block, or returns + * an enumerator if no block is given. * * "hello".each_byte {|c| print c, ' ' } * @@ -5833,23 +5817,15 @@ rb_str_each_byte(VALUE str) /* - * Document-method: chars * call-seq: - * str.chars => anEnumerator - * str.chars {|substr| block } => str + * str.chars {|cstr| block } => str + * str.chars => anEnumerator * - * Returns an enumerator that gives each character in the string. - * If a block is given, it iterates over each character in the string. - * - * "foo".chars.to_a #=> ["f","o","o"] - */ - -/* - * Document-method: each_char - * call-seq: * str.each_char {|cstr| block } => str + * str.each_char => anEnumerator * - * Passes each character in str to the given block. + * Passes each character in str to the given block, or returns + * an enumerator if no block is given. * * "hello".each_char {|c| print c, ' ' } * @@ -5889,28 +5865,19 @@ rb_str_each_char(VALUE str) } /* - * Document-method: codepoints * call-seq: - * str.codepoints => anEnumerator - * str.codepoints {|fixnum| block } => str + * str.codepoints {|integer| block } => str + * str.codepoints => anEnumerator * - * Returns an enumerator that gives the Integer ordinal - * of each character in the string, also known as a codepoint - * when applied to Unicode strings. If a block is given, it iterates - * over each character in the string. - * - * "foo\u0635".codepoints.to_a #=> [102, 111, 111, 1589] - */ - -/* - * Document-method: each_codepoint - * call-seq: * str.each_codepoint {|integer| block } => str + * str.each_codepoint => anEnumerator * * Passes the Integer ordinal of each character in str, * also known as a codepoint when applied to Unicode strings to the * given block. * + * If no block is given, an enumerator is returned instead. + * * "hello\u0639".each_codepoint {|c| print c, ' ' } * * produces: