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.

• iconv.h
• iconv_open()
• iconv()
• iconv_close()

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

• Iconv::IllegalSequence
• Iconv::InvalidCharacter
• Iconv::OutOfRange

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)