encode.rdoc

Returns a copy of self transcoded as determined by dst_encoding. By default, raises an exception if self contains an invalid byte or a character not defined in dst_encoding; that behavior may be modified by encoding options; see below.

With no arguments:

• Uses the same encoding if Encoding.default_internal is nil (the default):

  Encoding.default_internal # => nil
  s = "Ruby\x99".force_encoding('Windows-1252')
  s.encoding                # => #<Encoding:Windows-1252>
  s.bytes                   # => [82, 117, 98, 121, 153]
  t = s.encode              # => "Ruby\x99"
  t.encoding                # => #<Encoding:Windows-1252>
  t.bytes                   # => [82, 117, 98, 121, 226, 132, 162]
  

• Otherwise, uses the encoding Encoding.default_internal:

  Encoding.default_internal = 'UTF-8'
  t = s.encode              # => "Ruby™"
  t.encoding                # => #<Encoding:UTF-8>
  

With only argument dst_encoding given, uses that encoding:

s = "Ruby\x99".force_encoding('Windows-1252')
s.encoding            # => #<Encoding:Windows-1252>
t = s.encode('UTF-8') # => "Ruby™"
t.encoding            # => #<Encoding:UTF-8>

With arguments dst_encoding and src_encoding given, interprets self using src_encoding, encodes the new string using dst_encoding:

s = "Ruby\x99"
t = s.encode('UTF-8', 'Windows-1252') # => "Ruby™"
t.encoding                            # => #<Encoding:UTF-8>

Optional keyword arguments enc_opts specify encoding options; see Encoding Options.

Please note that, unless invalid: :replace option is given, conversion from an encoding enc to the same encoding enc (independent of whether enc is given explicitly or implicitly) is a no-op, i.e. the string is simply copied without any changes, and no exceptions are raised, even if there are invalid bytes.