Carbon


TruncateForUnicodeToText

Header: UnicodeConverter.h Carbon status: Supported

Identifies where your application can safely break a Unicode string to be converted to any encoding so that the string is broken in a way that preserves the text element integrity.

OSStatus TruncateForUnicodeToText (
    ConstUnicodeToTextInfo iUnicodeToTextInfo, 
    ByteCount iSourceLen, 
    ConstUniCharArrayPtr iSourceStr, 
    OptionBits iControlFlags, 
    ByteCount iMaxLen, 
    ByteCount *oTruncatedLen
);
Parameter descriptions
iUnicodeToTextInfo

A Unicode converter object UnicodeToTextInfo for the Unicode string to be divided up. The TruncateForUnicodeToText function does not modify the contents of this private structure.

iSourceLen

The length in bytes of the Unicode string to be divided up.

iSourceStr

A pointer to the Unicode string to be divided up.

iControlFlags

Truncation control flags. Specify the flag kUnicodeStringUnterminatedMask if truncating a buffer of text that belongs to a longer stream containing a subsequent buffer of text that could have characters belonging to a text element that begins at the end of the current buffer. If you set this flag, typically you would set the iMaxLen parameter equal to iSourceLen.

iMaxLen

The maximum allowable length of the string to be truncated. This must be less than or equal to iSourceLen.

oTruncatedLen

A pointer to a value of type ByteCount. On return, this value contains the length of the longest portion of the Unicode source string, pointed to by the iSourceStr parameter, that is less than or equal to the value of the iMaxLen parameter. This returned parameter identifies the byte after which you can truncate the string.

function result

A result code.

DISCUSSION

Your application can use this function to divide up a Unicode string properly truncating each portion before you call ConvertFromUnicodeToText or ConvertFromUnicodeToScriptCodeRun to convert the string. You can call this function repeatedly to properly truncate a text segment, each time identifying the new beginning of the string, until the last portion of the text is less than or equal to the maximum allowable length. Each time you use the function, you get a properly terminated string within the allowable length range.

Because this function does not modify the contents of the Unicode converter object, you can call this function between conversion calls.

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 7/17/2000)