Merge pull request #172 from lorentey/merge.1.0→main

Merge release/1.0 branch to main

README.md

@@ -70,15 +70,15 @@ We'd like this package to quickly embrace Swift language and toolchain improveme
 To use this package in a SwiftPM project, you need to set it up as a package dependency:
 
 ```swift
-// swift-tools-version:5.4
+// swift-tools-version:5.6
 import PackageDescription
 
 let package = Package(
   name: "MyPackage",
   dependencies: [
     .package(
       url: "https://github.com/apple/swift-collections.git", 
-      .upToNextMajor(from: "1.0.0") // or `.upToNextMinor
+      .upToNextMajor(from: "1.0.3") // or `.upToNextMinor
     )
   ],
   targets: [

Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Initializers.swift

@@ -75,6 +75,7 @@ extension OrderedDictionary {
   ///
   /// - Complexity: Expected O(*n*) on average, where *n* is the count if
   ///    key-value pairs, if `Key` implements high-quality hashing.
+  @_disfavoredOverload // https://github.com/apple/swift-collections/issues/125
   @inlinable
   public init<S: Sequence>(
     uniqueKeysWithValues keysAndValues: S
@@ -195,6 +196,7 @@ extension OrderedDictionary {
   ///
   /// - Complexity: Expected O(*n*) on average, where *n* is the count of
   ///    key-value pairs, if `Key` implements high-quality hashing.
+  @_disfavoredOverload // https://github.com/apple/swift-collections/issues/125
   @inlinable
   @inline(__always)
   public init<S: Sequence>(
@@ -368,6 +370,7 @@ extension OrderedDictionary {
   ///
   /// - Complexity: Expected O(*n*) on average, where *n* is the count if
   ///    key-value pairs, if `Key` implements high-quality hashing.
+  @_disfavoredOverload // https://github.com/apple/swift-collections/issues/125
   @inlinable
   public init<S: Sequence>(
     uncheckedUniqueKeysWithValues keysAndValues: S

Sources/OrderedCollections/OrderedDictionary/OrderedDictionary.swift

@@ -802,20 +802,25 @@ extension OrderedDictionary {
   ///
   ///     // Keeping existing value for key "a":
   ///     dictionary.merge(zip(["a", "c"], [3, 4])) { (current, _) in current }
-  ///     // ["b": 2, "a": 1, "c": 4]
+  ///     // ["a": 1, "b": 2, "c": 4]
   ///
   ///     // Taking the new value for key "a":
   ///     dictionary.merge(zip(["a", "d"], [5, 6])) { (_, new) in new }
-  ///     // ["b": 2, "a": 5, "c": 4, "d": 6]
+  ///     // ["a": 5, "b": 2, "c": 4, "d": 6]
+  ///
+  /// This operation preserves the order of keys in the original dictionary.
+  /// New key-value pairs are appended to the end in the order they appear in
+  /// the given sequence.
   ///
   /// - Parameters:
-  ///   - other: A sequence of key-value pairs.
+  ///   - 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.
   ///
   /// - Complexity: Expected to be O(*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 mutating func merge<S: Sequence>(
     _ keysAndValues: __owned S,
@@ -848,14 +853,18 @@ extension OrderedDictionary {
   ///
   ///     // Keeping existing value for key "a":
   ///     dictionary.merge(zip(["a", "c"], [3, 4])) { (current, _) in current }
-  ///     // ["b": 2, "a": 1, "c": 4]
+  ///     // ["a": 1, "b": 2, "c": 4]
   ///
   ///     // Taking the new value for key "a":
   ///     dictionary.merge(zip(["a", "d"], [5, 6])) { (_, new) in new }
-  ///     // ["b": 2, "a": 5, "c": 4, "d": 6]
+  ///     // ["a": 5, "b": 2, "c": 4, "d": 6]
+  ///
+  /// This operation preserves the order of keys in the original dictionary.
+  /// New key-value pairs are appended to the end in the order they appear in
+  /// the given sequence.
   ///
   /// - Parameters:
-  ///   - other: A sequence of key-value pairs.
+  ///   - 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.
@@ -889,9 +898,9 @@ extension OrderedDictionary {
   ///     let newKeyValues = zip(["a", "b"], [3, 4])
   ///
   ///     let keepingCurrent = dictionary.merging(newKeyValues) { (current, _) in current }
-  ///     // ["b": 2, "a": 1]
+  ///     // ["a": 1, "b": 2]
   ///     let replacingCurrent = dictionary.merging(newKeyValues) { (_, new) in new }
-  ///     // ["b": 4, "a": 3]
+  ///     // ["a": 3, "b": 4]
   ///
   /// - Parameters:
   ///   - other: A sequence of key-value pairs.
@@ -900,11 +909,14 @@ extension OrderedDictionary {
   ///     dictionary.
   ///
   /// - Returns: A new dictionary with the combined keys and values of this
-  ///   dictionary and `other`.
+  ///    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 __consuming func merging<S: Sequence>(
     _ other: __owned S,
@@ -932,9 +944,9 @@ extension OrderedDictionary {
   ///     let newKeyValues = zip(["a", "b"], [3, 4])
   ///
   ///     let keepingCurrent = dictionary.merging(newKeyValues) { (current, _) in current }
-  ///     // ["b": 2, "a": 1]
+  ///     // ["a": 1, "b": 2]
   ///     let replacingCurrent = dictionary.merging(newKeyValues) { (_, new) in new }
-  ///     // ["b": 4, "a": 3]
+  ///     // ["a": 3, "b": 4]
   ///
   /// - Parameters:
   ///   - other: A sequence of key-value pairs.
@@ -943,7 +955,9 @@ extension OrderedDictionary {
   ///     dictionary.
   ///
   /// - Returns: A new dictionary with the combined keys and values of this
-  ///   dictionary and `other`.
+  ///    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
@@ -967,7 +981,8 @@ extension OrderedDictionary {
   ///   argument and returns a Boolean value indicating whether the pair
   ///   should be included in the returned dictionary.
   ///
-  /// - Returns: A dictionary of the key-value pairs that `isIncluded` allows.
+  /// - Returns: A dictionary of the key-value pairs that `isIncluded` allows,
+  ///    in the same order that they appear in `self`.
   ///
   /// - Complexity: O(`count`)
   @inlinable
@@ -991,7 +1006,7 @@ extension OrderedDictionary {
   ///   accepts each value of the dictionary as its parameter and returns a
   ///   transformed value of the same or of a different type.
   /// - Returns: A dictionary containing the keys and transformed values of
-  ///   this dictionary.
+  ///   this dictionary, in the same order.
   ///
   /// - Complexity: O(`count`)
   @inlinable
@@ -1026,7 +1041,7 @@ extension OrderedDictionary {
   ///   optional transformed value of the same or of a different type.
   ///
   /// - Returns: A dictionary containing the keys and non-`nil` transformed
-  ///   values of this dictionary.
+  ///   values of this dictionary, in the same order.
   ///
   /// - Complexity: O(`count`)
   @inlinable

Tests/OrderedCollectionsTests/OrderedDictionary/OrderedDictionary Tests.swift

@@ -1290,5 +1290,75 @@ class OrderedDictionaryTests: CollectionTestCase {
     }
   }
 
+  func test_uniqueKeysWithValues_initializer_ambiguity() {
+    // https://github.com/apple/swift-collections/issues/125
+
+    let names = ["dylan", "bob", "aaron", "carol"]
+    let expected = names.map { (key: $0, value: 0) }
+
+    let d1 = OrderedDictionary(uniqueKeysWithValues: names.map { ($0, 0) })
+    expectEqualElements(d1, expected)
+
+    let d2 = OrderedDictionary(
+      uniqueKeysWithValues: ["dylan", "bob", "aaron", "carol"].map { ($0, 0) })
+    expectEqualElements(d2, expected)
+
+    let d3 = OrderedDictionary(
+      uniqueKeysWithValues: names.map { (key: $0, value: 0) })
+    expectEqualElements(d3, expected)
+
+    let d4 = OrderedDictionary(
+      uniqueKeysWithValues: ["dylan", "bob", "aaron", "carol"].map { (key: $0, value: 0) })
+    expectEqualElements(d4, expected)
+  }
+
+  func test_uniquingKeysWith_initializer_ambiguity() {
+    // https://github.com/apple/swift-collections/issues/125
+    let d1 = OrderedDictionary(
+      ["a", "b", "a"].map { ($0, 1) },
+      uniquingKeysWith: +)
+    expectEqualElements(d1, ["a": 2, "b": 1] as KeyValuePairs)
+
+    let d2 = OrderedDictionary(
+      ["a", "b", "a"].map { (key: $0, value: 1) },
+      uniquingKeysWith: +)
+    expectEqualElements(d2, ["a": 2, "b": 1] as KeyValuePairs)
+  }
+
+  func test_merge_ambiguity() {
+    // https://github.com/apple/swift-collections/issues/125
+
+    var d1: OrderedDictionary = ["a": 1, "b": 2]
+    d1.merge(
+      ["c", "a"].map { ($0, 1) },
+      uniquingKeysWith: +
+    )
+    expectEqualElements(d1, ["a": 2, "b": 2, "c": 1] as KeyValuePairs)
+
+    var d2: OrderedDictionary = ["a": 1, "b": 2]
+    d2.merge(
+      ["c", "a"].map { (key: $0, value: 1) },
+      uniquingKeysWith: +
+    )
+    expectEqualElements(d2, ["a": 2, "b": 2, "c": 1] as KeyValuePairs)
+  }
+
+  func test_merging_ambiguity() {
+    // https://github.com/apple/swift-collections/issues/125
+
+    let d1: OrderedDictionary = ["a": 1, "b": 2]
+    let d1m = d1.merging(
+      ["c", "a"].map { ($0, 1) },
+      uniquingKeysWith: +
+    )
+    expectEqualElements(d1m, ["a": 2, "b": 2, "c": 1] as KeyValuePairs)
+
+    let d2: OrderedDictionary = ["a": 1, "b": 2]
+    let d2m = d2.merging(
+      ["c", "a"].map { (key: $0, value: 1) },
+      uniquingKeysWith: +
+    )
+    expectEqualElements(d2m, ["a": 2, "b": 2, "c": 1] as KeyValuePairs)
+  }
 }
 

Utils/swift-collections.xcworkspace/xcshareddata/xcschemes/OrderedCollections.xcscheme

@@ -28,6 +28,16 @@
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
       shouldUseLaunchSchemeArgsEnv = "YES">
       <Testables>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "OrderedCollectionsTests"
+               BuildableName = "OrderedCollectionsTests"
+               BlueprintName = "OrderedCollectionsTests"
+               ReferencedContainer = "container:..">
+            </BuildableReference>
+         </TestableReference>
       </Testables>
    </TestAction>
    <LaunchAction

Utils/swift-collections.xcworkspace/xcshareddata/xcschemes/swift-collections-Package.xcscheme

@@ -6,20 +6,6 @@
       parallelizeBuildables = "YES"
       buildImplicitDependencies = "YES">
       <BuildActionEntries>
-         <BuildActionEntry
-            buildForTesting = "YES"
-            buildForRunning = "YES"
-            buildForProfiling = "YES"
-            buildForArchiving = "YES"
-            buildForAnalyzing = "YES">
-            <BuildableReference
-               BuildableIdentifier = "primary"
-               BlueprintIdentifier = "BitCollections"
-               BuildableName = "BitCollections"
-               BlueprintName = "BitCollections"
-               ReferencedContainer = "container:..">
-            </BuildableReference>
-         </BuildActionEntry>
          <BuildActionEntry
             buildForTesting = "YES"
             buildForRunning = "YES"
@@ -76,20 +62,6 @@
                ReferencedContainer = "container:..">
             </BuildableReference>
          </BuildActionEntry>
-         <BuildActionEntry
-            buildForTesting = "YES"
-            buildForRunning = "YES"
-            buildForProfiling = "NO"
-            buildForArchiving = "NO"
-            buildForAnalyzing = "YES">
-            <BuildableReference
-               BuildableIdentifier = "primary"
-               BlueprintIdentifier = "BitCollectionsTests"
-               BuildableName = "BitCollectionsTests"
-               BlueprintName = "BitCollectionsTests"
-               ReferencedContainer = "container:..">
-            </BuildableReference>
-         </BuildActionEntry>
          <BuildActionEntry
             buildForTesting = "YES"
             buildForRunning = "YES"
@@ -166,18 +138,9 @@
       buildConfiguration = "Debug"
       selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
-      shouldUseLaunchSchemeArgsEnv = "YES">
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      codeCoverageEnabled = "YES">
       <Testables>
-         <TestableReference
-            skipped = "NO">
-            <BuildableReference
-               BuildableIdentifier = "primary"
-               BlueprintIdentifier = "BitCollectionsTests"
-               BuildableName = "BitCollectionsTests"
-               BlueprintName = "BitCollectionsTests"
-               ReferencedContainer = "container:..">
-            </BuildableReference>
-         </TestableReference>
          <TestableReference
             skipped = "NO">
             <BuildableReference
@@ -240,9 +203,9 @@
       <MacroExpansion>
          <BuildableReference
             BuildableIdentifier = "primary"
-            BlueprintIdentifier = "BitCollections"
-            BuildableName = "BitCollections"
-            BlueprintName = "BitCollections"
+            BlueprintIdentifier = "Collections"
+            BuildableName = "Collections"
+            BlueprintName = "Collections"
             ReferencedContainer = "container:..">
          </BuildableReference>
       </MacroExpansion>