diff --git a/stdlib/public/core/Algorithm.swift b/stdlib/public/core/Algorithm.swift index 9049e55ba6d35..7958b2f8cd4f2 100644 --- a/stdlib/public/core/Algorithm.swift +++ b/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 } diff --git a/stdlib/public/core/Collection.swift b/stdlib/public/core/Collection.swift index 6285cf0e0a28c..440b60cb14b67 100644 --- a/stdlib/public/core/Collection.swift +++ b/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 diff --git a/stdlib/public/core/CollectionOfOne.swift b/stdlib/public/core/CollectionOfOne.swift index 10564532ac8ff..6b59dfffa28f0 100644 --- a/stdlib/public/core/CollectionOfOne.swift +++ b/stdlib/public/core/CollectionOfOne.swift @@ -19,12 +19,13 @@ public struct IteratorOverOne : 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 diff --git a/stdlib/public/core/ExistentialCollection.swift.gyb b/stdlib/public/core/ExistentialCollection.swift.gyb index c8a303cb1d414..6fa4a14ff2bad 100644 --- a/stdlib/public/core/ExistentialCollection.swift.gyb +++ b/stdlib/public/core/ExistentialCollection.swift.gyb @@ -74,8 +74,10 @@ public struct AnyIterator : 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 : IteratorProtocol { } internal class _AnyIteratorBoxBase : 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() } diff --git a/stdlib/public/core/Filter.swift.gyb b/stdlib/public/core/Filter.swift.gyb index 43e62060aad07..1122429cfc8d6 100644 --- a/stdlib/public/core/Filter.swift.gyb +++ b/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) { diff --git a/stdlib/public/core/Flatten.swift.gyb b/stdlib/public/core/Flatten.swift.gyb index ca94785668e11..184e389326e84 100644 --- a/stdlib/public/core/Flatten.swift.gyb +++ b/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) { diff --git a/stdlib/public/core/HashedCollections.swift.gyb b/stdlib/public/core/HashedCollections.swift.gyb index de11f9bd1a423..332e35f9507f8 100644 --- a/stdlib/public/core/HashedCollections.swift.gyb +++ b/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) { diff --git a/stdlib/public/core/Join.swift b/stdlib/public/core/Join.swift index ee6e1f514c074..f6c6e787a96fd 100644 --- a/stdlib/public/core/Join.swift +++ b/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 { diff --git a/stdlib/public/core/Map.swift.gyb b/stdlib/public/core/Map.swift.gyb index 59b457a3f583a..186cbf665054c 100644 --- a/stdlib/public/core/Map.swift.gyb +++ b/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) } diff --git a/stdlib/public/core/Sequence.swift b/stdlib/public/core/Sequence.swift index d354e3b3c45b2..9c44301687d35 100644 --- a/stdlib/public/core/Sequence.swift +++ b/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() } diff --git a/stdlib/public/core/Stride.swift.gyb b/stdlib/public/core/Stride.swift.gyb index d0d1b9a701cd1..b3ef593a626a9 100644 --- a/stdlib/public/core/Stride.swift.gyb +++ b/stdlib/public/core/Stride.swift.gyb @@ -131,8 +131,10 @@ public struct StrideToIterator : IteratorProtocol { internal let _end: Element internal let _stride: Element.Stride - /// 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() -> Element? { if _stride > 0 ? _current >= _end : _current <= _end { return nil @@ -188,8 +190,10 @@ public struct StrideThroughIterator : IteratorProtocol { internal let _stride: Element.Stride internal var _done: Bool = false - /// 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() -> Element? { if _done { return nil diff --git a/stdlib/public/core/StringUnicodeScalarView.swift b/stdlib/public/core/StringUnicodeScalarView.swift index fa1ca4ae94079..d2ebfd56cc23f 100644 --- a/stdlib/public/core/StringUnicodeScalarView.swift +++ b/stdlib/public/core/StringUnicodeScalarView.swift @@ -245,13 +245,13 @@ extension String { } } - /// Advances to the next element and returns it. + /// Advances to the next element and returns it, or `nil` if no next + /// element exists. /// - /// Do not call this method if a copy of the iterator has been advanced. + /// Once `nil` has been returned, all subsequent calls return `nil`. /// - /// - Returns: The next element in the collection if an element is - /// available; otherwise, `nil`. After returning `nil` once, this - /// method returns `nil` on every subsequent call. + /// - Precondition: `next()` has not been applied to a copy of `self` + /// since the copy was made. public mutating func next() -> UnicodeScalar? { var result: UnicodeDecodingResult if _baseSet { diff --git a/stdlib/public/core/UnsafeBufferPointer.swift.gyb b/stdlib/public/core/UnsafeBufferPointer.swift.gyb index ca98e2008310f..eb7a4ba2bc4cd 100644 --- a/stdlib/public/core/UnsafeBufferPointer.swift.gyb +++ b/stdlib/public/core/UnsafeBufferPointer.swift.gyb @@ -15,8 +15,10 @@ public struct UnsafeBufferPointerIterator : 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`. public mutating func next() -> Element? { if _position == _end { return nil } diff --git a/stdlib/public/core/Zip.swift b/stdlib/public/core/Zip.swift index 4107d60900751..44eaf5ea2b55e 100644 --- a/stdlib/public/core/Zip.swift +++ b/stdlib/public/core/Zip.swift @@ -31,12 +31,13 @@ public struct Zip2Iterator< (_baseStream1, _baseStream2) = (iterator1, iterator2) } - /// 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? { // The next() function needs to track if it has reached the end. If we // didn't, and the first sequence is longer than the second, then when we