Class Iconv
In: ext/iconv/iconv.c
Parent: Data

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.

Which coding systems are available is platform-dependent.

Examples

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

Document-method: Iconv::conv

Shorthand for

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

See Iconv.iconv.

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.

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

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.

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.

To view or add comments on this documentation, please go to the API wiki.

[Validate]