utf16.writer

function

Library: UTF-16 (OMFFUTF16)
Import : omffutf16.xmd

Returns: A writable output target for streaming data.


Declaration
export external string sink function 
   writer        bom value switch      add-bom         optional initial { true }
          big-endian value switch      make-big-endian optional initial { true }
                into value string sink output-data


Purpose

Use utf16.writer to accept UTF-8 encoded data and write that data to its value string sink output-data argument, converted from a UTF-8 encoding to a UTF-16 encoding. That is, the program writes UTF-8, but the provided output receives UTF-16.

utf16.writer has two further optional switch arguments, placed ahead of the output argument. true is the default value in both cases. The two arguments are:

Regardless of the value of add-bom, the BOM is only written out if data was written to utf16.writer.

Any malformed output data is written as a Unicode NOT-A-CHARACTER character (0xFFFD). The only malformed cases recognized are characters too large to be encodable as UTF-16 (that is, larger than 0xFFFF), and characters whose UTF-16 encodings would be the value of half of a surrogate pair.

Example

The following example will copy the file specified by the first command-line argument to the file specified by the second command-line option, converting from the UTF-8 encoding to UTF-16.

  import "omffutf16.xmd" prefixed by utf16.
  
  process
     set utf16.writer into file #args[2] to file #args[1]

Usage Note

To use utf16.writer, you must import OMFFUTF16 into your program using an import declaration such as:

  import "omffutf16.xmd" prefixed by utf16.

Other Library Functions