52 lines
2.1 KiB
Plaintext
52 lines
2.1 KiB
Plaintext
Returns a new \String object containing the given +string+.
|
|
|
|
The +options+ are optional keyword options (see below).
|
|
|
|
With no argument given and keyword +encoding+ also not given,
|
|
returns an empty string with the Encoding <tt>ASCII-8BIT</tt>:
|
|
|
|
s = String.new # => ""
|
|
s.encoding # => #<Encoding:ASCII-8BIT>
|
|
|
|
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 # => #<Encoding:UTF-16 (dummy)>
|
|
|
|
(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 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 # => #<Encoding:US-ASCII>
|
|
String.new('', encoding: Encoding::US_ASCII).encoding # => #<Encoding:US-ASCII>
|
|
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 its 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 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('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.
|