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:

add-bom: true if a byte order mark (BOM) is to be written as the first character in the output, false otherwise, and
make-big-endian: true if the output is to be written big endian. This is the default, because big endian is the Internet standard. If the output is to be written little endian, this argument is false.

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