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.

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.

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));
}

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));
}

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;
}

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.

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]