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

Return type: String sink 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

Use writer to accept UTF-8 encoded data and write that data to a "value string sink", its first 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.

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

• bom: true if a Byte Order Mark (BOM) is to be written as the first character in the output, false otherwise.
• 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.

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 (i.e. larger than 0xFFFF), and characters whose UTF-16 encodings would be the value of half of a surrogate pair.

Usage Note

To use writer , you must import omffutf16.xmd into your program using a statement like this:

  import "omffutf16.xmd" prefixed by utf16.

(Please see the import topic for more on importing.)

Example

  ; Copy the file named by the first command-line argument to
  ; the file named by the second command-line argument, converting
  ; from UTF-8 encoding (the default) to UTF-16 encoding on the
  ; output file.
  import "omffutf16.xmd" prefixed by utf16.
  process
     set utf16.writer into file #args [2] to file #args [1]

Related Syntax    utf16.writer

Other Library Functions    utf16.reader    utf16.writer

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACY LIBRARIES ] [ ERRORS ]