Legacy Document

Inside Macintosh: Text /

Chapter 6 - Script Manager / Script Manager Reference

Routines / Transliteration

TransliterateText

The TransliterateText function converts characters from one subscript to the closest possible approximation in a different subscript within the same 2-byte script system. TransliterateText also performs uppercasing and lowercasing, with consideration for regional variants, in the Roman script system and on Roman text within 2-byte script systems.

FUNCTION TransliterateText (srcHandle: Handle; 
                            dstHandle: Handle; 
                            target: Integer; srcMask: LongInt; 
                            script: ScriptCode): OSErr;

srcHandle

A handle to the source text to be transliterated.

dstHandle

A handle to a buffer that, upon completion of the call, contains the transliterated text.

target

A value that specifies what kind of text the source text is to be transliterated into. The low byte of the target is the format to convert
to. The high byte contains modifiers, whose meanings depend on the script code.

srcMask

A bit array that specifies which parts of the source text are to be transliterated. A bit is set for each script system or subscript that should be converted.

script

A value that specifies the script system of the text to be transliterated. Constants for all defined script codes are listed on page 6-52. To specify the font script, pass smCurrentScript in this parameter.

DESCRIPTION

The types of conversions TransliterateText performs are described in the section "Transliteration" beginning on page 6-43.

The TransliterateText function converts all of the text that you pass it in the srcHandle parameter. It determines the length of the source text (in bytes) from the handle size.

Before calling TransliterateText, allocate a handle (of any size) to pass in the dstHandle parameter. The length of the transliterated text may be different (as when converting between 1-byte and 2-byte characters), and TransliterateText sets the size of the destination handle as required. It is your responsibility to dispose of the destination handle when you no longer need it.

The srcMask parameter is the source mask; it specifies which subscript(s) represented in the source text should be converted to the target format. In all script systems, the srcMask parameter may have the following values: smMaskAscii, smMaskNative, and smMaskAll, as described on page 6-46. In 2-byte script systems, additional values are recognized, as described on page 6-46.

The low-order byte of the target parameter is the target format; it determines what form the the text should be transliterated to. In all script systems, there are two currently supported values for target format: smTransAscii and smTransNative, as described on page 6-46. In 2-byte script systems, additional values are recognized, as described on page 6-47.

The high-order byte of the target parameter is the target modifier; it provides additional formatting instructions. In all script systems, there are two values for target modifer: smTransLower and smTransUpper, as described on page 6-47.

Note

Because the low-ASCII character set (character codes $20-$7F) is present in all script systems, you could theoretically use the TransliterateText function to convert characters from one script system into another completely different script system. You could transliterate from a native subscript into ASCII under one script system, and then transliterate from that ASCII into a native subscript under a different script system. Such a procedure is not recommended, however, because of the imperfect nature of phonetic translation. Furthermore, many script systems do not support transliteration from native subscripts to ASCII.

SPECIAL CONSIDERATIONS

TransliterateText may move memory; your application should not call this function at interrupt time.

If you pass smCurrentScript in the script parameter, the conversion performed by TransliterateText can be affected by the state of the font force flag. It is unaffected by the international resources selection flag.

Transliteration of a block of text does not work across script-run boundaries. Because the TransliterateText function requires transliteration tables that are in a script system's international resources, you need to call it anew for each script run in your text.

Currently, the Roman version of TransliterateText checks the source mask only to ensure that at least one of the bits corresponding to the smMaskAscii and smMaskNative constants is set.

The Arabic and Hebrew versions of TransliterateText perform case conversion only. They allow the target values smTransAscii and smTransNative only; otherwise, they behave like the Roman version.

The TransliterateText tables for 1-byte script systems reside in the script's string-manipulation ('itl2') resource, so they can reflect region-specific or language-specific differences in uppercase conventions. If the string-manipulation resource does not include these tables, TransliterateText exits without doing anything.

The TransliterateText tables for 2-byte script systems reside in the script's transliteration ('trsl') resource. If the 'trsl' resource does not include these tables, TransliterateText exits without doing anything.

The Japanese, Traditional Chinese, and Simplified Chinese versions of TransliterateText have two modes of operation:

• If either smMaskAscii or smMaskNative is specified in the source mask, and if the target is smTransAscii, and if either of the target modifiers is specified, TransliterateText performs the specified case conversion on both 1-byte and 2-byte Roman letters.
• Otherwise, TransliterateText performs conversions according to the target format values defined on page 6-47. Any combination of source masks and target format is permitted.

RESULT CODES

In addition to Memory Manager errors, TransliterateText can return the
following results:

noErr	0	No error
	-1	Illegal source or target, or 'itl2' could not be loaded