123456789_123456789_123456789_123456789_123456789_

Class: Encoding

Relationships & Source Files
Namespace Children
Classes:
Converter
Exceptions:
CompatibilityError, ConverterNotFoundError, InvalidByteSequenceError, UndefinedConversionError
Inherits: Object
Defined in: encoding.c,
localeinit.c

Overview

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 s 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.

Class Attribute Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Class Attribute Details

.default_external ⇒ enc (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, 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.

[ GitHub ] 

  


# File 'encoding.c', line 1632



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 1661



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  (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 with -E option or nil otherwise.


  



  [ GitHub ]


  

  


# File 'encoding.c', line 1715



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


  








  

    .default_internal=(enc or nil)   (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 1741



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 1445



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


  








  

    .aliases  ⇒ 1   



  

    

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"}


  



  [ GitHub ]


  

  


# File 'encoding.c', line 1866



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?   



  

    

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 1415



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 1380



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  ⇒ Array, ...   



  

    

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 1350



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


  








  

    .locale_charmap  ⇒ String   



  

    

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 .find(Encoding.locale_charmap) may cause an error. If you need some encoding object even for unknown locale, .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_list  ⇒ Array, ...   



  

    

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 1823



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


  







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 641



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


  








  

    #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 625



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


  







Instance Method Details



  

    #_dump(*args)  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'encoding.c', line 1437



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


  








  

    #inspect  ⇒ String   



  

    

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 1268



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 
      #to_s  ⇒ String 
    

  



  

    

Alias for #to_s.


  





  








  

    #names  ⇒ Array   



  

    

Returns the list of name and aliases of the encoding.



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


  



  [ GitHub ]


  

  


# File 'encoding.c', line 1321



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   



  

    

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 528



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


  








  

    

      #name  ⇒ String 
      #to_s  ⇒ String 
    

    Also known as: #name
  



  

    

Returns the name of the encoding.



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


  





  


  [ GitHub ]


  

  


# File 'encoding.c', line 1295



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