1- Returns a new \String that is a copy of +string+.
1+ Returns a new \String object containing the given +string+.
22
3- With no arguments, returns the empty string with the Encoding <tt>ASCII-8BIT</tt>:
3+ The +options+ are optional keyword options (see below).
44
5- s = String.new
6- s # => ""
7- s.encoding # => #<Encoding:ASCII-8BIT>
5+ With no argument given and keyword +encoding+ also not given,
6+ returns an empty string with the Encoding <tt>ASCII-8BIT</tt>:
87
9- With optional argument +string+ and no keyword arguments,
10- returns a copy of +string+ with the same encoding:
8+ s = String.new # => ""
9+ s.encoding # => #<Encoding:ASCII-8BIT>
1110
12- String.new('foo') # => "foo"
13- String.new('тест') # => "тест"
14- String.new('こんにちは') # => "こんにちは"
11+ With argument +string+ given and keyword option +encoding+ not given,
12+ returns a new string with the same encoding as +string+:
13+
14+ s0 = 'foo'.encode(Encoding::UTF_16)
15+ s1 = String.new(s0)
16+ s1.encoding # => #<Encoding:UTF-16 (dummy)>
1517
1618(Unlike \String.new,
1719a {string literal}[rdoc-ref:syntax/literals.rdoc@String+Literals] like <tt>''</tt> or a
1820{here document literal}[rdoc-ref:syntax/literals.rdoc@Here+Document+Literals]
1921always has {script encoding}[rdoc-ref:encodings.rdoc@Script+Encoding].)
2022
21- With optional keyword argument +encoding+, returns a copy of +string+
22- with the specified encoding;
23+ With keyword option +encoding+ given,
24+ returns a string with the specified encoding;
2325the +encoding+ may be an Encoding object, an encoding name,
2426or an encoding name alias:
2527
28+ String.new(encoding: Encoding::US_ASCII).encoding # => #<Encoding:US-ASCII>
29+ String.new('', encoding: Encoding::US_ASCII).encoding # => #<Encoding:US-ASCII>
2630 String.new('foo', encoding: Encoding::US_ASCII).encoding # => #<Encoding:US-ASCII>
2731 String.new('foo', encoding: 'US-ASCII').encoding # => #<Encoding:US-ASCII>
2832 String.new('foo', encoding: 'ASCII').encoding # => #<Encoding:US-ASCII>
2933
3034The given encoding need not be valid for the string's content,
31- and that validity is not checked:
35+ and its validity is not checked:
3236
3337 s = String.new('こんにちは', encoding: 'ascii')
3438 s.valid_encoding? # => false
@@ -37,19 +41,11 @@ But the given +encoding+ itself is checked:
3741
3842 String.new('foo', encoding: 'bar') # Raises ArgumentError.
3943
40- With optional keyword argument +capacity+, returns a copy of +string+
41- (or an empty string, if +string+ is not given);
42- the given +capacity+ is advisory only,
44+ With keyword option +capacity+ given,
45+ the given value is advisory only,
4346and may or may not set the size of the internal buffer,
4447which may in turn affect performance:
4548
46- String.new(capacity: 1)
47- String.new('foo', capacity: 4096)
48-
49- Note that Ruby strings are null-terminated internally, so the internal
50- buffer size will be one or more bytes larger than the requested capacity
51- depending on the encoding.
52-
53- The +string+, +encoding+, and +capacity+ arguments may all be used together:
54-
55- String.new('hello', encoding: 'UTF-8', capacity: 25)
49+ String.new('foo', capacity: 1) # Buffer size is at least 4 (includes terminal null byte).
50+ String.new('foo', capacity: 4096) # Buffer size is at least 4;
51+ # may be equal to, greater than, or less than 4096.
0 commit comments