diff --git a/doc/string.rdoc b/doc/string.rdoc index 6c3ced298a..a4423c9d9b 100644 --- a/doc/string.rdoc +++ b/doc/string.rdoc @@ -49,24 +49,127 @@ class String end # call-seq: - # split(separator = $;, limit = nil) -> array - # split(separator = $;, limit = nil) {|substring| ... } -> self + # bytes -> array_of_bytes + # + # Returns an array of the bytes in +self+: + # + # 'hello'.bytes # => [104, 101, 108, 108, 111] + # 'тест'.bytes # => [209, 130, 208, 181, 209, 129, 209, 130] + # 'こんにちは'.bytes + # # => [227, 129, 147, 227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175] + # + def bytes; end + + # call-seq: + # each_byte {|byte| ... } -> self + # each_byte -> enumerator + # + # Calls the given block with each successive byte from +self+; + # returns +self+: + # + # 'hello'.each_byte {|byte| print byte, ' ' } + # print "\n" + # 'тест'.each_byte {|byte| print byte, ' ' } + # print "\n" + # 'こんにちは'.each_byte {|byte| print byte, ' ' } + # print "\n" + # + # Output: + # + # 104 101 108 108 111 + # 209 130 208 181 209 129 209 130 + # 227 129 147 227 130 147 227 129 171 227 129 161 227 129 175 + # + # Returns an enumerator if no block is given. + def each_byte; end + + + # call-seq: + # each_line(line_sep = $/, chomp: false) {|substring| ... } -> self + # each_line(line_sep = $/, chomp: false) -> enumerator + # + # With a block given, forms the substrings ("lines") + # that are the result of splitting +self+ + # at each occurrence of the given line separator +line_sep+; + # passes each line to the block; + # returns +self+: + # + # s = <<~EOT + # This is the first line. + # This is line two. + # + # This is line four. + # This is line five. + # EOT + # + # s.each_line {|line| p line } + # + # Output: + # + # "This is the first line.\n" + # "This is line two.\n" + # "\n" + # "This is line four.\n" + # "This is line five.\n" + # + # With a different +line_sep+: + # + # s.each_line(' is ') {|line| p line } + # + # Output: + # + # "This is " + # "the first line.\nThis is " + # "line two.\n\nThis is " + # "line four.\nThis is " + # "line five.\n" + # + # With +chomp+ as +true+, removes the trailing +line_sep+ from each line: + # + # s.each_line(chomp: true) {|line| p line } + # + # Output: + # + # "This is the first line." + # "This is line two." + # "" + # "This is line four." + # "This is line five." + # + # With an empty string as +line_sep+, + # forms and passes "paragraphs" by splitting at each occurrence + # of two or more newlines: + # + # s.each_line('') {|line| p line } + # + # Output: + # + # "This is the first line.\nThis is line two.\n\n" + # "This is line four.\nThis is line five.\n" + # + # With no block given, returns an enumerator. + # + def each_line; end + + # call-seq: + # split(field_sep = $;, limit = nil) -> array + # split(field_sep = $;, limit = nil) {|substring| ... } -> self # # Returns an array of substrings of +self+ # that are the result of splitting +self+ - # at each occurrence of the given +separator+. + # at each occurrence of the given field separator +field_sep+. # - # When argument +separator+ is $;: + # When +field_sep+ is $;: # # - If $; is +nil+ (its default value), - # the split occurs just as if +separator+ were given as a space character + # the split occurs just as if +field_sep+ were given as a space character # (see below). # # - If $; is a string, - # the split ocurs just as if +separator+ were given as that string + # the split ocurs just as if +field_sep+ were given as that string # (see below). # - # When argument +separator+ is ' ' and argument +limit+ is +nil+, + # When +field_sep+ is ' ' and +limit+ is +nil+, # the split occurs at each sequence of whitespace: # # 'abc def ghi'.split(' ') # => ["abc", "def", "ghi"] @@ -74,9 +177,9 @@ class String # 'abc def ghi'.split(' ') # => ["abc", "def", "ghi"] # ''.split(' ') # => [] # - # When argument +separator+ is a string different from ' ' - # and argument +limit+ is +nil+, - # the split occurs at each occurrence of the separator; + # When +field_sep+ is a string different from ' ' + # and +limit+ is +nil+, + # the split occurs at each occurrence of +field_sep+; # trailing empty substrings are not returned: # # 'abracadabra'.split('ab') # => ["", "racad", "ra"] @@ -87,7 +190,7 @@ class String # 'тест'.split('т') # => ["", "ес"] # 'こんにちは'.split('に') # => ["こん", "ちは"] # - # When argument +separator+ is a Regexp and argument +limit+ is +nil+, + # When +field_sep+ is a Regexp and +limit+ is +nil+, # the split occurs at each occurrence of a match; # trailing empty substrings are not returned: # @@ -101,7 +204,7 @@ class String # # '1:2:3'.split(/(:)()()/, 2) # => ["1", ":", "", "", "2:3"] # - # As seen above, if argument +limit+ is +nil+, + # As seen above, if +limit+ is +nil+, # trailing empty substrings are not returned; # the same is true if +limit+ is zero: # @@ -118,7 +221,7 @@ class String # 'aaabcdaaa'.split('a', 7) # => ["", "", "", "bcd", "", "", ""] # 'aaabcdaaa'.split('a', 8) # => ["", "", "", "bcd", "", "", ""] # - # Note that if +separator+ is a \Regexp containing groups, + # Note that if +field_sep+ is a \Regexp containing groups, # their matches are in the returned array, but do not count toward the limit. # # If +limit+ is negative, it behaves the same as if +limit+ was +nil+, diff --git a/string.c b/string.c index 8ac45b2b96..4776f6e40d 100644 --- a/string.c +++ b/string.c @@ -8652,9 +8652,7 @@ literal_split_pattern(VALUE spat, split_type_t default_type) return default_type; } -/* - * String#split is documented at doc/string.rdoc. - */ +// String#split is documented at doc/string.rdoc. static VALUE rb_str_split_m(int argc, VALUE *argv, VALUE str) @@ -9065,52 +9063,7 @@ rb_str_enumerate_lines(int argc, VALUE *argv, VALUE str, VALUE ary) return orig; } -/* - * call-seq: - * str.each_line(separator=$/, chomp: false) {|substr| block } -> str - * str.each_line(separator=$/, chomp: false) -> an_enumerator - * - * 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 +chomp+ is +true+, +separator+ will be removed from the end of each - * line. - * - * If no block is given, an enumerator is returned instead. - * - * "hello\nworld".each_line {|s| p s} - * # prints: - * # "hello\n" - * # "world" - * - * "hello\nworld".each_line('l') {|s| p s} - * # prints: - * # "hel" - * # "l" - * # "o\nworl" - * # "d" - * - * "hello\n\n\nworld".each_line('') {|s| p s} - * # prints - * # "hello\n\n" - * # "world" - * - * "hello\nworld".each_line(chomp: true) {|s| p s} - * # prints: - * # "hello" - * # "world" - * - * "hello\nworld".each_line('l', chomp: true) {|s| p s} - * # prints: - * # "he" - * # "" - * # "o\nwor" - * # "d" - * - */ +// String#each_line is documented at doc/string.rdoc. static VALUE rb_str_each_line(int argc, VALUE *argv, VALUE str) @@ -9121,21 +9074,11 @@ rb_str_each_line(int argc, VALUE *argv, VALUE str) /* * call-seq: - * str.lines(separator=$/, chomp: false) -> an_array + * lines(Line_sep = $/, chomp: false) -> array_of_strings * - * Returns an array of lines in str split using the supplied - * record separator ($/ by default). This is a - * shorthand for str.each_line(separator, getline_args).to_a. + * Forms substrings ("lines") of +self+ according to the given arguments + * (see String#each_line for details); returns the lines in an array. * - * If +chomp+ is +true+, +separator+ will be removed from the end of each - * line. - * - * "hello\nworld\n".lines #=> ["hello\n", "world\n"] - * "hello world".lines(' ') #=> ["hello ", " ", "world"] - * "hello\nworld\n".lines(chomp: true) #=> ["hello", "world"] - * - * If a block is given, which is a deprecated form, works the same as - * each_line. */ static VALUE @@ -9165,20 +9108,7 @@ rb_str_enumerate_bytes(VALUE str, VALUE ary) return str; } -/* - * call-seq: - * str.each_byte {|integer| block } -> str - * str.each_byte -> an_enumerator - * - * Passes each byte in str to the given block, or returns an - * enumerator if no block is given. - * - * "hello".each_byte {|c| print c, ' ' } - * - * produces: - * - * 104 101 108 108 111 - */ +// String#each_byte is documented in doc/string.rdoc. static VALUE rb_str_each_byte(VALUE str) @@ -9187,16 +9117,7 @@ rb_str_each_byte(VALUE str) return rb_str_enumerate_bytes(str, 0); } -/* - * call-seq: - * str.bytes -> an_array - * - * Returns an array of bytes in str. This is a shorthand for - * str.each_byte.to_a. - * - * If a block is given, which is a deprecated form, works the same as - * each_byte. - */ +// String#bytes is documented in doc/string.rdoc. static VALUE rb_str_bytes(VALUE str)