[swift-evolution] [Review] SE-0059: Update API Naming Guidelines and Rewrite Set APIs Accordingly

[Brent Royal-Gordon]

> My apologies if this was previously discussed. Was there ever a reason given for not using operators for set combiners? That is, | & - ^ for union, intersection, subtracting, and symmetricDifference, and |= &= -= ^= for the mutating versions.

With a few exceptions (like `+` for concatenation), Swift doesn't overload operators to give them different meanings, even if they're kinda similar if you squint enough.

* * *

My review follows:

> https://github.com/apple/swift-evolution/blob/master/proposals/0059-updated-set-apis.md


> 	• What is your evaluation of the proposal?

I'm in favor of the updated guidelines and new names; they are straightforward and understandable. I'm not entirely happy with `subtract` being different from the others, but contorting it to match seems unwise, particularly when we're trying to demonstrate the API guidelines.

I have some issues with the new `insert(_:)` return value:

* I'm not sure what the purpose is of returning the new value if a value is inserted. Couldn't we return an `Element?` containing the old value if there is one, or `nil` if there's a new value?

* If an `insert` might collide with several elements, shouldn't we return a set of all the colliding elements, instead of `nil`? (This would do away with the exception for `OptionSetType.insert`.)

* Whatever `insert` does, shouldn't `update(with:)` do the same thing? Particularly with regards to updating multiple elements?

* How far does this "don't throw away information that's hard to recalculate" principle go? Should the mutating operations like `formUnion` return some indication of the affected elements? Should the *nonmutating* ones?

* If we're going to officially support equal-but-distinct elements in the SetAlgebra API, shouldn't we have an equivalent to NSSet's `member(_:)` method?

We can try to work out these and other issues in this thread, but unless there are straightforward answers, I think the better move might be to sever the return value change and discuss it separately. It brings up a lot of subtle questions across the entire API.

> 	• Is the problem being addressed significant enough to warrant a change to Swift?

Yes. These APIs need to be renamed.

> 	• Does this proposal fit well with the feel and direction of Swift?

Yes. It solves an important issue with the guidelines.

> 	• If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?

This API is superior to NSSet/NSMutableSet and Ruby's Set, which are the two set APIs I'm most familiar with.

> 	• How much effort did you put into your review? A glance, a quick reading, or an in-depth study?

On the naming issue, I participated heavily in the Threads of Infinite Bikeshedding.

On the return value issue, something slightly more than a quick reading.

-- 
Brent Royal-Gordon
Architechies