Ruby 1.9.2 リファレンスマニュアル > ライブラリ一覧 > 組み込みライブラリ > Encoding::Converterクラス

class Encoding::Converter

クラスの継承リスト: Encoding::Converter < Object < Kernel < BasicObject

Abstract

特異メソッド

asciicompat_encoding(string) -> encoding | nil

asciicompat_encoding(encoding) -> encoding | nil

同じ文字集合を持つ ASCII 互換エンコーディングを返します。

[PARAM] string:

エンコーディング名

[PARAM] encoding:

エンコーディングオブジェクト

[RETURN]

ASCII 互換エンコーディングのオブジェクトか nil

引数とエンコーディングと同じ文字集合を持つ ASCII 互換エンコーディングを返します。引数と戻り値、2 つのエンコーディング間では変換しても未定義文字の例外は発生しません。 引数が ASCII 互換エンコーディングである場合や、エンコーディングでない場合は nil を返します。

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

new(source_encoding, destination_encoding)

new(source_encoding, destination_encoding, options)

new(convpath)

Encoding::Converter オブジェクトを作成します。

[PARAM] source_encoding:

変換元のエンコーディング

[PARAM] destination_encoding:

変換先のエンコーディング

[PARAM] options:

変換の詳細を指定する定数やハッシュ

[PARAM] convpath:

変換経路の配列

options では String#encode でのハッシュオプションに加えて、以下の定数が利用可能です。

• 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

インスタンスメソッド

convert(source_string) -> String

与えられた文字列を変換して、変換できた結果を返します。 引数の末尾の文字がバイト列の途中で終わっている場合、そのバイト列は変換器内に取り置かれます。 変換を終了させるには 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")

convpath -> Array

変換器が行う変換の経路を配列にして返します。

[RETURN]

変換器が行う変換の経路の配列

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

destination_encoding -> Encoding

変換先のエンコーディングを返します。

[RETURN]

変換先のエンコーディング

finish -> String

変換処理を終了し、結果文字列の末尾を返します。 変換元の文字列の末尾がバイト列の途中で終わっていた場合、

[RETURN]

変換結果の末尾

[EXCEPTION] Encoding::InvalidByteSequenceError:

ec = Encoding::Converter.new("utf-8", "iso-2022-jp")
p ec.convert("\u3042")     #=> "\e$B$\""
p ec.finish                #=> "\e(B"

insert_output(string)

変換器内のバッファに文字列を挿入します。 バッファに保持された文字列は、次の変換時の変換結果と一緒に返されます。

変換先がステートフルなエンコーディングであった場合、 挿入された文字列は状態に基づいて変換され、状態を更新します。

このメソッドは変換に際してエラーが発生した際にのみ利用されるべきです。

[PARAM] string:

挿入する文字列

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-20     22-JP"), ""]

inspect -> String

Encoding::Converter オブジェクトの情報を簡単に表示します。

[RETURN]

変換器の情報を簡単に可視化した文字列です。

last_error -> Exception | nil

直前に変換器で発生した例外に相当する例外オブジェクトを返します 直線の変換で例外が発生していない場合は nil を返します。

primitive_convert(source_buffer, destination_buffer) -> Symbol

primitive_convert(source_buffer, destination_buffer, destination_byteoffset) -> Symbol

primitive_convert(source_buffer, destination_buffer, destination_byteoffset, destination_bytesize) -> Symbol

primitive_convert(source_buffer, destination_buffer, destination_byteoffset, destination_bytesize, opttions) -> Symbol

エンコーディング変換のためのメソッドの中で、もっとも細かな扱いが可能なメソッドです。

可搬性を確保しつつ、不正なバイトや変換先で未定義な文字の扱いを細かに指定したいときは、Encoding::Converter#primitive_convert が唯一の方法になります。

[PARAM] source_buffer:

変換元文字列のバッファ

[PARAM] destination_buffer:

変換先文字列を格納するバッファ

[PARAM] destination_byteoffset:

変換先バッファでのオフセット

[PARAM] destination_bytesize:

変換先バッファの容量

[PARAM] options:

変換の詳細を指定する定数やハッシュ

[RETURN]

変換結果祖表す Symbol

options には以下が指定できます。

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

戻り値は以下のうちのどれかです。

• :invalid_byte_sequence
• :incomplete_input
• :undefined_conversion
• :after_output
• :destination_buffer_full
• :source_buffer_empty
• :finished

ec = Encoding::Converter.new("UTF-8", "EUC-JP")
src = "abc\x81あいう\u{20bb7}\xe3"
dst = ''

不正なバイトや変換先で未定義なバイトをエスケープしつつ変換する例です。以上のように、戻り値で分岐させつつ、Encoding::Converter#primitive_errinfo の情報を参照して処理していくことになります。

begin
  ret = ec.primitive_convert(src, dst)
  p [ret, src, dst, ec.primitive_errinfo]
  case ret
  when :invalid_byte_sequence
    ec.insert_output(ec.primitive_errinfo[3].dump[1..-2])
    redo
  when :undefined_conversion
    c = ec.primitive_errinfo[3].dup.force_encoding(ec.primitive_errinfo[1])
    ec.insert_output('\x{%X:%s}' % [c.ord, c.encoding])
    redo
  when :incomplete_input
    ec.insert_output(ec.primitive_errinfo[3].dump[1..-2])
  hen :finished
  end
  break
end while nil

primitive_errinfo -> Array

直前の Encoding::Converter#primitive_convert による変換の結果を保持する五要素の配列を返します。

[RETURN]

[result, enc1, enc2, error_bytes, readagain_bytes] という五要素の配列

result は直前の primitive_convert の戻り値です。 それ以外の四要素は :invalid_byte_sequence か :incomplete_input か :undefined_conversion だった場合に意味を持ちます。 enc1 はエラーの発生した原始変換の変換元のエンコーディング、enc2 は変換先のエンコーディングです。 error_bytes はエラーの発生原因となったバイト列、readagain_bytes は先読みによって変換器内部に保持されているバイト列です。

primitive_errinfo はもっぱら Encoding::Converter#primitive_convert と組み合わせて使います。Encoding::Converter#convert を用いている場合にも取得することはできますが、有用な使い方は難しいでしょう。

# \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", "UTF-8", "\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
#=> ""

putback -> String

putback(max_numbytes) -> String

後の変換用に変換器内部で保持しているバイト列をはき出します。

[PARAM] max_numbytes:

[RETURN]

格納されていたバイト列

replacement -> String

変換器に設定されている置換文字を返します。

[RETURN]

変換器に設定されている置換文字

ec = Encoding::Converter.new("euc-jp", "us-ascii")
p ec.replacement    #=> "?"

ec = Encoding::Converter.new("euc-jp", "utf-8")
p ec.replacement    #=> "\uFFFD"

replacement=(string)

置換文字を設定します。

[PARAM] string:

変換器に設定する置換文字

ec = Encoding::Converter.new("utf-8", "us-ascii", :undef => :replace)
ec.replacement = "<undef>"
p ec.convert("a \u3042 b")      #=> "a <undef> b"

source_encoding -> Encoding

変換元のエンコーディングを返します。

[RETURN]

変換元のエンコーディング