`protocol Equatable`

Inheritance | View Protocol Hierarchy → |
---|---|

Import | `import Swift` |

### Instance Methods

func ==(_:rhs:)
Required

Returns a Boolean value indicating whether two values are equal.

Equality is the inverse of inequality. For any values `a`

and `b`

,
`a == b`

implies that `a != b`

is `false`

.

**Parameters:**
**lhs:** A value to compare.
**rhs:** Another value to compare.

#### Declaration

`func ==(lhs: Self, rhs: Self) -> Bool`

A type that can be compared for value equality.

Types that conform to the

`Equatable`

protocol can be compared for equality using the equal-to operator (`==`

) or inequality using the not-equal-to operator (`!=`

). Most basic types in the Swift standard library conform to`Equatable`

.Some sequence and collection operations can be used more simply when the elements conform to

`Equatable`

. For example, to check whether an array contains a particular value, you can pass the value itself to the`contains(_:)`

method when the array's element conforms to`Equatable`

instead of providing a closure that determines equivalence. The following example shows how the`contains(_:)`

method can be used with an array of strings.## Conforming to the Equatable Protocol

Adding

`Equatable`

conformance to your custom types means that you can use more convenient APIs when searching for particular instances in a collection.`Equatable`

is also the base protocol for the`Hashable`

and`Comparable`

protocols, which allow more uses of your custom type, such as constructing sets or sorting the elements of a collection.To adopt the

`Equatable`

protocol, implement the equal-to operator (`==`

) as a static method of your type. The standard library provides an implementation for the not-equal-to operator (`!=`

) for any`Equatable`

type, which calls the custom`==`

function and negates its result.As an example, consider a

`StreetAddress`

structure that holds the parts of a street address: a house or building number, the street name, and an optional unit number. Here's the initial declaration of the`StreetAddress`

type:Now suppose you have an array of addresses that you need to check for a particular address. To use the

`contains(_:)`

method without including a closure in each call, extend the`StreetAddress`

type to conform to`Equatable`

.The

`StreetAddress`

type now conforms to`Equatable`

. You can use`==`

to check for equality between any two instances or call the`Equatable`

-constrained`contains(_:)`

method.Equality implies substitutability---any two instances that compare equally can be used interchangeably in any code that depends on their values. To maintain substitutability, the

`==`

operator should take into account all visible aspects of an`Equatable`

type. Exposing nonvalue aspects of`Equatable`

types other than class identity is discouraged, and any thatareexposed should be explicitly pointed out in documentation.Since equality between instances of

`Equatable`

types is an equivalence relation, any of your custom types that conform to`Equatable`

must satisfy three conditions, for any values`a`

,`b`

, and`c`

:`a == a`

is always`true`

(Reflexivity)`a == b`

implies`b == a`

(Symmetry)`a == b`

and`b == c`

implies`a == c`

(Transitivity)Moreover, inequality is the inverse of equality, so any custom implementation of the

`!=`

operator must guarantee that`a != b`

implies`!(a == b)`

. The default implementation of the`!=`

operator function satisfies this requirement.## Equality is Separate From Identity

The identity of a class instance is not part of an instance's value. Consider a class called

`IntegerRef`

that wraps an integer value. Here's the definition for`IntegerRef`

and the`==`

function that makes it conform to`Equatable`

:The implementation of the

`==`

function returns the same value whether its two arguments are the same instance or are two different instances with the same integer stored in their`value`

properties. For example:Class instance identity, on the other hand, is compared using the triple-equals identical-to operator (

`===`

). For example: