diff --git a/doc/string/new.rdoc b/doc/string/new.rdoc
index 1d44291f76..e2752d6e1f 100644
--- a/doc/string/new.rdoc
+++ b/doc/string/new.rdoc
@@ -1,34 +1,38 @@
-Returns a new \String that is a copy of +string+.
+Returns a new \String object containing the given +string+.
-With no arguments, returns the empty string with the Encoding ASCII-8BIT:
+The +options+ are optional keyword options (see below).
- s = String.new
- s # => ""
- s.encoding # => #
+With no argument given and keyword +encoding+ also not given,
+returns an empty string with the Encoding ASCII-8BIT:
-With optional argument +string+ and no keyword arguments,
-returns a copy of +string+ with the same encoding:
+ s = String.new # => ""
+ s.encoding # => #
- String.new('foo') # => "foo"
- String.new('тест') # => "тест"
- String.new('こんにちは') # => "こんにちは"
+With argument +string+ given and keyword option +encoding+ not given,
+returns a new string with the same encoding as +string+:
+
+ s0 = 'foo'.encode(Encoding::UTF_16)
+ s1 = String.new(s0)
+ s1.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].)
-With optional keyword argument +encoding+, returns a copy of +string+
-with the specified encoding;
+With keyword option +encoding+ given,
+returns a string with the specified encoding;
the +encoding+ may be an Encoding object, an encoding name,
or an encoding name alias:
+ String.new(encoding: Encoding::US_ASCII).encoding # => #
+ String.new('', encoding: Encoding::US_ASCII).encoding # => #
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:
+and its validity is not checked:
s = String.new('こんにちは', encoding: 'ascii')
s.valid_encoding? # => false
@@ -37,19 +41,11 @@ 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,
+With keyword option +capacity+ given,
+the given value 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)
-
-Note that Ruby strings are null-terminated internally, so the internal
-buffer size will be one or more bytes larger than the requested capacity
-depending on the encoding.
-
-The +string+, +encoding+, and +capacity+ arguments may all be used together:
-
- String.new('hello', encoding: 'UTF-8', capacity: 25)
+ String.new('foo', capacity: 1) # Buffer size is at least 4 (includes terminal null byte).
+ String.new('foo', capacity: 4096) # Buffer size is at least 4;
+ # may be equal to, greater than, or less than 4096.
diff --git a/string.c b/string.c
index 3b40dafb53..2d5e20984b 100644
--- a/string.c
+++ b/string.c
@@ -2346,10 +2346,15 @@ rb_str_with_debug_created_info(VALUE str, VALUE path, int line)
return rb_str_freeze(str);
}
+/*
+ * The documentation block below uses an include (instead of inline text)
+ * because the included text has non-ASCII characters (which are not allowed in a C file).
+ */
+
/*
*
* call-seq:
- * String.new(string = '', **opts) -> new_string
+ * String.new(string = ''.encode(Encoding::ASCII_8BIT) , **options) -> new_string
*
* :include: doc/string/new.rdoc
*