File: //usr/lib/ruby/gems/3.2.0/gems/rbs-2.8.2/core/encoding.rbs
# <!-- rdoc-file=encoding.c -->
# 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::ISO_8859_1.name
# #=> "ISO-8859-1"
#
# Encoding::ISO_8859_1.names
# #=> ["ISO-8859-1", "ISO8859-1"]
#
# Ruby methods dealing with encodings return or accept Encoding instances as
# arguments (when a method accepts an Encoding instance as an argument, it can
# be passed an Encoding name or alias instead).
#
# "some string".encoding
# #=> #<Encoding:UTF-8>
#
# string = "some string".encode(Encoding::ISO_8859_1)
# #=> "some string"
# string.encoding
# #=> #<Encoding:ISO-8859-1>
#
# "some string".encode "ISO-8859-1"
# #=> "some string"
#
# Encoding::ASCII_8BIT is a special encoding that is usually used for a byte
# string, not a character string. But as the name insists, its characters in the
# range of ASCII are considered as ASCII characters. This is useful when you
# use ASCII-8BIT characters with other ASCII compatible characters.
#
# ## Changing an encoding
#
# The associated Encoding of a String can be changed in two different ways.
#
# First, it is possible to set the Encoding of a string to a new Encoding
# without changing the internal byte representation of the string, with
# String#force_encoding. This is how you can tell Ruby the correct encoding of a
# string.
#
# string
# #=> "R\xC3\xA9sum\xC3\xA9"
# string.encoding
# #=> #<Encoding:ISO-8859-1>
# string.force_encoding(Encoding::UTF_8)
# #=> "R\u00E9sum\u00E9"
#
# Second, it is possible to transcode a string, i.e. translate its internal byte
# representation to another encoding. Its associated encoding is also set to the
# other encoding. See String#encode for the various forms of transcoding, and
# the Encoding::Converter class for additional control over the transcoding
# process.
#
# string
# #=> "R\u00E9sum\u00E9"
# string.encoding
# #=> #<Encoding:UTF-8>
# string = string.encode!(Encoding::ISO_8859_1)
# #=> "R\xE9sum\xE9"
# string.encoding
# #=> #<Encoding::ISO-8859-1>
#
# ## Script encoding
#
# All Ruby script code has an associated Encoding which any String literal
# created in the source code will be associated to.
#
# The default script encoding is Encoding::UTF_8 after v2.0, but it can be
# changed by a magic comment on the first line of the source code file (or
# second line, if there is a shebang line on the first). The comment must
# contain the word `coding` or `encoding`, followed by a colon, space and the
# Encoding name or alias:
#
# # encoding: UTF-8
#
# "some string".encoding
# #=> #<Encoding:UTF-8>
#
# The `__ENCODING__` keyword returns the script encoding of the file which the
# keyword is written:
#
# # encoding: ISO-8859-1
#
# __ENCODING__
# #=> #<Encoding:ISO-8859-1>
#
# `ruby -K` will change the default locale encoding, but this is not
# recommended. Ruby source files should declare its script encoding by a magic
# comment even when they only depend on US-ASCII strings or regular expressions.
#
# ## Locale encoding
#
# The default encoding of the environment. Usually derived from locale.
#
# see Encoding.locale_charmap, Encoding.find('locale')
#
# ## Filesystem encoding
#
# The default encoding of strings from the filesystem of the environment. This
# is used for strings of file names or paths.
#
# see Encoding.find('filesystem')
#
# ## External encoding
#
# Each IO object has an external encoding which indicates the encoding that Ruby
# will use to read its data. By default Ruby sets the external encoding of an IO
# object to the default external encoding. The default external encoding is set
# by locale encoding or the interpreter `-E` option. Encoding.default_external
# returns the current value of the external encoding.
#
# ENV["LANG"]
# #=> "UTF-8"
# Encoding.default_external
# #=> #<Encoding:UTF-8>
#
# $ ruby -E ISO-8859-1 -e "p Encoding.default_external"
# #<Encoding:ISO-8859-1>
#
# $ LANG=C ruby -e 'p Encoding.default_external'
# #<Encoding:US-ASCII>
#
# The default external encoding may also be set through
# Encoding.default_external=, but you should not do this as strings created
# before and after the change will have inconsistent encodings. Instead use
# `ruby -E` to invoke ruby with the correct external encoding.
#
# When you know that the actual encoding of the data of an IO object is not the
# default external encoding, you can reset its external encoding with
# IO#set_encoding or set it at IO object creation (see IO.new options).
#
# ## Internal encoding
#
# To process the data of an IO object which has an encoding different from its
# external encoding, you can set its internal encoding. Ruby will use this
# internal encoding to transcode the data when it is read from the IO object.
#
# Conversely, when data is written to the IO object it is transcoded from the
# internal encoding to the external encoding of the IO object.
#
# The internal encoding of an IO object can be set with IO#set_encoding or at IO
# object creation (see IO.new options).
#
# The internal encoding is optional and when not set, the Ruby default internal
# encoding is used. If not explicitly set this default internal encoding is
# `nil` meaning that by default, no transcoding occurs.
#
# The default internal encoding can be set with the interpreter option `-E`.
# Encoding.default_internal returns the current internal encoding.
#
# $ ruby -e 'p Encoding.default_internal'
# nil
#
# $ ruby -E ISO-8859-1:UTF-8 -e "p [Encoding.default_external, \
# Encoding.default_internal]"
# [#<Encoding:ISO-8859-1>, #<Encoding:UTF-8>]
#
# The default internal encoding may also be set through
# Encoding.default_internal=, but you should not do this as strings created
# before and after the change will have inconsistent encodings. Instead use
# `ruby -E` to invoke ruby with the correct internal encoding.
#
# ## IO encoding example
#
# In the following example a UTF-8 encoded string "Ru00E9sumu00E9" is transcoded
# for output to ISO-8859-1 encoding, then read back in and transcoded to UTF-8:
#
# string = "R\u00E9sum\u00E9"
#
# open("transcoded.txt", "w:ISO-8859-1") do |io|
# io.write(string)
# end
#
# puts "raw text:"
# p File.binread("transcoded.txt")
# puts
#
# open("transcoded.txt", "r:ISO-8859-1:UTF-8") do |io|
# puts "transcoded text:"
# p io.read
# end
#
# While writing the file, the internal encoding is not specified as it is only
# necessary for reading. While reading the file both the internal and external
# encoding must be specified to obtain the correct result.
#
# $ ruby t.rb
# raw text:
# "R\xE9sum\xE9"
#
# transcoded text:
# "R\u00E9sum\u00E9"
#
class Encoding < Object
# <!--
# rdoc-file=encoding.c
# - Encoding.aliases -> {"alias1" => "orig1", "alias2" => "orig2", ...}
# -->
# 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"}
#
def self.aliases: () -> ::Hash[String, String]
# <!--
# rdoc-file=encoding.c
# - Encoding.compatible?(obj1, obj2) -> enc or nil
# -->
# 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
#
def self.compatible?: (untyped obj1, untyped obj2) -> Encoding?
# <!--
# rdoc-file=encoding.c
# - Encoding.default_external -> enc
# -->
# Returns default external encoding.
#
# The default external encoding is used by default for strings created from the
# following locations:
#
# * CSV
# * File data read from disk
# * SDBM
# * StringIO
# * Zlib::GzipReader
# * Zlib::GzipWriter
# * String#inspect
# * Regexp#inspect
#
#
# 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.
#
def self.default_external: () -> Encoding
# <!--
# rdoc-file=encoding.c
# - Encoding.default_external = enc
# -->
# Sets default external encoding. You should not set Encoding::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 Encoding::default_external for information on how the default external
# encoding is used.
#
def self.default_external=: (String arg0) -> String
| (Encoding arg0) -> Encoding
# <!--
# rdoc-file=encoding.c
# - Encoding.default_internal -> enc
# -->
# 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:
#
# * CSV
# * Etc.sysconfdir and Etc.systmpdir
# * File data read from disk
# * File names from Dir
# * Integer#chr
# * String#inspect and Regexp#inspect
# * Strings returned from Readline
# * Strings returned from SDBM
# * Time#zone
# * Values from ENV
# * Values in ARGV including $PROGRAM_NAME
#
#
# 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.
#
# Encoding::default_internal is initialized with -E option or nil otherwise.
#
def self.default_internal: () -> Encoding?
# <!--
# rdoc-file=encoding.c
# - Encoding.default_internal = enc or nil
# -->
# Sets default internal encoding or removes default internal encoding when
# passed nil. You should not set Encoding::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 Encoding::default_internal for information on how the default internal
# encoding is used.
#
def self.default_internal=: (String arg0) -> String?
| (Encoding arg0) -> Encoding?
| (nil arg0) -> nil
# <!--
# rdoc-file=encoding.c
# - Encoding.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.
#
def self.find: (String | Encoding arg0) -> Encoding
# <!--
# rdoc-file=encoding.c
# - Encoding.list -> [enc1, enc2, ...]
# -->
# 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)>]
#
def self.list: () -> ::Array[Encoding]
# <!--
# rdoc-file=encoding.c
# - Encoding.name_list -> ["enc1", "enc2", ...]
# -->
# 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"]
#
def self.name_list: () -> ::Array[String]
# <!--
# rdoc-file=encoding.c
# - enc.ascii_compatible? -> true or false
# -->
# Returns whether ASCII-compatible or not.
#
# Encoding::UTF_8.ascii_compatible? #=> true
# Encoding::UTF_16BE.ascii_compatible? #=> false
#
def ascii_compatible?: () -> bool
# <!--
# rdoc-file=encoding.c
# - enc.dummy? -> true or false
# -->
# 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
#
def dummy?: () -> bool
# <!--
# rdoc-file=encoding.c
# - enc.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)>"
#
def inspect: () -> String
# <!-- rdoc-file=encoding.c -->
# Returns the name of the encoding.
#
# Encoding::UTF_8.name #=> "UTF-8"
#
def name: () -> String
# <!--
# rdoc-file=encoding.c
# - enc.names -> array
# -->
# Returns the list of name and aliases of the encoding.
#
# Encoding::WINDOWS_31J.names #=> ["Windows-31J", "CP932", "csWindows31J", "SJIS", "PCK"]
#
def names: () -> ::Array[String]
# <!--
# rdoc-file=encoding.c
# - enc.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.
#
def replicate: (String name) -> Encoding
# <!--
# rdoc-file=encoding.c
# - enc.name -> string
# - enc.to_s -> string
# -->
# Returns the name of the encoding.
#
# Encoding::UTF_8.name #=> "UTF-8"
#
def to_s: () -> String
end
Encoding::ANSI_X3_4_1968: Encoding
Encoding::ASCII: Encoding
Encoding::ASCII_8BIT: Encoding
Encoding::BIG5: Encoding
Encoding::BIG5_HKSCS: Encoding
Encoding::BIG5_HKSCS_2008: Encoding
Encoding::BIG5_UAO: Encoding
Encoding::BINARY: Encoding
Encoding::Big5: Encoding
Encoding::Big5_HKSCS: Encoding
Encoding::Big5_HKSCS_2008: Encoding
Encoding::Big5_UAO: Encoding
Encoding::CESU_8: Encoding
Encoding::CP1250: Encoding
Encoding::CP1251: Encoding
Encoding::CP1252: Encoding
Encoding::CP1253: Encoding
Encoding::CP1254: Encoding
Encoding::CP1255: Encoding
Encoding::CP1256: Encoding
Encoding::CP1257: Encoding
Encoding::CP1258: Encoding
Encoding::CP437: Encoding
Encoding::CP50220: Encoding
Encoding::CP50221: Encoding
Encoding::CP51932: Encoding
Encoding::CP65000: Encoding
Encoding::CP65001: Encoding
Encoding::CP737: Encoding
Encoding::CP775: Encoding
Encoding::CP850: Encoding
Encoding::CP852: Encoding
Encoding::CP855: Encoding
Encoding::CP857: Encoding
Encoding::CP860: Encoding
Encoding::CP861: Encoding
Encoding::CP862: Encoding
Encoding::CP863: Encoding
Encoding::CP864: Encoding
Encoding::CP865: Encoding
Encoding::CP866: Encoding
Encoding::CP869: Encoding
Encoding::CP874: Encoding
Encoding::CP878: Encoding
Encoding::CP932: Encoding
Encoding::CP936: Encoding
Encoding::CP949: Encoding
Encoding::CP950: Encoding
Encoding::CP951: Encoding
Encoding::CSWINDOWS31J: Encoding
Encoding::CsWindows31J: Encoding
Encoding::EBCDIC_CP_US: Encoding
Encoding::EMACS_MULE: Encoding
Encoding::EUCCN: Encoding
Encoding::EUCJP: Encoding
Encoding::EUCJP_MS: Encoding
Encoding::EUCKR: Encoding
Encoding::EUCTW: Encoding
Encoding::EUC_CN: Encoding
Encoding::EUC_JISX0213: Encoding
Encoding::EUC_JIS_2004: Encoding
Encoding::EUC_JP: Encoding
Encoding::EUC_JP_MS: Encoding
Encoding::EUC_KR: Encoding
Encoding::EUC_TW: Encoding
Encoding::Emacs_Mule: Encoding
Encoding::EucCN: Encoding
Encoding::EucJP: Encoding
Encoding::EucJP_ms: Encoding
Encoding::EucKR: Encoding
Encoding::EucTW: Encoding
Encoding::GB12345: Encoding
Encoding::GB18030: Encoding
Encoding::GB1988: Encoding
Encoding::GB2312: Encoding
Encoding::GBK: Encoding
Encoding::IBM037: Encoding
Encoding::IBM437: Encoding
Encoding::IBM737: Encoding
Encoding::IBM775: Encoding
Encoding::IBM850: Encoding
Encoding::IBM852: Encoding
Encoding::IBM855: Encoding
Encoding::IBM857: Encoding
Encoding::IBM860: Encoding
Encoding::IBM861: Encoding
Encoding::IBM862: Encoding
Encoding::IBM863: Encoding
Encoding::IBM864: Encoding
Encoding::IBM865: Encoding
Encoding::IBM866: Encoding
Encoding::IBM869: Encoding
Encoding::ISO2022_JP: Encoding
Encoding::ISO2022_JP2: Encoding
Encoding::ISO8859_1: Encoding
Encoding::ISO8859_10: Encoding
Encoding::ISO8859_11: Encoding
Encoding::ISO8859_13: Encoding
Encoding::ISO8859_14: Encoding
Encoding::ISO8859_15: Encoding
Encoding::ISO8859_16: Encoding
Encoding::ISO8859_2: Encoding
Encoding::ISO8859_3: Encoding
Encoding::ISO8859_4: Encoding
Encoding::ISO8859_5: Encoding
Encoding::ISO8859_6: Encoding
Encoding::ISO8859_7: Encoding
Encoding::ISO8859_8: Encoding
Encoding::ISO8859_9: Encoding
Encoding::ISO_2022_JP: Encoding
Encoding::ISO_2022_JP_2: Encoding
Encoding::ISO_2022_JP_KDDI: Encoding
Encoding::ISO_8859_1: Encoding
Encoding::ISO_8859_10: Encoding
Encoding::ISO_8859_11: Encoding
Encoding::ISO_8859_13: Encoding
Encoding::ISO_8859_14: Encoding
Encoding::ISO_8859_15: Encoding
Encoding::ISO_8859_16: Encoding
Encoding::ISO_8859_2: Encoding
Encoding::ISO_8859_3: Encoding
Encoding::ISO_8859_4: Encoding
Encoding::ISO_8859_5: Encoding
Encoding::ISO_8859_6: Encoding
Encoding::ISO_8859_7: Encoding
Encoding::ISO_8859_8: Encoding
Encoding::ISO_8859_9: Encoding
Encoding::KOI8_R: Encoding
Encoding::KOI8_U: Encoding
Encoding::MACCENTEURO: Encoding
Encoding::MACCROATIAN: Encoding
Encoding::MACCYRILLIC: Encoding
Encoding::MACGREEK: Encoding
Encoding::MACICELAND: Encoding
Encoding::MACJAPAN: Encoding
Encoding::MACJAPANESE: Encoding
Encoding::MACROMAN: Encoding
Encoding::MACROMANIA: Encoding
Encoding::MACTHAI: Encoding
Encoding::MACTURKISH: Encoding
Encoding::MACUKRAINE: Encoding
Encoding::MacCentEuro: Encoding
Encoding::MacCroatian: Encoding
Encoding::MacCyrillic: Encoding
Encoding::MacGreek: Encoding
Encoding::MacIceland: Encoding
Encoding::MacJapan: Encoding
Encoding::MacJapanese: Encoding
Encoding::MacRoman: Encoding
Encoding::MacRomania: Encoding
Encoding::MacThai: Encoding
Encoding::MacTurkish: Encoding
Encoding::MacUkraine: Encoding
Encoding::PCK: Encoding
Encoding::SHIFT_JIS: Encoding
Encoding::SJIS: Encoding
Encoding::SJIS_DOCOMO: Encoding
Encoding::SJIS_DoCoMo: Encoding
Encoding::SJIS_KDDI: Encoding
Encoding::SJIS_SOFTBANK: Encoding
Encoding::SJIS_SoftBank: Encoding
Encoding::STATELESS_ISO_2022_JP: Encoding
Encoding::STATELESS_ISO_2022_JP_KDDI: Encoding
Encoding::Shift_JIS: Encoding
Encoding::Stateless_ISO_2022_JP: Encoding
Encoding::Stateless_ISO_2022_JP_KDDI: Encoding
Encoding::TIS_620: Encoding
Encoding::UCS_2BE: Encoding
Encoding::UCS_4BE: Encoding
Encoding::UCS_4LE: Encoding
Encoding::US_ASCII: Encoding
Encoding::UTF8_DOCOMO: Encoding
Encoding::UTF8_DoCoMo: Encoding
Encoding::UTF8_KDDI: Encoding
Encoding::UTF8_MAC: Encoding
Encoding::UTF8_SOFTBANK: Encoding
Encoding::UTF8_SoftBank: Encoding
Encoding::UTF_16: Encoding
Encoding::UTF_16BE: Encoding
Encoding::UTF_16LE: Encoding
Encoding::UTF_32: Encoding
Encoding::UTF_32BE: Encoding
Encoding::UTF_32LE: Encoding
Encoding::UTF_7: Encoding
Encoding::UTF_8: Encoding
Encoding::UTF_8_HFS: Encoding
Encoding::UTF_8_MAC: Encoding
Encoding::WINDOWS_1250: Encoding
Encoding::WINDOWS_1251: Encoding
Encoding::WINDOWS_1252: Encoding
Encoding::WINDOWS_1253: Encoding
Encoding::WINDOWS_1254: Encoding
Encoding::WINDOWS_1255: Encoding
Encoding::WINDOWS_1256: Encoding
Encoding::WINDOWS_1257: Encoding
Encoding::WINDOWS_1258: Encoding
Encoding::WINDOWS_31J: Encoding
Encoding::WINDOWS_874: Encoding
Encoding::Windows_1250: Encoding
Encoding::Windows_1251: Encoding
Encoding::Windows_1252: Encoding
Encoding::Windows_1253: Encoding
Encoding::Windows_1254: Encoding
Encoding::Windows_1255: Encoding
Encoding::Windows_1256: Encoding
Encoding::Windows_1257: Encoding
Encoding::Windows_1258: Encoding
Encoding::Windows_31J: Encoding
Encoding::Windows_874: Encoding
# <!-- rdoc-file=transcode.c -->
# Encoding conversion class.
#
class Encoding::Converter < Object
type encoding = String | Encoding
type decorator = "universal_newline"
| "crlf_newline"
| "cr_newline"
| "xml_text_escape"
| "xml_attr_content_escape"
| "xml_attr_quote"
type conversion_path = Array[[encoding, encoding] | decorator]
type convert_result = :invalid_byte_sequence
| :incomplete_input
| :undefined_conversion
| :after_output
| :destination_buffer_full
| :source_buffer_empty
| :finished
# <!--
# rdoc-file=transcode.c
# - Encoding::Converter.asciicompat_encoding(string) -> encoding or nil
# - Encoding::Converter.asciicompat_encoding(encoding) -> encoding or nil
# -->
# Returns the corresponding ASCII compatible encoding.
#
# Returns nil if the argument is an ASCII compatible encoding.
#
# "corresponding ASCII compatible encoding" is an ASCII compatible encoding
# which can represents exactly the same characters as the given ASCII
# incompatible encoding. So, no conversion undefined error occurs when
# converting between the two encodings.
#
# Encoding::Converter.asciicompat_encoding("ISO-2022-JP") #=> #<Encoding:stateless-ISO-2022-JP>
# Encoding::Converter.asciicompat_encoding("UTF-16BE") #=> #<Encoding:UTF-8>
# Encoding::Converter.asciicompat_encoding("UTF-8") #=> nil
#
def self.asciicompat_encoding: (encoding enc) -> Encoding?
# <!--
# rdoc-file=transcode.c
# - Encoding::Converter.search_convpath(source_encoding, destination_encoding) -> ary
# - Encoding::Converter.search_convpath(source_encoding, destination_encoding, opt) -> ary
# -->
# Returns a conversion path.
#
# p Encoding::Converter.search_convpath("ISO-8859-1", "EUC-JP")
# #=> [[#<Encoding:ISO-8859-1>, #<Encoding:UTF-8>],
# # [#<Encoding:UTF-8>, #<Encoding:EUC-JP>]]
#
# p Encoding::Converter.search_convpath("ISO-8859-1", "EUC-JP", universal_newline: true)
# or
# p Encoding::Converter.search_convpath("ISO-8859-1", "EUC-JP", newline: :universal)
# #=> [[#<Encoding:ISO-8859-1>, #<Encoding:UTF-8>],
# # [#<Encoding:UTF-8>, #<Encoding:EUC-JP>],
# # "universal_newline"]
#
# p Encoding::Converter.search_convpath("ISO-8859-1", "UTF-32BE", universal_newline: true)
# or
# p Encoding::Converter.search_convpath("ISO-8859-1", "UTF-32BE", newline: :universal)
# #=> [[#<Encoding:ISO-8859-1>, #<Encoding:UTF-8>],
# # "universal_newline",
# # [#<Encoding:UTF-8>, #<Encoding:UTF-32BE>]]
#
def self.search_convpath: (
encoding source,
encoding destination,
?newline: :universal | :crlf | :cr,
?universal_newline: bool,
?crlf_newline: bool,
?cr_newline: bool,
?xml: :text | :attr
) -> conversion_path
public
# <!--
# rdoc-file=transcode.c
# - ec == other -> true or false
# -->
#
def ==: (self) -> bool
# <!--
# rdoc-file=transcode.c
# - ec.convert(source_string) -> destination_string
# -->
# Convert source_string and return destination_string.
#
# source_string is assumed as a part of source. i.e. :partial_input=>true is
# specified internally. finish method should be used last.
#
# ec = Encoding::Converter.new("utf-8", "euc-jp")
# puts ec.convert("\u3042").dump #=> "\xA4\xA2"
# puts ec.finish.dump #=> ""
#
# ec = Encoding::Converter.new("euc-jp", "utf-8")
# puts ec.convert("\xA4").dump #=> ""
# puts ec.convert("\xA2").dump #=> "\xE3\x81\x82"
# puts ec.finish.dump #=> ""
#
# ec = Encoding::Converter.new("utf-8", "iso-2022-jp")
# puts ec.convert("\xE3").dump #=> "".force_encoding("ISO-2022-JP")
# puts ec.convert("\x81").dump #=> "".force_encoding("ISO-2022-JP")
# puts ec.convert("\x82").dump #=> "\e$B$\"".force_encoding("ISO-2022-JP")
# puts ec.finish.dump #=> "\e(B".force_encoding("ISO-2022-JP")
#
# If a conversion error occur, Encoding::UndefinedConversionError or
# Encoding::InvalidByteSequenceError is raised. Encoding::Converter#convert
# doesn't supply methods to recover or restart from these exceptions. When you
# want to handle these conversion errors, use
# Encoding::Converter#primitive_convert.
#
def convert: (String source) -> String
# <!--
# rdoc-file=transcode.c
# - ec.convpath -> ary
# -->
# Returns the conversion path of ec.
#
# The result is an array of conversions.
#
# ec = Encoding::Converter.new("ISO-8859-1", "EUC-JP", crlf_newline: true)
# p ec.convpath
# #=> [[#<Encoding:ISO-8859-1>, #<Encoding:UTF-8>],
# # [#<Encoding:UTF-8>, #<Encoding:EUC-JP>],
# # "crlf_newline"]
#
# Each element of the array is a pair of encodings or a string. A pair means an
# encoding conversion. A string means a decorator.
#
# In the above example, [#<Encoding:ISO-8859-1>, #<Encoding:UTF-8>] means a
# converter from ISO-8859-1 to UTF-8. "crlf_newline" means newline converter
# from LF to CRLF.
#
def convpath: () -> conversion_path
# <!--
# rdoc-file=transcode.c
# - ec.destination_encoding -> encoding
# -->
# Returns the destination encoding as an Encoding object.
#
def destination_encoding: () -> Encoding
# <!--
# rdoc-file=transcode.c
# - ec.finish -> string
# -->
# Finishes the converter. It returns the last part of the converted string.
#
# ec = Encoding::Converter.new("utf-8", "iso-2022-jp")
# p ec.convert("\u3042") #=> "\e$B$\""
# p ec.finish #=> "\e(B"
#
def finish: () -> String
# <!--
# rdoc-file=transcode.c
# - ec.insert_output(string) -> nil
# -->
# Inserts string into the encoding converter. The string will be converted to
# the destination encoding and output on later conversions.
#
# If the destination encoding is stateful, string is converted according to the
# state and the state is updated.
#
# This method should be used only when a conversion error occurs.
#
# ec = Encoding::Converter.new("utf-8", "iso-8859-1")
# src = "HIRAGANA LETTER A is \u{3042}."
# dst = ""
# p ec.primitive_convert(src, dst) #=> :undefined_conversion
# puts "[#{dst.dump}, #{src.dump}]" #=> ["HIRAGANA LETTER A is ", "."]
# ec.insert_output("<err>")
# p ec.primitive_convert(src, dst) #=> :finished
# puts "[#{dst.dump}, #{src.dump}]" #=> ["HIRAGANA LETTER A is <err>.", ""]
#
# ec = Encoding::Converter.new("utf-8", "iso-2022-jp")
# src = "\u{306F 3041 3068 2661 3002}" # U+2661 is not representable in iso-2022-jp
# dst = ""
# p ec.primitive_convert(src, dst) #=> :undefined_conversion
# puts "[#{dst.dump}, #{src.dump}]" #=> ["\e$B$O$!$H".force_encoding("ISO-2022-JP"), "\xE3\x80\x82"]
# ec.insert_output "?" # state change required to output "?".
# p ec.primitive_convert(src, dst) #=> :finished
# puts "[#{dst.dump}, #{src.dump}]" #=> ["\e$B$O$!$H\e(B?\e$B!#\e(B".force_encoding("ISO-2022-JP"), ""]
#
def insert_output: (String) -> nil
# <!--
# rdoc-file=transcode.c
# - ec.inspect -> string
# -->
# Returns a printable version of *ec*
#
# ec = Encoding::Converter.new("iso-8859-1", "utf-8")
# puts ec.inspect #=> #<Encoding::Converter: ISO-8859-1 to UTF-8>
#
def inspect: () -> String
# <!--
# rdoc-file=transcode.c
# - ec.last_error -> exception or nil
# -->
# Returns an exception object for the last conversion. Returns nil if the last
# conversion did not produce an error.
#
# "error" means that Encoding::InvalidByteSequenceError and
# Encoding::UndefinedConversionError for Encoding::Converter#convert and
# :invalid_byte_sequence, :incomplete_input and :undefined_conversion for
# Encoding::Converter#primitive_convert.
#
# ec = Encoding::Converter.new("utf-8", "iso-8859-1")
# p ec.primitive_convert(src="\xf1abcd", dst="") #=> :invalid_byte_sequence
# p ec.last_error #=> #<Encoding::InvalidByteSequenceError: "\xF1" followed by "a" on UTF-8>
# p ec.primitive_convert(src, dst, nil, 1) #=> :destination_buffer_full
# p ec.last_error #=> nil
#
def last_error: () -> Encoding::InvalidByteSequenceError?
| () -> Encoding::UndefinedConversionError?
# <!--
# rdoc-file=transcode.c
# - ec.primitive_convert(source_buffer, destination_buffer) -> symbol
# - ec.primitive_convert(source_buffer, destination_buffer, destination_byteoffset) -> symbol
# - ec.primitive_convert(source_buffer, destination_buffer, destination_byteoffset, destination_bytesize) -> symbol
# - ec.primitive_convert(source_buffer, destination_buffer, destination_byteoffset, destination_bytesize, opt) -> symbol
# -->
# possible opt elements:
# hash form:
# :partial_input => true # source buffer may be part of larger source
# :after_output => true # stop conversion after output before input
# integer form:
# Encoding::Converter::PARTIAL_INPUT
# Encoding::Converter::AFTER_OUTPUT
#
# possible results:
# :invalid_byte_sequence
# :incomplete_input
# :undefined_conversion
# :after_output
# :destination_buffer_full
# :source_buffer_empty
# :finished
#
# primitive_convert converts source_buffer into destination_buffer.
#
# source_buffer should be a string or nil. nil means an empty string.
#
# destination_buffer should be a string.
#
# destination_byteoffset should be an integer or nil. nil means the end of
# destination_buffer. If it is omitted, nil is assumed.
#
# destination_bytesize should be an integer or nil. nil means unlimited. If it
# is omitted, nil is assumed.
#
# opt should be nil, a hash or an integer. nil means no flags. If it is omitted,
# nil is assumed.
#
# primitive_convert converts the content of source_buffer from beginning and
# store the result into destination_buffer.
#
# destination_byteoffset and destination_bytesize specify the region which the
# converted result is stored. destination_byteoffset specifies the start
# position in destination_buffer in bytes. If destination_byteoffset is nil,
# destination_buffer.bytesize is used for appending the result.
# destination_bytesize specifies maximum number of bytes. If
# destination_bytesize is nil, destination size is unlimited. After conversion,
# destination_buffer is resized to destination_byteoffset + actually produced
# number of bytes. Also destination_buffer's encoding is set to
# destination_encoding.
#
# primitive_convert drops the converted part of source_buffer. the dropped part
# is converted in destination_buffer or buffered in Encoding::Converter object.
#
# primitive_convert stops conversion when one of following condition met.
# * invalid byte sequence found in source buffer (:invalid_byte_sequence)
# `primitive_errinfo` and `last_error` methods returns the detail of the
# error.
# * unexpected end of source buffer (:incomplete_input) this occur only when
# :partial_input is not specified. `primitive_errinfo` and `last_error`
# methods returns the detail of the error.
# * character not representable in output encoding (:undefined_conversion)
# `primitive_errinfo` and `last_error` methods returns the detail of the
# error.
# * after some output is generated, before input is done (:after_output) this
# occur only when :after_output is specified.
# * destination buffer is full (:destination_buffer_full) this occur only when
# destination_bytesize is non-nil.
# * source buffer is empty (:source_buffer_empty) this occur only when
# :partial_input is specified.
# * conversion is finished (:finished)
#
#
# example:
# ec = Encoding::Converter.new("UTF-8", "UTF-16BE")
# ret = ec.primitive_convert(src="pi", dst="", nil, 100)
# p [ret, src, dst] #=> [:finished, "", "\x00p\x00i"]
#
# ec = Encoding::Converter.new("UTF-8", "UTF-16BE")
# ret = ec.primitive_convert(src="pi", dst="", nil, 1)
# p [ret, src, dst] #=> [:destination_buffer_full, "i", "\x00"]
# ret = ec.primitive_convert(src, dst="", nil, 1)
# p [ret, src, dst] #=> [:destination_buffer_full, "", "p"]
# ret = ec.primitive_convert(src, dst="", nil, 1)
# p [ret, src, dst] #=> [:destination_buffer_full, "", "\x00"]
# ret = ec.primitive_convert(src, dst="", nil, 1)
# p [ret, src, dst] #=> [:finished, "", "i"]
#
def primitive_convert: (
String? source,
String destination,
?Integer? destination_byteoffset,
?Integer? destination_bytesize,
?partial_input: bool,
?after_output: bool
) -> convert_result
| (
String? source,
String destination,
?Integer? destination_byteoffset,
?Integer? destination_bytesize,
?Integer opt
) -> convert_result
# <!--
# rdoc-file=transcode.c
# - ec.primitive_errinfo -> array
# -->
# primitive_errinfo returns important information regarding the last error as a
# 5-element array:
#
# [result, enc1, enc2, error_bytes, readagain_bytes]
#
# result is the last result of primitive_convert.
#
# Other elements are only meaningful when result is :invalid_byte_sequence,
# :incomplete_input or :undefined_conversion.
#
# enc1 and enc2 indicate a conversion step as a pair of strings. For example, a
# converter from EUC-JP to ISO-8859-1 converts a string as follows: EUC-JP ->
# UTF-8 -> ISO-8859-1. So [enc1, enc2] is either ["EUC-JP", "UTF-8"] or
# ["UTF-8", "ISO-8859-1"].
#
# error_bytes and readagain_bytes indicate the byte sequences which caused the
# error. error_bytes is discarded portion. readagain_bytes is buffered portion
# which is read again on next conversion.
#
# Example:
#
# # \xff is invalid as EUC-JP.
# ec = Encoding::Converter.new("EUC-JP", "Shift_JIS")
# ec.primitive_convert(src="\xff", dst="", nil, 10)
# p ec.primitive_errinfo
# #=> [:invalid_byte_sequence, "EUC-JP", "Shift_JIS", "\xFF", ""]
#
# # HIRAGANA LETTER A (\xa4\xa2 in EUC-JP) is not representable in ISO-8859-1.
# # Since this error is occur in UTF-8 to ISO-8859-1 conversion,
# # error_bytes is HIRAGANA LETTER A in UTF-8 (\xE3\x81\x82).
# ec = Encoding::Converter.new("EUC-JP", "ISO-8859-1")
# ec.primitive_convert(src="\xa4\xa2", dst="", nil, 10)
# p ec.primitive_errinfo
# #=> [:undefined_conversion, "UTF-8", "ISO-8859-1", "\xE3\x81\x82", ""]
#
# # partial character is invalid
# ec = Encoding::Converter.new("EUC-JP", "ISO-8859-1")
# ec.primitive_convert(src="\xa4", dst="", nil, 10)
# p ec.primitive_errinfo
# #=> [:incomplete_input, "EUC-JP", "UTF-8", "\xA4", ""]
#
# # Encoding::Converter::PARTIAL_INPUT prevents invalid errors by
# # partial characters.
# ec = Encoding::Converter.new("EUC-JP", "ISO-8859-1")
# ec.primitive_convert(src="\xa4", dst="", nil, 10, Encoding::Converter::PARTIAL_INPUT)
# p ec.primitive_errinfo
# #=> [:source_buffer_empty, nil, nil, nil, nil]
#
# # \xd8\x00\x00@ is invalid as UTF-16BE because
# # no low surrogate after high surrogate (\xd8\x00).
# # It is detected by 3rd byte (\00) which is part of next character.
# # So the high surrogate (\xd8\x00) is discarded and
# # the 3rd byte is read again later.
# # Since the byte is buffered in ec, it is dropped from src.
# ec = Encoding::Converter.new("UTF-16BE", "UTF-8")
# ec.primitive_convert(src="\xd8\x00\x00@", dst="", nil, 10)
# p ec.primitive_errinfo
# #=> [:invalid_byte_sequence, "UTF-16BE", "UTF-8", "\xD8\x00", "\x00"]
# p src
# #=> "@"
#
# # Similar to UTF-16BE, \x00\xd8@\x00 is invalid as UTF-16LE.
# # The problem is detected by 4th byte.
# ec = Encoding::Converter.new("UTF-16LE", "UTF-8")
# ec.primitive_convert(src="\x00\xd8@\x00", dst="", nil, 10)
# p ec.primitive_errinfo
# #=> [:invalid_byte_sequence, "UTF-16LE", "UTF-8", "\x00\xD8", "@\x00"]
# p src
# #=> ""
#
def primitive_errinfo: () -> [convert_result, String?, String?, String?, String?]
# <!--
# rdoc-file=transcode.c
# - ec.putback -> string
# - ec.putback(max_numbytes) -> string
# -->
# Put back the bytes which will be converted.
#
# The bytes are caused by invalid_byte_sequence error. When
# invalid_byte_sequence error, some bytes are discarded and some bytes are
# buffered to be converted later. The latter bytes can be put back. It can be
# observed by Encoding::InvalidByteSequenceError#readagain_bytes and
# Encoding::Converter#primitive_errinfo.
#
# ec = Encoding::Converter.new("utf-16le", "iso-8859-1")
# src = "\x00\xd8\x61\x00"
# dst = ""
# p ec.primitive_convert(src, dst) #=> :invalid_byte_sequence
# p ec.primitive_errinfo #=> [:invalid_byte_sequence, "UTF-16LE", "UTF-8", "\x00\xD8", "a\x00"]
# p ec.putback #=> "a\x00"
# p ec.putback #=> "" # no more bytes to put back
#
def putback: (?Integer max_numbytes) -> String
# <!--
# rdoc-file=transcode.c
# - ec.replacement -> string
# -->
# Returns the replacement string.
#
# ec = Encoding::Converter.new("euc-jp", "us-ascii")
# p ec.replacement #=> "?"
#
# ec = Encoding::Converter.new("euc-jp", "utf-8")
# p ec.replacement #=> "\uFFFD"
#
def replacement: () -> String
# <!--
# rdoc-file=transcode.c
# - ec.replacement = string
# -->
# Sets the replacement string.
#
# ec = Encoding::Converter.new("utf-8", "us-ascii", :undef => :replace)
# ec.replacement = "<undef>"
# p ec.convert("a \u3042 b") #=> "a <undef> b"
#
def replacement=: (String str) -> String
# <!--
# rdoc-file=transcode.c
# - ec.source_encoding -> encoding
# -->
# Returns the source encoding as an Encoding object.
#
def source_encoding: () -> Encoding
private
# <!--
# rdoc-file=transcode.c
# - Encoding::Converter.new(source_encoding, destination_encoding)
# - Encoding::Converter.new(source_encoding, destination_encoding, opt)
# - Encoding::Converter.new(convpath)
# -->
# possible options elements:
# hash form:
# :invalid => nil # raise error on invalid byte sequence (default)
# :invalid => :replace # replace invalid byte sequence
# :undef => nil # raise error on undefined conversion (default)
# :undef => :replace # replace undefined conversion
# :replace => string # replacement string ("?" or "\uFFFD" if not specified)
# :newline => :universal # decorator for converting CRLF and CR to LF
# :newline => :crlf # decorator for converting LF to CRLF
# :newline => :cr # decorator for converting LF to CR
# :universal_newline => true # decorator for converting CRLF and CR to LF
# :crlf_newline => true # decorator for converting LF to CRLF
# :cr_newline => true # decorator for converting LF to CR
# :xml => :text # escape as XML CharData.
# :xml => :attr # escape as XML AttValue
# integer form:
# Encoding::Converter::INVALID_REPLACE
# Encoding::Converter::UNDEF_REPLACE
# Encoding::Converter::UNDEF_HEX_CHARREF
# Encoding::Converter::UNIVERSAL_NEWLINE_DECORATOR
# Encoding::Converter::CRLF_NEWLINE_DECORATOR
# Encoding::Converter::CR_NEWLINE_DECORATOR
# Encoding::Converter::XML_TEXT_DECORATOR
# Encoding::Converter::XML_ATTR_CONTENT_DECORATOR
# Encoding::Converter::XML_ATTR_QUOTE_DECORATOR
#
# Encoding::Converter.new creates an instance of Encoding::Converter.
#
# Source_encoding and destination_encoding should be a string or Encoding
# object.
#
# opt should be nil, a hash or an integer.
#
# convpath should be an array. convpath may contain
# * two-element arrays which contain encodings or encoding names, or
# * strings representing decorator names.
#
#
# Encoding::Converter.new optionally takes an option. The option should be a
# hash or an integer. The option hash can contain :invalid => nil, etc. The
# option integer should be logical-or of constants such as
# Encoding::Converter::INVALID_REPLACE, etc.
#
# :invalid => nil
# : Raise error on invalid byte sequence. This is a default behavior.
# :invalid => :replace
# : Replace invalid byte sequence by replacement string.
# :undef => nil
# : Raise an error if a character in source_encoding is not defined in
# destination_encoding. This is a default behavior.
# :undef => :replace
# : Replace undefined character in destination_encoding with replacement
# string.
# :replace => string
# : Specify the replacement string. If not specified, "uFFFD" is used for
# Unicode encodings and "?" for others.
# :universal_newline => true
# : Convert CRLF and CR to LF.
# :crlf_newline => true
# : Convert LF to CRLF.
# :cr_newline => true
# : Convert LF to CR.
# :xml => :text
# : Escape as XML CharData. This form can be used as an HTML 4.0 #PCDATA.
# * '&' -> '&'
# * '<' -> '<'
# * '>' -> '>'
# * undefined characters in destination_encoding -> hexadecimal CharRef
# such as &#xHH;
#
# :xml => :attr
# : Escape as XML AttValue. The converted result is quoted as "...". This form
# can be used as an HTML 4.0 attribute value.
# * '&' -> '&'
# * '<' -> '<'
# * '>' -> '>'
# * '"' -> '"'
# * undefined characters in destination_encoding -> hexadecimal CharRef
# such as &#xHH;
#
#
#
# Examples:
# # UTF-16BE to UTF-8
# ec = Encoding::Converter.new("UTF-16BE", "UTF-8")
#
# # Usually, decorators such as newline conversion are inserted last.
# ec = Encoding::Converter.new("UTF-16BE", "UTF-8", :universal_newline => true)
# p ec.convpath #=> [[#<Encoding:UTF-16BE>, #<Encoding:UTF-8>],
# # "universal_newline"]
#
# # But, if the last encoding is ASCII incompatible,
# # decorators are inserted before the last conversion.
# ec = Encoding::Converter.new("UTF-8", "UTF-16BE", :crlf_newline => true)
# p ec.convpath #=> ["crlf_newline",
# # [#<Encoding:UTF-8>, #<Encoding:UTF-16BE>]]
#
# # Conversion path can be specified directly.
# ec = Encoding::Converter.new(["universal_newline", ["EUC-JP", "UTF-8"], ["UTF-8", "UTF-16BE"]])
# p ec.convpath #=> ["universal_newline",
# # [#<Encoding:EUC-JP>, #<Encoding:UTF-8>],
# # [#<Encoding:UTF-8>, #<Encoding:UTF-16BE>]]
#
def initialize: (encoding source, encoding destination) -> void
| (encoding source, encoding destination,
?invalid: :replace | nil,
?undef: :replace | nil,
?replace: String,
?newline: :universal | :crlf | :cr,
?universal_newline: bool,
?crlf_newline: bool,
?cr_newline: bool,
?xml: :text | :attr
) -> void
| (encoding source, encoding destination, Integer opts) -> void
| (conversion_path convpath) -> void
end
# <!-- rdoc-file=transcode.c -->
# AFTER_OUTPUT
#
# Stop converting after some output is complete but before all of the input was
# consumed. See primitive_convert for an example.
#
Encoding::Converter::AFTER_OUTPUT: Integer
# <!-- rdoc-file=transcode.c -->
# CRLF_NEWLINE_DECORATOR
#
# Decorator for converting LF to CRLF
#
Encoding::Converter::CRLF_NEWLINE_DECORATOR: Integer
# <!-- rdoc-file=transcode.c -->
# CR_NEWLINE_DECORATOR
#
# Decorator for converting LF to CR
#
Encoding::Converter::CR_NEWLINE_DECORATOR: Integer
# <!-- rdoc-file=transcode.c -->
# INVALID_MASK
#
# Mask for invalid byte sequences
#
Encoding::Converter::INVALID_MASK: Integer
# <!-- rdoc-file=transcode.c -->
# INVALID_REPLACE
#
# Replace invalid byte sequences
#
Encoding::Converter::INVALID_REPLACE: Integer
# <!-- rdoc-file=transcode.c -->
# PARTIAL_INPUT
#
# Indicates the source may be part of a larger string. See primitive_convert
# for an example.
#
Encoding::Converter::PARTIAL_INPUT: Integer
# <!-- rdoc-file=transcode.c -->
# UNDEF_HEX_CHARREF
#
# Replace byte sequences that are undefined in the destination encoding with an
# XML hexadecimal character reference. This is valid for XML conversion.
#
Encoding::Converter::UNDEF_HEX_CHARREF: Integer
# <!-- rdoc-file=transcode.c -->
# UNDEF_MASK
#
# Mask for a valid character in the source encoding but no related character(s)
# in destination encoding.
#
Encoding::Converter::UNDEF_MASK: Integer
# <!-- rdoc-file=transcode.c -->
# UNDEF_REPLACE
#
# Replace byte sequences that are undefined in the destination encoding.
#
Encoding::Converter::UNDEF_REPLACE: Integer
# <!-- rdoc-file=transcode.c -->
# UNIVERSAL_NEWLINE_DECORATOR
#
# Decorator for converting CRLF and CR to LF
#
Encoding::Converter::UNIVERSAL_NEWLINE_DECORATOR: Integer
# <!-- rdoc-file=transcode.c -->
# XML_ATTR_CONTENT_DECORATOR
#
# Escape as XML AttValue
#
Encoding::Converter::XML_ATTR_CONTENT_DECORATOR: Integer
# <!-- rdoc-file=transcode.c -->
# XML_ATTR_QUOTE_DECORATOR
#
# Escape as XML AttValue
#
Encoding::Converter::XML_ATTR_QUOTE_DECORATOR: Integer
# <!-- rdoc-file=transcode.c -->
# XML_TEXT_DECORATOR
#
# Escape as XML CharData
#
Encoding::Converter::XML_TEXT_DECORATOR: Integer
# <!-- rdoc-file=error.c -->
# Raised by Encoding and String methods when the source encoding is incompatible
# with the target encoding.
#
class Encoding::CompatibilityError < EncodingError
end
# <!-- rdoc-file=transcode.c -->
# Raised by transcoding methods when a named encoding does not correspond with a
# known converter.
#
class Encoding::ConverterNotFoundError < EncodingError
end
# <!-- rdoc-file=transcode.c -->
# Raised by Encoding and String methods when the string being transcoded
# contains a byte invalid for the either the source or target encoding.
#
class Encoding::InvalidByteSequenceError < EncodingError
public
# <!--
# rdoc-file=transcode.c
# - ecerr.destination_encoding -> string
# -->
# Returns the destination encoding as an encoding object.
#
def destination_encoding: () -> Encoding
# <!--
# rdoc-file=transcode.c
# - ecerr.destination_encoding_name -> string
# -->
# Returns the destination encoding name as a string.
#
def destination_encoding_name: () -> String
# <!--
# rdoc-file=transcode.c
# - ecerr.error_bytes -> string
# -->
# Returns the discarded bytes when Encoding::InvalidByteSequenceError occurs.
#
# ec = Encoding::Converter.new("EUC-JP", "ISO-8859-1")
# begin
# ec.convert("abc\xA1\xFFdef")
# rescue Encoding::InvalidByteSequenceError
# p $! #=> #<Encoding::InvalidByteSequenceError: "\xA1" followed by "\xFF" on EUC-JP>
# puts $!.error_bytes.dump #=> "\xA1"
# puts $!.readagain_bytes.dump #=> "\xFF"
# end
#
def error_bytes: () -> String
# <!--
# rdoc-file=transcode.c
# - ecerr.incomplete_input? -> true or false
# -->
# Returns true if the invalid byte sequence error is caused by premature end of
# string.
#
# ec = Encoding::Converter.new("EUC-JP", "ISO-8859-1")
#
# begin
# ec.convert("abc\xA1z")
# rescue Encoding::InvalidByteSequenceError
# p $! #=> #<Encoding::InvalidByteSequenceError: "\xA1" followed by "z" on EUC-JP>
# p $!.incomplete_input? #=> false
# end
#
# begin
# ec.convert("abc\xA1")
# ec.finish
# rescue Encoding::InvalidByteSequenceError
# p $! #=> #<Encoding::InvalidByteSequenceError: incomplete "\xA1" on EUC-JP>
# p $!.incomplete_input? #=> true
# end
#
def incomplete_input?: () -> bool
# <!--
# rdoc-file=transcode.c
# - ecerr.readagain_bytes -> string
# -->
# Returns the bytes to be read again when Encoding::InvalidByteSequenceError
# occurs.
#
def readagain_bytes: () -> String
# <!--
# rdoc-file=transcode.c
# - ecerr.source_encoding -> encoding
# -->
# Returns the source encoding as an encoding object.
#
# Note that the result may not be equal to the source encoding of the encoding
# converter if the conversion has multiple steps.
#
# ec = Encoding::Converter.new("ISO-8859-1", "EUC-JP") # ISO-8859-1 -> UTF-8 -> EUC-JP
# begin
# ec.convert("\xa0") # NO-BREAK SPACE, which is available in UTF-8 but not in EUC-JP.
# rescue Encoding::UndefinedConversionError
# p $!.source_encoding #=> #<Encoding:UTF-8>
# p $!.destination_encoding #=> #<Encoding:EUC-JP>
# p $!.source_encoding_name #=> "UTF-8"
# p $!.destination_encoding_name #=> "EUC-JP"
# end
#
def source_encoding: () -> Encoding
# <!--
# rdoc-file=transcode.c
# - ecerr.source_encoding_name -> string
# -->
# Returns the source encoding name as a string.
#
def source_encoding_name: () -> String
end
# <!-- rdoc-file=transcode.c -->
# Raised by Encoding and String methods when a transcoding operation fails.
#
class Encoding::UndefinedConversionError < EncodingError
public
# <!--
# rdoc-file=transcode.c
# - ecerr.destination_encoding -> string
# -->
# Returns the destination encoding as an encoding object.
#
def destination_encoding: () -> Encoding
# <!--
# rdoc-file=transcode.c
# - ecerr.destination_encoding_name -> string
# -->
# Returns the destination encoding name as a string.
#
def destination_encoding_name: () -> String
# <!--
# rdoc-file=transcode.c
# - ecerr.error_char -> string
# -->
# Returns the one-character string which cause
# Encoding::UndefinedConversionError.
#
# ec = Encoding::Converter.new("ISO-8859-1", "EUC-JP")
# begin
# ec.convert("\xa0")
# rescue Encoding::UndefinedConversionError
# puts $!.error_char.dump #=> "\xC2\xA0"
# p $!.error_char.encoding #=> #<Encoding:UTF-8>
# end
#
def error_char: () -> String
# <!--
# rdoc-file=transcode.c
# - ecerr.source_encoding -> encoding
# -->
# Returns the source encoding as an encoding object.
#
# Note that the result may not be equal to the source encoding of the encoding
# converter if the conversion has multiple steps.
#
# ec = Encoding::Converter.new("ISO-8859-1", "EUC-JP") # ISO-8859-1 -> UTF-8 -> EUC-JP
# begin
# ec.convert("\xa0") # NO-BREAK SPACE, which is available in UTF-8 but not in EUC-JP.
# rescue Encoding::UndefinedConversionError
# p $!.source_encoding #=> #<Encoding:UTF-8>
# p $!.destination_encoding #=> #<Encoding:EUC-JP>
# p $!.source_encoding_name #=> "UTF-8"
# p $!.destination_encoding_name #=> "EUC-JP"
# end
#
def source_encoding: () -> Encoding
# <!--
# rdoc-file=transcode.c
# - ecerr.source_encoding_name -> string
# -->
# Returns the source encoding name as a string.
#
def source_encoding_name: () -> String
end