Character Encoding Conversion (X)

The X conversion code applies a character encoding.

The format of the conversion code is

Xname

Xname.modes

where

name	is the name of the encoding to be applied.

modes

is a list of case insensitive mode qualifiers to the specified encoding, each represented by a single character. The modes are separated from the name by a period.

Used as an output conversion, the X conversion code takes internal data and encodes it to an external representation such as UTF-8. Used as an input conversion, the data is transformed from its external representation to a QM character string. Although primarily intended for use on ECS mode systems, the X conversion code is supported on non-ECS mode systems but limited to the 8 bit character set.

See Character Encodings for a description of the built-in encodings.

Users can add their own encodings by cataloguing a pair of QMBasic subroutines named ENCODE.name and DECODE.name where name is the encoding name to be defined. These subroutines should be declared as

SUBROUTINE ENCODE.name(RESULT, STR, MODES, STATUS)

and

SUBROUTINE DECODE.name(RESULT, STR, MODES, STATUS)

where

RESULT

is the returned encoded / decoded data

STR	is the data string to transform

MODES

is the modes qualifier from the conversion code

STATUS

is set to the value to be returned by the STATUS() function after the conversion.

Encodings defined in this way can be used in all places where a character encoding name is used by QM.

The status value returned by the subroutine should follow the standard rules for conversion codes:

0	Successful

1	Data cannot be converted

2	Conversion code not recognised

3	Data converted may be faulty. This might be used, for example, where an input conversion on a non-ECS system yields a character outside the 8 bit set that has been replaced by some substitute character.