diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2022-03-21 14:58:00 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-03-21 14:58:00 -0500 |
commit | c129b6119dfb8d53521b986465c3a85e08d874fe (patch) | |
tree | cc22f0be21e0418239c5036be3c2e299241c77bd /doc/string | |
parent | 1fd1f7bbfc5603cdcfa98363a9ec9e106705a0a3 (diff) |
[DOC] Use RDoc inclusions in string.c (#5683)
As @peterzhu2118 and @duerst have pointed out, putting string method's RDoc into doc/ (which allows non-ASCII in examples) makes the "click to toggle source" feature not work for that method.
This PR moves the primary method doc back into string.c, then includes RDoc from doc/string/*.rdoc, and also removes doc/string.rdoc.
The affected methods are:
::new
#bytes
#each_byte
#each_line
#split
The call-seq is in string.c because it works there; it did not work when the call-seq is in doc/string/*.rdoc.
This PR also updates the relevant guidance in doc/documentation_guide.rdoc.
Notes
Notes:
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
Diffstat (limited to 'doc/string')
-rw-r--r-- | doc/string/bytes.rdoc | 6 | ||||
-rw-r--r-- | doc/string/each_byte.rdoc | 17 | ||||
-rw-r--r-- | doc/string/each_line.rdoc | 60 | ||||
-rw-r--r-- | doc/string/new.rdoc | 37 | ||||
-rw-r--r-- | doc/string/split.rdoc | 84 |
5 files changed, 204 insertions, 0 deletions
diff --git a/doc/string/bytes.rdoc b/doc/string/bytes.rdoc new file mode 100644 index 0000000000..a9e89f1cd1 --- /dev/null +++ b/doc/string/bytes.rdoc @@ -0,0 +1,6 @@ +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] diff --git a/doc/string/each_byte.rdoc b/doc/string/each_byte.rdoc new file mode 100644 index 0000000000..643118fea3 --- /dev/null +++ b/doc/string/each_byte.rdoc @@ -0,0 +1,17 @@ +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. diff --git a/doc/string/each_line.rdoc b/doc/string/each_line.rdoc new file mode 100644 index 0000000000..e254c22d40 --- /dev/null +++ b/doc/string/each_line.rdoc @@ -0,0 +1,60 @@ +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. diff --git a/doc/string/new.rdoc b/doc/string/new.rdoc new file mode 100644 index 0000000000..3eee2b82e0 --- /dev/null +++ b/doc/string/new.rdoc @@ -0,0 +1,37 @@ +Returns a new \String that is a copy of +string+. + +With no arguments, returns the empty string with the Encoding <tt>ASCII-8BIT</tt>: + s = String.new + s # => "" + s.encoding # => #<Encoding:ASCII-8BIT> + +With the single \String argument +string+, returns a copy of +string+ +with the same encoding as +string+: + s = String.new('Que veut dire ça?') + s # => "Que veut dire ça?" + s.encoding # => #<Encoding:UTF-8> + +Literal strings like <tt>""</tt> or here-documents always use +Encoding@Script+encoding, unlike String.new. + +With keyword +encoding+, returns a copy of +str+ +with the specified encoding: + s = String.new(encoding: 'ASCII') + s.encoding # => #<Encoding:US-ASCII> + s = String.new('foo', encoding: 'ASCII') + s.encoding # => #<Encoding:US-ASCII> + +Note that these are equivalent: + s0 = String.new('foo', encoding: 'ASCII') + s1 = 'foo'.force_encoding('ASCII') + s0.encoding == s1.encoding # => true + +With keyword +capacity+, returns a copy of +str+; +the given +capacity+ may set the size of the internal buffer, +which may affect performance: + String.new(capacity: 1) # => "" + String.new(capacity: 4096) # => "" + +The +string+, +encoding+, and +capacity+ arguments may all be used together: + + String.new('hello', encoding: 'UTF-8', capacity: 25) diff --git a/doc/string/split.rdoc b/doc/string/split.rdoc new file mode 100644 index 0000000000..d93b76d9b4 --- /dev/null +++ b/doc/string/split.rdoc @@ -0,0 +1,84 @@ +Returns an array of substrings of +self+ +that are the result of splitting +self+ +at each occurrence of the given field separator +field_sep+. + +When +field_sep+ is <tt>$;</tt>: + +- If <tt>$;</tt> is +nil+ (its default value), + the split occurs just as if +field_sep+ were given as a space character + (see below). + +- If <tt>$;</tt> is a string, + the split ocurs just as if +field_sep+ were given as that string + (see below). + +When +field_sep+ is <tt>' '</tt> and +limit+ is +nil+, +the split occurs at each sequence of whitespace: + + 'abc def ghi'.split(' ') => ["abc", "def", "ghi"] + "abc \n\tdef\t\n ghi".split(' ') # => ["abc", "def", "ghi"] + 'abc def ghi'.split(' ') => ["abc", "def", "ghi"] + ''.split(' ') => [] + +When +field_sep+ is a string different from <tt>' '</tt> +and +limit+ is +nil+, +the split occurs at each occurrence of +field_sep+; +trailing empty substrings are not returned: + + 'abracadabra'.split('ab') => ["", "racad", "ra"] + 'aaabcdaaa'.split('a') => ["", "", "", "bcd"] + ''.split('a') => [] + '3.14159'.split('1') => ["3.", "4", "59"] + '!@#$%^$&*($)_+'.split('$') # => ["!@#", "%^", "&*(", ")_+"] + 'тест'.split('т') => ["", "ес"] + 'こんにちは'.split('に') => ["こん", "ちは"] + +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: + + 'abracadabra'.split(/ab/) # => ["", "racad", "ra"] + 'aaabcdaaa'.split(/a/) => ["", "", "", "bcd"] + 'aaabcdaaa'.split(//) => ["a", "a", "a", "b", "c", "d", "a", "a", "a"] + '1 + 1 == 2'.split(/\W+/) # => ["1", "1", "2"] + +If the \Regexp contains groups, their matches are also included +in the returned array: + + '1:2:3'.split(/(:)()()/, 2) # => ["1", ":", "", "", "2:3"] + +As seen above, if +limit+ is +nil+, +trailing empty substrings are not returned; +the same is true if +limit+ is zero: + + 'aaabcdaaa'.split('a') => ["", "", "", "bcd"] + 'aaabcdaaa'.split('a', 0) # => ["", "", "", "bcd"] + +If +limit+ is positive integer +n+, no more than <tt>n - 1-</tt> +splits occur, so that at most +n+ substrings are returned, +and trailing empty substrings are included: + + 'aaabcdaaa'.split('a', 1) # => ["aaabcdaaa"] + 'aaabcdaaa'.split('a', 2) # => ["", "aabcdaaa"] + 'aaabcdaaa'.split('a', 5) # => ["", "", "", "bcd", "aa"] + 'aaabcdaaa'.split('a', 7) # => ["", "", "", "bcd", "", "", ""] + 'aaabcdaaa'.split('a', 8) # => ["", "", "", "bcd", "", "", ""] + +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+, +meaning that there is no limit, +and trailing empty substrings are included: + + 'aaabcdaaa'.split('a', -1) # => ["", "", "", "bcd", "", "", ""] + +If a block is given, it is called with each substring: + + 'abc def ghi'.split(' ') {|substring| p substring } + +Output: + + "abc" + "def" + "ghi" |