SetAlgebra

protocol SetAlgebra

A type that provides mathematical set operations.

You use types that conform to the SetAlgebra protocol when you need efficient membership tests or mathematical set operations such as intersection, union, and subtraction. In the standard library, you can use the Set type with elements of any hashable type, or you can easily create bit masks with SetAlgebra conformance using the OptionSet protocol. See those types for more information.

Note: Unlike ordinary set types, the Element type of an OptionSet is identical to the OptionSet type itself. The SetAlgebra protocol is specifically designed to accommodate both kinds of set.

Conforming to the SetAlgebra Protocol

When implementing a custom type that conforms to the SetAlgebra protocol, you must implement the required initializers and methods. For the inherited methods to work properly, conforming types must meet the following axioms. Assume that S is a custom type that conforms to the SetAlgebra protocol, x and y are instances of S, and e is of type S.Element---the type that the set holds.

  • S() == []
  • x.intersection(x) == x
  • x.intersection([]) == []
  • x.union(x) == x
  • x.union([]) == x
  • x.contains(e) implies x.union(y).contains(e)
  • x.union(y).contains(e) implies x.contains(e) || y.contains(e)
  • x.contains(e) && y.contains(e) if and only if x.intersection(y).contains(e) x.isSubset(of:** y) implies x.union(y) == y x.isSuperset(of:** y) implies x.union(y) == x x.isSubset(of:** y) if and only if y.isSuperset(of: x) x.isStrictSuperset(of:** y) if and only if x.isSuperset(of: y) && x != y **x.isStrictSubset(of:** y) if and only if x.isSubset(of: y) && x != y
Inheritance Equatable, ExpressibleByArrayLiteral View Protocol Hierarchy →
Associated Types
Element

A type for which the conforming type provides a containment test.

ArrayLiteralElement

The type of the elements of an array literal.

Import import Swift

Initializers

init() Required

Creates an empty set.

This initializer is equivalent to initializing with an empty array literal. For example, you create an empty Set instance with either this initializer or with an empty array literal.

var emptySet = Set<Int>()
print(emptySet.isEmpty)
// Prints "true"

emptySet = []
print(emptySet.isEmpty)
// Prints "true"

Declaration

init()
init(_:)

Creates a new set from a finite sequence of items.

Use this initializer to create a new set from an existing sequence, like an array or a range:

let validIndices = Set(0..<7).subtracting([2, 4, 5])
print(validIndices)
// Prints "[6, 0, 1, 3]"

sequence: The elements to use as members of the new set.

Declaration

init<S>(_ sequence: S)
init(arrayLiteral:) Required

Creates an instance initialized with the given elements.

Declaration

init(arrayLiteral elements: Self.ArrayLiteralElement...)

Declared In

ExpressibleByArrayLiteral

Instance Variables

var isEmpty: Bool

A Boolean value that indicates whether the set has no elements.

Declaration

var isEmpty: Bool { get }

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

Declared In

Equatable
func contains(_:) Required

Returns a Boolean value that indicates whether the given element exists in the set.

This example uses the contains(_:) method to test whether an integer is a member of a set of prime numbers.

let primes: Set = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37]
let x = 5
if primes.contains(x) {
    print("\(x) is prime!")
} else {
    print("\(x). Not prime.")
}
// Prints "5 is prime!"

member: An element to look for in the set. Returns: true if member exists in the set; otherwise, false.

Declaration

func contains(_ member: Self.Element) -> Bool
mutating func formIntersection(_:) Required

Removes the elements of this set that aren't also in the given set.

In the following example, the elements of the employees set that are not also members of the neighbors set are removed. In particular, the names "Alicia", "Chris", and "Diana" are removed.

var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
employees.formIntersection(neighbors)
print(employees)
// Prints "["Bethany", "Eric"]"

other: A set of the same type as the current set.

Declaration

mutating func formIntersection(_ other: Self)
mutating func formSymmetricDifference(_:) Required

Removes the elements of the set that are also in the given set and adds the members of the given set that are not already in the set.

In the following example, the elements of the employees set that are also members of neighbors are removed from employees, while the elements of neighbors that are not members of employees are added to employees. In particular, the names "Bethany" and "Eric" are removed from employees while the name "Forlani" is added.

var employees: Set = ["Alicia", "Bethany", "Diana", "Eric"]
let neighbors: Set = ["Bethany", "Eric", "Forlani"]
employees.formSymmetricDifference(neighbors)
print(employees)
// Prints "["Diana", "Forlani", "Alicia"]"

