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 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:

• 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 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 utf16.omffutf16-version utf16.reader utf16.writer

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