Generic Structure

KeyValuePairs

A lightweight collection of key-value pairs.

Declaration

@frozen struct KeyValuePairs<Key, Value>

Overview

Use a KeyValuePairs instance when you need an ordered collection of key-value pairs and don’t require the fast key lookup that the Dictionary type provides. Unlike key-value pairs in a true dictionary, neither the key nor the value of a KeyValuePairs instance must conform to the Hashable protocol.

You initialize a KeyValuePairs instance using a Swift dictionary literal. Besides maintaining the order of the original dictionary literal, KeyValuePairs also allows duplicates keys. For example:

let recordTimes: KeyValuePairs = ["Florence Griffith-Joyner": 10.49,
                                      "Evelyn Ashford": 10.76,
                                      "Evelyn Ashford": 10.79,
                                      "Marlies Gohr": 10.81]
print(recordTimes.first!)
// Prints "("Florence Griffith-Joyner", 10.49)"

Some operations that are efficient on a dictionary are slower when using KeyValuePairs. In particular, to find the value matching a key, you must search through every element of the collection. The call to firstIndex(where:) in the following example must traverse the whole collection to find the element that matches the predicate:

let runner = "Marlies Gohr"
if let index = recordTimes.firstIndex(where: { $0.0 == runner }) {
    let time = recordTimes[index].1
    print("\(runner) set a 100m record of \(time) seconds.")
} else {
    print("\(runner) couldn't be found in the records.")
}
// Prints "Marlies Gohr set a 100m record of 10.81 seconds."

Key-Value Pairs as a Function Parameter

When calling a function with a KeyValuePairs parameter, you can pass a Swift dictionary literal without causing a Dictionary to be created. This capability can be especially important when the order of elements in the literal is significant.

For example, you could create an IntPairs structure that holds a list of two-integer tuples and use an initializer that accepts a KeyValuePairs instance.

struct IntPairs {
    var elements: [(Int, Int)]

    init(_ elements: KeyValuePairs<Int, Int>) {
        self.elements = Array(elements)
    }
}

When you’re ready to create a new IntPairs instance, use a dictionary literal as the parameter to the IntPairs initializer. The KeyValuePairs instance preserves the order of the elements as passed.

let pairs = IntPairs([1: 2, 1: 1, 3: 4, 2: 1])
print(pairs.elements)
// Prints "[(1, 2), (1, 1), (3, 4), (2, 1)]"

Topics

Type Aliases

typealias KeyValuePairs.Element

The element type of a KeyValuePairs: a tuple containing an individual key-value pair.

typealias KeyValuePairs.Index

A type that represents a position in the collection.

typealias KeyValuePairs.Indices

A type that represents the indices that are valid for subscripting the collection, in ascending order.

typealias KeyValuePairs.Iterator

A type that provides the collection’s iteration interface and encapsulates its iteration state.

typealias KeyValuePairs.SubSequence

A sequence that represents a contiguous subrange of the collection’s elements.

Initializers

init(dictionaryLiteral: (Key, Value)...)

Creates a new KeyValuePairs instance from the given dictionary literal.

Instance Properties

var count: Int

The number of elements in the collection.

var debugDescription: String

A string that represents the contents of the dictionary, suitable for debugging.

var description: String

A string that represents the contents of the dictionary.

var endIndex: KeyValuePairs<Key, Value>.Index

The collection’s “past the end” position—that is, the position one greater than the last valid subscript argument.

var first: (key: Key, value: Value)?

The first element of the collection.

var indices: Range<Int>

The indices that are valid for subscripting the collection, in ascending order.

var isEmpty: Bool

A Boolean value indicating whether the collection is empty.

var last: (key: Key, value: Value)?

The last element of the collection.

var lazy: LazySequence<KeyValuePairs<Key, Value>>

A sequence containing the same elements as this sequence, but on which some operations, such as map and filter, are implemented lazily.

var startIndex: KeyValuePairs<Key, Value>.Index

The position of the first element in a nonempty collection.

var underestimatedCount: Int

A value less than or equal to the number of elements in the collection.

Instance Methods

func allSatisfy(((key: Key, value: Value)) -> Bool) -> Bool