other: A set of the same type.

Declaration

mutating func formSymmetricDifference(_ other: Self)
mutating func formUnion(_:) Required

Adds the elements of the given set to the set.

In the following example, the elements of the visitors set are added to the attendees set:

var attendees: Set = ["Alicia", "Bethany", "Diana"]
let visitors: Set = ["Diana", "Marcia", "Nathaniel"]
attendees.formUnion(visitors)
print(attendees)
// Prints "["Diana", "Nathaniel", "Bethany", "Alicia", "Marcia"]"

If the set already contains one or more elements that are also in other, the existing members are kept.

var initialIndices = Set(0..<5)
initialIndices.formUnion([2, 3, 6, 7])
print(initialIndices)
// Prints "[2, 4, 6, 7, 0, 1, 3]"

other: A set of the same type as the current set.

Declaration

mutating func formUnion(_ other: Self)
mutating func insert(_:) Required

Inserts the given element in the set if it is not already present.

If an element equal to newMember is already contained in the set, this method has no effect. In this example, a new element is inserted into classDays, a set of days of the week. When an existing element is inserted, the classDays set does not change.

enum DayOfTheWeek: Int {
    case sunday, monday, tuesday, wednesday, thursday,
        friday, saturday
}

var classDays: Set<DayOfTheWeek> = [.wednesday, .friday]
print(classDays.insert(.monday))
// Prints "(true, .monday)"
print(classDays)
// Prints "[.friday, .wednesday, .monday]"

print(classDays.insert(.friday))
// Prints "(false, .friday)"
print(classDays)
// Prints "[.friday, .wednesday, .monday]"

newMember: An element to insert into the set. Returns: (true, newMember) if newMember was not contained in the set. If an element equal to newMember was already contained in the set, the method returns (false, oldMember), where oldMember is the element that was equal to newMember. In some cases, oldMember may be distinguishable from newMember by identity comparison or some other means.

Declaration

mutating func insert(_ newMember: Self.Element) -> (inserted: Bool, memberAfterInsert: Self.Element)
func intersection(_:) Required

Returns a new set with the elements that are common to both this set and the given set.

In the following example, the bothNeighborsAndEmployees set is made up of the elements that are in both the employees and neighbors sets. Elements that are in only one or the other are left out of the result of the intersection.

let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
let bothNeighborsAndEmployees = employees.intersection(neighbors)
print(bothNeighborsAndEmployees)
// Prints "["Bethany", "Eric"]"

other: A set of the same type as the current set. Returns: A new set.

Note: if this set and other contain elements that are equal but distinguishable (e.g. via ===), which of these elements is present in the result is unspecified.

Declaration

func intersection(_ other: Self) -> Self
func isDisjoint(with:)

Returns a Boolean value that indicates whether the set has no members in common with the given set.

In the following example, the employees set is disjoint with the visitors set because no name appears in both sets.

let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
let visitors: Set = ["Marcia", "Nathaniel", "Olivia"]
print(employees.isDisjoint(with: visitors))
// Prints "true"

other: A set of the same type as the current set. Returns: true if the set has no elements in common with other; otherwise, false.

Declaration

func isDisjoint(with other: Self) -> Bool
func isSubset(of:)

Returns a Boolean value that indicates whether the set is a subset of another set.

Set A is a subset of another set B if every member of A is also a member of B.

let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
let attendees: Set = ["Alicia", "Bethany", "Diana"]
print(attendees.isSubset(of: employees))
// Prints "true"

other: A set of the same type as the current set. Returns: true if the set is a subset of other; otherwise, false.

Declaration

func isSubset(of other: Self) -> Bool
func isSuperset(of:)

Returns a Boolean value that indicates whether the set is a superset of the given set.

Set A is a superset of another set B if every member of B is also a member of A.

let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
let attendees: Set = ["Alicia", "Bethany", "Diana"]
print(employees.isSuperset(of: attendees))
// Prints "true"

other: A set of the same type as the current set. Returns: true if the set is a superset of possibleSubset; otherwise, false.

Declaration

func isSuperset(of other: Self) -> Bool
mutating func remove(_:) Required

Removes the given element and any elements subsumed by the given element.

member: The element of the set to remove. Returns: For ordinary sets, an element equal to member if member is contained in the set; otherwise, nil. In some cases, a returned element may be distinguishable from newMember by identity comparison or some other means.

