class Encoding - Documentation for Ruby 3.2

# class Encoding

An Encoding instance represents a character encoding usable in Ruby. It is defined as a constant under the Encoding namespace. It has a name and, optionally, aliases:

    Encoding::US_ASCII.name  # => "US-ASCII"
    Encoding::US_ASCII.names # => ["US-ASCII", "ASCII", "ANSI_X3.4-1968", "646"]

A Ruby method that accepts an encoding as an argument will accept:

- An Encoding object.

- The name of an encoding.

- An alias for an encoding name.

These are equivalent:

    'foo'.encode(Encoding::US_ASCII) # Encoding object.
    'foo'.encode('US-ASCII')         # Encoding name.
    'foo'.encode('ASCII')            # Encoding alias.

For a full discussion of encodings and their uses, see the Encodings document.

Encoding::ASCII_8BIT is a special-purpose encoding that is usually used for a string of bytes, not a string of characters. But as the name indicates, its characters in the ASCII range are considered as ASCII characters. This is useful when you use other ASCII-compatible encodings.

### Public Class Methods

aliases -> {"alias1" => "orig1", "alias2" → "orig2", ...} click to toggle source

Returns the hash of available encoding alias and original encoding name.

    Encoding.aliases
    #=> {"BINARY"=>"ASCII-8BIT", "ASCII"=>"US-ASCII", "ANSI_X3.4-1968"=>"US-ASCII",
          "SJIS"=>"Windows-31J", "eucJP"=>"EUC-JP", "CP932"=>"Windows-31J"}

    static VALUE
    rb_enc_aliases(VALUE klass)
    {
        VALUE aliases[2];
        aliases[0] = rb_hash_new();
        aliases[1] = rb_ary_new();

        st_foreach(global_enc_table.names, rb_enc_aliases_enc_i, (st_data_t)aliases);

        return aliases[0];
    }

compatible?(obj1, obj2) → enc or nil click to toggle source

Checks the compatibility of two objects.

If the objects are both strings they are compatible when they are concatenatable. The encoding of the concatenated string will be returned if they are compatible, nil if they are not.

    Encoding.compatible?("\xa1".force_encoding("iso-8859-1"), "b")
    #=> #<Encoding:ISO-8859-1>

    Encoding.compatible?(
      "\xa1".force_encoding("iso-8859-1"),
      "\xa1\xa1".force_encoding("euc-jp"))
    #=> nil

If the objects are non-strings their encodings are compatible when they have an encoding and:

- Either encoding is US-ASCII compatible

- One of the encodings is a 7-bit encoding

    static VALUE
    enc_compatible_p(VALUE klass, VALUE str1, VALUE str2)
    {
        rb_encoding *enc;

        if (!enc_capable(str1)) return Qnil;
        if (!enc_capable(str2)) return Qnil;
        enc = rb_enc_compatible(str1, str2);
        if (!enc) return Qnil;
        return rb_enc_from_encoding(enc);
    }

default_external → enc click to toggle source

Returns default external encoding.

The default external encoding is used by default for strings created from the following locations:

- `CSV`

- `File` data read from disk

- SDBM

- `StringIO`

- `Zlib::GzipReader`

- `Zlib::GzipWriter`

- `String#inspect`

- `Regexp#inspect`

While strings created from these locations will have this encoding, the encoding may not be valid. Be sure to check `String#valid_encoding?`.

`File` data written to disk will be transcoded to the default external encoding when written, if `default_internal` is not nil.

The default external encoding is initialized by the -E option. If -E isn’t set, it is initialized to UTF-8 on Windows and the locale on other operating systems.

    static VALUE
    get_default_external(VALUE klass)
    {
        return rb_enc_default_external();
    }

default_external = enc click to toggle source

Sets default external encoding. You should not set `Encoding::default_external` in ruby code as strings created before changing the value may have a different encoding from strings created after the value was changed., instead you should use `ruby -E` to invoke ruby with the correct default_external.

See `Encoding::default_external` for information on how the default external encoding is used.

    static VALUE
    set_default_external(VALUE klass, VALUE encoding)
    {
        rb_warning("setting Encoding.default_external");
        rb_enc_set_default_external(encoding);
        return encoding;
    }

