Comprehensive documentation for Collection?

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

It’s a problem with Apple documentation. swiftdoc.org does list the associated types, but is no longer maintained :(.

-- Howard.

···

On 16 Dec 2017, at 1:17 pm, Nevin Brackett-Rozinsky via swift-users <swift-users@swift.org> wrote:

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 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 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
_______________________________________________
swift-users mailing list
swift-users@swift.org
https://lists.swift.org/mailman/listinfo/swift-users

Meant to respond to the list with this reply:

The Index associated type used to show up on developer.apple.com. The way it’s declared changed between Swift 3.x and Swift 4.0 such that it doesn’t appear anymore. (It’s declared as part of _IndexableBase, where the underscore indicates that the type is intended to be an undocumented implementation detail: https://github.com/apple/swift/blob/master/docs/StdlibRationales.rst#protocols-with-restricted-conformance-rules)

On the current swift-4.1-branch, Index is declared directly on Collection, so it should start showing up again in the future.

-Kyle

···

On Dec 15, 2017, at 10:06 PM, Howard Lovatt via swift-users <swift-users@swift.org> wrote:

It’s a problem with Apple documentation. swiftdoc.org does list the associated types, but is no longer maintained :(.

-- Howard.

On 16 Dec 2017, at 1:17 pm, Nevin Brackett-Rozinsky via swift-users <swift-users@swift.org> wrote:

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 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 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
_______________________________________________
swift-users mailing list
swift-users@swift.org
https://lists.swift.org/mailman/listinfo/swift-users

_______________________________________________
swift-users mailing list
swift-users@swift.org
https://lists.swift.org/mailman/listinfo/swift-users