stdlib: Make data structure protocols ready for future move-only types.

We would like to eventually extend Array, Dictionary, and Set to support move-only element types when the language does. To that end, we need to get the `consuming`-ness of protocol requirements on Sequence, Collection, and related protocols right for forward compatibility so that a future version of Swift that extends these types to support move-only data structures remains ABI- and API-compatible with older versions of the language. Mark requirements as `__consuming` where it would be necessary for a move-only implementation of one of these types.

Author: jckarter

stdlib/public/core/Collection.swift

@@ -522,7 +522,7 @@ public protocol Collection: Sequence where SubSequence: Collection {
   /// - Returns: A subsequence up to, but not including, the `end` position.
   ///
   /// - Complexity: O(1)
-  func prefix(upTo end: Index) -> SubSequence
+  __consuming func prefix(upTo end: Index) -> SubSequence
 
   /// Returns a subsequence from the specified position to the end of the
   /// collection.
@@ -557,7 +557,7 @@ public protocol Collection: Sequence where SubSequence: Collection {
   /// - Returns: A subsequence starting at the `start` position.
   ///
   /// - Complexity: O(1)
-  func suffix(from start: Index) -> SubSequence
+  __consuming func suffix(from start: Index) -> SubSequence
 
   /// Returns a subsequence from the start of the collection through the
   /// specified position.
@@ -588,7 +588,7 @@ public protocol Collection: Sequence where SubSequence: Collection {
   /// - Returns: A subsequence up to, and including, the `end` position.
   ///
   /// - Complexity: O(1)
-  func prefix(through position: Index) -> SubSequence
+  __consuming func prefix(through position: Index) -> SubSequence
 
   /// A Boolean value indicating whether the collection is empty.
   ///
@@ -643,6 +643,11 @@ public protocol Collection: Sequence where SubSequence: Collection {
   /// - Complexity: Hopefully less than O(`count`).
   func _customLastIndexOfEquatableElement(_ element: Element) -> Index??
 
+  // FIXME(move-only types): `first` might not be implementable by collections
+  // with move-only elements, since they would need to be able to somehow form
+  // a temporary `Optional<Element>` value from a non-optional Element without
+  // modifying the collection.
+
   /// The first element of the collection.
   ///
   /// If the collection is empty, the value of this property is `nil`.
@@ -818,7 +823,7 @@ public protocol Collection: Sequence where SubSequence: Collection {
   ///   a random element.
   /// - Returns: A random element from the collection. If the collection is
   ///   empty, the method returns `nil`.
-  func randomElement<T: RandomNumberGenerator>(
+  __consuming func randomElement<T: RandomNumberGenerator>(
     using generator: inout T
   ) -> Element?
 

stdlib/public/core/RangeReplaceableCollection.swift

@@ -175,7 +175,7 @@ public protocol RangeReplaceableCollection : Collection
   ///
   /// - Complexity: O(1) on average, over many additions to the same
   ///   collection.
-  mutating func append(_ newElement: Element)
+  mutating func append(_ newElement: __owned Element)
 
   /// Adds the elements of a sequence or collection to the end of this
   /// collection.
@@ -197,7 +197,7 @@ public protocol RangeReplaceableCollection : Collection
   ///   collection.
   // FIXME(ABI)#166 (Evolution): Consider replacing .append(contentsOf) with +=
   // suggestion in SE-91
-  mutating func append<S : Sequence>(contentsOf newElements: S)
+  mutating func append<S : Sequence>(contentsOf newElements: __owned S)
     where S.Element == Element
 
   /// Inserts a new element into the collection at the specified position.
@@ -222,7 +222,7 @@ public protocol RangeReplaceableCollection : Collection
   ///   `index` must be a valid index into the collection.
   ///
   /// - Complexity: O(*n*), where *n* is the length of the collection.
-  mutating func insert(_ newElement: Element, at i: Index)
+  mutating func insert(_ newElement: __owned Element, at i: Index)
 
   /// Inserts the elements of a sequence into the collection at the specified
   /// position.
@@ -250,7 +250,7 @@ public protocol RangeReplaceableCollection : Collection
   ///   and `newElements`. If `i` is equal to the collection's `endIndex`
   ///   property, the complexity is O(*n*), where *n* is the length of
   ///   `newElements`.
-  mutating func insert<S : Collection>(contentsOf newElements: S, at i: Index)
+  mutating func insert<S : Collection>(contentsOf newElements: __owned S, at i: Index)
     where S.Element == Element
 
   /// Removes and returns the element at the specified position.

stdlib/public/core/Sequence.swift

@@ -336,7 +336,7 @@ public protocol Sequence {
           SubSequence.SubSequence == SubSequence
 
   /// Returns an iterator over the elements of this sequence.
-  func makeIterator() -> Iterator
+  __consuming func makeIterator() -> Iterator
 
   /// A value less than or equal to the number of elements in the sequence,
   /// calculated nondestructively.
@@ -384,7 +384,7 @@ public protocol Sequence {
   ///   sequence as its argument and returns a Boolean value indicating
   ///   whether the element should be included in the returned array.
   /// - Returns: An array of the elements that `isIncluded` allowed.
-  func filter(
+  __consuming func filter(
     _ isIncluded: (Element) throws -> Bool
   ) rethrows -> [Element]
 
@@ -442,7 +442,7 @@ public protocol Sequence {
   ///
   /// - Complexity: O(*n*), where *n* is the number of elements to drop from
   ///   the beginning of the sequence.
-  func dropFirst(_ n: Int) -> SubSequence
+  __consuming func dropFirst(_ n: Int) -> SubSequence
 
   /// Returns a subsequence containing all but the specified number of final
   /// elements.
@@ -462,7 +462,7 @@ public protocol Sequence {
   /// - Returns: A subsequence leaving off the specified number of elements.
   ///
   /// - Complexity: O(*n*), where *n* is the length of the sequence.
-  func dropLast(_ n: Int) -> SubSequence
+  __consuming func dropLast(_ n: Int) -> SubSequence
 
   /// Returns a subsequence by skipping elements while `predicate` returns
   /// `true` and returning the remaining elements.
@@ -472,7 +472,7 @@ public protocol Sequence {
   ///   whether the element is a match.
   ///
   /// - Complexity: O(*n*), where *n* is the length of the collection.
-  func drop(
+  __consuming func drop(
     while predicate: (Element) throws -> Bool
   ) rethrows -> SubSequence
 
@@ -492,7 +492,7 @@ public protocol Sequence {
   ///   `maxLength` must be greater than or equal to zero.
   /// - Returns: A subsequence starting at the beginning of this sequence
   ///   with at most `maxLength` elements.
-  func prefix(_ maxLength: Int) -> SubSequence
+  __consuming func prefix(_ maxLength: Int) -> SubSequence
 
   /// Returns a subsequence containing the initial, consecutive elements that
   /// satisfy the given predicate.
@@ -516,7 +516,7 @@ public protocol Sequence {
   ///   satisfy `predicate`.
   ///
   /// - Complexity: O(*n*), where *n* is the length of the collection.
-  func prefix(
+  __consuming func prefix(
     while predicate: (Element) throws -> Bool
   ) rethrows -> SubSequence
 
@@ -539,7 +539,7 @@ public protocol Sequence {
   ///   at most `maxLength` elements.
   ///
   /// - Complexity: O(*n*), where *n* is the length of the sequence.
-  func suffix(_ maxLength: Int) -> SubSequence
+  __consuming func suffix(_ maxLength: Int) -> SubSequence
 
   /// Returns the longest possible subsequences of the sequence, in order, that
   /// don't contain elements satisfying the given predicate.
@@ -590,7 +590,7 @@ public protocol Sequence {
   ///   - isSeparator: A closure that returns `true` if its argument should be
   ///     used to split the sequence; otherwise, `false`.
   /// - Returns: An array of subsequences, split from this sequence's elements.
-  func split(
+  __consuming func split(
     maxSplits: Int, omittingEmptySubsequences: Bool,
     whereSeparator isSeparator: (Element) throws -> Bool
   ) rethrows -> [SubSequence]
@@ -607,11 +607,11 @@ public protocol Sequence {
 
   /// Create a native array buffer containing the elements of `self`,
   /// in the same order.
-  func _copyToContiguousArray() -> ContiguousArray<Element>
+  __consuming func _copyToContiguousArray() -> ContiguousArray<Element>
 
   /// Copy `self` into an unsafe buffer, returning a partially-consumed
   /// iterator with any elements that didn't fit remaining.
-  func _copyContents(
+  __consuming func _copyContents(
     initializing ptr: UnsafeMutableBufferPointer<Element>
   ) -> (Iterator,UnsafeMutableBufferPointer<Element>.Index)
 }

stdlib/public/core/SetAlgebra.swift

@@ -115,7 +115,7 @@ public protocol SetAlgebra : Equatable, ExpressibleByArrayLiteral {
   /// - Note: if this set and `other` contain elements that are equal but
   ///   distinguishable (e.g. via `===`), which of these elements is present
   ///   in the result is unspecified.
-  func union(_ other: Self) -> Self
+  __consuming func union(_ other: __owned Self) -> Self
 
   /// Returns a new set with the elements that are common to both this set and
   /// the given set.
@@ -137,7 +137,7 @@ public protocol SetAlgebra : Equatable, ExpressibleByArrayLiteral {
   /// - Note: if this set and `other` contain elements that are equal but
   ///   distinguishable (e.g. via `===`), which of these elements is present
   ///   in the result is unspecified.
-  func intersection(_ other: Self) -> Self
+  __consuming func intersection(_ other: __owned Self) -> Self
 
   /// Returns a new set with the elements that are either in this set or in the
   /// given set, but not in both.
@@ -155,7 +155,12 @@ public protocol SetAlgebra : Equatable, ExpressibleByArrayLiteral {
   ///
   /// - Parameter other: A set of the same type as the current set.
   /// - Returns: A new set.
-  func symmetricDifference(_ other: Self) -> Self
+  __consuming func symmetricDifference(_ other: __owned Self) -> Self
+
+  // FIXME(move-only types): SetAlgebra.insert is not implementable by a
+  // set with move-only Element type, since it would be necessary to copy
+  // the argument in order to both store it inside the set and return it as
+  // the `memberAfterInsert`.
 
   /// Inserts the given element in the set if it is not already present.
   ///
@@ -189,7 +194,7 @@ public protocol SetAlgebra : Equatable, ExpressibleByArrayLiteral {
   ///   other means.
   @discardableResult
   mutating func insert(
-    _ newMember: Element
+    _ newMember: __owned Element
   ) -> (inserted: Bool, memberAfterInsert: Element)
 
   /// Removes the given element and any elements subsumed by the given element.
@@ -231,7 +236,7 @@ public protocol SetAlgebra : Equatable, ExpressibleByArrayLiteral {
   ///   `OptionSet` types, this method returns any intersection between the 
   ///   set and `[newMember]`, or `nil` if the intersection is empty.
   @discardableResult
-  mutating func update(with newMember: Element) -> Element?
+  mutating func update(with newMember: __owned Element) -> Element?
 
   /// Adds the elements of the given set to the set.
   ///
@@ -253,7 +258,7 @@ public protocol SetAlgebra : Equatable, ExpressibleByArrayLiteral {
   ///     // Prints "[2, 4, 6, 7, 0, 1, 3]"
   ///
   /// - Parameter other: A set of the same type as the current set.
-  mutating func formUnion(_ other: Self)
+  mutating func formUnion(_ other: __owned Self)
 
   /// Removes the elements of this set that aren't also in the given set.
   ///
@@ -268,7 +273,7 @@ public protocol SetAlgebra : Equatable, ExpressibleByArrayLiteral {
   ///     // Prints "["Bethany", "Eric"]"
   ///
   /// - Parameter other: A set of the same type as the current set.
-  mutating func formIntersection(_ other: Self)
+  mutating func formIntersection(_ other: __owned Self)
 
   /// Removes the elements of the set that are also in the given set and adds
   /// the members of the given set that are not already in the set.
@@ -286,7 +291,7 @@ public protocol SetAlgebra : Equatable, ExpressibleByArrayLiteral {
   ///     // Prints "["Diana", "Forlani", "Alicia"]"
   ///
   /// - Parameter other: A set of the same type.
-  mutating func formSymmetricDifference(_ other: Self)
+  mutating func formSymmetricDifference(_ other: __owned Self)
 
   //===--- Requirements with default implementations ----------------------===//
   /// Returns a new set containing the elements of this set that do not occur
@@ -303,7 +308,7 @@ public protocol SetAlgebra : Equatable, ExpressibleByArrayLiteral {
   ///
   /// - Parameter other: A set of the same type as the current set.
   /// - Returns: A new set.
-  func subtracting(_ other: Self) -> Self
+  __consuming func subtracting(_ other: Self) -> Self
 
   /// Returns a Boolean value that indicates whether the set is a subset of
   /// another set.
@@ -365,7 +370,7 @@ public protocol SetAlgebra : Equatable, ExpressibleByArrayLiteral {
   ///     // Prints "[6, 0, 1, 3]"
   ///
   /// - Parameter sequence: The elements to use as members of the new set.
-  init<S : Sequence>(_ sequence: S) where S.Element == Element
+  init<S : Sequence>(_ sequence: __owned S) where S.Element == Element
 
   /// Removes the elements of the given set from this set.
   ///