класс Encoding

Родительский класс:: Object

Экземпляр Encoding представляет кодировку символов, которую можно использовать в Ruby. Она определена как константа в пространстве имён Encoding. У неё есть имя и, при необходимости, псевдонимы:

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

Метод Ruby, принимающий кодировку в качестве аргумента, может принимать:

Объект Encoding.
Имя кодировки.
Псевдоним имени кодировки.

Эти варианты эквивалентны:

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

Полное обсуждение кодировок и их применения см. в документе о кодировках.

Encoding::ASCII_8BIT — это специальная кодировка, обычно используемая для строки байтов, а не строки символов. Однако, как следует из названия, символы в диапазоне ASCII считаются символами ASCII. Это полезно при использовании других кодировок, совместимых с ASCII.

Константы

UNICODE_VERSION: Поддерживаемая версия Unicode.

Атрибуты

name [R]

Имя кодировки.

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

to_s [R]

Имя кодировки.

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

Общедоступные методы класса

aliases -> {"alias1" => "orig1", "alias2" → "orig2", ...} Показать исходный код

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

    GLOBAL_ENC_TABLE_LOCKING(enc_table) {
        st_foreach(enc_table->names, rb_enc_aliases_enc_i, (st_data_t)aliases);
    }

    return aliases[0];
}

Возвращает хеш доступных псевдонимов кодировок и исходных имён кодировок.

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

compatible?(obj1, obj2) → enc or nil Показать исходный код

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);
}

Проверяет совместимость двух объектов.

Если оба объекта являются строками, они совместимы, когда их можно объединить. Если строки совместимы, возвращается кодировка объединённой строки, в противном случае возвращается nil.

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

Если объекты не являются строками, их кодировки совместимы, если у них есть кодировка и выполняется одно из условий:

Одна из кодировок совместима с US-ASCII.
Одна из кодировок является 7-битной.

default_external → enc Показать исходный код

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

Возвращает внешнюю кодировку по умолчанию.

Внешняя кодировка по умолчанию используется для строк, созданных из следующих источников:

CSV
данные File, считанные с диска
SDBM
StringIO
Zlib::GzipReader
Zlib::GzipWriter
String#inspect
Regexp#inspect

Хотя строки, созданные из этих источников, будут иметь эту кодировку, она может быть недопустимой. Обязательно проверьте String#valid_encoding?.

При записи на диск данные File будут транскодированы во внешнюю кодировку по умолчанию, если default_internal не равна nil.

Внешняя кодировка по умолчанию задаётся параметром -E. Если параметр -E не указан, в Windows она устанавливается в UTF-8, а в других операционных системах — в кодировку локали.

default_external = enc Показать исходный код

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

Задаёт внешнюю кодировку по умолчанию. Не следует задавать Encoding::default_external в коде Ruby, поскольку строки, созданные до изменения значения, могут иметь другую кодировку, чем строки, созданные после него. Вместо этого следует использовать ruby -E, чтобы запустить Ruby с нужным значением default_external.

Сведения об использовании внешней кодировки по умолчанию см. в разделе Encoding::default_external.

default_internal → enc Показать исходный код

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

Возвращает внутреннюю кодировку по умолчанию. Если внутренняя кодировка по умолчанию не равна nil, строки будут транскодированы в неё в следующих случаях:

CSV
Etc.sysconfdir и Etc.systmpdir
данные File, считанные с диска
имена File из Dir
Integer#chr
String#inspect и Regexp#inspect
Строки, возвращаемые Readline
Строки, возвращаемые SDBM
Time#zone
Значения из ENV
Значения в ARGV, включая $PROGRAM_NAME

Кроме того, String#encode и String#encode! используют внутреннюю кодировку по умолчанию, если кодировка не указана.

В качестве кодировки создаваемых строк используется кодировка скрипта (__ENCODING__), а не default_internal.

Encoding::default_internal задаётся параметром -E или, если он не указан, принимает значение nil.

default_internal = enc or nil Показать исходный код

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

Задаёт внутреннюю кодировку по умолчанию или сбрасывает её, если передано значение nil. Не следует задавать Encoding::default_internal в коде Ruby, поскольку строки, созданные до изменения значения, могут иметь другую кодировку, чем строки, созданные после него. Вместо этого следует использовать ruby -E, чтобы запустить Ruby с нужным значением default_internal.

Сведения об использовании внутренней кодировки по умолчанию см. в разделе Encoding::default_internal.

find(string) → enc Показать исходный код

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);
}

Ищет кодировку по указанному имени. name должно быть строкой.

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

Этот метод принимает имена и псевдонимы кодировок, включая следующие специальные псевдонимы:

“external”: внешняя кодировка по умолчанию
“internal”: внутренняя кодировка по умолчанию
“locale”: кодировка локали
“filesystem”: кодировка файловой системы

Если кодировка с указанным именем не найдена, возникает исключение ArgumentError. Однако только Encoding.find("internal") возвращает nil, если кодировка с именем “internal” не найдена, то есть если в Ruby не задана внутренняя кодировка по умолчанию.

list → [enc1, enc2, ...] Показать исходный код

static VALUE
enc_list(VALUE klass)
{
    VALUE list = RUBY_ATOMIC_VALUE_LOAD(rb_encoding_list);
    return rb_ary_dup(list);
}

Возвращает список загруженных кодировок.

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)>]

locale_charmap → string Показать исходный код

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
}

Возвращает имя таблицы символов локали. Если подходящие сведения отсутствуют, возвращает nil.

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"

Результат сильно зависит от платформы. Поэтому Encoding.find(Encoding.locale_charmap) может вызвать ошибку. Если объект кодировки нужен даже для неизвестной локали, можно использовать Encoding.find(“locale”).

name_list → ["enc1", "enc2", ...] Показать исходный код

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

Возвращает список доступных имён кодировок.

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

Общедоступные методы экземпляра

ascii_compatible? → true or false Показать исходный код

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

Возвращает true, если кодировка совместима с ASCII, и false в противном случае.

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

dummy? → true or false Показать исходный код

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

Возвращает true для фиктивных кодировок. Фиктивная кодировка — это кодировка, обработка символов в которой реализована не полностью. Она используется для кодировок с состоянием.

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

inspect → string Показать исходный код

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

    if (!is_data_encoding(self)) {
        not_encoding(self);
    }
    if (!(enc = RTYPEDDATA_GET_DATA(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_inspect_name(enc),
                          (ENC_DUMMY_P(enc) ? " (dummy)" : ""),
                          rb_enc_autoload_p(enc) ? " (autoload)" : "");
}

Возвращает строку, представляющую кодировку в удобном для программистов виде.

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

names → array Показать исходный код

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

    args[0] = (VALUE)rb_to_encoding_index(self);
    args[1] = rb_ary_new2(0);

    GLOBAL_ENC_TABLE_LOCKING(enc_table) {
        st_foreach(enc_table->names, enc_names_i, (st_data_t)args);
    }
    return args[1];
}

Возвращает список имени и псевдонимов кодировки.

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

Ruby Core © 1993–2025 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.