Returns a Boolean value indicating whether every element of a sequence satisfies a given predicate.

func compactMap<ElementOfResult>(((key: Key, value: Value)) -> ElementOfResult?) -> [ElementOfResult]

Returns an array containing the non-nil results of calling the given transformation with each element of this sequence.

func contains(where: ((key: Key, value: Value)) -> Bool) -> Bool

Returns a Boolean value indicating whether the sequence contains an element that satisfies the given predicate.

func difference<C>(from: C, by: (C.Element, (key: Key, value: Value)) -> Bool) -> CollectionDifference<(key: Key, value: Value)>

Returns the difference needed to produce this collection’s ordered elements from the given collection, using the given predicate as an equivalence test.

func distance(from: Int, to: Int) -> Int

Returns the distance between two indices.

func drop(while: ((key: Key, value: Value)) -> Bool) -> Slice<KeyValuePairs<Key, Value>>

Returns a subsequence by skipping elements while predicate returns true and returning the remaining elements.

func dropFirst(Int) -> Slice<KeyValuePairs<Key, Value>>

Returns a subsequence containing all but the given number of initial elements.

func dropLast(Int) -> Slice<KeyValuePairs<Key, Value>>

Returns a subsequence containing all but the specified number of final elements.

func elementsEqual<OtherSequence>(OtherSequence, by: ((key: Key, value: Value), OtherSequence.Element) -> Bool) -> Bool

Returns a Boolean value indicating whether this sequence and another sequence contain equivalent elements in the same order, using the given predicate as the equivalence test.

func enumerated() -> EnumeratedSequence<KeyValuePairs<Key, Value>>

Returns a sequence of pairs (n, x), where n represents a consecutive integer starting at zero and x represents an element of the sequence.

func filter(((key: Key, value: Value)) -> Bool) -> [(key: Key, value: Value)]

Returns an array containing, in order, the elements of the sequence that satisfy the given predicate.

func first(where: ((key: Key, value: Value)) -> Bool) -> (key: Key, value: Value)?

Returns the first element of the sequence that satisfies the given predicate.

func firstIndex(where: ((key: Key, value: Value)) -> Bool) -> Int?

Returns the first index in which an element of the collection satisfies the given predicate.

func flatMap<SegmentOfResult>(((key: Key, value: Value)) -> SegmentOfResult) -> [SegmentOfResult.Element]

Returns an array containing the concatenated results of calling the given transformation with each element of this sequence.

func forEach(((key: Key, value: Value)) -> Void)

Calls the given closure on each element in the sequence in the same order as a for-in loop.

func formIndex(inout Int, offsetBy: Int)

Offsets the given index by the specified distance.

func formIndex(inout Int, offsetBy: Int, limitedBy: Int) -> Bool

Offsets the given index by the specified distance, or so that it equals the given limiting index.

func formIndex(after: inout Int)

Replaces the given index with its successor.

func formIndex(before: inout Int)

Replaces the given index with its predecessor.

func index(Int, offsetBy: Int) -> Int

Returns an index that is the specified distance from the given index.

func index(Int, offsetBy: Int, limitedBy: Int) -> Int?

Returns an index that is the specified distance from the given index, unless that distance is beyond a given limiting index.

func index(after: Int) -> Int

Returns the position immediately after the given index.

func index(before: Int) -> Int

Returns the position immediately after the given index.

func last(where: ((key: Key, value: Value)) -> Bool) -> (key: Key, value: Value)?

Returns the last element of the sequence that satisfies the given predicate.

func lastIndex(where: ((key: Key, value: Value)) -> Bool) -> Int?

Returns the index of the last element in the collection that matches the given predicate.

func lexicographicallyPrecedes<OtherSequence>(OtherSequence, by: ((key: Key, value: Value), (key: Key, value: Value)) -> Bool) -> Bool

Returns a Boolean value indicating whether the sequence precedes another sequence in a lexicographical (dictionary) ordering, using the given predicate to compare elements.

func makeIterator() -> IndexingIterator<KeyValuePairs<Key, Value>>

Returns an iterator over the elements of the collection.