default_internal → enc click to toggle source

Returns default internal encoding. Strings will be transcoded to the default internal encoding in the following places if the default internal encoding is not nil:

- `CSV`

- `Etc.sysconfdir` and `Etc.systmpdir`

- `File` data read from disk

- `File` names from `Dir`

- `Integer#chr`

- `String#inspect` and `Regexp#inspect`

- Strings returned from `Readline`

- Strings returned from SDBM

- `Time#zone`

- Values from `ENV`

- Values in ARGV including $PROGRAM_NAME

Additionally `String#encode` and `String#encode!` use the default internal encoding if no encoding is given.

The script encoding (__ENCODING__), not `default_internal`, is used as the encoding of created strings.

`Encoding::default_internal` is initialized with -E option or nil otherwise.

    static VALUE
    get_default_internal(VALUE klass)
    {
        return rb_enc_default_internal();
    }

default_internal = enc or nil click to toggle source

Sets default internal encoding or removes default internal encoding when passed nil. You should not set `Encoding::default_internal` in ruby code as strings created before changing the value may have a different encoding from strings created after the change. Instead you should use `ruby -E` to invoke ruby with the correct default_internal.

See `Encoding::default_internal` for information on how the default internal encoding is used.

    static VALUE
    set_default_internal(VALUE klass, VALUE encoding)
    {
        rb_warning("setting Encoding.default_internal");
        rb_enc_set_default_internal(encoding);
        return encoding;
    }

find(string) → enc click to toggle source

Search the encoding with specified name. name should be a string.

    Encoding.find("US-ASCII")  #=> #<Encoding:US-ASCII>

Names which this method accept are encoding names and aliases including following special aliases

“external”

  default external encoding

“internal”

  default internal encoding

“locale”

  locale encoding

“filesystem”

  filesystem encoding

An `ArgumentError` is raised when no encoding with name. Only `Encoding.find("internal")` however returns nil when no encoding named “internal”, in other words, when Ruby has no default internal encoding.

    static VALUE
    enc_find(VALUE klass, VALUE enc)
    {
        int idx;
        if (is_obj_encoding(enc))
            return enc;
        idx = str_to_encindex(enc);
        if (idx == UNSPECIFIED_ENCODING) return Qnil;
        return rb_enc_from_encoding_index(idx);
    }

list → [enc1, enc2, ...] click to toggle source

Returns the list of loaded encodings.

    Encoding.list
    #=> [#<Encoding:ASCII-8BIT>, #<Encoding:UTF-8>,
          #<Encoding:ISO-2022-JP (dummy)>]

    Encoding.find("US-ASCII")
    #=> #<Encoding:US-ASCII>

    Encoding.list
    #=> [#<Encoding:ASCII-8BIT>, #<Encoding:UTF-8>,
          #<Encoding:US-ASCII>, #<Encoding:ISO-2022-JP (dummy)>]

    static VALUE
    enc_list(VALUE klass)
    {
        VALUE ary = rb_ary_new2(0);
        rb_ary_replace(ary, rb_encoding_list);
        return ary;
    }

locale_charmap → string click to toggle source

Returns the locale charmap name. It returns nil if no appropriate information.

    Debian GNU/Linux
      LANG=C
        Encoding.locale_charmap  #=> "ANSI_X3.4-1968"
      LANG=ja_JP.EUC-JP
        Encoding.locale_charmap  #=> "EUC-JP"

    SunOS 5
      LANG=C
        Encoding.locale_charmap  #=> "646"
      LANG=ja
        Encoding.locale_charmap  #=> "eucJP"

The result is highly platform dependent. So `Encoding.find(Encoding.locale_charmap)` may cause an error. If you need some encoding object even for unknown locale, `Encoding.find`(“locale”) can be used.

    VALUE
    rb_locale_charmap(VALUE klass)
    {
    #if NO_LOCALE_CHARMAP
        return rb_usascii_str_new_cstr("US-ASCII");
    #else
        return locale_charmap(rb_usascii_str_new_cstr);
    #endif
    }

