---
title: "UCCompareText(_:_:_:_:_:_:_:)"
framework: coreservices
role: symbol
role_heading: Function
path: coreservices/1390642-uccomparetext
---

# UCCompareText(_:_:_:_:_:_:_:)

Uses locale-specific collation information to compare Unicode strings.

## Declaration

```swift
func UCCompareText(_ collatorRef: CollatorRef!, _ text1Ptr: UnsafePointer<UniChar>!, _ text1Length: Int, _ text2Ptr: UnsafePointer<UniChar>!, _ text2Length: Int, _ equivalent: UnsafeMutablePointer<DarwinBoolean>!, _ order: UnsafeMutablePointer<Int32>!) -> OSStatus
```

## Parameters

- `collatorRef`: A valid reference to a collator object; NULL is not allowed. You can use the function doc://com.apple.documentation/documentation/coreservices/1390403-uccreatecollator to obtain a collator reference.
- `text1Ptr`: A pointer to the first Unicode string (a UniChar array) to compare.
- `text1Length`: The total count of Unicode characters in the first string being compared.
- `text2Ptr`: A pointer to the second Unicode string to compare.
- `text2Length`: The total count of Unicode characters in the second string being compared.
- `equivalent`: A pointer to a Boolean value or NULL. On return, UCCompareText produces a value of true if the strings 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 pass NULL for the equivalent parameter and only use the order parameter’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 the equivalent or the order parameters to NULL, but not both.
- `order`: A pointer to a signed, 32-bit integer value, or pass NULL. If you wish simply to test strings for equivalence, using your specified options (which can be much faster than determining ordering), you can pass NULL for the order parameter and only use the equivalent parameter’s result. (Note that either the equivalent or the order parameters may be NULL, but not both.

## Return Value

Return Value A result code.  The function can return paramErr (for example, if collatorRef, text1Ptr, or text2Ptr are NULL.

## Discussion

Discussion You can use the UCCompareText function to perform various types of string comparison for a given set of locale and collation specifications. You can  simply test whether two strings are equivalent   determine the relative ordering of two strings   check whether a given string is equivalent to any string in an ordered list  You can also call the UCCompareText function multiple times to compare different strings using the same collator object. If you wish to compare the same strings several times, as when sorting a list of strings, it may be more efficient for you to derive a collation key for each string and then compare the collation keys. For more on comparison using collation keys, see the functions  UCGetCollationKey(_:_:_:_:_:_:)  and  UCCompareCollationKeys(_:_:_:_:_:_:).

## See Also

### Comparing Unicode Strings

- [UCCreateCollator(_:_:_:_:)](coreservices/1390403-uccreatecollator.md)
- [UCGetCollationKey(_:_:_:_:_:_:)](coreservices/1390468-ucgetcollationkey.md)
- [UCCompareCollationKeys(_:_:_:_:_:_:)](coreservices/1390378-uccomparecollationkeys.md)
- [UCDisposeCollator(_:)](coreservices/1390435-ucdisposecollator.md)
- [UCCompareTextDefault(_:_:_:_:_:_:_:)](coreservices/1390472-uccomparetextdefault.md)
- [UCCompareTextNoLocale(_:_:_:_:_:_:_:)](coreservices/1390513-uccomparetextnolocale.md)