mirror of
https://github.com/apple/swift-collections
synced 2026-11-22 04:20:40 +00:00
DocC keeps changing its link syntax. The latest iteration appears to have trouble dealing with `Self`-taking or `Self`-returning methods, so change our API to replace `Self` with a direct mention of the concrete type. ¯\\\_(ツ)\_/¯ That said, the new compiler also found a large number of mismatching parameter names, and that was really helpful.
270 lines
11 KiB
Swift
270 lines
11 KiB
Swift
//===----------------------------------------------------------------------===//
|
|
//
|
|
// This source file is part of the Swift Collections open source project
|
|
//
|
|
// Copyright (c) 2022 - 2026 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
|
|
//
|
|
// SPDX-License-Identifier: Apache-2.0 WITH Swift-exception
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
extension TreeDictionary {
|
|
/// Merges the key-value pairs in the given sequence into the dictionary,
|
|
/// using a combining closure to determine the value for any duplicate keys.
|
|
///
|
|
/// Use the `combine` closure to select a value to use in the updated
|
|
/// dictionary, or to combine existing and new values. As the key-value
|
|
/// pairs are merged with the dictionary, the `combine` closure is called
|
|
/// with the current and new values for any duplicate keys that are
|
|
/// encountered.
|
|
///
|
|
/// This example shows how to choose the current or new values for any
|
|
/// duplicate keys:
|
|
///
|
|
/// var dictionary: TreeDictionary = ["a": 1, "b": 2]
|
|
///
|
|
/// // Keeping existing value for key "a":
|
|
/// dictionary.merge(zip(["a", "c"], [3, 4])) { (current, _) in current }
|
|
/// // ["a": 1, "b": 2, "c": 4] (in some order)
|
|
///
|
|
/// // Taking the new value for key "a":
|
|
/// dictionary.merge(zip(["a", "d"], [5, 6])) { (_, new) in new }
|
|
/// // ["a": 5, "b": 2, "c": 4, "d": 6] (in some order)
|
|
///
|
|
/// - Parameters:
|
|
/// - keysAndValues: A sequence of key-value pairs.
|
|
/// - combine: A closure that takes the current and new values for any
|
|
/// duplicate keys. The closure returns the desired value for the final
|
|
/// dictionary.
|
|
@inlinable
|
|
public mutating func merge(
|
|
_ keysAndValues: TreeDictionary,
|
|
uniquingKeysWith combine: (Value, Value) throws -> Value
|
|
) rethrows {
|
|
_invalidateIndices()
|
|
_ = try _root.merge(.top, keysAndValues._root, combine)
|
|
_invariantCheck()
|
|
}
|
|
|
|
/// Merges the key-value pairs in the given sequence into the dictionary,
|
|
/// using a combining closure to determine the value for any duplicate keys.
|
|
///
|
|
/// Use the `combine` closure to select a value to use in the updated
|
|
/// dictionary, or to combine existing and new values. As the key-value
|
|
/// pairs are merged with the dictionary, the `combine` closure is called
|
|
/// with the current and new values for any duplicate keys that are
|
|
/// encountered.
|
|
///
|
|
/// This example shows how to choose the current or new values for any
|
|
/// duplicate keys:
|
|
///
|
|
/// var dictionary: TreeDictionary = ["a": 1, "b": 2]
|
|
///
|
|
/// // Keeping existing value for key "a":
|
|
/// dictionary.merge(zip(["a", "c"], [3, 4])) { (current, _) in current }
|
|
/// // ["a": 1, "b": 2, "c": 4] (in some order)
|
|
///
|
|
/// // Taking the new value for key "a":
|
|
/// dictionary.merge(zip(["a", "d"], [5, 6])) { (_, new) in new }
|
|
/// // ["a": 5, "b": 2, "c": 4, "d": 6] (in some order)
|
|
///
|
|
/// - Parameters:
|
|
/// - keysAndValues: A sequence of key-value pairs.
|
|
/// - combine: A closure that takes the current and new values for any
|
|
/// duplicate keys. The closure returns the desired value for the final
|
|
/// dictionary.
|
|
@inlinable
|
|
public mutating func merge(
|
|
_ keysAndValues: __owned some Sequence<(Key, Value)>,
|
|
uniquingKeysWith combine: (Value, Value) throws -> Value
|
|
) rethrows {
|
|
for (key, value) in keysAndValues {
|
|
try self.updateValue(forKey: key) { target in
|
|
if let old = target {
|
|
target = try combine(old, value)
|
|
} else {
|
|
target = value
|
|
}
|
|
}
|
|
}
|
|
_invariantCheck()
|
|
}
|
|
|
|
/// Merges the key-value pairs in the given sequence into the dictionary,
|
|
/// using a combining closure to determine the value for any duplicate keys.
|
|
///
|
|
/// Use the `combine` closure to select a value to use in the updated
|
|
/// dictionary, or to combine existing and new values. As the key-value
|
|
/// pairs are merged with the dictionary, the `combine` closure is called
|
|
/// with the current and new values for any duplicate keys that are
|
|
/// encountered.
|
|
///
|
|
/// This example shows how to choose the current or new values for any
|
|
/// duplicate keys:
|
|
///
|
|
/// var dictionary: TreeDictionary = ["a": 1, "b": 2]
|
|
///
|
|
/// // Keeping existing value for key "a":
|
|
/// dictionary.merge(zip(["a", "c"], [3, 4])) { (current, _) in current }
|
|
/// // ["a": 1, "b": 2, "c": 4] (in some order)
|
|
///
|
|
/// // Taking the new value for key "a":
|
|
/// dictionary.merge(zip(["a", "d"], [5, 6])) { (_, new) in new }
|
|
/// // ["a": 5, "b": 2, "c": 4, "d": 6] (in some order)
|
|
///
|
|
/// - Parameters:
|
|
/// - keysAndValues: A sequence of key-value pairs.
|
|
/// - combine: A closure that takes the current and new values for any
|
|
/// duplicate keys. The closure returns the desired value for the final
|
|
/// dictionary.
|
|
@_disfavoredOverload // https://github.com/apple/swift-collections/issues/125
|
|
@inlinable
|
|
public mutating func merge(
|
|
_ keysAndValues: __owned some Sequence<Element>,
|
|
uniquingKeysWith combine: (Value, Value) throws -> Value
|
|
) rethrows {
|
|
try merge(
|
|
keysAndValues.lazy.map { ($0.key, $0.value) },
|
|
uniquingKeysWith: combine)
|
|
}
|
|
|
|
/// Creates a dictionary by merging key-value pairs in a sequence into this
|
|
/// dictionary, using a combining closure to determine the value for
|
|
/// duplicate keys.
|
|
///
|
|
/// Use the `combine` closure to select a value to use in the returned
|
|
/// dictionary, or to combine existing and new values. As the key-value
|
|
/// pairs are merged with the dictionary, the `combine` closure is called
|
|
/// with the current and new values for any duplicate keys that are
|
|
/// encountered.
|
|
///
|
|
/// This example shows how to choose the current or new values for any
|
|
/// duplicate keys:
|
|
///
|
|
/// let dictionary: OrderedDictionary = ["a": 1, "b": 2]
|
|
/// let newKeyValues = zip(["a", "b"], [3, 4])
|
|
///
|
|
/// let keepingCurrent = dictionary.merging(newKeyValues) { (current, _) in current }
|
|
/// // ["a": 1, "b": 2]
|
|
/// let replacingCurrent = dictionary.merging(newKeyValues) { (_, new) in new }
|
|
/// // ["a": 3, "b": 4]
|
|
///
|
|
/// - Parameters:
|
|
/// - other: A sequence of key-value pairs.
|
|
/// - combine: A closure that takes the current and new values for any
|
|
/// duplicate keys. The closure returns the desired value for the final
|
|
/// dictionary.
|
|
///
|
|
/// - Returns: A new dictionary with the combined keys and values of this
|
|
/// dictionary and `other`. The order of keys in the result dictionary
|
|
/// matches that of `self`, with additional key-value pairs (if any)
|
|
/// appended at the end in the order they appear in `other`.
|
|
///
|
|
/// - Complexity: Expected to be O(`count` + *n*) on average, where *n* is the
|
|
/// number of elements in `keysAndValues`, if `Key` implements high-quality
|
|
/// hashing.
|
|
@inlinable
|
|
public func merging(
|
|
_ other: TreeDictionary,
|
|
uniquingKeysWith combine: (Value, Value) throws -> Value
|
|
) rethrows -> Self {
|
|
var copy = self
|
|
try copy.merge(other, uniquingKeysWith: combine)
|
|
return copy
|
|
}
|
|
|
|
/// Creates a dictionary by merging key-value pairs in a sequence into this
|
|
/// dictionary, using a combining closure to determine the value for
|
|
/// duplicate keys.
|
|
///
|
|
/// Use the `combine` closure to select a value to use in the returned
|
|
/// dictionary, or to combine existing and new values. As the key-value
|
|
/// pairs are merged with the dictionary, the `combine` closure is called
|
|
/// with the current and new values for any duplicate keys that are
|
|
/// encountered.
|
|
///
|
|
/// This example shows how to choose the current or new values for any
|
|
/// duplicate keys:
|
|
///
|
|
/// let dictionary: OrderedDictionary = ["a": 1, "b": 2]
|
|
/// let newKeyValues = zip(["a", "b"], [3, 4])
|
|
///
|
|
/// let keepingCurrent = dictionary.merging(newKeyValues) { (current, _) in current }
|
|
/// // ["a": 1, "b": 2]
|
|
/// let replacingCurrent = dictionary.merging(newKeyValues) { (_, new) in new }
|
|
/// // ["a": 3, "b": 4]
|
|
///
|
|
/// - Parameters:
|
|
/// - other: A sequence of key-value pairs.
|
|
/// - combine: A closure that takes the current and new values for any
|
|
/// duplicate keys. The closure returns the desired value for the final
|
|
/// dictionary.
|
|
///
|
|
/// - Returns: A new dictionary with the combined keys and values of this
|
|
/// dictionary and `other`. The order of keys in the result dictionary
|
|
/// matches that of `self`, with additional key-value pairs (if any)
|
|
/// appended at the end in the order they appear in `other`.
|
|
///
|
|
/// - Complexity: Expected to be O(`count` + *n*) on average, where *n* is the
|
|
/// number of elements in `keysAndValues`, if `Key` implements high-quality
|
|
/// hashing.
|
|
@inlinable
|
|
public func merging(
|
|
_ other: __owned some Sequence<(Key, Value)>,
|
|
uniquingKeysWith combine: (Value, Value) throws -> Value
|
|
) rethrows -> Self {
|
|
var copy = self
|
|
try copy.merge(other, uniquingKeysWith: combine)
|
|
return copy
|
|
}
|
|
|
|
/// Creates a dictionary by merging key-value pairs in a sequence into this
|
|
/// dictionary, using a combining closure to determine the value for
|
|
/// duplicate keys.
|
|
///
|
|
/// Use the `combine` closure to select a value to use in the returned
|
|
/// dictionary, or to combine existing and new values. As the key-value
|
|
/// pairs are merged with the dictionary, the `combine` closure is called
|
|
/// with the current and new values for any duplicate keys that are
|
|
/// encountered.
|
|
///
|
|
/// This example shows how to choose the current or new values for any
|
|
/// duplicate keys:
|
|
///
|
|
/// let dictionary: OrderedDictionary = ["a": 1, "b": 2]
|
|
/// let newKeyValues = zip(["a", "b"], [3, 4])
|
|
///
|
|
/// let keepingCurrent = dictionary.merging(newKeyValues) { (current, _) in current }
|
|
/// // ["a": 1, "b": 2]
|
|
/// let replacingCurrent = dictionary.merging(newKeyValues) { (_, new) in new }
|
|
/// // ["a": 3, "b": 4]
|
|
///
|
|
/// - Parameters:
|
|
/// - other: A sequence of key-value pairs.
|
|
/// - combine: A closure that takes the current and new values for any
|
|
/// duplicate keys. The closure returns the desired value for the final
|
|
/// dictionary.
|
|
///
|
|
/// - Returns: A new dictionary with the combined keys and values of this
|
|
/// dictionary and `other`. The order of keys in the result dictionary
|
|
/// matches that of `self`, with additional key-value pairs (if any)
|
|
/// appended at the end in the order they appear in `other`.
|
|
///
|
|
/// - Complexity: Expected to be O(`count` + *n*) on average, where *n* is the
|
|
/// number of elements in `keysAndValues`, if `Key` implements high-quality
|
|
/// hashing.
|
|
@_disfavoredOverload // https://github.com/apple/swift-collections/issues/125
|
|
@inlinable
|
|
public func merging(
|
|
_ other: __owned some Sequence<Element>,
|
|
uniquingKeysWith combine: (Value, Value) throws -> Value
|
|
) rethrows -> Self {
|
|
var copy = self
|
|
try copy.merge(other, uniquingKeysWith: combine)
|
|
return copy
|
|
}
|
|
}
|