For sets where the set type and element type are the same, like OptionSet types, this method returns any intersection between the set and [member], or nil if the intersection is empty.

Declaration

mutating func remove(_ member: Self.Element) -> Self.Element?
mutating func subtract(_:)

Removes the elements of the given set from this set.

In the following example, the elements of the employees set that are also members of the neighbors set are removed. In particular, the names "Bethany" and "Eric" are removed from employees.

var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
employees.subtract(neighbors)
print(employees)
// Prints "["Diana", "Chris", "Alicia"]"

other: A set of the same type as the current set.

Declaration

mutating func subtract(_ other: Self)
func subtracting(_:)

Returns a new set containing the elements of this set that do not occur in the given set.

In the following example, the nonNeighbors set is made up of the elements of the employees set that are not elements of neighbors:

let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
let nonNeighbors = employees.subtracting(neighbors)
print(nonNeighbors)
// Prints "["Diana", "Chris", "Alicia"]"

other: A set of the same type as the current set. Returns: A new set.

Declaration

func subtracting(_ other: Self) -> Self
func symmetricDifference(_:) Required

Returns a new set with the elements that are either in this set or in the given set, but not in both.

In the following example, the eitherNeighborsOrEmployees set is made up of the elements of the employees and neighbors sets that are not in both employees and neighbors. In particular, the names "Bethany" and "Eric" do not appear in eitherNeighborsOrEmployees.

let employees: Set = ["Alicia", "Bethany", "Diana", "Eric"]
let neighbors: Set = ["Bethany", "Eric", "Forlani"]
let eitherNeighborsOrEmployees = employees.symmetricDifference(neighbors)
print(eitherNeighborsOrEmployees)
// Prints "["Diana", "Forlani", "Alicia"]"

other: A set of the same type as the current set. Returns: A new set.

Declaration

func symmetricDifference(_ other: Self) -> Self
func union(_:) Required

Returns a new set with the elements of both this and the given set.

In the following example, the attendeesAndVisitors set is made up of the elements of the attendees and visitors sets:

let attendees: Set = ["Alicia", "Bethany", "Diana"]
let visitors = ["Marcia", "Nathaniel"]
let attendeesAndVisitors = attendees.union(visitors)
print(attendeesAndVisitors)
// Prints "["Diana", "Nathaniel", "Bethany", "Alicia", "Marcia"]"

If the set already contains one or more elements that are also in other, the existing members are kept.

let initialIndices = Set(0..<5)
let expandedIndices = initialIndices.union([2, 3, 6, 7])
print(expandedIndices)
// Prints "[2, 4, 6, 7, 0, 1, 3]"

other: A set of the same type as the current set. Returns: A new set with the unique elements of this set and other.

Note: if this set and other contain elements that are equal but distinguishable (e.g. via ===), which of these elements is present in the result is unspecified.

Declaration

func union(_ other: Self) -> Self
mutating func update(with:) Required

Inserts the given element into the set unconditionally.

If an element equal to newMember is already contained in the set, newMember replaces the existing element. In this example, an existing element is inserted into classDays, a set of days of the week.

enum DayOfTheWeek: Int {
    case sunday, monday, tuesday, wednesday, thursday,
        friday, saturday
}

var classDays: Set<DayOfTheWeek> = [.monday, .wednesday, .friday]
print(classDays.update(with: .monday))
// Prints "Optional(.monday)"

newMember: An element to insert into the set. Returns: For ordinary sets, an element equal to newMember if the set already contained such a member; otherwise, nil. In some cases, the returned element may be distinguishable from newMember by identity comparison or some other means.

For sets where the set type and element type are the same, like OptionSet types, this method returns any intersection between the set and [newMember], or nil if the intersection is empty.

Declaration

mutating func update(with newMember: Self.Element) -> Self.Element?

Default Implementations

init(_:)

Creates a new set from a finite sequence of items.

Use this initializer to create a new set from an existing sequence, like an array or a range:

let validIndices = Set(0..<7).subtracting([2, 4, 5])
print(validIndices)
// Prints "[6, 0, 1, 3]"

sequence: The elements to use as members of the new set.

Declaration

init<S>(_ sequence: S)
var isEmpty: Bool

A Boolean value that indicates whether the set has no elements.

Declaration

var isEmpty: Bool { get }
func !=(_:rhs:)

Returns a Boolean value indicating whether two values are not equal.

Inequality is the inverse of equality. For any values a and b, a != b implies that a == b is false.

