From 7be4d900f0e14e6093c726fbc4416560fd56c931 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sat, 2 Apr 2022 14:26:49 -0500 Subject: [PATCH] [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). --- doc/string/new.rdoc | 58 ++++++++++++++++++++++++++++----------------- doc/transcode.rdoc | 2 +- io.c | 22 ++++++++--------- string.c | 4 +--- 4 files changed, 49 insertions(+), 37 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 ASCII-8BIT: + s = String.new s # => "" s.encoding # => # -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 # => # +With optional argument +string+ and no keyword arguments, +returns a copy of +string+ with the same encoding: -Literal strings like "" or here-documents always use -{script encoding}[rdoc-ref:Encoding@Script+Encoding], unlike String.new. + String.new('foo') # => "foo" + String.new('тест') # => "тест" + String.new('こんにちは') # => "こんにちは" -With keyword +encoding+, returns a copy of +str+ -with the specified encoding: - s = String.new(encoding: 'ASCII') - s.encoding # => # - s = String.new('foo', encoding: 'ASCII') - s.encoding # => # +(Unlike \String.new, +a {string literal}[rdoc-ref:syntax/literals.rdoc@String+Literals] like '' or a +{here document literal}[rdoc-ref:syntax/literals.rdoc@Here+Document+Literals] +always has {script encoding}[rdoc-ref:encodings.rdoc@Script+Encoding].) -Note that these are equivalent: - s0 = String.new('foo', encoding: 'ASCII') - s1 = 'foo'.force_encoding('ASCII') - s0.encoding == s1.encoding # => true +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: -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) # => "" + String.new('foo', encoding: Encoding::US_ASCII).encoding # => # + String.new('foo', encoding: 'US-ASCII').encoding # => # + String.new('foo', encoding: 'ASCII').encoding # => # + +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 # => # # # 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(...) diff --git a/io.c b/io.c index eda7c35257..fcb0cc69f4 100644 --- a/io.c +++ b/io.c @@ -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. * * Forked \Process @@ -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]. * */ diff --git a/string.c b/string.c index 401fcca2fc..f6987459ed 100644 --- a/string.c +++ b/string.c @@ -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 *