In Files

  • iconv/iconv.c

Iconv

::BrokenLibrary

Detected a bug of underlying iconv(3) libray.

  • returns an error without setting errno properly

Public Class Methods

charset_map click to toggle source

Returns the map from canonical name to system dependent name.

conv(to, from, str) click to toggle source

Shorthand for

Iconv.iconv(to, from, str).join

See ::iconv.

 
               static VALUE
iconv_s_conv
    (self, to, from, str)
    VALUE self, to, from, str;
{
    struct iconv_env_t arg;

    arg.argc = 1;
    arg.argv = &str;
    arg.append = rb_str_append;
    arg.ret = rb_str_new(0, 0);
    arg.cd = iconv_create(to, from);
    return rb_ensure(iconv_s_convert, (VALUE)&arg, iconv_free, ICONV2VALUE(arg.cd));
}
iconv(to, from, *strs) click to toggle source

Shorthand for

Iconv.open(to, from) { |cd|
  (strs + [nil]).collect { |s| cd.iconv(s) }
}

Parameters ↑

to, from

see ::new

strs

strings to be converted

Exceptions ↑

Exceptions thrown by ::new, ::open and #iconv.

 
               static VALUE
iconv_s_iconv
    (argc, argv, self)
    int argc;
    VALUE *argv;
    VALUE self;
{
    struct iconv_env_t arg;

    if (argc < 2)               /* needs `to' and `from' arguments at least */
        rb_raise(rb_eArgError, "wrong number of arguments (%d for %d)", argc, 2);

    arg.argc = argc -= 2;
    arg.argv = argv + 2;
    arg.append = rb_ary_push;
    arg.ret = rb_ary_new2(argc);
    arg.cd = iconv_create(argv[0], argv[1]);
    return rb_ensure(iconv_s_convert, (VALUE)&arg, iconv_free, ICONV2VALUE(arg.cd));
}
new(to, from) click to toggle source

Creates new code converter from a coding-system designated with from to another one designated with to.

Parameters ↑

to

encoding name for destination

from

encoding name for source

Exceptions ↑

TypeError

if to or from aren't String

InvalidEncoding

if designated converter couldn't find out

SystemCallError

if iconv_open(3) fails

 
               static VALUE
iconv_initialize
    (self, to, from)
    VALUE self;
    VALUE to;
    VALUE from;
{
    iconv_free(check_iconv(self));
    DATA_PTR(self) = NULL;
    DATA_PTR(self) = (void *)ICONV2VALUE(iconv_create(to, from));
    return self;
}
open(to, from) { |iconv| ... } click to toggle source

Equivalent to ::new except that when it is called with a block, it yields with the new instance and closes it, and returns the result which returned from the block.

 
               static VALUE
iconv_s_open
    (self, to, from)
    VALUE self;
    VALUE to;
    VALUE from;
{
    VALUE cd = ICONV2VALUE(iconv_create(to, from));

    self = Data_Wrap_Struct(self, NULL, ICONV_FREE, (void *)cd);
    if (rb_block_given_p()) {
        return rb_ensure(rb_yield, self, (VALUE(*)())iconv_finish, self);
    }
    else {
        return self;
    }
}

Public Instance Methods

close() click to toggle source

Finishes conversion.

After calling this, calling #iconv will cause an exception, but multiple calls of close are guaranteed to end successfully.

Returns a string containing the byte sequence to change the output buffer to its initial shift state.

 
               static VALUE
iconv_finish
    (self)
    VALUE self;
{
    VALUE cd = check_iconv(self);

    if (!cd) return Qnil;
    DATA_PTR(self) = NULL;

    return rb_ensure(iconv_init_state, cd, iconv_free, cd);
}
iconv(str, start=0, length=-1) click to toggle source

Converts string and returns the result.

  • If str is a String, converts str[start, length] and returns the converted string.

  • If str is nil, places converter itself into initial shift state and just returns a string containing the byte sequence to change the output buffer to its initial shift state.

  • Otherwise, raises an exception.

Parameters ↑

str

string to be converted, or nil

start

starting offset

length

conversion length; nil or -1 means whole the string from start

Exceptions ↑

  • IconvIllegalSequence

  • IconvInvalidCharacter

  • IconvOutOfRange

Examples ↑

See the Iconv documentation.

 
               static VALUE
iconv_iconv
    (argc, argv, self)
    int argc;
    VALUE *argv;
    VALUE self;
{
    VALUE str, n1, n2;
    VALUE cd = check_iconv(self);
    long start = 0, length = 0, slen = 0;

    rb_scan_args(argc, argv, "12", &str, &n1, &n2);
    if (!NIL_P(str)) slen = RSTRING_LEN(StringValue(str));
    if (argc != 2 || !RTEST(rb_range_beg_len(n1, &start, &length, slen, 0))) {
        if (NIL_P(n1) || ((start = NUM2LONG(n1)) < 0 ? (start += slen) >= 0 : start < slen)) {
            if (NIL_P(n2)) {
                length = -1;
            }
            else if ((length = NUM2LONG(n2)) >= slen - start) {
                length = slen - start;
            }
        }
    }

    return iconv_convert(VALUE2ICONV(cd), str, start, length, NULL);
}

Commenting is here to help enhance the documentation. For example, sample code, or clarification of the documentation.

If you are posting code samples in your comments, please wrap them in "<pre><code class="ruby" > ... </code></pre>" markup in order to get syntax highlighting.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file a bug report so that it can be corrected for the next release. Thank you.

blog comments powered by Disqus