diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2020-05-15 16:14:50 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-05-15 14:14:50 -0700 |
commit | cc525d764b841fef1256222185647c670e9d199c (patch) | |
tree | b41436b20ba8b9f4d044cda1a0ef646f628521c6 /string.c | |
parent | 24739c62e5cee1eaa0857fee2800c8bcba8c9ced (diff) | |
download | ruby-cc525d764b841fef1256222185647c670e9d199c.tar.gz |
[ci skip] Enhanced rdoc for String.new (#3067)
* Per @nobu review
* Enhanced rdoc for String.new
* Respond to review
Diffstat (limited to 'string.c')
-rw-r--r-- | string.c | 103 |
1 files changed, 88 insertions, 15 deletions
@@ -1554,21 +1554,94 @@ rb_str_resurrect(VALUE str) /* * call-seq: - * String.new(str="") -> new_str - * String.new(str="", encoding: enc) -> new_str - * String.new(str="", capacity: size) -> new_str - * - * Returns a new string object containing a copy of <i>str</i>. - * - * The optional <i>encoding</i> keyword argument specifies the encoding - * of the new string. - * If not specified, the encoding of <i>str</i> is used - * (or ASCII-8BIT, if <i>str</i> is not specified). - * - * The optional <i>capacity</i> keyword argument specifies the size - * of the internal buffer. - * This may improve performance, when the string will be concatenated many - * times (causing many realloc calls). + * String.new(str='') -> new_str + * String.new(str='', encoding: enc) -> new_str + * String.new(str='', capacity: size) -> new_str + * + * Argument +str+, if given, it must be a + * {String-convertible object}[doc/implicit_conversion_rdoc.html#label-String-Convertible+Objects] + * (implements +to_str). + * + * Argument +encoding+, if given, must be: + * - A {String-convertible object}[doc/implicit_conversion_rdoc.html#label-String-Convertible+Objects] + * (implements +to_str+). + * - The name of an encoding that is compatible with +str+. + * + * Argument +capacity+, if given, must be an + * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects] + * (implements +to_int+). + * + * The +str+, +encoding+, and +capacity+ arguments may all be used together: + * String.new('hello', encoding: 'UTF-8', capacity: 25) + * + * Returns a new \String that is a copy of <i>str</i>. + * + * --- + * + * With no arguments, returns the empty string with the Encoding <tt>ASCII-8BIT</tt>: + * s = Str.new + * s # => "" + * s.encoding # => #<Encoding:ASCII-8BIT> + * + * With the single argument +str+, returns a copy of +str+ + * with the same encoding as +str+: + * 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}[Encoding.html#class-Encoding-label-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) # => " + * + * No exception is raised for zero or negative values: + * String.new(capacity: 0) # => " + * String.new(capacity: -1) # => " + * + * --- + * + * Raises an exception if +str+ is not \String-convertible: + * # Raises TypeError (no implicit conversion of Integer into String): + * String.new(0) + * + * Raises an exception if +encoding+ is not \String-convertible + * or an Encoding object: + * # Raises TypeError (no implicit conversion of Integer into String): + * String.new(encoding: 0) + * + * Raises an exception if the given +encoding+ is not a valid encoding name: + * # Raises ArgumentError (unknown encoding name - FOO) + * String.new(encoding: 'FOO') + * + * Raises an exception if the given +encoding+ is incompatible with +str+: + * utf8 = 'Que veut dire ça?' + * ascii = 'Que veut dire ça?'.force_encoding('ASCII') + * # Raises Encoding::CompatibilityError (incompatible character encodings: UTF-8 and US-ASCII) + * utf8.include? ascii + * + * Raises an exception if +capacity+ is not \Integer-convertible: + * # Raises TypeError (no implicit conversion of Symbol into Integer): + * String.new(capacity: :foo) */ static VALUE |