[amendment] Add inverse() to SE-0240 for API parity with Foundation (#1052)

* [amendment] Add `inverse()` to SE-0240 for API parity with -[NSOrderedCollectionDifference inverseDifference]

* Kick off amendment review

Author: numist

proposals/0240-ordered-collection-diffing.md

@@ -2,8 +2,9 @@
 
 * Proposal: [SE-0240](0240-ordered-collection-diffing.md)
 * Authors: [Scott Perry](https://github.com/numist), [Kyle Macomber](https://github.com/kylemacomber)
-* Review Manager: [Doug Gregor](https://github.com/DougGregor)
+* Review Manager: [Doug Gregor](https://github.com/DougGregor), [Ben Cohen](https://github.com/AirspeedSwift)
 * Status: **Implemented (Swift 5.1)**
+* Amendment status: **Active Review (June 19 - 25 2019)** 
 * Implementation: [apple/swift#21845](https://github.com/apple/swift/pull/21845)
 * Decision notes: [Rationale](https://forums.swift.org/t/accepted-with-modifications-se-0240-ordered-collection-diffing/20008)
 
@@ -140,6 +141,9 @@ public struct CollectionDifference<ChangeElement> {
 
     /// The `.remove` changes contained by this difference, from lowest offset to highest
     public var removals: [Change] { get }
+
+    /// Produces a difference that is the functional inverse of `self`
+    public func inverse() -> CollectionDifference<ChangeElement>
 }
 
 /// A CollectionDifference is itself a Collection.
@@ -290,26 +294,6 @@ The name `CollectionDifference` gives us the opportunity to build a family of re
 
 This API allows for more interesting functionality that is not included in this proposal.
 
-For example, this propsal could have included a `inverted()` function on the difference type that would return a new difference that would undo the application of the original.
-
-The lack of additional conveniences and functionality is intentional; the goal of this proposal is to lay the groundwork that such extensions would be built upon.
-
-In the case of `inverted()`, clients of the API in this proposal can use `Collection.map()` to invert the case of each `Change` and feed the result into `CollectionDifference.init(_:)`:
-
-``` swift
-let diff: CollectionDifference<Int> = /* ... */
-let inverted = CollectionDifference<Int>(
-    diff.map({(change) -> CollectionDifference<Int>.Change in
-        switch change {
-        case .insert(offset: let o, element: let e, associatedWith: let a):
-            return .remove(offset: o, element: e, associatedWith: a)
-        case .remove(offset: let o, element: let e, associatedWith: let a):
-            return .insert(offset: o, element: e, associatedWith: a)
-        }
-    })
-)!
-```
-
 ### `mutating apply(_:)`
 
 There is no mutating applicator because there is no algorithmic advantage to in-place application.