name_list → ["enc1", "enc2", ...] click to toggle source

Returns the list of available encoding names.

    Encoding.name_list
    #=> ["US-ASCII", "ASCII-8BIT", "UTF-8",
          "ISO-8859-1", "Shift_JIS", "EUC-JP",
          "Windows-31J",
          "BINARY", "CP932", "eucJP"]

    static VALUE
    rb_enc_name_list(VALUE klass)
    {
        VALUE ary = rb_ary_new2(global_enc_table.names->num_entries);
        st_foreach(global_enc_table.names, rb_enc_name_list_i, (st_data_t)ary);
        return ary;
    }

### Public Instance Methods

ascii_compatible? → true or false click to toggle source

Returns whether ASCII-compatible or not.

    Encoding::UTF_8.ascii_compatible?     #=> true
    Encoding::UTF_16BE.ascii_compatible?  #=> false

    static VALUE
    enc_ascii_compatible_p(VALUE enc)
    {
        return RBOOL(rb_enc_asciicompat(must_encoding(enc)));
    }

dummy? → true or false click to toggle source

Returns true for dummy encodings. A dummy encoding is an encoding for which character handling is not properly implemented. It is used for stateful encodings.

    Encoding::ISO_2022_JP.dummy?       #=> true
    Encoding::UTF_8.dummy?             #=> false

    static VALUE
    enc_dummy_p(VALUE enc)
    {
        return RBOOL(ENC_DUMMY_P(must_encoding(enc)));
    }

inspect → string click to toggle source

Returns a string which represents the encoding for programmers.

    Encoding::UTF_8.inspect       #=> "#<Encoding:UTF-8>"
    Encoding::ISO_2022_JP.inspect #=> "#<Encoding:ISO-2022-JP (dummy)>"

    static VALUE
    enc_inspect(VALUE self)
    {
        rb_encoding *enc;

        if (!is_data_encoding(self)) {
            not_encoding(self);
        }
        if (!(enc = DATA_PTR(self)) || rb_enc_from_index(rb_enc_to_index(enc)) != enc) {
            rb_raise(rb_eTypeError, "broken Encoding");
        }
        return rb_enc_sprintf(rb_usascii_encoding(),
                              "#<%"PRIsVALUE":%s%s%s>", rb_obj_class(self),
                              rb_enc_name(enc),
                              (ENC_DUMMY_P(enc) ? " (dummy)" : ""),
                              rb_enc_autoload_p(enc) ? " (autoload)" : "");
    }

name → string

Returns the name of the encoding.

    Encoding::UTF_8.name      #=> "UTF-8"

Alias for: to_s
names → array click to toggle source

Returns the list of name and aliases of the encoding.

    Encoding::WINDOWS_31J.names  #=> ["Windows-31J", "CP932", "csWindows31J", "SJIS", "PCK"]

    static VALUE
    enc_names(VALUE self)
    {
        VALUE args[2];

        args[0] = (VALUE)rb_to_encoding_index(self);
        args[1] = rb_ary_new2(0);
        st_foreach(global_enc_table.names, enc_names_i, (st_data_t)args);
        return args[1];
    }

replicate(name) → encoding click to toggle source

Returns a replicated encoding of enc whose name is name. The new encoding should have the same byte structure of enc. If name is used by another encoding, raise `ArgumentError`.

    static VALUE
    enc_replicate_m(VALUE encoding, VALUE name)
    {
        int idx;
        rb_warn_deprecated_to_remove("3.3", "Encoding#replicate", "the original encoding");

        idx = rb_enc_replicate(name_for_encoding(&name), rb_to_encoding(encoding));
        RB_GC_GUARD(name);
        return rb_enc_from_encoding_index(idx);
    }

to_s → string click to toggle source

Returns the name of the encoding.

    Encoding::UTF_8.name      #=> "UTF-8"

    static VALUE
    enc_name(VALUE self)
    {
        return rb_fstring_cstr(rb_enc_name((rb_encoding*)DATA_PTR(self)));
    }

Also aliased as: name