Carbon


CharacterType

Header: Script.h Carbon status: Supported

Returns a variety of information about the character represented by a given byte, including its type, class, orientation, direction, case, and size (in bytes).

SInt16 CharacterType (
    Ptr textBuf, 
    SInt16 textOffset, 
    ScriptCode script
);
Parameter descriptions
textBuf

A pointer to a text buffer containing the character to be examined.

textOffset

The offset to the location of the character to be examined. (It can be an offset to either the first or the second byte of a 2-byte character.) Offset is in bytes; the first byte of the first character has an offset of 0.

script

A value that specifies the script system the byte belongs to. Constants for all defined script codes are listed in “Script Codes”. To specify the font script, pass smCurrentScript in this parameter.

function result

An integer bit field that provides information about the requested character.

DISCUSSION

The CharacterType return value is an integer bit field that provides information about the requested character. The field has the following format:

The script system associated with the character you wish to examine must be enabled in order for any of these three functions to provide useful information.

For 1-byte script systems, the character-type tables reside in the string-manipulation ('itl2') resource and reflect region-specific or language-specific differences in uppercase conventions. The CharacterType function gets the tables from the string-manipulation resource using the GetIntlResource function.

For 2-byte script systems, the character-type tables reside in the encoding/rendering ('itl5') resource, not the string-manipulation resource. Whenever you call CharacterType, the necessary character-set encoding information is taken from the encoding/rendering resource. You cannot use the GetIntlResource function to access 2-byte character-type tables directly.

The Script Manager defines the recognized character types, character classes, and character modifiers (bits 12–15), with constants to describe them. The CharacterType field masks are described in“Character Type Field Masks”.

The Script Manager also defines a set of masks with which you can isolate each of the fields in the CharacterType return value. If you perform an AND operation with the CharacterType result and the mask for a particular field, you select only the bits in that field. Once you’ve done that, you can test the result, using the constants that represent the possible results.

CharacterType calls CharacterByteType to determine whether the byte at textOffset is a 1-byte character or the first byte or second byte of a 2-byte character. The larger the text buffer, the longer CharacterByteType takes to execute. To be most efficient, place the pointer textBuf at the beginning of the character of interest before calling CharacterType. (If you want to be compatible with older versions of CharacterType, also set textOffset to 1, rather than 0, for 2-byte characters.)

SPECIAL CONSIDERATIONS

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

If you specify smCurrentScript for the script parameter, CharacterType always assumes that the text in the buffer belongs to the font script. It is unaffected by the state of the font force flag or the international resources selection flag.

For 1-byte script systems, the character-type tables are in the string-manipulation ('itl2') resource. For 2-byte script systems, they are in the encoding/rendering ('itl5') resource. If the appropriate resource does not include these tables, CharacterType exits without doing anything.

Some Roman fonts (for example, Symbol) substitute other characters for the standard characters in the Standard Roman character set. Since the Roman script system CharacterType function assumes the Standard Roman character set, it may return inappropriate results for nonstandard characters.

VERSION NOTES

In versions of system software earlier than 7.0, the textOffset parameter to the CharacterType function must point to the second byte of a 2-byte character.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)