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

Brent Royal-Gordon brent at architechies.com
Thu Feb 11 17:24:02 CST 2016

> 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

More information about the swift-evolution mailing list