names=primitive_convert
visibility=public
kind=defined

--- 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, options) -> 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 = ''
  
  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])
    when :finished
    end
    break
  end while nil

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

