diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2022-04-02 14:26:49 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-04-02 14:26:49 -0500 |
commit | 7be4d900f0e14e6093c726fbc4416560fd56c931 (patch) | |
tree | 73f6c240485b3289bd7ea0fbc8b128cd6cd2fc10 | |
parent | 4d2623ead2b526fda0dd1e919d9d1dd1d159f57e (diff) |
[DOC] Enhanced RDoc for String (#5751)
Adds to doc for String.new, also making it compliant with documentation_guide.rdoc.
Fixes some broken links in io.c (that I failed to correct yesterday).
Notes
Notes:
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
-rw-r--r-- | doc/string/new.rdoc | 66 | ||||
-rw-r--r-- | doc/transcode.rdoc | 2 | ||||
-rw-r--r-- | io.c | 22 | ||||
-rw-r--r-- | string.c | 4 |
4 files changed, 53 insertions, 41 deletions
diff --git a/doc/string/new.rdoc b/doc/string/new.rdoc index b8dac00856..d955e61c87 100644 --- a/doc/string/new.rdoc +++ b/doc/string/new.rdoc @@ -1,36 +1,50 @@ 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 -{script encoding}[rdoc-ref: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) # => "" +With optional argument +string+ and no keyword arguments, +returns a copy of +string+ with the same encoding: + + String.new('foo') # => "foo" + String.new('тест') # => "тест" + String.new('こんにちは') # => "こんにちは" + +(Unlike \String.new, +a {string literal}[rdoc-ref:syntax/literals.rdoc@String+Literals] like <tt>''</tt> or a +{here document literal}[rdoc-ref:syntax/literals.rdoc@Here+Document+Literals] +always has {script encoding}[rdoc-ref:encodings.rdoc@Script+Encoding].) + +With optional keyword argument +encoding+, returns a copy of +string+ +with the specified encoding; +the +encoding+ may be an Encoding object, an encoding name, +or an encoding name alias: + + String.new('foo', encoding: Encoding::US_ASCII).encoding # => #<Encoding:US-ASCII> + String.new('foo', encoding: 'US-ASCII').encoding # => #<Encoding:US-ASCII> + String.new('foo', encoding: 'ASCII').encoding # => #<Encoding:US-ASCII> + +The given encoding need not be valid for the string's content, +and that validity is not checked: + + s = String.new('こんにちは', encoding: 'ascii') + s.valid_encoding? # => false + +But the given +encoding+ itself is checked: + + String.new('foo', encoding: 'bar') # Raises ArgumentError. + +With optional keyword argument +capacity+, returns a copy of +string+ +(or an empty string, if +string+ is not given); +the given +capacity+ is advisory only, +and may or may not set the size of the internal buffer, +which may in turn affect performance: + + String.new(capacity: 1) + String.new('foo', capacity: 4096) The +string+, +encoding+, and +capacity+ arguments may all be used together: diff --git a/doc/transcode.rdoc b/doc/transcode.rdoc index 9be6982cea..4f15dff94a 100644 --- a/doc/transcode.rdoc +++ b/doc/transcode.rdoc @@ -44,7 +44,7 @@ class String # t.encoding # => #<Encoding:UTF-8> # # Optional keyword arguments +enc_opts+ specify encoding options; - # see {Encoding Options}[rdoc-ref:Encoding@Encoding+Options]. + # see {Encoding Options}[rdoc-ref:encodings.rdoc@Encoding+Options]. def encode(dst_encoding = Encoding.default_internal, **enc_opts) # Pseudo code Primitive.str_encode(...) @@ -7458,7 +7458,7 @@ static VALUE popen_finish(VALUE port, VALUE klass); * Optional keyword arguments +opts+ specify: * * - {Open options}[rdoc-ref:IO@Open+Options]. - * - {Encoding options}[rdoc-ref:Encoding@Encoding+Options]. + * - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options]. * - Options for Kernel#spawn. * * <b>Forked \Process</b> @@ -8080,7 +8080,7 @@ rb_freopen(VALUE fname, const char *mode, FILE *fp) * Optional keyword arguments +opts+ specify: * * - {Open Options}[rdoc-ref:IO@Open+Options]. - * - {Encoding options}[rdoc-ref:Encoding@Encoding+Options]. + * - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options]. * */ @@ -9012,7 +9012,7 @@ rb_io_make_open_file(VALUE obj) * Optional keyword arguments +opts+ specify: * * - {Open Options}[rdoc-ref:IO@Open+Options]. - * - {Encoding options}[rdoc-ref:Encoding@Encoding+Options]. + * - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options]. * * Examples: * @@ -9156,7 +9156,7 @@ rb_io_set_encoding_by_bom(VALUE io) * Optional keyword arguments +opts+ specify: * * - {Open Options}[rdoc-ref:IO@Open+Options]. - * - {Encoding options}[rdoc-ref:Encoding@Encoding+Options]. + * - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options]. * * Examples: * @@ -9835,7 +9835,7 @@ static VALUE argf_readlines(int, VALUE *, VALUE); * For all forms above, optional keyword arguments specify: * * - {Line Options}[rdoc-ref:IO@Line+Options]. - * - {Encoding options}[rdoc-ref:Encoding@Encoding+Options]. + * - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options]. * * Examples: * @@ -11100,7 +11100,7 @@ pipe_pair_close(VALUE rw) * Optional keyword arguments +opts+ specify: * * - {Open Options}[rdoc-ref:IO@Open+Options]. - * - {Encoding Options}[rdoc-ref:Encoding@Encoding+Options]. + * - {Encoding Options}[rdoc-ref:encodings.rdoc@Encoding+Options]. * * With no block given, returns the two endpoints in an array: * @@ -11362,7 +11362,7 @@ io_s_foreach(VALUE v) * Optional keyword arguments +opts+ specify: * * - {Open Options}[rdoc-ref:IO@Open+Options]. - * - {Encoding options}[rdoc-ref:Encoding@Encoding+Options]. + * - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options]. * - {Line Options}[rdoc-ref:IO@Line+Options]. * * Returns an Enumerator if no block is given. @@ -11460,7 +11460,7 @@ io_s_readlines(VALUE v) * Optional keyword arguments +opts+ specify: * * - {Open Options}[rdoc-ref:IO@Open+Options]. - * - {Encoding options}[rdoc-ref:Encoding@Encoding+Options]. + * - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options]. * - {Line Options}[rdoc-ref:IO@Line+Options]. * */ @@ -11550,7 +11550,7 @@ seek_before_access(VALUE argp) * Optional keyword arguments +opts+ specify: * * - {Open Options}[rdoc-ref:IO@Open+Options]. - * - {Encoding options}[rdoc-ref:Encoding@Encoding+Options]. + * - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options]. * */ @@ -11741,7 +11741,7 @@ io_s_write(int argc, VALUE *argv, VALUE klass, int binary) * Optional keyword arguments +opts+ specify: * * - {Open Options}[rdoc-ref:IO@Open+Options]. - * - {Encoding options}[rdoc-ref:Encoding@Encoding+Options]. + * - {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options]. * */ @@ -12825,7 +12825,7 @@ rb_io_internal_encoding(VALUE io) * and internal encodings for the stream. * * Optional keyword arguments +enc_opts+ specify - * {Encoding options}[rdoc-ref:Encoding@Encoding+Options]. + * {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options]. * */ @@ -1813,9 +1813,7 @@ rb_ec_str_resurrect(struct rb_execution_context_struct *ec, VALUE str) /* * * call-seq: - * String.new(string = '') -> new_string - * String.new(string = '', encoding: encoding) -> new_string - * String.new(string = '', capacity: size) -> new_string + * String.new(string = '', **opts) -> new_string * * :include: doc/string/new.rdoc * |