Class: Iconv

Inherits:

Data

• Object
• Data
• Iconv

Defined in:

ext/rubysl/iconv/iconv.c,
ext/rubysl/iconv/iconv.c

Overview

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.

• iconv.h: www.opengroup.org/onlinepubs/007908799/xsh/iconv.h.html

• iconv_open(): www.opengroup.org/onlinepubs/007908799/xsh/iconv_open.html

• iconv(): www.opengroup.org/onlinepubs/007908799/xsh/iconv.html

• iconv_close(): www.opengroup.org/onlinepubs/007908799/xsh/iconv_close.html

Which coding systems are available is platform-dependent.

Examples

1. Simple conversion between two charsets.

   converted_text = Iconv.conv('iso-8859-15', 'utf-8', text)
   

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

3. Invoke Iconv.open with a block.

   Iconv.open(to, from) do |cd|
     input.each { |s| output << cd.iconv(s) }
     output << cd.iconv(nil)
   end
   

4. Shorthand for (3).

   Iconv.iconv(to, from, *input.to_a)
   

Defined Under Namespace

Modules: Failure Classes: BrokenLibrary, IllegalSequence, InvalidCharacter, InvalidEncoding, OutOfRange

Class Method Summary

• .charset_map ⇒ Object

  Returns the map from canonical name to system dependent name.

• .conv(to, from, str) ⇒ Object

  Shorthand for Iconv.iconv(to, from, str).join See Iconv.iconv.

• .iconv(to, from, *strs) ⇒ Object

  Shorthand for Iconv.open(to, from) { |cd| (strs + [nil]).collect { |s| cd.iconv(s) } }.

• .open(to, from) {|iconv| ... } ⇒ Object

  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.

Instance Method Summary

• #close ⇒ Object

  Finishes conversion.

• #iconv(to, from, *strs) ⇒ Object

  Shorthand for Iconv.open(to, from) { |cd| (strs + [nil]).collect { |s| cd.iconv(s) } }.

• #new(to, from) ⇒ Object constructor

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

Constructor Details

#new(to, from) ⇒ Object

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

Class Method Details

.charset_map ⇒ Object

Returns the map from canonical name to system dependent name.

.conv(to, from, str) ⇒ Object

Shorthand for

Iconv.iconv(to, from, str).join

See Iconv.iconv.

.iconv(to, from, *strs) ⇒ Object

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.

.open(to, from) {|iconv| ... } ⇒ Object

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.

Yields:

• (iconv)

Instance Method Details

#close ⇒ Object

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.

#iconv(to, from, *strs) ⇒ Object

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.