Re: [swift-users] Comprehensive documentation for Collection?

[Kyle Murray via 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 
>  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 
>>  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
___
swift-users mailing list
swift-users@swift.org
https://lists.swift.org/mailman/listinfo/swift-users

Re: [swift-users] Comprehensive documentation for Collection?

[Howard Lovatt via swift-users]

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 
>  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

[swift-users] Comprehensive documentation for Collection?

[Nevin Brackett-Rozinsky via swift-users]

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