Important: The information in this document is obsolete and should not be used for new development.
TransliterateText
TheTransliterateText
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 conversionsTransliterateText
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 thesrcHandle
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 thedstHandle
parameter. The length of the transliterated text may be different (as when converting between 1-byte and 2-byte characters), andTransliterateText
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, thesrcMask
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
andsmTransNative
, 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 thescript
parameter, the conversion performed byTransliterateText
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 thesmMaskAscii
andsmMaskNative
constants is set.The Arabic and Hebrew versions of
TransliterateText
perform case conversion only. They allow the target valuessmTransAscii
andsmTransNative
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
orsmMaskNative
is specified in the source mask, and if the target issmTransAscii
, 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