From: Nathan Beyer <nbeyer@...>
Date: 2012-07-19T10:08:54+09:00
Subject: what are the C extension analogs of String#force_encoding and String#encode?

Within C extension code, what are the appropriate C functions to use
that provide the equivalent functionality of String#force_encoding and
String#encode? I wasn't able to find anything in the README.EXT
(http://svn.ruby-lang.org/repos/ruby/tags/v1_9_3_194/README.EXT).

= String#force_encoding
Based on these articles [1] [2], it seems as though the the suggested
approach for forcing an encoding change in a C extension is to use the
'rb_enc_associate_index' function defined in 'ruby/encoding.h'. Is
that accurate?

The implementation of String#force_encoding does a bit more than that:

static VALUE
rb_str_force_encoding(VALUE str, VALUE enc)
{
    str_modifiable(str);
    rb_enc_associate(str, rb_to_encoding(enc));
    ENC_CODERANGE_CLEAR(str);
    return str;
}

This implementation adds an invocation of the ENC_CODERANGE_CLEAR
macro and I'm not clear on what this does or when/why it would be
needed.

= String#encode
I wasn't able to find any documentation about String transcoding
within C extensions. Based on the implementation of String#encode,
there seems to be a function 'rb_str_encode' in 'ruby/encoding.h' that
might be appropriate, but there's no documentation for the method and
I couldn't completely reverse engineer how the 'ecflags' and 'ecopts'
arguments are used.

-Nathan

[1] http://yugui.jp/articles/838
[2] http://tenderlovemaking.com/2009/06/26/string-encoding-in-ruby-1-9-c-extensions.html