UCCreateCollator(_:_:_:_:)

Creates an object encapsulating locale and collation information, for the purpose of performing Unicode string comparison.

Declaration

func UCCreateCollator(_ locale: LocaleRef!, _ opVariant: LocaleOperationVariant, _ options: UCCollateOptions, _ collatorRef: UnsafeMutablePointer<CollatorRef?>!) -> OSStatus

Parameters

locale:
A valid LocaleRef representing a specific locale, or pass NULL to request the default system locale. You can supply the value kUnicodeCollationClass in the opClass parameter of the Locales Utilities functions LocaleOperationCountLocales and LocaleOperationGetLocales to obtain the locales available for collation on the current system.
opVariant:
A LocaleOperationVariant value identifying a collation variant within the locale specified in the locale parameter. You can also pass 0 to request the default collation variant for any locale. To obtain the varieties of locale-specific collation that are currently available, you can supply the value kUnicodeCollationClass in the opClass parameter of the Locales Utilities functions LocaleOperationCountLocales and LocaleOperationGetLocales.
options:
A UCCollateOptions value specifying any collation options that you want to use for the string comparison.
collatorRef:
A pointer to a value of type CollatorRef. On return, the CollatorRef value contains a valid reference to a new collator object.

Return Value

A result code. The function can return memory errors and paramErr, for example, if the collatorRef parameter is NULL. It can also return resource errors in Mac OS 9 and CarbonLib.

Discussion

To perform Unicode string comparison, you must supply locale and collation specifications to a collation function such as UCCompareText(_:_:_:_:_:_:_:). You provide this information by means of a collator object, created via the UCCreateCollator function. When finished with the collator object, you dispose of it using the function UCDisposeCollator(_:).

Special Considerations

The collator object is allocated in the current heap. This function can move memory.