primitive_convert

        # Encoding::Converter.primitive_convert

(from ruby core)
### Implementation from Converter
---
    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"]