Extended maintenance of Ruby versions 1.8.7 and 1.9.2 ended on July 31, 2014. Read more

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, code samples, or clarification of the documentation.

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 bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus