Merge pull request #1702 from PatrickPijnappel/iterator-post-nil-guarantee

[stdlib] Change post-nil guarantee for IteratorProtocol.next()

Author: gribozavr

stdlib/public/core/Algorithm.swift

@@ -80,10 +80,10 @@ 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.
+  /// Advances to the next element and returns it, or `nil` if no next element
+  /// exists.
   ///
-  /// - Requires: No preceding call to `self.next()` has returned `nil`.
+  /// 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

@@ -378,10 +378,8 @@ public struct IndexingIterator<
   /// exists.
   ///
   /// Repeatedly calling this method returns all the elements of the underlying
-  /// sequence in order. As soon as the sequence has run out of elements, the
-  /// `next()` method returns `nil`.
-  ///
-  /// You must not call this method if it has previously returned `nil`.
+  /// sequence in order.  As soon as the sequence has run out of elements, all
+  /// subsequent calls return `nil`.
   ///
   /// This example shows how an iterator can be used explicitly to emulate a
   /// `for`-`in` loop. First, retrieve a sequence's iterator, and then call

stdlib/public/core/CollectionOfOne.swift

@@ -19,12 +19,13 @@ public struct IteratorOverOne<Element> : IteratorProtocol, Sequence {
     self._elements = _elements
   }
 
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
+  /// Advances to the next element and returns 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

@@ -74,8 +74,10 @@ public struct AnyIterator<Element> : IteratorProtocol {
     self._box = _box
   }
 
-  /// Advances to the next element and returns it, or `nil` if no next
-  /// element exists.
+  /// Advances to the next element and returns 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()
   }
@@ -96,8 +98,10 @@ internal struct _ClosureBasedIterator<Element> : IteratorProtocol {
 }
 
 internal class _AnyIteratorBoxBase<Element> : IteratorProtocol {
-  /// Advances to the next element and returns it, or `nil` if no next
-  /// element exists.
+  /// Advances to the next element and returns 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/Filter.swift.gyb

@@ -26,12 +26,13 @@ from gyb_stdlib_support import (
 public struct LazyFilterIterator<
   Base : IteratorProtocol
 > : IteratorProtocol, Sequence {
-  /// Advances to the next element and returns it, or `nil` if no next
-  /// element exists.
+  /// Advances to the next element and returns 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? {
     while let n = _base.next() {
       if _predicate(n) {

stdlib/public/core/Flatten.swift.gyb

@@ -35,12 +35,13 @@ public struct FlattenIterator<
     self._base = _base
   }
 
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
+  /// Advances to the next element and returns 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

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

stdlib/public/core/Join.swift

@@ -36,8 +36,10 @@ public struct JoinedIterator<
     self._separatorData = ContiguousArray(separator)
   }
 
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
+  /// Advances to the next element and returns 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.gyb

@@ -24,12 +24,13 @@ from gyb_stdlib_support import (
 public struct LazyMapIterator<
   Base : IteratorProtocol, Element
 > : IteratorProtocol, Sequence {
-  /// Advance to the next element and return it, or `nil` if no next
-  /// element exists.
+  /// Advances to the next element and returns 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/Sequence.swift

@@ -178,16 +178,15 @@ public protocol IteratorProtocol {
   /// The type of element traversed by the iterator.
   associatedtype Element
 
-  /// Advances and returns the next element of the underlying sequence, or
-  /// `nil` if no next element exists.
+  /// Advances to the next element and returns it, or `nil` if no next element
+  /// exists.  Once `nil` has been returned, all subsequent calls return `nil`.
   ///
   /// Repeatedly calling this method returns, in order, all the elements of the
-  /// underlying sequence. After the sequence has run out of elements, the
-  /// `next()` method returns `nil`.
+  /// underlying sequence.  As soon as the sequence has run out of elements, all
+  /// subsequent calls return `nil`.
   ///
-  /// You must not call this method if it has previously returned `nil` or if
-  /// any other copy of this iterator has been advanced with a call to its
-  /// `next()` method.
+  /// You must not call this method if any other copy of this iterator has been
+  /// advanced with a call to its `next()` method.
   ///
   /// The following example shows how an iterator can be used explicitly to
   /// emulate a `for`-`in` loop. First, retrieve a sequence's iterator, and
@@ -1196,12 +1195,13 @@ public struct IteratorSequence<
     _base = base
   }
 
-  /// Advances to the next element and returns it, or `nil` if no next
-  /// element exists.
+  /// Advances to the next element and returns 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()
   }