Re: Iconv#iconv returning wrong object (ri broken?)

On Mon, Nov 19, 2007 at 04:29:29PM +0900, Dirk Traulsen wrote:
> Today it returns a string,while the documentation describes a complete 
> different method which returns an array. It is already broken! 

Are you sure you understand how iconv works, particularly with
stateful encoding?

The class method takes multiple args (possibly), thus returns an array.
Also, because it does a complete conversion, where "complete" means that
the final object is nil, giving the encoder to dump any final internal
state.

The instance method doesn't return an array because it doesn't take
multiple args to convert, and is part of an ongoing sequence of
conversions. Each call returns a string. At the end of the conversion
you must call the instance method with nil.

You may find the docs more comprehensible here:

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi/trunk/ext/iconv/iconv.c?view=markup


Btw, to those who may be watching, ri appears to be broken, it doesn't
allow you to see the instance method.

~/bin % ri 'Iconv::iconv' | cat
----------------------------------------------------------- Iconv::iconv
      Iconv.iconv(to, from, *strs)
------------------------------------------------------------------------
     Shorthand for

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

     Parameters
     <tt>to, from</tt>: see Iconv.new

     <tt>strs</tt>:     strings to be converted

     Exceptions
     Exceptions thrown by Iconv.new, Iconv.open and Iconv#iconv.

~/bin % ri 'Iconv#iconv' | cat
------------------------------------------------------------ Iconv#iconv
      Iconv.iconv(to, from, *strs)
------------------------------------------------------------------------

  (SAME DOCS AS ABOVE, WHICH IS WRONG)