function
|
Library: UTF-16 (OMFFUTF16)
Import : omffutf16.xmd |
Returns: A writable output target for streaming data. |
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.
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.)
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]