instance method Encoding::Converter#convert

与えられた文字列を変換して、変換できた結果を返します。引数の末尾の文字がバイト列の途中で終わっている場合、そのバイト列は変換器内に取り置かれます。変換を終了させるには Encoding::Converter#finish を呼びます。

Encoding::Converter を用いると、文字列の一部または全部を渡して変換を行うことができます。よって、不正なバイトを意識せずにストリームから読み出した文字列を変換したいときには Encoding::Converter が適します。

なお、Encoding::Converter#convert では、これらの例外を捕獲しても、例外を起こしたところから変換を再開することはできません。不正なバイトや変換先で未定義な文字をエスケープしたい場合やさらに細かい指定を行いたい場合は、Encoding::Converter#primitive_convert を用います。

[PARAM] source_string:

変換する文字列の一部または全部です。

[RETURN]

変換結果である文字列の一部または全部です。

[EXCEPTION] Encoding::InvalidByteSequenceError:

変換元のエンコーディングにおいて不正なバイト列があった場合に発生します。

[EXCEPTION] Encoding::UndefinedConversionError:

変換先のエンコーディングで未定義な文字があった場合に発生します。

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