A type that can be compared for value equality.
- Xcode 6.0.1+
- Swift Standard Library
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
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
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
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
Street 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
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
Street type to conform to
Street type now conforms to
Equatable. You can use
== to check for equality between any two instances or call the
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 that are exposed 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 == ais always
a == bimplies
b == a(Symmetry)
a == band
b == cimplies
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
Integer that wraps an integer value. Here’s the definition for
Integer and the
== function that makes it conform to
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: