rbs 2.0.0 → 2.1.0

data/core/encoding.rbs

@@ -1,101 +1,378 @@
+# <!-- 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-1986"=>"US-ASCII",
-  #           "SJIS"=>"Shift_JIS", "eucJP"=>"EUC-JP", "CP932"=>"Windows-31J"}
+  #     #=> {"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]
 
-  def self.compatible?: (untyped obj1, untyped obj2) -> Encoding?
-
-  # Returns default external encoding.
-  #
-  # The default external encoding is used by default for strings created
-  # from the following locations:
+  # <!--
+  #   rdoc-file=encoding.c
+  #   - Encoding.compatible?(obj1, obj2) -> enc or nil
+  # -->
+  # Checks the compatibility of two objects.
   #
-  #   - CSV
+  # 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.
   #
-  #   - [File](https://ruby-doc.org/core-2.6.3/File.html) data read from
-  #     disk
+  #     Encoding.compatible?("\xa1".force_encoding("iso-8859-1"), "b")
+  #     #=> #<Encoding:ISO-8859-1>
   #
-  #   - SDBM
+  #     Encoding.compatible?(
+  #       "\xa1".force_encoding("iso-8859-1"),
+  #       "\xa1\xa1".force_encoding("euc-jp"))
+  #     #=> nil
   #
-  #   - StringIO
+  # 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
   #
-  #   - Zlib::GzipReader
+  def self.compatible?: (untyped obj1, untyped obj2) -> Encoding?
+
+  # <!--
+  #   rdoc-file=encoding.c
+  #   - Encoding.default_external -> enc
+  # -->
+  # Returns default external encoding.
   #
-  #   - Zlib::GzipWriter
+  # The default external encoding is used by default for strings created from the
+  # following locations:
   #
-  #   - [String\#inspect](https://ruby-doc.org/core-2.6.3/String.html#method-i-inspect)
+  # *   CSV
+  # *   File data read from disk
+  # *   SDBM
+  # *   StringIO
+  # *   Zlib::GzipReader
+  # *   Zlib::GzipWriter
+  # *   String#inspect
+  # *   Regexp#inspect
   #
-  #   - [Regexp\#inspect](https://ruby-doc.org/core-2.6.3/Regexp.html#method-i-inspect)
   #
   # While strings created from these locations will have this encoding, the
-  # encoding may not be valid. Be sure to check
-  # [String\#valid\_encoding?](https://ruby-doc.org/core-2.6.3/String.html#method-i-valid_encoding-3F)
-  # .
+  # 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.
   #
-  # [File](https://ruby-doc.org/core-2.6.3/File.html) data written to disk
-  # will be transcoded to the default external encoding when written.
+  # 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.
   #
-  # The default external encoding is initialized by the locale or -E option.
   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
 
-  # 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:
+  # <!--
+  #   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
+  # *   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
   #
-  #   - Etc.sysconfdir and Etc.systmpdir
   #
-  #   - [File](https://ruby-doc.org/core-2.6.3/File.html) data read from
-  #     disk
+  # Additionally String#encode and String#encode! use the default internal
+  # encoding if no encoding is given.
   #
-  #   - [File](https://ruby-doc.org/core-2.6.3/File.html) names from
-  #     [Dir](https://ruby-doc.org/core-2.6.3/Dir.html)
+  # The script encoding (__ENCODING__), not default_internal, is used as the
+  # encoding of created strings.
   #
-  #   - [Integer\#chr](https://ruby-doc.org/core-2.6.3/Integer.html#method-i-chr)
+  # Encoding::default_internal is initialized with -E option or nil otherwise.
   #
-  #   - [String\#inspect](https://ruby-doc.org/core-2.6.3/String.html#method-i-inspect)
-  #     and
-  #     [Regexp\#inspect](https://ruby-doc.org/core-2.6.3/Regexp.html#method-i-inspect)
+  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.
   #
-  #   - Strings returned from Readline
+  # See Encoding::default_internal for information on how the default internal
+  # encoding is used.
   #
-  #   - Strings returned from SDBM
+  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.
   #
-  #   - [Time\#zone](https://ruby-doc.org/core-2.6.3/Time.html#method-i-zone)
+  #     Encoding.find("US-ASCII")  #=> #<Encoding:US-ASCII>
   #
-  #   - Values from [ENV](https://ruby-doc.org/core-2.6.3/ENV.html)
+  # Names which this method accept are encoding names and aliases including
+  # following special aliases
   #
-  #   - Values in ARGV including $PROGRAM\_NAME
+  # "external"
+  # :   default external encoding
+  # "internal"
+  # :   default internal encoding
+  # "locale"
+  # :   locale encoding
+  # "filesystem"
+  # :   filesystem encoding
   #
-  # Additionally
-  # [String\#encode](https://ruby-doc.org/core-2.6.3/String.html#method-i-encode)
-  # and
-  # [String\#encode\!](https://ruby-doc.org/core-2.6.3/String.html#method-i-encode-21)
-  # use the default internal encoding if no encoding is given.
   #
-  # The locale encoding (\_\_ENCODING\_\_), not
-  # [::default\_internal](Encoding.downloaded.ruby_doc#method-c-default_internal)
-  # , is used as the encoding of created strings.
+  # 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.
   #
-  # [::default\_internal](Encoding.downloaded.ruby_doc#method-c-default_internal)
-  # is initialized by the source file's internal\_encoding or -E option.
-  def self.default_internal: () -> Encoding?
-
-  def self.default_internal=: (String arg0) -> String?
-                            | (Encoding arg0) -> Encoding?
-                            | (nil arg0) -> nil
-
   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
@@ -103,49 +380,80 @@ class Encoding < Object
   #           "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.
   #
-  # ```ruby
-  # Encoding::UTF_8.ascii_compatible?     #=> true
-  # Encoding::UTF_16BE.ascii_compatible?  #=> false
-  # ```
+  #     Encoding::UTF_8.ascii_compatible?     #=> true
+  #     Encoding::UTF_16BE.ascii_compatible?  #=> false
+  #
   def ascii_compatible?: () -> bool
 
-  # 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.
+  # <!--
+  #   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
   #
-  # ```ruby
-  # 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.
   #
-  # ```ruby
-  # Encoding::UTF_8.name      #=> "UTF-8"
-  # ```
+  #     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.
   #
-  # ```ruby
-  # Encoding::WINDOWS_31J.names  #=> ["Windows-31J", "CP932", "csWindows31J"]
-  # ```
+  #     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.
   #
-  # ```ruby
-  # Encoding::UTF_8.name      #=> "UTF-8"
-  # ```
+  #     Encoding::UTF_8.name      #=> "UTF-8"
+  #
   def to_s: () -> String
 end
 
@@ -567,43 +875,130 @@ Encoding::Windows_31J: Encoding
 
 Encoding::Windows_874: Encoding
 
+# <!-- rdoc-file=transcode.c -->
+# Encoding conversion class.
+#
 class Encoding::Converter < Object
 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
 end
 
+# <!-- rdoc-file=transcode.c -->
+# Raised by Encoding and String methods when a transcoding operation fails.
+#
 class Encoding::UndefinedConversionError < EncodingError
 end