[OrderedSet] Add OrderedSet.appending(contentsOf:)

Sources/OrderedCollections/OrderedSet/OrderedSet+Partial SetAlgebra union.swift

@@ -81,5 +81,28 @@ extension OrderedSet {
     result.formUnion(other)
     return result
   }
+
+  /// Returns a new set with the contents of a sequence appended to the end of the set, excluding
+  /// elements that are already members.
+  ///
+  ///     let a: OrderedSet = [1, 2, 3, 4]
+  ///     let b: OrderedSet = [0, 2, 4, 6]
+  ///     a.union(b) // [1, 2, 3, 4, 0, 6]
+  ///
+  /// This is functionally equivalent to `self.union(elements)`, but it's
+  /// more explicit about how the new members are ordered in the new set.
+  ///
+  /// - Parameter elements: A finite sequence of elements to append.
+  ///
+  /// - Complexity: Expected to be O(`self.count` + `elements.count`) on average,
+  ///    if `Element` implements high-quality hashing.
+  @inlinable
+  public __consuming func appending(
+    contentsOf elements: __owned some Sequence<Element>
+  ) -> Self {
+    var result = self
+    result.append(contentsOf: elements)
+    return result
+  }
 }
 

Tests/OrderedCollectionsTests/OrderedSet/OrderedSetTests.swift

@@ -961,6 +961,20 @@ class OrderedSetTests: CollectionTestCase {
     }
   }
 
+  func test_appending_Self() {
+    withSampleRanges { r1, r2 in
+      let expected = Set(r1).union(r2).sorted()
+
+      let u1 = OrderedSet(r1)
+      let u2 = OrderedSet(r2)
+      let actual1 = u1.appending(contentsOf: u2)
+      expectEqualElements(actual1, expected)
+
+      let actual2 = actual1.appending(contentsOf: u2).appending(contentsOf: u1)
+      expectEqualElements(actual2, expected)
+    }
+  }
+
   func test_formUnion_Self() {
     withSampleRanges { r1, r2 in
       let expected = Set(r1).union(r2).sorted()