класс Encoding

Родитель:: Объект

Экземпляр 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 не задана, она инициализируется как UTF-8 в Windows и в соответствии с локалью на других операционных системах.

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 с правильной стандартной внешней кодировкой.

См. 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 с правильной стандартной внутренней кодировкой.

См. 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
}

Возвращает имя локали charmap. Возвращает 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 или 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 или 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 → строка

Исходный код

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 → строка

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

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

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

names → массив

Исходный код

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 → строка

Исходный код

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–2024 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.