A collection whose elements are key-value pairs.
- Xcode 6.0.1+
- Swift Standard Library
A dictionary is a type of hash table, providing fast access to the entries it contains. Each entry in the table is identified using its key, which is a hashable type such as a string or number. You use that key to retrieve the corresponding value, which can be any object. In other languages, similar data types are known as hashes or associated arrays.
Create a new dictionary by using a dictionary literal. A dictionary literal is a comma-separated list of key-value pairs, in which a colon separates each key from its associated value, surrounded by square brackets. You can assign a dictionary literal to a variable or constant or pass it to a function that expects a dictionary.
Here’s how you would create a dictionary of HTTP response codes and their related messages:
response variable is inferred to have type
[Int: String]. The
Key type of the dictionary is
Int, and the
Value type of the dictionary is
To create a dictionary with no key-value pairs, use an empty dictionary literal (
Any type that conforms to the
Hashable protocol can be used as a dictionary’s
Key type, including all of Swift’s basic types. You can use your own custom types as dictionary keys by making them conform to the
Getting and Setting Dictionary Values
The most common way to access values in a dictionary is to use a key as a subscript. Subscripting with a key takes the following form:
Subscripting a dictionary with a key returns an optional value, because a dictionary might not hold a value for the key that you use in the subscript.
The next example uses key-based subscripting of the
response dictionary with two keys that exist in the dictionary and one that does not.
You can also update, modify, or remove keys and values from a dictionary using the key-based subscript. To add a new key-value pair, assign a value to a key that isn’t yet a part of the dictionary.
Update an existing value by assigning a new value to a key that already exists in the dictionary. If you assign
nil to an existing key, the key and its associated value are removed. The following example updates the value for the
404 code to be simply “Not found” and removes the key-value pair for the
500 code entirely.
In a mutable
Dictionary instance, you can modify in place a value that you’ve accessed through a keyed subscript. The code sample below declares a dictionary called
interesting with string keys and values that are integer arrays, then sorts each array in-place in descending order.
Iterating Over the Contents of a Dictionary
Every dictionary is an unordered collection of key-value pairs. You can iterate over a dictionary using a
in loop, decomposing each key-value pair into the elements of a tuple.
The order of key-value pairs in a dictionary is stable between mutations but is otherwise unpredictable. If you need an ordered collection of key-value pairs and don’t need the fast key lookup that
Dictionary provides, see the
Key type for an alternative.
You can search a dictionary’s contents for a particular value using the
first methods supplied by default implementation. The following example checks to see if
image contains any paths in the
Note that in this example,
image is subscripted using a dictionary index. Unlike the key-based subscript, the index-based subscript returns the corresponding key-value pair as a non-optional tuple.
A dictionary’s indices stay valid across additions to the dictionary as long as the dictionary has enough capacity to store the added values without allocating more buffer. When a dictionary outgrows its buffer, existing indices may be invalidated without any notification.
When you know how many new values you’re adding to a dictionary, use the
init(minimum initializer to allocate the correct amount of buffer.
Bridging Between Dictionary and NSDictionary
You can bridge between
NSDictionary using the
as operator. For bridging to be possible, the
Value types of a dictionary must be classes,
@objc protocols, or types that bridge to Foundation types.
NSDictionary always takes O(1) time and space. When the dictionary’s
Value types are neither classes nor
@objc protocols, any required bridging of elements occurs at the first access of each element. For this reason, the first operation that uses the contents of the dictionary may take O(n).
Dictionary first calls the
copy(with:) method (
- copy in Objective-C) on the dictionary to get an immutable copy and then performs additional Swift bookkeeping work that takes O(1) time. For instances of
NSDictionary that are already immutable,
copy(with:) usually returns the same dictionary in O(1) time; otherwise, the copying performance is unspecified. The instances of
Dictionary share buffer using the same copy-on-write optimization that is used when two instances of
Dictionary share buffer.