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

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

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]
            

Related Topics
  • utf16.writer
Other Library Functions