Class | Iconv
In: | iconv/iconv.c
Parent: | Data

## Summary

Ruby extension for charset conversion.

## Abstract

Iconv is a wrapper class for the UNIX 95 `iconv()` function family, which translates string between various encoding systems.

See Open Group’s on-line documents for more details.

- `iconv.h`: www.opengroup.org/onlinepubs/007908799/xsh/iconv.h.html
- `iconv_open()`: www.opengroup.org/onlinepubs/007908799/xsh/iconv_open.html
- `iconv()`: www.opengroup.org/onlinepubs/007908799/xsh/iconv.html
- `iconv_close()`: www.opengroup.org/onlinepubs/007908799/xsh/iconv_close.html

Which coding systems are available is platform-dependent.

## Examples

1. Instantiate a new Iconv and use method Iconv#iconv.

         cd = Iconv.new(to, from)
         begin
           input.each { |s| output << cd.iconv(s) }
           output << cd.iconv(nil)                   # Don't forget this!
         ensure
           cd.close
         end

2. Invoke Iconv.open with a block.

         Iconv.open(to, from) do |cd|
           input.each { |s| output << cd.iconv(s) }
           output << cd.iconv(nil)
         end

3. Shorthand for (2).

         Iconv.iconv(to, from, *input.to_a)

4. Simple conversion between two charsets.

         converted_text = Iconv.new('iso-8859-15', 'utf-8').iconv(text)

### Methods

charset_map close conv iconv iconv new open

### Classes and Modules

Module Iconv::Failure
Class Iconv::IllegalSequence
Class Iconv::InvalidCharacter
Class Iconv::InvalidEncoding
Class Iconv::OutOfRange

### Public Class methods

Iconv.charset_map

Returns the map from canonical name to system dependent name.

Iconv.iconv(to, from, *strs)

Document-method: Iconv::conv

Shorthand for

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

See Iconv.iconv.

[Source]

    /*
     * Document-method: Iconv::conv
     * call-seq: Iconv.iconv(to, from, *strs)
     *
     * Shorthand for
     *   Iconv.iconv(to, from, str).join
     * See Iconv.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.iconv(to, from, *strs)

Shorthand for

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

### Parameters

`to, from`: | see Iconv.new
`strs`: | strings to be converted

### Exceptions

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

[Source]

    /*
     * Document-method: iconv
     * call-seq: Iconv.iconv(to, from, *strs)
     *
     * Shorthand for
     *   Iconv.open(to, from) { |cd|
     *     (strs + [nil]).collect { |s| cd.iconv(s) }
     *   }
     *
     * === Parameters
     *
     * <tt>to, from</tt>:: see Iconv.new
     * <tt>strs</tt>:: strings to be converted
     *
     * === Exceptions
     *
     * Exceptions thrown by Iconv.new, Iconv.open and Iconv#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));
    }

Iconv.new(to, from)

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

[Source]

    /*
     * Document-method: new
     * call-seq: Iconv.new(to, from)
     *
     * 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 <tt>iconv_open(3)</tt> 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;
    }

Iconv.open(to, from) { |iconv| ... }

Equivalent to Iconv.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.

[Source]

    /*
     * Document-method: open
     * call-seq: Iconv.open(to, from) { |iconv| ... }
     *
     * Equivalent to Iconv.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()

Finishes conversion.

After calling this, calling Iconv#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.

Iconv.iconv(to, from, *strs)

Shorthand for

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

### Parameters

`to, from`: | see Iconv.new
`strs`: | strings to be converted

### Exceptions

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

[Source]

    /*
     * Document-method: iconv
     * call-seq: iconv(str, start=0, length=-1)
     *
     * Converts string and returns the result.
     * * If +str+ is a String, converts <tt>str[start, length]</tt> 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);

        n1 = n2 = Qnil;
        rb_scan_args(argc, argv, "12", &str, &n1, &n2);

        return iconv_convert(VALUE2ICONV(cd), str,
    			 NIL_P(n1) ? 0 : NUM2INT(n1),
    			 NIL_P(n2) ? -1 : NUM2INT(n2),
    			 NULL);
    }

[Validate]