AnEncoding instance represents a characterencoding usable in Ruby. It is defined as a constant under theEncoding namespace. It has a name and optionally,aliases:

Encoding::ISO_8859_1.name#=> "ISO-8859-1"Encoding::ISO_8859_1.names#=> ["ISO-8859-1", "ISO8859-1"]

Ruby methods dealing with encodings return or acceptEncoding instances as arguments (when a methodaccepts anEncoding instance as an argument, itcan be passed anEncoding name or aliasinstead).

"some string".encoding#=> #<Encoding:UTF-8>string ="some string".encode(Encoding::ISO_8859_1)#=> "some string"string.encoding#=> #<Encoding:ISO-8859-1>"some string".encode"ISO-8859-1"#=> "some string"

Encoding::ASCII_8BIT is a special encoding that is usually used for a bytestring, not a character string. But as the name insists, its characters inthe range of ASCII are considered as ASCII characters. This is useful whenyou use ASCII-8BIT characters with other ASCII compatible characters.

Changing an encoding¶↑

The associatedEncoding of aString can be changed in two different ways.

First, it is possible to set theEncoding of astring to a newEncoding without changing theinternal byte representation of the string, withString#force_encoding. Thisis how you can tell Ruby the correct encoding of a string.

string#=> "R\xC3\xA9sum\xC3\xA9"string.encoding#=> #<Encoding:ISO-8859-1>string.force_encoding(Encoding::UTF_8)#=> "R\u00E9sum\u00E9"

Second, it is possible to transcode a string, i.e. translate its internalbyte representation to another encoding. Its associated encoding is alsoset to the other encoding. SeeString#encode for the various formsof transcoding, and theEncoding::Converter class for additionalcontrol over the transcoding process.

string#=> "R\u00E9sum\u00E9"string.encoding#=> #<Encoding:UTF-8>string =string.encode!(Encoding::ISO_8859_1)#=> "R\xE9sum\xE9"string.encoding#=> #<Encoding::ISO-8859-1>

Script encoding¶↑

All Ruby script code has an associatedEncodingwhich anyString literal created in the sourcecode will be associated to.

The default script encoding is Encoding::UTF_8 after v2.0, but it can bechanged by a magic comment on the first line of the source code file (orsecond line, if there is a shebang line on the first). The comment mustcontain the wordcoding orencoding, followed bya colon, space and theEncoding name or alias:

# encoding: UTF-8"some string".encoding#=> #<Encoding:UTF-8>

The__ENCODING__ keyword returns the script encoding of thefile which the keyword is written:

# encoding: ISO-8859-1__ENCODING__#=> #<Encoding:ISO-8859-1>

ruby -K will change the default locale encoding, but this isnot recommended. Ruby source files should declare its script encoding by amagic comment even when they only depend on US-ASCII strings or regularexpressions.

Locale encoding¶↑

The default encoding of the environment. Usually derived from locale.

see::locale_charmap,::find('locale')

Filesystem encoding¶↑

The default encoding of strings from the filesystem of the environment.This is used for strings of file names or paths.

see::find('filesystem')

External encoding¶↑

EachIO object has an external encoding whichindicates the encoding that Ruby will use to read its data. By default Rubysets the external encoding of anIO object to thedefault external encoding. The default external encoding is set by localeencoding or the interpreter-E option.::default_externalreturns the current value of the external encoding.

ENV["LANG"]#=> "UTF-8"Encoding.default_external#=> #<Encoding:UTF-8>$ ruby -E ISO-8859-1 -e "p Encoding.default_external"#<Encoding:ISO-8859-1>$ LANG=C ruby -e 'p Encoding.default_external'#<Encoding:US-ASCII>

The default external encoding may also be set through::default_external=,but you should not do this as strings created before and after the changewill have inconsistent encodings. Instead useruby -E toinvoke ruby with the correct external encoding.

When you know that the actual encoding of the data of anIO object is not the default external encoding, you canreset its external encoding withIO#set_encoding or set it atIO object creation (seeIO.new options).

Internal encoding¶↑

To process the data of anIO object which has anencoding different from its external encoding, you can set its internalencoding. Ruby will use this internal encoding to transcode the data whenit is read from theIO object.

Conversely, when data is written to theIO object itis transcoded from the internal encoding to the external encoding of theIO object.

The internal encoding of anIO object can be set withIO#set_encoding or atIO object creation (seeIO.new options).

The internal encoding is optional and when not set, the Ruby defaultinternal encoding is used. If not explicitly set this default internalencoding isnil meaning that by default, no transcodingoccurs.

The default internal encoding can be set with the interpreter option-E.::default_internalreturns the current internal encoding.

$ ruby -e 'p Encoding.default_internal'nil$ ruby -E ISO-8859-1:UTF-8 -e "p [Encoding.default_external, \  Encoding.default_internal]"[#<Encoding:ISO-8859-1>, #<Encoding:UTF-8>]

The default internal encoding may also be set through::default_internal=,but you should not do this as strings created before and after the changewill have inconsistent encodings. Instead useruby -E toinvoke ruby with the correct internal encoding.

IO encoding example¶↑

In the following example a UTF-8 encoded string “Ru00E9sumu00E9” istranscoded for output to ISO-8859-1 encoding, then read back in andtranscoded to UTF-8:

string ="R\u00E9sum\u00E9"open("transcoded.txt","w:ISO-8859-1")do|io|io.write(string)endputs"raw text:"pFile.binread("transcoded.txt")putsopen("transcoded.txt","r:ISO-8859-1:UTF-8")do|io|puts"transcoded text:"pio.readend

While writing the file, the internal encoding is not specified as it isonly necessary for reading. While reading the file both the internal andexternal encoding must be specified to obtain the correct result.

$ ruby t.rbraw text:"R\xE9sum\xE9"transcoded text:"R\u00E9sum\u00E9"