Class: Iconv

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

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

Invoke Iconv.open with a block.

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

Shorthand for (2).
```
  Iconv.iconv(to, from, *input.to_a)
```

Simple conversion between two charsets.

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

Methods

charset_map close conv iconv iconv new open

Classes and Modules

Module Iconv::Failure
Class Iconv::BrokenLibrary
Class Iconv::IllegalSequence
Class Iconv::InvalidCharacter
Class Iconv::InvalidEncoding
Class Iconv::OutOfRange

Public Class methods

Iconv.charset_map

Returns the map from canonical name to system dependent name.

Iconv.iconv(to, from, *strs)

Document-method: Iconv::conv

Shorthand for

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

See Iconv.iconv.

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.

Iconv.new(to, from)

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

Iconv.open(to, from) { |iconv| ... }

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.

Public Instance methods

close()

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