iconv

# Summary

Ruby extension for codeset conversion.

## License

    $Revision: 0.4.5.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 the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

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