123456789_123456789_123456789_123456789_123456789_

Class: Encoding

Relationships & Source Files
Namespace Children
Classes:
Inherits: Object
Defined in: encoding.c,
localeinit.c

Class Attribute Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Class Attribute Details

.default_externalenc (rw)

Returns default external encoding.

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

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.

The default external encoding is initialized by the locale or -E option.

[ GitHub ]

  
# File 'encoding.c', line 1473

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

.default_external=(enc) (rw)

Sets default external encoding. You should not set .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 .default_external for information on how the default external encoding is used.

[ GitHub ]

  
# File 'encoding.c', line 1502

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

.default_internalenc (rw)

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:

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.

default_internal is initialized by the source file's internal_encoding or -E option.

[ GitHub ]

  
# File 'encoding.c', line 1557

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

.default_internal=(enc) (rw)

Sets default internal encoding or removes default internal encoding when passed nil. You should not set .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 .default_internal for information on how the default internal encoding is used.

[ GitHub ]

  
# File 'encoding.c', line 1583

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

Class Method Details

._load(str)

This method is for internal use only.
[ GitHub ]

  
# File 'encoding.c', line 1303

static VALUE
enc_load(VALUE klass, VALUE str)
{
    return str;
}

.aliases1

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

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

  
# File 'encoding.c', line 1708

static VALUE
rb_enc_aliases(VALUE klass)
{
    VALUE aliases[2];
    aliases[0] = rb_hash_new();
    aliases[1] = rb_ary_new();
    st_foreach(enc_table.names, rb_enc_aliases_enc_i, (st_data_t)aliases);
    return aliases[0];
}

.compatible?(obj1, obj2) ⇒ enc?

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

[ GitHub ]

  
# File 'encoding.c', line 1274

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

.find(string) ⇒ enc

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.

[ GitHub ]

  
# File 'encoding.c', line 1239

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

.listArray, ...

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

  
# File 'encoding.c', line 1209

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

.locale_charmapString

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.

[ GitHub ]

  
# File 'localeinit.c', line 90

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_listArray, ...

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"]
[ GitHub ]

  
# File 'encoding.c', line 1665

static VALUE
rb_enc_name_list(VALUE klass)
{
    VALUE 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;
}

Instance Attribute Details

#ascii_compatible?Boolean (readonly)

Returns whether ASCII-compatible or not.

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

  
# File 'encoding.c', line 511

static VALUE
enc_ascii_compatible_p(VALUE enc)
{
    return rb_enc_asciicompat(must_encoding(enc)) ? Qtrue : Qfalse;
}

#dummy?Boolean (readonly)

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
[ GitHub ]

  
# File 'encoding.c', line 495

static VALUE
enc_dummy_p(VALUE enc)
{
    return ENC_DUMMY_P(must_encoding(enc)) ? Qtrue : Qfalse;
}

Instance Method Details

#_dump(*args)

This method is for internal use only.
[ GitHub ]

  
# File 'encoding.c', line 1295

static VALUE
enc_dump(int argc, VALUE *argv, VALUE self)
{
    rb_check_arity(argc, 0, 1);
    return enc_name(self);
}

#inspectString

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)>"
[ GitHub ]

  
# File 'encoding.c', line 1127

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)" : ""),
			  enc_autoload_p(enc) ? " (autoload)" : "");
}

#nameString #to_sString

Alias for #to_s.

#namesArray

Returns the list of name and aliases of the encoding.

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

  
# File 'encoding.c', line 1180

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

#replicate(name) ⇒ Encoding

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.

[ GitHub ]

  
# File 'encoding.c', line 422

static VALUE
enc_replicate(VALUE encoding, VALUE name)
{
    return rb_enc_from_encoding_index(
	rb_enc_replicate(StringValueCStr(name),
			 rb_to_encoding(encoding)));
}

#nameString #to_sString
Also known as: #name

Returns the name of the encoding.

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

  
# File 'encoding.c', line 1154

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