[swift-users] Comprehensive documentation for Collection?

[Nevin Brackett-Rozinsky]

In Xcode if I write,

extension Collection {
    var secondIndex: Index { return index(after: startIndex) }
}

and then option-click on “Index”, it shows “associatedtype Index :
Comparable” followed by a description. Is this documented somewhere?

When I look at the documentation for Collection
<https://developer.apple.com/documentation/swift/collection> on
developer.apple.com there is no mention of an Index associated type. I also
don’t see it in The Swift Programming Language.

If someone didn’t already know Collection.Index exists, how would they be
expected to learn of it? And if they didn’t know it must be Comparable how
would they learn that?

Also, are there any semantic requirements on Collection.Index, for example
is it required that “idx < index(after: idx)” must evaluate to true for any
valid index “idx”?

• • •

On a somewhat related note, the “indices” property of Collection has a
discussion section visible by option-clicking in Xcode or by looking
at the documentation
for it
<https://developer.apple.com/documentation/swift/collection/1641719-indices>
on developer.apple.com.

And that discussion recommends against iterating over “indices” when
mutating a collection, because “indices” could hold a strong reference to
the collection and thus create an unexpected copy. Instead one should
manually advance from startIndex to endIndex in a while loop.

Now, this is at least documented, but perhaps it should be made more
prominent? It seems to me that if “for i in c.indices” represents a
performance pitfall then it should be regarded as an attractive nuisance.

Nevin
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-users/attachments/20171215/85c252e8/attachment.html>