protocol
OptionSet
Inheritance |
Equatable, ExpressibleByArrayLiteral, RawRepresentable, SetAlgebra
View Protocol Hierarchy →
|
---|---|
Associated Types |
The element type of the option set. To inherit all the default implementations from the
The raw type that can be used to represent all values of the conforming type. Every distinct value of the conforming type has a corresponding unique
value of the 1 inherited item hidden. (Show all) |
Import |
|
Initializers
Creates a new option set from the given raw value.
This initializer always succeeds, even if the value passed as rawValue
exceeds the static properties declared as part of the option set. This
example creates an instance of ShippingOptions
with a raw value beyond
the highest element, with a bit mask that effectively contains all the
declared static members.
let
extraOptions
=
ShippingOptions
(
rawValue
:
255
)
(
extraOptions
.
isStrictSuperset
(
of
: .
all
))
// Prints "true"
rawValue
: The raw value of the option set to create. Each bit
of rawValue
potentially represents an element of the option set,
though raw values may include bits that are not defined as distinct
values of the OptionSet
type.
Declaration
init
(
rawValue
:
Self
.
RawValue
)
Declared In
OptionSet
, RawRepresentable
Creates an instance initialized with the given elements.
Declaration
init
(
arrayLiteral
elements
:
Self
.
Element
...)
Declared In
ExpressibleByArrayLiteral
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.
Declaration
init
()
Declared In
SetAlgebra
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
])
(
validIndices
)
// Prints "[6, 0, 1, 3]"
sequence
: The elements to use as members of the new set.
Declaration
init
<
S
:
Sequence
where
S
.
Iterator
.
Element
==
Element
>
(
_
sequence
:
S
)
Declared In
SetAlgebra
3 inherited items hidden. (Show all)
Instance Variables
The corresponding value of the raw type.
A new instance initialized with rawValue
will be equivalent to this
instance. For example:
enum
PaperSize
:
String
{
case
A4
,
A5
,
Letter
,
Legal
}
let
selectedSize
=
PaperSize
.
Letter
(
selectedSize
.
rawValue
)
// Prints "Letter"
(
selectedSize
==
PaperSize
(
rawValue
:
selectedSize
.
rawValue
)!)
// Prints "true"
Declaration
var
rawValue
:
Self
.
RawValue
{
get
}
Declared In
RawRepresentable
A Boolean value that indicates whether the set has no elements.
Declaration
var
isEmpty
:
Bool
{
get
}
Declared In
SetAlgebra
2 inherited items hidden. (Show all)
Instance Methods
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
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
) {
(
"\(
x
) is prime!"
)
}
else
{
(
"\(
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
Declared In
SetAlgebra
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.
other
: A set of the same type as the current set.
Declaration
mutating
func
formIntersection
(
_
other
:
Self
)
Declared In
SetAlgebra
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 "Alicia"
, "Chris"
, and
"Diana"
are removed from employees
while the names "Forlani"
and
"Greta"
are added.
other
: A set of the same type.
Declaration
mutating
func
formSymmetricDifference
(
_
other
:
Self
)
Declared In
SetAlgebra
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:
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
])
(
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
)
Declared In
SetAlgebra
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
]
(
classDays
.
insert
(.
monday
))
// Prints "(true, .monday)"
(
classDays
)
// Prints "[.friday, .wednesday, .monday]"
(
classDays
.
insert
(.
friday
))
// Prints "(false, .friday)"
(
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
)
Declared In
SetAlgebra
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 either one or the other, but not both, are left out
of the result of the intersection.
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
Declared In
SetAlgebra
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.
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
Declared In
SetAlgebra
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.
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
Declared In
SetAlgebra
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.
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
Declared In
SetAlgebra
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
?
Declared In
SetAlgebra
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
.
other
: A set of the same type as the current set.
Declaration
mutating
func
subtract
(
_
other
:
Self
)
Declared In
SetAlgebra
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
:
other
: A set of the same type as the current set.
Returns: A new set.
Declaration
func
subtracting
(
_
other
:
Self
) -
>
Self
Declared In
SetAlgebra
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
.
other
: A set of the same type as the current set.
Returns: A new set.
Declaration
func
symmetricDifference
(
_
other
:
Self
) -
>
Self
Declared In
SetAlgebra
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
)
(
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
])
(
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
Declared In
SetAlgebra
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.
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
?
Declared In
SetAlgebra
16 inherited items hidden. (Show all)
Default Implementations
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
])
(
validIndices
)
// Prints "[6, 0, 1, 3]"
sequence
: The elements to use as members of the new set.
Declaration
init
<
S
:
Sequence
where
S
.
Iterator
.
Element
==
Element
>
(
_
sequence
:
S
)
Declared In
SetAlgebra
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"
]) {
(
"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
...)
Declared In
SetAlgebra
A Boolean value that indicates whether the set has no elements.
Declaration
var
isEmpty
:
Bool
{
get
}
Declared In
SetAlgebra
Returns a new option set with only the elements contained in both this set and the given set.
This example uses the intersection(_:)
method to limit the available
shipping options to what can be used with a PO Box destination.
// Can only ship standard or priority to PO Boxes
let
poboxShipping
:
ShippingOptions
= [.
standard
, .
priority
]
let
memberShipping
:
ShippingOptions
=
[.
standard
, .
priority
, .
secondDay
]
let
availableOptions
=
memberShipping
.
intersection
(
poboxShipping
)
(
availableOptions
.
contains
(.
priority
))
// Prints "true"
(
availableOptions
.
contains
(.
secondDay
))
// Prints "false"
other
: An option set.
Returns: A new option set with only the elements contained in both this
set and other
.
Declaration
func
intersection
(
_
other
:
Self
) -
>
Self
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.
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
Declared In
SetAlgebra
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.
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
Declared In
SetAlgebra
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.
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
Declared In
SetAlgebra
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.
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
Declared In
SetAlgebra
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.
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
Declared In
SetAlgebra
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
.
other
: A set of the same type as the current set.
Declaration
mutating
func
subtract
(
_
other
:
Self
)
Declared In
SetAlgebra
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
:
other
: A set of the same type as the current set.
Returns: A new set.
Declaration
func
subtracting
(
_
other
:
Self
) -
>
Self
Declared In
SetAlgebra
Returns a new option set with the elements contained in this set or in the given set, but not in both.
other
: An option set.
Returns: A new option set with only the elements contained in either
this set or other
, but not in both.
Declaration
func
symmetricDifference
(
_
other
:
Self
) -
>
Self
Returns a new option set of the elements contained in this set, in the given set, or in both.
This example uses the union(_:)
method to add two more shipping options
to the default set.
let
defaultShipping
=
ShippingOptions
.
standard
let
memberShipping
=
defaultShipping
.
union
([.
secondDay
, .
priority
])
(
memberShipping
.
contains
(.
priority
))
// Prints "true"
other
: An option set.
Returns: A new option set made up of the elements contained in this
set, in other
, or in both.
Declaration
func
union
(
_
other
:
Self
) -
>
Self
10 inherited items hidden. (Show all)
Where Element == Self
Returns a Boolean value that indicates whether a given element is a member of the option set.
This example uses the contains(_:)
method to check whether next-day
shipping is in the availableOptions
instance.
let
availableOptions
=
ShippingOptions
.
express
if
availableOptions
.
contains
(.
nextDay
) {
(
"Next day shipping available"
)
}
// Prints "Next day shipping available"
member
: The element to look for in the option set.
Returns: true
if the option set contains member
; otherwise,
false
.
Declaration
func
contains
(
_
member
:
Self
) -
>
Bool
Adds the given element to the option set if it is not already a member.
In the following example, the .secondDay
shipping option is added to
the freeOptions
option set if purchasePrice
is greater than 50.0. For
the ShippingOptions
declaration, see the OptionSet
protocol
discussion.
let
purchasePrice
=
87.55
var
freeOptions
:
ShippingOptions
= [.
standard
, .
priority
]
if
purchasePrice
>
50
{
freeOptions
.
insert
(.
secondDay
)
}
(
freeOptions
.
contains
(.
secondDay
))
// Prints "true"
newMember
: The element to insert.
Returns: (true, newMember)
if newMember
was not contained in
self
. Otherwise, returns (false, oldMember)
, where oldMember
is
the member of the set equal to newMember
.
Declaration
mutating
func
insert
(
_
newMember
:
Self
) -
>
(
inserted
:
Bool
,
memberAfterInsert
:
Self
)
Removes the given element and all elements subsumed by it.
In the following example, the .priority
shipping option is removed from
the options
option set. Attempting to remove the same shipping option
a second time results in nil
, because options
no longer contains
.priority
as a member.
var
options
:
ShippingOptions
= [.
secondDay
, .
priority
]
let
priorityOption
=
options
.
remove
(.
priority
)
(
priorityOption
== .
priority
)
// Prints "true"
(
options
.
remove
(.
priority
))
// Prints "nil"
In the next example, the .express
element is passed to remove(_:)
.
Although .express
is not a member of options
, .express
subsumes
the remaining .secondDay
element of the option set. Therefore,
options
is emptied and the intersection between .express
and
options
is returned.
let
expressOption
=
options
.
remove
(.
express
)
(
expressOption
== .
express
)
// Prints "false"
(
expressOption
== .
secondDay
)
// Prints "true"
member
: The element of the set to remove.
Returns: The intersection of [member]
and the set, if the
intersection was nonempty; otherwise, nil
.
Declaration
mutating
func
remove
(
_
member
:
Self
) -
>
Self
?
Inserts the given element into the set.
If newMember
is not contained in the set but subsumes current members
of the set, the subsumed members are returned.
var
options
:
ShippingOptions
= [.
secondDay
, .
priority
]
let
replaced
=
options
.
update
(
with
: .
express
)
(
replaced
== .
secondDay
)
// Prints "true"
Returns: The intersection of [newMember]
and the set if the
intersection was nonempty; otherwise, nil
.
Declaration
mutating
func
update
(
with
newMember
:
Self
) -
>
Self
?
Where RawValue : BitwiseOperations
Creates an empty option set.
This initializer creates an option set with a raw value of zero.
Declaration
init
()
Removes all elements of this option set that are not also present in the given set.
This method is implemented as a &
(bitwise AND) operation on the
two sets' raw values.
other
: An option set.
Declaration
mutating
func
formIntersection
(
_
other
:
Self
)
Replaces this set with a new set containing all elements contained in either this set or the given set, but not in both.
This method is implemented as a ^
(bitwise XOR) operation on the two
sets' raw values.
other
: An option set.
Declaration
mutating
func
formSymmetricDifference
(
_
other
:
Self
)
Inserts the elements of another set into this option set.
This method is implemented as a |
(bitwise OR) operation on the
two sets' raw values.
other
: An option set.
Declaration
mutating
func
formUnion
(
_
other
:
Self
)
A type that presents a mathematical set interface to a bit mask.
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. TherawValue
property must be of a type that conforms to theBitwiseOperations
protocol, such asInt
orUInt8
. 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 arawValue
property of typeInt
that stores the bit mask of available shipping options. The static membersNextDay
,SecondDay
,Priority
, andStandard
are unique, individual options.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 thenextDay
andsecondDay
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.
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:
See Also:
BitwiseOperations
,SetAlgebra