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 *