Character Encoding Conversion (X)

Character Encoding Conversion (X)

Top  Previous  Next

 

The X conversion code applies a character encoding.

 

 

The format of the conversion code is

 

Xname

Xname.modes

 

where

 

nameis the name of the encoding to be applied.

 

modesis 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

RESULTis the returned encoded / decoded data
STRis the data string to transform
MODESis the modes qualifier from the conversion code
STATUSis 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:

0Successful
1Data cannot be converted
2Conversion code not recognised
3Data 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.