utf16-output-file

function

Library: Character encodings, international (OMEFIO)
Include: omefio.xin

Declaration

define external string sink function utf16-output-file
                value string filename
         endian value integer endian optional initial {0}
        add-bom value switch add-bom optional initial {true}
  exceptions-to value io-exception exceptions-to optional

Purpose

This function accepts UTF-8 encoded data and writes that data to the file named in the "filename" argument, converting the UTF-8 encoding to a UTF-16 encoding. The program writes out UTF-8, but the file receives UTF-16.

Arguments:

"filename". This is the name of the UTF-16 encoded file you want to write. If a zero-length "filename" is used (that is, ""), then utf16-output-file does not open a file, but writes to standard output. The zero-length "filename" option allows the conversion functionality to be used in an OmniMark program that is being used as a filter.
"endian". This optional argument determines the binary ordering of pairs of octets in the UTF-16 encoding (in the file). The default is the binary ordering option associated with the stream to which the external string sink function is attached.
"add-bom". When true, this optional argument indicates to the function that a leading Byte Order Mark (BOM) is to be written to the file, in addition to whatever data is written to the stream to which the external string source function is attached. When false, no BOM is written to the file (unless you write the UTF-8 encoding of a BOM to the stream). The default value for this argument is "true".
"exceptions-to". This optional argument indicates that errors are to be recorded in the passed "io-exception" object, and that the OmniMark program is not to be immediately terminated. There are three types of errors, categorized according to how they are handled:
- Whenever an invalid or out-of-range encoding is found, it is converted to the UTF-16 encoding of the Unicode "REPLACEMENT CHARACTER" (0xFFFD). If "exceptions-to" is specified, the "io-exception" object is marked for a data encoding error, and the function continues processing.
- If the external string source function cannot be created, either because the declaration does not match what is expected or because there is not enough memory to create the source object, an error is signaled to OmniMark, and your program is terminated.
- If "exceptions-to" is specified, then for any other type of error that occurs during memory allocation, file opening or closing, or reading or writing, the "io-exception" object is marked for the error found, and processing continues. If "exceptions-to" is not specified, an error is signaled to OmniMark and your program is terminated.

Example:

  ; Opening a stream to write UTF-16 encoded characters to a file.
  
  open my-utf16-output as utf16-output-file "widetext.txt"

Related Topics

Other Library Functions