---
title: "compare(_:options:range:locale:)"
framework: foundation
role: symbol
role_heading: Instance Method
path: "foundation/nsstring/compare(_:options:range:locale:)"
---

# compare(_:options:range:locale:)

Compares the string using the specified options and returns the lexical ordering for the range.

## Declaration

```swift
func compare(_ string: String, options mask: NSString.CompareOptions = [], range rangeOfReceiverToCompare: NSRange, locale: Any?) -> ComparisonResult
```

## Parameters

- `string`: The string with which to compare the range of the receiver specified by range. This value must not be nil. If this value is nil, the behavior is undefined and may change in future versions of macOS.
- `mask`: Options for the search—you can combine any of the following using a C bitwise OR operator: NSCaseInsensitiveSearch, NSLiteralSearch, NSNumericSearch. See https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Strings/introStrings.html#//apple_ref/doc/uid/10000035i for details on these options.
- `rangeOfReceiverToCompare`: The range of the receiver over which to perform the comparison. The range must not exceed the bounds of the receiver. important: Raises an NSRangeException if range exceeds the bounds of the receiver.
- `locale`: An instance of doc://com.apple.foundation/documentation/Foundation/NSLocale. To use the current locale, pass [doc://com.apple.foundation/documentation/Foundation/NSLocale doc://com.apple.foundation/documentation/Foundation/NSLocale/current]. For example, if you are comparing strings to present to the end-user, use the current locale. To use the system locale, pass nil.

## Return Value

Return Value Returns an ComparisonResult value that indicates the lexical ordering of a specified range within the receiver and a given string. ComparisonResult.orderedAscending if the substring of the receiver given by range precedes aString in lexical ordering for the locale given in dict, ComparisonResult.orderedSame if the substring of the receiver and aString are equivalent in lexical value, and ComparisonResult.orderedDescending if the substring of the receiver follows aString.

## Discussion

Discussion The locale argument affects both equality and ordering algorithms. For example, in some locales, accented characters are ordered immediately after the base; other locales order them after “z”.

## See Also

### Identifying and Comparing Strings

- [caseInsensitiveCompare(_:)](foundation/nsstring/caseinsensitivecompare(_:).md)
- [localizedCaseInsensitiveCompare(_:)](foundation/nsstring/localizedcaseinsensitivecompare(_:).md)
- [compare(_:)](foundation/nsstring/compare(_:).md)
- [localizedCompare(_:)](foundation/nsstring/localizedcompare(_:).md)
- [compare(_:options:)](foundation/nsstring/compare(_:options:).md)
- [compare(_:options:range:)](foundation/nsstring/compare(_:options:range:).md)
- [localizedStandardCompare(_:)](foundation/nsstring/localizedstandardcompare(_:).md)
- [hasPrefix(_:)](foundation/nsstring/hasprefix(_:).md)
- [hasSuffix(_:)](foundation/nsstring/hassuffix(_:).md)
- [isEqual(to:)](foundation/nsstring/isequal(to:).md)
- [hash](foundation/nsstring/hash.md)
- [NSString.CompareOptions](foundation/nsstring/compareoptions.md)
- [NSString.EncodingConversionOptions](foundation/nsstring/encodingconversionoptions.md)