1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
//===--- KeyValuePairs.swift ----------------------------------------------===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2014 - 2018 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
//
//===----------------------------------------------------------------------===//
/// A lightweight collection of key-value pairs.
///
/// 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 "(key: "Florence Griffith-Joyner", value: 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)]"
@frozen // trivial-implementation
public struct KeyValuePairs<Key, Value>: ExpressibleByDictionaryLiteral {
@usableFromInline // trivial-implementation
internal let _elements: [(Key, Value)]
/// Creates a new `KeyValuePairs` instance from the given dictionary
/// literal.
///
/// The order of the key-value pairs is kept intact in the resulting
/// `KeyValuePairs` instance.
@inlinable // trivial-implementation
public init(dictionaryLiteral elements: (Key, Value)...) {
self._elements = elements
}
}
/// `Collection` conformance that allows `KeyValuePairs` to
/// interoperate with the rest of the standard library.
extension KeyValuePairs: RandomAccessCollection {
/// The element type of a `KeyValuePairs`: a tuple containing an
/// individual key-value pair.
public typealias Element = (key: Key, value: Value)
public typealias Index = Int
public typealias Indices = Range<Int>
public typealias SubSequence = Slice<KeyValuePairs>
/// The position of the first element in a nonempty collection.
///
/// If the `KeyValuePairs` instance is empty, `startIndex` is equal to
/// `endIndex`.
@inlinable // trivial-implementation
public var startIndex: Index { return 0 }
/// The collection's "past the end" position---that is, the position one
/// greater than the last valid subscript argument.
///
/// If the `KeyValuePairs` instance is empty, `endIndex` is equal to
/// `startIndex`.
@inlinable // trivial-implementation
public var endIndex: Index { return _elements.endIndex }
/// Accesses the element at the specified position.
///
/// - Parameter position: The position of the element to access. `position`
/// must be a valid index of the collection that is not equal to the
/// `endIndex` property.
/// - Returns: The key-value pair at position `position`.
@inlinable // trivial-implementation
public subscript(position: Index) -> Element {
return _elements[position]
}
}
extension KeyValuePairs: CustomStringConvertible {
/// A string that represents the contents of the dictionary.
public var description: String {
return _makeKeyValuePairDescription()
}
}
extension KeyValuePairs: CustomDebugStringConvertible {
/// A string that represents the contents of the dictionary, suitable for
/// debugging.
public var debugDescription: String {
return _makeKeyValuePairDescription()
}
}
extension KeyValuePairs: Sendable
where Key: Sendable, Value: Sendable { }
|
