Summary

Ruby extension for codeset conversion.

License

$Revision: 0.4.5.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 the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

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.
Iconv#iconv(str, [ start = 0, [ length = -1 ] ])
Converts string and returns converted one.
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.
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)