doc/string/new.rdoc

   1 Returns a new \String that is a copy of +string+.
   2
   3 With no arguments, returns the empty string with the Encoding <tt>ASCII-8BIT</tt>:
   4
   5   s = String.new
   6   s # => ""
   7   s.encoding # => #<Encoding:ASCII-8BIT>
   8
   9 With optional argument +string+ and no keyword arguments,
  10 returns a copy of +string+ with the same encoding:
  11
  12   String.new('foo')               # => "foo"
  13   String.new('тест')              # => "тест"
  14   String.new('こんにちは')          # => "こんにちは"
  15
  16 (Unlike \String.new,
  17 a {string literal}[rdoc-ref:syntax/literals.rdoc@String+Literals] like <tt>''</tt> or a
  18 {here document literal}[rdoc-ref:syntax/literals.rdoc@Here+Document+Literals]
  19 always has {script encoding}[rdoc-ref:encodings.rdoc@Script+Encoding].)
  20
  21 With optional keyword argument +encoding+, returns a copy of +string+
  22 with the specified encoding;
  23 the +encoding+ may be an Encoding object, an encoding name,
  24 or an encoding name alias:
  25
  26   String.new('foo', encoding: Encoding::US_ASCII).encoding # => #<Encoding:US-ASCII>
  27   String.new('foo', encoding: 'US-ASCII').encoding         # => #<Encoding:US-ASCII>
  28   String.new('foo', encoding: 'ASCII').encoding            # => #<Encoding:US-ASCII>
  29
  30 The given encoding need not be valid for the string's content,
  31 and that validity is not checked:
  32
  33   s = String.new('こんにちは', encoding: 'ascii')
  34   s.valid_encoding? # => false
  35
  36 But the given +encoding+ itself is checked:
  37
  38   String.new('foo', encoding: 'bar') # Raises ArgumentError.
  39
  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,
  43 and may or may not set the size of the internal buffer,
  44 which may in turn affect performance:
  45
  46   String.new(capacity: 1)
  47   String.new('foo', capacity: 4096)
  48
  49 The +string+, +encoding+, and +capacity+ arguments may all be used together:
  50
  51   String.new('hello', encoding: 'UTF-8', capacity: 25)