Google

PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

Summary

Ruby extension for codeset conversion.

License

$Revision: 0.0 $
$Copyleft: (c) 1999-2001 Nobuyoshi.Nakada <nobu.nokada@softhome.net> $

This library is free software; you can redistribute it and/or modify it under the terms of Ruby's Lisence. See COPYING and/or COPYING.ja file in ruby distribtion.

Abstract

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

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

Which coding systems are available, it depends on the platform.

Classes & Modules

Iconv

Class methods

Iconv.new(to, from)

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

Parameters
to

coding-system name for destination.

from

coding-system name for source.

Exceptions
TypeError

if to or from aren't String

ArgumentError

if designated converter couldn't find out.

SystemCallError

when iconv_open(3) failed.

Iconv.open(to, from)

Equivalents to Iconv.new except with in the case of called with a block, yields with the new instance and closes it, and returns the result which returned from the block.

Iconv.iconv(to, from, *strs)

Shorthand for

Iconv.new(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 and Iconv#iconv.

Instance methods

Iconv#close

Finishes conversion.

  • After calling this, invoking method Iconv#iconv will cause exception, but multiple calls of close are guaranteed to end successfully.
  • Returns a string contains the byte sequence to change the output buffer to its initial shift state.
Iconv#iconv(str, [ start = 0, [ length = -1 ] ])

Converts string and returns converted one.

  • In the case of str is String, converts str[start, length]. Returns converted string.
  • In the case of str is nil, places converter itself into initial shift state and just returns a string contains the byte sequence to change the output buffer to its initial shift state.
  • Otherwise, causes exception.
Parameters
str

string to be converted or nil.

start

starting offset.

length

conversion length, nil or -1 means whole string from start.

Exceptions

Exceptions

Iconv::Failure

Base exceptional attributes from Iconv.

Instance methods

Iconv::Failure#success

Returns string(s) translated successfully until the exception occurred.

  • In the case of failure occurred within Iconv.iconv, returned value is an array of strings translated successfully preceding failure and the last element is string on the way.
Iconv::Failure#failed

Returns substring of the original string passed to Iconv that starts at the character caused the exception.

Iconv::Failure#inspect

Returns inspected string like as: #<type: "success", "failed">

Iconv::IllegalSequence

Exception in the case of any illegal sequence detected.

Superclass

ArgumentError

Included Modules

Iconv::Failure

Iconv::InvalidCharacter

Exception in the case of output coding system can't express the character.

Superclass

ArgumentError

Included Modules

Iconv::Failure

Iconv::OutOfRange

Iconv library internal error. Must not occur.

Superclass

RuntimeError

Included Modules

Iconv::Failure

Example

  1. Instantiate a new Iconv, 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.new with a block.

    Iconv.new(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)