[swift-evolution] ed/ing, InPlace, Set/SetAlgebra naming resolution

[Dave Abrahams]

on Fri Feb 12 2016, Sébastien Blondiau <swift-evolution at swift.org> wrote:

> Using only the operators | & - ^ |= &= -= ^= for the operations on Set
> would simplify the code and resolve the problem of the names of these
> functions. Set do not really need these functions as method, only the
> operators would be enough, like the BitwiseOperationsType which do not
> have the methods xor and orInPlace ...

We have a semantic muddle in this area, because:

* We believe that bitwise operations on integers are distinct from set
  operations and should use different notation.

* We believe that option sets are set-like and should use set notation.

* Yet option sets are, semantically, exactly like the bitwise aspect of
  integers (i.e. the set elements are the same type as the sets themselves
  and may subsume one-another).

We can't really keep all these contradictions in the air at once and not
end up with a naming mess.

> With the operators, the question of "does this function mutate?" would
> not be anymore. The code would get clarity and brevity without problem
> of naming. Isn’t that the API Design Guidelines?
>
> --
> Sébastien
>
>> Le 12 févr. 2016 à 00:24, Brent Royal-Gordon via swift-evolution <swift-evolution at swift.org> a écrit :
>> 
>>> The API guidelines working group took up the issue of the InPlace suffix
>>> yesterday, and decided that it was not to be used anywhere in the
>>> standard library.  We are planning to apply the changes shown here
>>> <https://gist.github.com/dabrahams/d872556291a3cb797bd5> to the API of
>>> SetAlgebra (and consequently Set) to make it conform to the guidelines
>>> under development.
>> 
>> My suggestions:
>> 
>> 	union -> union
>> 	intersect -> intersection
>> 	subtract -> subtraction
>> 
>> 	unionInPlace -> unite
>> 	intersectInPlace -> intersect
>> 	subtractInPlace -> subtract
>> 
>> In other words, treat the mutating forms as imperative verbs and the nonmutating forms as nouns. This basically makes the nonmutating forms into accessors, which I think is a good alternative given the trouble we're having with -ing/-ed.
>> 
>> That still leaves exclusiveOr, which is frankly a horrible name to begin with. I think we have to derive a name from the "symmetric difference" terminology, giving us
>> 
>> 	exclusiveOr -> difference
>> 	exclusiveOrInPlace -> differ
>> 
>> However, given the difficulty we're having coming up with names, we might want to explore using operators instead.
>> 
>> 	union -> |
>> 	intersect -> &
>> 	subtract -> -
>> 	exclusiveOr -> ^
>> 
>> This gives us extremely straightforward mutating operators, of course, since we do have a convention for in-place operators:
>> 
>> 	unionInPlace -> |=
>> 	intersectInPlace -> &=
>> 	subtract -> -=
>> 	exclusiveOr -> ^=
>> 
>> Some things to like about these operators:
>> 
>> * They are not used for anything on sequences or collections, so they don't overload existing concepts like concatenation with incompatible semantics.
>> * They have the same commutativity and transitivity as the associated integer operations.
>> * The bitwise forms of `|` and `&` are already documented (in `_DisallowMixedSignArithmetic`) as the union and intersection of the bits, and `^` is documented in a compatible way.  Meanwhile, `-` literally means "subtraction", the exact same operation we're exposing.
>> * And of course, it's just *nice* to not have to write long, unwieldy method names for fundamental operations.
>> 
>> Swift generally tries not to overload operators too much, but I think in this case, these overloads would be appropriate and helpful, while also getting us out of a sticky naming problem.
>> 
>> -- 
>> Brent Royal-Gordon
>> Architechies
>> 
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave