6.2 Conversion functions

The basics of the conversion are as follows:

#!r6rs
(import (vicare)
  (prefix (vicare iconv) iconv.))

(let* ((handle    (iconv.iconv-open
                    (iconv.iconv-encoding UTF-16BE) ;from
                    (iconv.iconv-encoding UTF-8)))  ;to
       (in.bv     (string->utf16 "ciao hello salut"
                    (endianness big)))
       (out.bv    (make-bytevector 16)))
  (let-values (((in.start out.start)
               (iconv.iconv! handle in.bv 0 #f out.bv 0 #f)))
    (utf8->string out.bv)))
⇒ "ciao hello salut"

The following bindings are exported by the (vicare iconv) library.

Function: iconv-open from to

Build and return a new conversion context object for the specified encodings. from and to must be enumeration sets of type enum-iconv-encoding. The returned handle must be finalised with iconv-close; this operation is automatically performed when the handle is garbage collected.

NOTE Beware of the order of the arguments! An error may be difficult to detect.

Function: iconv? obj

Return true if obj is an Iconv context object. Context objects are disjoint from the other Scheme objects.

Function: iconv-closed? context

Return #t if context is an Iconv context already closed; return #f otherwise.

Function: iconv-close context

Close the conversion context releasing all the associated resources. Applying this function multiple times to the same context object is safe: the first time the context is finalised, the subsequent times nothing happens.

Function: iconv! context in in.start in.past out out.start out.past

Convert a range of bytes from the bytevector in and store the result into a range of bytes in the bytevector out, according to the context specified by context.

in.start is a fixnum representing the input inclusive start index; in.past is a fixnum representing the input exclusive end index; out.start is a fixnum representing the output inclusive start index; out.past is a fixnum representing the output exclusive end index. They must be such that:

0 <= in.start  <= in.past  <= length(in)
0 <= out.start <= out.past <= length(out)

As special cases: if in.past is false, the input past index is the length of in; if out.past is false, the output past index is the length of out.

If the operation is successful return two values:

1. A fixnum representing the index of the first byte in in that was not consumed. If all the input range was processed: this value equals in.past.
2. A fixnum representing the index of the first byte in out that was not filled with output data. If all the output range was filled with output: this value equals out.past.

If an error occurs raise an exception.

NOTE Beware of the order of the arguments! An error may be difficult to detect.