This is the default implementation of the not-equal-to operator (!=) for any type that conforms to Equatable.

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

Declaration

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

Declared In

Equatable
func isDisjoint(with:)

Returns a Boolean value that indicates whether the set has no members in common with the given set.

In the following example, the employees set is disjoint with the visitors set because no name appears in both sets.

let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
let visitors: Set = ["Marcia", "Nathaniel", "Olivia"]
print(employees.isDisjoint(with: visitors))
// Prints "true"

other: A set of the same type as the current set. Returns: true if the set has no elements in common with other; otherwise, false.

Declaration

func isDisjoint(with other: Self) -> Bool
func isStrictSubset(of:)

Returns a Boolean value that indicates whether this set is a strict subset of the given set.

Set A is a strict subset of another set B if every member of A is also a member of B and B contains at least one element that is not a member of A.

let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
let attendees: Set = ["Alicia", "Bethany", "Diana"]
print(attendees.isStrictSubset(of: employees))
// Prints "true"

// A set is never a strict subset of itself:
print(attendees.isStrictSubset(of: attendees))
// Prints "false"

other: A set of the same type as the current set. Returns: true if the set is a strict subset of other; otherwise, false.

Declaration

func isStrictSubset(of other: Self) -> Bool
func isStrictSuperset(of:)

Returns a Boolean value that indicates whether this set is a strict superset of the given set.

Set A is a strict superset of another set B if every member of B is also a member of A and A contains at least one element that is not a member of B.

let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
let attendees: Set = ["Alicia", "Bethany", "Diana"]
print(employees.isStrictSuperset(of: attendees))
// Prints "true"

// A set is never a strict superset of itself:
print(employees.isStrictSuperset(of: employees))
// Prints "false"

other: A set of the same type as the current set. Returns: true if the set is a strict superset of other; otherwise, false.

Declaration

func isStrictSuperset(of other: Self) -> Bool
func isSubset(of:)

Returns a Boolean value that indicates whether the set is a subset of another set.

Set A is a subset of another set B if every member of A is also a member of B.

let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
let attendees: Set = ["Alicia", "Bethany", "Diana"]
print(attendees.isSubset(of: employees))
// Prints "true"

other: A set of the same type as the current set. Returns: true if the set is a subset of other; otherwise, false.

Declaration

func isSubset(of other: Self) -> Bool
func isSuperset(of:)

Returns a Boolean value that indicates whether the set is a superset of the given set.

Set A is a superset of another set B if every member of B is also a member of A.

let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
let attendees: Set = ["Alicia", "Bethany", "Diana"]
print(employees.isSuperset(of: attendees))
// Prints "true"

other: A set of the same type as the current set. Returns: true if the set is a superset of other; otherwise, false.

Declaration

func isSuperset(of other: Self) -> Bool
mutating func subtract(_:)

Removes the elements of the given set from this set.

In the following example, the elements of the employees set that are also members of the neighbors set are removed. In particular, the names "Bethany" and "Eric" are removed from employees.

var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
employees.subtract(neighbors)
print(employees)
// Prints "["Diana", "Chris", "Alicia"]"

other: A set of the same type as the current set.

Declaration

mutating func subtract(_ other: Self)
func subtracting(_:)

Returns a new set containing the elements of this set that do not occur in the given set.

In the following example, the nonNeighbors set is made up of the elements of the employees set that are not elements of neighbors:

let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
let nonNeighbors = employees.subtract(neighbors)
print(nonNeighbors)
// Prints "["Diana", "Chris", "Alicia"]"

other: A set of the same type as the current set. Returns: A new set.

Declaration

func subtracting(_ other: Self) -> Self

Where ArrayLiteralElement == Element

init(arrayLiteral:)

Creates a set containing the elements of the given array literal.

Do not call this initializer directly. It is used by the compiler when you use an array literal. Instead, create a new set using an array literal as its value by enclosing a comma-separated list of values in square brackets. You can use an array literal anywhere a set is expected by the type context.

Here, a set of strings is created from an array literal holding only strings:

let ingredients: Set = ["cocoa beans", "sugar", "cocoa butter", "salt"]
if ingredients.isSuperset(of: ["sugar", "salt"]) {
    print("Whatever it is, it's bound to be delicious!")
}
// Prints "Whatever it is, it's bound to be delicious!"

arrayLiteral: A list of elements of the new set.

Declaration

init(arrayLiteral: Self.Element...)