Summary

Ruby extension for codeset conversion.

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) {|cd| ...}

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.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.

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

Input conversion stopped due to an input byte that does not belong to the input codeset, or the output codeset does not contain the character.

Superclass

ArgumentError

Included Modules

Iconv::Failure

Iconv::InvalidCharacter

Input conversion stopped due to an incomplete character or shift sequence at the end of the input buffer.

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.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)