intlTransliterateString

Converts a string between character sets.

Synopsis

int32 intlTransliterateString(const void *string,CharacterSets stringSet,void *result,CharacterSets resultSet,uint32 resultSize,uint8 unknownFiller);

Description

Converts a string between two character sets. This is typically used to convert a string from or to UniCode. The conversion is done as well as possible. If certain characters from the source string cannot be represented in the destination character set, the unknownFiller byte will be inserted in the result buffer in their place.

Arguments

string: The string to transliterate.

stringSet: The character set of the string to transliterate. This describes the interpretation of the bytes in the source string.

result: A memory buffer where the result of the transliteration can be put.

resultSet: The character set to use for the resulting string.

resultSize: The number of bytes available in the result buffer. This limits the number of bytes that are put into the buffer.

unknownFiller: If a character sequence cannot be adequately converted from the source character set, then this byte will be put into the result buffer in place of the character sequence. When converting to a 16-bit character set, then this byte will be extended to 16-bits and inserted.

Return Value

If positive, returns the number of characters in the result buffer. If negative, returns an error code.

> = 0: Number of characters in the result buffer.

INTL_ERR_BADSOURCEBUFFER

The string pointer supplied was bad.

INTL_ERR_BADCHARACTER

SET: The "stringSet" or "resultSet" arguments did not specify valid character sets.

INTL_ERR_BADRESULTBUFFER

The result buffer pointer was NULL or wasn't invalid writable memory.

INTL_ERR_BUFFERTOOSMALL

There was not enough room in the result buffer.

INTL_ERR_BADITEM: locItem was not an existing locale item.

Implementation

Folio call implemented in international folio V24.

Caveats

This function is not as smart as it could be. When converting from UniCode to ASCII, characters not in the first UniCode page (codes greater than 0x00ff) are never converted and always replaced with the unknownFiller byte. The upper pages of the UniCode set contain many characters which could be converted to equivalent ASCII characters, but these are not supported at this time.

Associated Files

intl.h