Protocol

OptionSet

A type that presents a mathematical set interface to a bit mask.

Overview

You use the OptionSet protocol to represent bit mask types, where individual bits represent members of the set. Adopting this protocol in your custom types lets you perform set-related operations such as membership tests, unions, and intersections on those types. What’s more, when implemented using specific criteria, adoption of this protocol requires no extra work on your part.

When creating an option set, include a rawValue property in your type declaration. The rawValue property must be of a type that conforms to the BitwiseOperations protocol, such as Int or UInt8. Next, create unique options as static properties of your custom type using unique powers of two (1, 2, 4, 8, 16, and so forth) for each individual property’s raw value so that each property can be represented by a single bit of the type’s raw value.

For example, consider a custom type called ShippingOptions that is an option set of the possible ways to ship a customer’s purchase. ShippingOptions includes a rawValue property of type Int that stores the bit mask of available shipping options. The static members NextDay, SecondDay, Priority, and Standard are unique, individual options.

struct ShippingOptions: OptionSet {
    let rawValue: Int

    static let nextDay    = ShippingOptions(rawValue: 1 << 0)
    static let secondDay  = ShippingOptions(rawValue: 1 << 1)
    static let priority   = ShippingOptions(rawValue: 1 << 2)
    static let standard   = ShippingOptions(rawValue: 1 << 3)

    static let express: ShippingOptions = [.nextDay, .secondDay]
    static let all: ShippingOptions = [.express, .priority, .standard]
}

Declare additional preconfigured option set values as static properties initialized with an array literal containing other option values. In the example, because the express static property is assigned an array literal with the nextDay and secondDay options, it will contain those two elements.

Using an Option Set Type

When you need to create an instance of an option set, assign one of the type’s static members to your variable or constant. Alternatively, to create an option set instance with multiple members, assign an array literal with multiple static members of the option set. To create an empty instance, assign an empty array literal to your variable.

let singleOption: ShippingOptions = .priority
let multipleOptions: ShippingOptions = [.nextDay, .secondDay, .priority]
let noOptions: ShippingOptions = []

Use set-related operations to check for membership and to add or remove members from an instance of your custom option set type. The following example shows how you can determine free shipping options based on a customer’s purchase price:

let purchasePrice = 87.55

var freeOptions: ShippingOptions = []
if purchasePrice > 50 {
    freeOptions.insert(.priority)
}

if freeOptions.contains(.priority) {
    print("You've earned free priority shipping!")
} else {
    print("Add more to your cart for free priority shipping!")
}
// Prints "You've earned free priority shipping!"

Protocol Requirements

Associated Types

Element

The element type of the option set.

Initializers

init(rawValue: Self.RawValue)

Creates a new option set from the given raw value.

Default Implementations

Initializers

init()

Creates an empty option set.

Instance Methods

func contains(Self)

Returns a Boolean value that indicates whether a given element is a member of the option set.

func formIntersection(Self)

Removes all elements of this option set that are not also present in the given set.

func formSymmetricDifference(Self)

Replaces this set with a new set containing all elements contained in either this set or the given set, but not in both.

func formUnion(Self)

Inserts the elements of another set into this option set.

func insert(Self.Element)

Adds the given element to the option set if it is not already a member.

func intersection(Self)

Returns a new option set with only the elements contained in both this set and the given set.

func remove(Self.Element)

Removes the given element and all elements subsumed by it.

func symmetricDifference(Self)

Returns a new option set with the elements contained in this set or in the given set, but not in both.

func union(Self)

Returns a new option set of the elements contained in this set, in the given set, or in both.

func update(with: Self.Element)

Inserts the given element into the set.

Relationships

Adopted By

See Also

Related Symbols

BitwiseOperations, SetAlgebra