класс 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.

Публичные методы класса

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

    st_foreach(global_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);
}

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

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 ary = rb_ary_new2(0);
    rb_ary_replace(ary, rb_encoding_list);
    return ary;
}

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

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

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

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

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

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 = 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_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)>"

name → string

Возвращает имя кодировки.

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

Псевдоним для: to_s

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);
    st_foreach(global_enc_table.names, enc_names_i, (st_data_t)args);
    return args[1];
}

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

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

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

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

Возвращает имя кодировки.

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

Также имеет псевдоним: name

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