UCCompareCollationKeys(_:_:_:_:_:_:)
Uses collation keys to compare Unicode strings.
Declaration
func UCCompareCollationKeys(_ key1Ptr: UnsafePointer<UCCollationValue>!, _ key1Length: Int, _ key2Ptr: UnsafePointer<UCCollationValue>!, _ key2Length: Int, _ equivalent: UnsafeMutablePointer<DarwinBoolean>!, _ order: UnsafeMutablePointer<Int32>!) -> OSStatusParameters
- key1Ptr:
A pointer to the collation key (a
UCCollationValuearray) for the first string to compare. You can obtain a collation key with the function 1390468 Ucgetcollationkey. The collation key supplied inkey1Ptrfor the first string must be generated with the same collator object as that used to generate the collation key supplied inkey2Ptrfor the second string. - key1Length:
An
ItemCountvalue specifying the actual length of the collation key supplied in thekey1Ptrparameter. You can obtain this value from the function 1390468 Ucgetcollationkey when you obtain the new collation key. - key2Ptr:
A pointer to the collation key (a
UCCollationValuearray) for the second string to compare. You can obtain a collation key with the function 1390468 Ucgetcollationkey. The collation key supplied inkey2Ptrfor the second string must be generated with the same collator object as that used to generate the collation key supplied inkey1Ptrfor the first string. - key2Length:
An
ItemCountvalue specifying the actual length of the collation key supplied in thekey2Ptrparameter. You can obtain this value from the function 1390468 Ucgetcollationkey when you obtain the new collation key. - equivalent:
A pointer to a
Booleanvalue or passNULL. On return,UCCompareCollationKeysproduces a value oftrueif the strings represented by the collation keys are equivalent for the options you have specified in the collator object. If you wish simply to sort a list of strings in order, using your specified options, you can passNULLfor theequivalentparameter and only use theorderparameter’s result. In this case, all available comparison criteria are used to put the strings in a deterministic order, even if they are considered “equivalent” for the options you have specified. Note that you can set either theequivalentor theorderparameters toNULL, but not both. - order:
A pointer to a signed, 32-bit integer value, or pass
NULL. If you wish simply to test the strings represented by the collation keys for equivalence, using your specified options (which can be much faster than determining ordering), you can passNULLfor theorderparameter and only use theequivalentparameter’s result. (Note that either theequivalentor theorderparameters may beNULL, but not both.
Return Value
A result code. This function can return paramErr, for example, if key1Ptr or key2Ptr are NULL.
Discussion
If you wish to compare the same strings several times, as when sorting a list of strings, it may be most efficient for you to derive a collation key for each string and then compare the collation keys. A collation key is a transformation of the string that depends on the collator object (that is, it depends on the locale, the collation variant if any, and the collation options).
Collation keys that are generated using the same collator object—but for different strings—can quickly be compared with each other, without further reference to the collator object or collation tables. The disadvantage is that the collation keys may be rather large. After you use the function UCGetCollationKey(_:_:_:_:_:_:) to create a collation key from a given string and collator object, you can call the UCCompareCollationKeys function to compare two collation keys that were generated with the same collator object.
If you are comparing different strings, it may be more efficient for you to call the function UCCompareText(_:_:_:_:_:_:_:) multiple times using the same collator object.
Note that collation keys should be used only in a runtime context. They should not be stored in a persistent state (such as to disk) because the format of a collation key could change in the future.