[stdlib] Add post-nil guarantee for IteratorProtocol.next() to always return nil

Author: PatrickPijnappel

stdlib/public/core/Algorithm.swift

@@ -84,10 +84,8 @@ public struct EnumeratedIterator<
   /// The type of element returned by `next()`.
   public typealias Element = (offset: Int, element: Base.Element)
 
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
-  ///
-  /// - Requires: No preceding call to `self.next()` has returned `nil`.
+  /// Advance to the next element and return it, or `nil` if no next element
+  /// exists. Once `nil` has been returned, all subsequent calls return `nil`.
   public mutating func next() -> Element? {
     guard let b = _base.next() else { return nil }
     defer { _count += 1 }

stdlib/public/core/Collection.swift

@@ -81,10 +81,8 @@ public struct IndexingIterator<Elements : Indexable>
     self._position = _elements.startIndex
   }
 
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
-  ///
-  /// - Precondition: No preceding call to `self.next()` has returned `nil`.
+  /// Advance to the next element and return it, or `nil` if no next element
+  /// exists. Once `nil` has been returned, all subsequent calls return `nil`.
   public mutating func next() -> Elements._Element? {
     if _position == _elements.endIndex { return nil }
     let element = _elements[_position]

stdlib/public/core/CollectionOfOne.swift

@@ -19,12 +19,11 @@ public struct IteratorOverOne<Element> : IteratorProtocol, Sequence {
     self._elements = _elements
   }
 
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
+  /// Advance to the next element and return it, or `nil` if no next element
+  /// exists. Once `nil` has been returned, all subsequent calls return `nil`.
   ///
   /// - Precondition: `next()` has not been applied to a copy of `self`
-  ///   since the copy was made, and no preceding call to `self.next()`
-  ///   has returned `nil`.
+  ///   since the copy was made.
   public mutating func next() -> Element? {
     let result = _elements
     _elements = nil

stdlib/public/core/ExistentialCollection.swift.gyb

@@ -66,8 +66,8 @@ public struct AnyIterator<Element> : IteratorProtocol {
     self._box = _box
   }
 
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
+  /// Advance to the next element and return it, or `nil` if no next element
+  /// exists. Once `nil` has been returned, all subsequent calls return `nil`.
   public func next() -> Element? {
     return _box.next()
   }
@@ -92,8 +92,8 @@ internal class _AnyIteratorBase {}
 internal class _AnyIteratorBoxBase<Element>
   : _AnyIteratorBase, IteratorProtocol {
 
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
+  /// Advance to the next element and return it, or `nil` if no next element
+  /// exists. Once `nil` has been returned, all subsequent calls return `nil`.
   ///
   /// - Note: Subclasses must override this method.
   internal func next() -> Element? { _abstract() }

stdlib/public/core/Flatten.swift.gyb

@@ -27,12 +27,11 @@ public struct FlattenIterator<
     self._base = base
   }
 
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
+  /// Advance to the next element and return it, or `nil` if no next element
+  /// exists. Once `nil` has been returned, all subsequent calls return `nil`.
   ///
   /// - Precondition: `next()` has not been applied to a copy of `self`
-  ///   since the copy was made, and no preceding call to `self.next()`
-  ///   has returned `nil`.
+  ///   since the copy was made.
   public mutating func next() -> Base.Element.Iterator.Element? {
     repeat {
       if _fastPath(_inner != nil) {

stdlib/public/core/HashedCollections.swift.gyb

@@ -3983,10 +3983,8 @@ public struct ${Self}Iterator<${TypeParametersDecl}> : IteratorProtocol {
     }
   }
 
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
-  ///
-  /// - Precondition: No preceding call to `self.next()` has returned `nil`.
+  /// Advance to the next element and return it, or `nil` if no next element
+  /// exists. Once `nil` has been returned, all subsequent calls return `nil`.
   public mutating func next() -> ${Sequence}? {
     if _fastPath(_guaranteedNative) {
       return _nativeNext()

stdlib/public/core/Join.swift

@@ -36,8 +36,8 @@ public struct JoinedIterator<
     self._separatorData = ContiguousArray(separator)
   }
 
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
+  /// Advance to the next element and return it, or `nil` if no next element
+  /// exists. Once `nil` has been returned, all subsequent calls return `nil`.
   public mutating func next() -> Base.Element.Iterator.Element? {
     repeat {
       switch _state {

stdlib/public/core/Map.swift

@@ -16,12 +16,11 @@
 public struct LazyMapIterator<
   Base : IteratorProtocol, Element
 > : IteratorProtocol, Sequence {
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
+  /// Advance to the next element and return it, or `nil` if no next element
+  /// exists. Once `nil` has been returned, all subsequent calls return `nil`.
   ///
   /// - Precondition: `next()` has not been applied to a copy of `self`
-  ///   since the copy was made, and no preceding call to `self.next()`
-  ///   has returned `nil`.
+  ///   since the copy was made.
   public mutating func next() -> Element? {
     return _base.next().map(_transform)
   }

stdlib/public/core/Range.swift

@@ -22,8 +22,8 @@ public struct RangeIterator<
     self.endIndex = _bounds.endIndex
   }
 
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
+  /// Advance to the next element and return it, or `nil` if no next element
+  /// exists. Once `nil` has been returned, all subsequent calls return `nil`.
   public mutating func next() -> Element? {
     if startIndex == endIndex { return nil }
     let element = startIndex

stdlib/public/core/Sequence.swift

@@ -26,14 +26,11 @@ public protocol IteratorProtocol {
   /// The type of element traversed by `self`.
   associatedtype Element
 
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
+  /// Advance to the next element and return it, or `nil` if no next element
+  /// exists. Once `nil` has been returned, all subsequent calls return `nil`.
   ///
   /// - Precondition: `next()` has not been applied to a copy of `self`
-  ///   since the copy was made, and no preceding call to `self.next()`
-  ///   has returned `nil`.  Specific implementations of this protocol
-  ///   are encouraged to respond to violations of this requirement by
-  ///   calling `preconditionFailure("...")`.
+  ///   since the copy was made.
   @warn_unused_result
   mutating func next() -> Element?
 }
@@ -637,12 +634,11 @@ public struct IteratorSequence<
     _base = base
   }
 
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
+  /// Advance to the next element and return it, or `nil` if no next element
+  /// exists. Once `nil` has been returned, all subsequent calls return `nil`.
   ///
   /// - Precondition: `next()` has not been applied to a copy of `self`
-  ///   since the copy was made, and no preceding call to `self.next()`
-  ///   has returned `nil`.
+  ///   since the copy was made.
   public mutating func next() -> Base.Element? {
     return _base.next()
   }