@@ -30,9 +30,17 @@ extension Sequence where Element: Sendable {
3030 /// given closure. The given closure is executed concurrently
3131 /// on multiple queues to reduce the wall-time consumed by the reduction.
3232 ///
33- /// Use the `reduce(into:_:)` method to produce a single value from the
34- /// elements of an entire sequence. For example, you can use this method on an
35- /// array of integers to filter adjacent equal entries or count frequencies.
33+ /// This synchronous method uses Grand Central Dispatch to parallelize the reduction
34+ /// by recursively combining pairs of elements until a single result remains.
35+ ///
36+ /// Example:
37+ /// ```swift
38+ /// let numbers = [1, 2, 3, 4, 5]
39+ /// let sum = numbers.concurrentReduce(defaultValue: 0) { accumulator, value in
40+ /// accumulator += value
41+ /// }
42+ /// // Result: 15
43+ /// ```
3644 ///
3745 /// - Parameters:
3846 /// - defaultValue: A default value for Element. This value is utilized only
@@ -74,17 +82,24 @@ extension Sequence where Element: Sendable {
7482 /// using the given closure. The given closure is executed concurrently
7583 /// on multiple queues to reduce the wall-time consumed by the reduction.
7684 ///
77- /// Use the `reduce(into:_:)` method to produce a single value from the
78- /// elements of an entire sequence. For example, you can use this method on an
79- /// array of integers to filter adjacent equal entries or count frequencies.
85+ /// This specialized method merges dictionaries with custom conflict resolution
86+ /// for duplicate keys.
8087 ///
81- /// - Parameters:
82- /// - defaultValue: A default value for Element. This value is utilized only
83- /// when the receiver is empty.
84- /// - combine: A closure that returns the desired value for
85- /// the given key when multiple values are present for the given key.
86- /// - Returns: The final reduced value. If the sequence has no elements,
87- /// the result is `defaultValue`.
88+ /// Example:
89+ /// ```swift
90+ /// let dictionaries = [
91+ /// ["apple": 1, "banana": 2],
92+ /// ["apple": 3, "cherry": 5]
93+ /// ]
94+ /// let merged = dictionaries.concurrentReduce { key, first, second in
95+ /// return first + second // Sum values for duplicate keys
96+ /// }
97+ /// // Result: ["apple": 4, "banana": 2, "cherry": 5]
98+ /// ```
99+ ///
100+ /// - Parameter combine: A closure that returns the desired value for
101+ /// the given key when multiple values are present for the given key.
102+ /// - Returns: The final reduced dictionary.
88103 public func concurrentReduce< Key, Value> (
89104 combine: @Sendable ( Key , Value , Value ) -> Value
90105 ) -> Element where Element == [ Key : Value ] {
@@ -101,20 +116,24 @@ extension Sequence where Element: Sendable {
101116 #endif
102117
103118 /// Returns the result of combining the elements of the sequence using the
104- /// given closure. The given closure is executed concurrently
105- /// on multiple queues to reduce the wall-time consumed by the reduction .
119+ /// given async closure. The given closure is executed concurrently
120+ /// using Swift's structured concurrency to reduce wall-time.
106121 ///
107- /// Use the `reduce(into:_:)` method to produce a single value from the
108- /// elements of an entire sequence. For example, you can use this method on an
109- /// array of integers to filter adjacent equal entries or count frequencies.
122+ /// This asynchronous method uses task groups to parallelize the reduction
123+ /// by recursively combining pairs of elements until a single result remains.
124+ ///
125+ /// Example:
126+ /// ```swift
127+ /// let files: [URL] = […]
128+ /// let mergedFileContents = await endpoints.concurrentReduce(defaultValue: FileContents()) { accumulated, file in
129+ /// try await accumulated.merge(readData(from: file))
130+ /// }
131+ /// ```
110132 ///
111133 /// - Parameters:
112134 /// - defaultValue: A default value for Element. This value is utilized only
113135 /// when the receiver is empty.
114- /// - reducingIntoFirst: A closure that combines an accumulating value and
115- /// an element of the sequence into a new reduced value, to be used
116- /// in the next call of the `reducingIntoFirst` closure or returned to
117- /// the caller.
136+ /// - reducer: A closure that combines two elements into a new reduced value.
118137 /// - Returns: The final reduced value. If the sequence has no elements,
119138 /// the result is `defaultValue`.
120139 public func concurrentReduce(
@@ -155,20 +174,24 @@ extension Sequence where Element: Sendable {
155174 }
156175
157176 /// Returns the result of combining the elements of the sequence of dictionaries
158- /// using the given closure. The given closure is executed concurrently
159- /// on multiple queues to reduce the wall-time consumed by the reduction .
177+ /// using the given async closure. The given closure is executed concurrently
178+ /// using Swift's structured concurrency to reduce wall-time.
160179 ///
161- /// Use the `reduce(into:_:)` method to produce a single value from the
162- /// elements of an entire sequence. For example, you can use this method on an
163- /// array of integers to filter adjacent equal entries or count frequencies.
180+ /// This specialized async method merges dictionaries with custom conflict resolution
181+ /// for duplicate keys.
164182 ///
165- /// - Parameters:
166- /// - defaultValue: A default value for Element. This value is utilized only
167- /// when the receiver is empty.
168- /// - combine: A closure that returns the desired value for
169- /// the given key when multiple values are present for the given key.
170- /// - Returns: The final reduced value. If the sequence has no elements,
171- /// the result is `defaultValue`.
183+ /// Example:
184+ /// ```swift
185+ /// let userGroups = await fetchUserGroups() // Returns [[String: User]]
186+ /// let mergedUsers = await userGroups.concurrentReduce { key, user1, user2 in
187+ /// // Custom logic to merge duplicate users
188+ /// return user1.updatedAt > user2.updatedAt ? user1 : user2
189+ /// }
190+ /// ```
191+ ///
192+ /// - Parameter combine: A closure that returns the desired value for
193+ /// the given key when multiple values are present for the given key.
194+ /// - Returns: The final reduced dictionary.
172195 public func concurrentReduce< Key, Value> (
173196 combine: @escaping @Sendable ( Key, Value, Value) throws -> Value
174197 ) async rethrows -> Element where Element == [ Key : Value ] {
0 commit comments