A function identified as deprecated has been superseded and may become unsupported in the future.
Creates an object encapsulating locale and text-break information, for the purpose of finding boundaries in Unicode text. (Deprecated in Mac OS X v10.6. Use CFStringTokenizer (for locale-sensitive word, line, paragraph, and sentence breaks) and CFStringGetRangeOfComposedCharactersAtIndex (for cluster breaks) instead.)
OSStatus UCCreateTextBreakLocator ( LocaleRef locale, LocaleOperationVariant opVariant, UCTextBreakType breakTypes, TextBreakLocatorRef *breakRef );
A valid LocaleRef representing a specific locale, or pass NULL to request the default system locale. You can supply the value kUnicodeTextBreakClass in the opClass parameter of the Locales Utilities functions LocaleOperationCountLocales and LocaleOperationGetLocales to obtain the locales available for finding text boundaries on the current system.
A LocaleOperationVariant value identifying a text-break operation variant within the locale specified in the locale parameter. You can also pass 0 to request the default text-break variant for any locale. To obtain the varieties of locale-specific text-break variants that are currently available, you can supply the value kUnicodeTextBreakClass in the opClass parameter of the Locales Utilities functions LocaleOperationCountLocales and LocaleOperationGetLocales.
A UCTextBreakType value specifying each type of text boundary that the text-break locator should support. You do not need to create a text-break locator solely for the BreakChar type; it is locale-independent and automatically supported by the function UCFindTextBreak. If BreakChar is the only type for which you call the UCCreateTextBreakLocator function, on return the breakRef parameter returns a NULL value (with no error).
A pointer to a value of type TextBreakLocatorRef. On return, the TextBreakLocatorRef value contains a valid reference to a new text-break locator object.
A result code. The function can return memory errors and paramErr (for example, if the breakRef parameter is NULL or if invalid bits are set in the breakTypes parameter). It can also return resource errors in Mac OS 9 and CarbonLib.
To find boundaries in Unicode text, you must supply locale and text-break specifications to the function UCFindTextBreak. You provide this information by means of a text-break locator object, created via the UCCreateTextBreakLocator function. When finished with the text-break locator object, you should dispose of it using the function UCDisposeTextBreakLocator.
The UCCreateTextBreakLocator function creates a text-break locator object for a specified locale, a specified text-break variant within that locale, and a specified set of break types. The different types of breaks or boundaries in a line of Unicode text can include
Boundaries of characters (treating surrogate pairs as a single character).
Boundaries of character clusters. A cluster is a group of characters that should be treated as single text element for editing operations such as cursor movement. Typically this includes groups such as a base character followed by a sequence of combining characters, for example, a Hangul syllable represented as a sequence of conjoining jamo characters or an Indic consonant cluster.
Boundaries of words. This can be used to determine what to highlight as the result of a double-click.
Potential line break locations.
This function can move memory.
UnicodeUtilities.hDisposes a text-break locator object. (Deprecated in Mac OS X v10.6. Use CFStringTokenizer (for locale-sensitive word, line, paragraph, and sentence breaks) and CFStringGetRangeOfComposedCharactersAtIndex (for cluster breaks) instead.)
OSStatus UCDisposeTextBreakLocator ( TextBreakLocatorRef *breakRef );
A reference to a valid text-break locator object. The UCDisposeTextBreakLocator function sets *breakRef to NULL.
A result code. This function can return paramErr, for example, if the breakRef parameter is NULL.
To find boundaries in Unicode text, you must supply locale and text-break specifications to the function UCFindTextBreak. You provide this information by means of a text-break locator object, created via the function UCCreateTextBreakLocator. When finished with the text-break locator object, you should dispose of it using the function UCDisposeTextBreakLocator.
UnicodeUtilities.hUses locale-specific text-break information to find boundaries in Unicode text. (Deprecated in Mac OS X v10.6. Use CFStringTokenizer (for locale-sensitive word, line, paragraph, and sentence breaks) and CFStringGetRangeOfComposedCharactersAtIndex (for cluster breaks) instead.)
OSStatus UCFindTextBreak ( TextBreakLocatorRef breakRef, UCTextBreakType breakType, UCTextBreakOptions options, const UniChar *textPtr, UniCharCount textLength, UniCharArrayOffset startOffset, UniCharArrayOffset *breakOffset );
A valid reference to a text-break locator object. If the type of boundary specified by the breakType parameter is BreakChar, you can pass NULL. You use the function UCCreateTextBreakLocator to obtain a text-break locator object reference. If non-NULL, the text-break locator object must support the type of boundary specified in the breakType parameter.
A value of type UCTextBreakType, with exactly one bit set to specify a single type of boundary to be located. Since support for finding character boundaries is locale-independent and built into the UCFindTextBreak function, if you specify BreakChar as the type of boundary, then the breakRef parameter is ignored and may be NULL.
A UCTextBreakOptions value to specify the operation of the UCFindTextBreak function. You can use text-break locator options to control some location-independent aspects of a text-boundary search. Note that if you do not specify any UCTextBreakOptions values, UCFindTextBreak searches forward, but assumes that the startOffset value refers to the character preceding the offset rather than the one at the offset. This can result in UCFindTextBreak returning an offset that is equal to the start offset.
A pointer to the initial character of the Unicode string to search.
The total count of Unicode characters in the string to search.
A UniCharArrayOffset value specifying the offset from which UCFindTextBreak is to begin searching for the next text boundary of the type specified in the breakType parameter. If startOffset == 0 then kUCTextBreakLeadingEdgeMask must be set in the options parameter; if startOffset == textLength then kUCTextBreakLeadingEdgeMask must not be set.
A pointer to a UniCharArrayOffset value. On return, the value pointed to by the breakOffset parameter is set to the offset of the text boundary located by UCFindTextBreak. In normal usage (when exactly one of kUCTextBreakLeadingEdgeMask and kUCTextBreakGoBackwardsMask are set), the result returned in breakOffset is not equal to that supplied in the startOffset parameter unless an error occurs (and the function result is other than noErr). However, when kUCTextBreakLeadingEdgeMask and kUCTextBreakGoBackwardsMask are both set or both clear, the result produced in breakOffset can be equal to the value of startOffset.
A result code. The text-break locator referenced by the breakRef parameter must support the type of boundary specified in the breakType parameter; otherwise, the function returns kUCTextBreakLocatorMissingType.
The UCFindTextBreak function starts from a specified offset in a text buffer, and then proceeds forward or backward (as requested) until it finds the next text boundary of a particular locale-specific type, using a given set of options. The different types of breaks or boundaries in a line of Unicode text can include
Boundaries of characters (treating surrogate pairs as a single character).
Boundaries of character clusters. A cluster is a group of characters that should be treated as single text element for editing operations such as cursor movement. Typically this includes groups such as a base character followed by a sequence of combining characters, for example, a Hangul syllable represented as a sequence of conjoining jamo characters or an Indic consonant cluster.
Boundaries of words. This can be used to determine what to highlight as the result of a double-click.
Potential line break locations.
Finding boundaries of characters is a locale-independent operation, and support for it is built directly into the UCFindTextBreak function. If that is the only type of text boundary that you wish to locate, it is not necessary to call UCCreateTextBreakLocator and create a text-break locator object.
When finished with the text-break locator object, dispose it using the function UCDisposeTextBreakLocator.
UnicodeUtilities.hLast updated: 2008-12-12
Mac OS X Reference Library Data Management: Strings, Text, & Fonts Unicode Utilities Reference