encode

The first form returns a copy of str transcoded to encoding encoding. The second form returns a copy of str transcoded from src_encoding to dst_encoding. The last form returns a copy of str transcoded to Encoding.default_internal.

By default, the first and second form raise Encoding::UndefinedConversionError for characters that are undefined in the destination encoding, and Encoding::InvalidByteSequenceError for invalid byte sequences in the source encoding. The last form by default does not raise exceptions but uses replacement strings.

Please note that conversion from an encoding enc to the same encoding enc is a no-op, i.e. the receiver is returned without any changes, and no exceptions are raised, even if there are invalid bytes.

The options Hash gives details for conversion and can have the following keys:

:invalid

If the value is :replace, encode replaces invalid byte sequences in str with the replacement character. The default is to raise the Encoding::InvalidByteSequenceError exception

:undef

If the value is :replace, encode replaces characters which are undefined in the destination encoding with the replacement character. The default is to raise the Encoding::UndefinedConversionError.

:replace

Sets the replacement string to the given value. The default replacement string is âuFFFDâ for Unicode encoding forms, and â?â otherwise.

:fallback

Sets the replacement string by the given object for undefined character. The object should be a Hash, a Proc, a Method, or an object which has [] method. Its key is an undefined character encoded in the source encoding of current transcoder. Its value can be any encoding until it can be converted into the destination encoding of the transcoder.

:xml

The value must be :text or :attr. If the value is :text encode replaces undefined characters with their (upper-case hexadecimal) numeric character references. '&', '<', and '>' are converted to â&amp;â, â&lt;â, and â&gt;â, respectively. If the value is :attr, encode also quotes the replacement result (using 'â'), and replaces 'â' with â&quot;â.

:cr_newline

Replaces LF (ânâ) with CR (ârâ) if value is true.

:crlf_newline

Replaces LF (ânâ) with CRLF (ârnâ) if value is true.

:universal_newline

Replaces CRLF (ârnâ) and CR (ârâ) with LF (ânâ) if value is true.