func map<T>(((key: Key, value: Value)) -> T) -> [T]

Returns an array containing the results of mapping the given closure over the sequence’s elements.

func max(by: ((key: Key, value: Value), (key: Key, value: Value)) -> Bool) -> (key: Key, value: Value)?

Returns the maximum element in the sequence, using the given predicate as the comparison between elements.

func min(by: ((key: Key, value: Value), (key: Key, value: Value)) -> Bool) -> (key: Key, value: Value)?

Returns the minimum element in the sequence, using the given predicate as the comparison between elements.

func prefix(Int) -> Slice<KeyValuePairs<Key, Value>>

Returns a subsequence, up to the specified maximum length, containing the initial elements of the collection.

func prefix(through: Int) -> Slice<KeyValuePairs<Key, Value>>

Returns a subsequence from the start of the collection through the specified position.

func prefix(upTo: Int) -> Slice<KeyValuePairs<Key, Value>>

Returns a subsequence from the start of the collection up to, but not including, the specified position.

func prefix(while: ((key: Key, value: Value)) -> Bool) -> Slice<KeyValuePairs<Key, Value>>

Returns a subsequence containing the initial elements until predicate returns false and skipping the remaining elements.

func randomElement() -> (key: Key, value: Value)?

Returns a random element of the collection.

func randomElement<T>(using: inout T) -> (key: Key, value: Value)?

Returns a random element of the collection, using the given generator as a source for randomness.

func reduce<Result>(Result, (Result, (key: Key, value: Value)) -> Result) -> Result

Returns the result of combining the elements of the sequence using the given closure.

func reduce<Result>(into: Result, (inout Result, (key: Key, value: Value)) -> ()) -> Result

Returns the result of combining the elements of the sequence using the given closure.

func reversed() -> ReversedCollection<KeyValuePairs<Key, Value>>

Returns a view presenting the elements of the collection in reverse order.

func shuffled() -> [(key: Key, value: Value)]

Returns the elements of the sequence, shuffled.

func shuffled<T>(using: inout T) -> [(key: Key, value: Value)]

Returns the elements of the sequence, shuffled using the given generator as a source for randomness.

func sorted(by: ((key: Key, value: Value), (key: Key, value: Value)) -> Bool) -> [(key: Key, value: Value)]

Returns the elements of the sequence, sorted using the given predicate as the comparison between elements.

func split(maxSplits: Int, omittingEmptySubsequences: Bool, whereSeparator: ((key: Key, value: Value)) -> Bool) -> [Slice<KeyValuePairs<Key, Value>>]

Returns the longest possible subsequences of the collection, in order, that don’t contain elements satisfying the given predicate.

func starts<PossiblePrefix>(with: PossiblePrefix, by: ((key: Key, value: Value), PossiblePrefix.Element) -> Bool) -> Bool

Returns a Boolean value indicating whether the initial elements of the sequence are equivalent to the elements in another sequence, using the given predicate as the equivalence test.

func suffix(Int) -> Slice<KeyValuePairs<Key, Value>>

Returns a subsequence, up to the given maximum length, containing the final elements of the collection.

func suffix(from: Int) -> Slice<KeyValuePairs<Key, Value>>

Returns a subsequence from the specified position to the end of the collection.

func withContiguousStorageIfAvailable<R>((UnsafeBufferPointer<(key: Key, value: Value)>) -> R) -> R?

Call body(p), where p is a pointer to the collection’s contiguous storage. If no such storage exists, it is first created. If the collection does not support an internal representation in a form of contiguous storage, body is not called and nil is returned.

Subscripts

subscript<R>(R) -> Slice<KeyValuePairs<Key, Value>>

Accesses the contiguous subrange of the collection’s elements specified by a range expression.

subscript(Range<Int>) -> Slice<KeyValuePairs<Key, Value>>

Accesses a contiguous subrange of the collection’s elements.

See Also

Special-Use Collections

func repeatElement<T>(T, count: Int) -> Repeated<T>

Creates a collection containing the specified number of the given element.

struct CollectionOfOne

A collection containing a single element.

struct EmptyCollection

A collection whose element type is Element but that is always empty.