SetAlgebra naming update

Evolution Discussion
1

Just an update:

The naming guidelines working group went back into negotiation over
the shape of SetAlgebra (and thus, Set and OptionSet) for
Swift 3, and reached a new consensus. We intend to bring forward a
proposal for the API shown here:

  SetAlgebra / Math

and to update the guidelines to suggest using the "form" prefix to
create a verb phrase for a mutating method when the operation is
fundamentally non-mutating and described by a noun.

Regards,

···

--
Dave

2

Just an update:

The naming guidelines working group went back into negotiation over
the shape of SetAlgebra (and thus, Set and OptionSet) for
Swift 3, and reached a new consensus. We intend to bring forward a
proposal for the API shown here:

SetAlgebra / Math

and to update the guidelines to suggest using the "form" prefix to
create a verb phrase for a mutating method when the operation is
fundamentally non-mutating and described by a noun.

I've got to say, I expected to hate this until I clicked the link and saw the actual
proposed syntax. For the most part, it's good: clear and readable.

Not a fan of "subtracting" (would prefer "bySubtracting"). Other than that
really impressed by how this evolved.

-- E

···

On Mar 24, 2016, at 2:39 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

3

Much improved, IMO. A few thoughts:
* typo in "formSymmetricDifference"
* I don't know about the preposition "from" in "form symmetric difference
from" (also, inconsistent, because you don't have "form union with")
* "form" is fine, but scans similarly to "from" when reading quickly

···

On Thu, Mar 24, 2016 at 3:41 PM Dave Abrahams via swift-evolution < swift-evolution@swift.org> wrote:

Just an update:

The naming guidelines working group went back into negotiation over
the shape of SetAlgebra (and thus, Set and OptionSet) for
Swift 3, and reached a new consensus. We intend to bring forward a
proposal for the API shown here:

  SetAlgebra / Math

and to update the guidelines to suggest using the "form" prefix to
create a verb phrase for a mutating method when the operation is
fundamentally non-mutating and described by a noun.

Regards,

--
Dave

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

4

I would suggest xxxing and xxx naming like sorting and sort, e.g.:

    y = x.unioning(z)
    x.union(z)

The consistency of naming is more important to me than correct English. The
reason for this preference is that it quickly becomes 2nd nature to know
the names of variations and because the names begin with the same root and
are therefore code completion friendly.

···

On Friday, 25 March 2016, Dave Abrahams via swift-evolution < swift-evolution@swift.org> wrote:

Just an update:

The naming guidelines working group went back into negotiation over
the shape of SetAlgebra (and thus, Set and OptionSet) for
Swift 3, and reached a new consensus. We intend to bring forward a
proposal for the API shown here:

  SetAlgebra / Math

and to update the guidelines to suggest using the "form" prefix to
create a verb phrase for a mutating method when the operation is
fundamentally non-mutating and described by a noun.

Regards,

--
Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <javascript:;>
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-- Howard.

5

Can we rename `subtract` to `complement`, since that’s the correct term? At least, I’m assuming that’s what `subtract` means… if not, I’m confused.

- Dave Sweeris

···

On Mar 24, 2016, at 3:39 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

Just an update:

The naming guidelines working group went back into negotiation over
the shape of SetAlgebra (and thus, Set and OptionSet) for
Swift 3, and reached a new consensus. We intend to bring forward a
proposal for the API shown here:

SetAlgebra / Math

and to update the guidelines to suggest using the "form" prefix to
create a verb phrase for a mutating method when the operation is
fundamentally non-mutating and described by a noun.

Regards,

--
Dave

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

6

I don't love it but given how long we've spent discussing this and you've spent thinking about it I can believe it's the answer that makes the most sense. I do have one question: what are 'element(_:subsumes:)' and 'element(_:isDisjointWith:)' for? Imported option sets with non-orthogonal options? I know that's not that uncommon, but I don't know why I would need dedicated operations for it, especially when these types have Element == Self.

(The naming guidelines also fall down on static methods like this. The base name doesn't describe the operation at all.)

Jordan

···

On Mar 24, 2016, at 13:39, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

Just an update:

The naming guidelines working group went back into negotiation over
the shape of SetAlgebra (and thus, Set and OptionSet) for
Swift 3, and reached a new consensus. We intend to bring forward a
proposal for the API shown here:

SetAlgebra / Math

and to update the guidelines to suggest using the "form" prefix to
create a verb phrase for a mutating method when the operation is
fundamentally non-mutating and described by a noun.

Regards,

--
Dave

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

7

I think that this is a great improvement and is consistent enough to
accept. `form` will take some getting used to.
TJ

···

On Thu, Mar 24, 2016 at 9:39 PM, Dave Abrahams via swift-evolution < swift-evolution@swift.org> wrote:

Just an update:

The naming guidelines working group went back into negotiation over
the shape of SetAlgebra (and thus, Set and OptionSet) for
Swift 3, and reached a new consensus. We intend to bring forward a
proposal for the API shown here:

  SetAlgebra / Math

and to update the guidelines to suggest using the "form" prefix to
create a verb phrase for a mutating method when the operation is
fundamentally non-mutating and described by a noun.

Regards,

--
Dave

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

8

x by subtracting y

means, “give me x, and get it by subtracting y.” The use of “byXXXing”
in existing Cocoa APIs doesn't really set a precedent because it was
always preceded by a noun that described the result being returned,
e.g. “x.stringByAppending(y),” which is a completely different thing.

···

on Thu Mar 24 2016, Erica Sadun <swift-evolution@swift.org> wrote:

On Mar 24, 2016, at 2:39 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

Just an update:

The naming guidelines working group went back into negotiation over
the shape of SetAlgebra (and thus, Set and OptionSet) for
Swift 3, and reached a new consensus. We intend to bring forward a
proposal for the API shown here:

SetAlgebra / Math

and to update the guidelines to suggest using the "form" prefix to
create a verb phrase for a mutating method when the operation is
fundamentally non-mutating and described by a noun.

I've got to say, I expected to hate this until I clicked the link and saw the actual
proposed syntax. For the most part, it's good: clear and readable.

Not a fan of "subtracting" (would prefer "bySubtracting"). Other than that
really impressed by how this evolved.

--
Dave

9

Much improved, IMO. A few thoughts:
* typo in "formSymmetricDifference"

Thanks, fixed.

* I don't know about the preposition "from" in "form symmetric difference
from" (also, inconsistent, because you don't have "form union with")

Good point. What would you suggest? We could use “with:” everywhere in
the “formXXX” methods...

* "form" is fine, but scans similarly to "from" when reading quickly

That's a good point. Maybe that's another good reason to drop “from:”
as a preposition in formSymmetricDifference.

···

on Thu Mar 24 2016, Xiaodi Wu <swift-evolution@swift.org> wrote:

On Thu, Mar 24, 2016 at 3:41 PM Dave Abrahams via swift-evolution < > swift-evolution@swift.org> wrote:

Just an update:

The naming guidelines working group went back into negotiation over
the shape of SetAlgebra (and thus, Set and OptionSet) for
Swift 3, and reached a new consensus. We intend to bring forward a
proposal for the API shown here:

  SetAlgebra / Math

and to update the guidelines to suggest using the "form" prefix to
create a verb phrase for a mutating method when the operation is
fundamentally non-mutating and described by a noun.

Regards,

--
Dave

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

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

--
Dave

10

The problem with “difference” is that it's not symmetrical; you really
need to do something to clarify which is the minuend and which is the
subtrahend (yes, I had to look those terms up to write this post!)

subtract and subtracting make that clear.

···

on Thu Mar 24 2016, Ricardo Parada <swift-evolution@swift.org> wrote:

Hi all,

I could get used to the formNoun naming convention for the mutable versions of the methods.

I would suggest the following changes:

Remove the parameter label from symmetricDifference() and formSymmetricDifference() to be consistent with the other methods.

Consider renaming:
subtracting / subtract

to:
difference / formDifference

in order to keep the API consistent.

--
Dave

11

Hi all,

I could get used to the formNoun naming convention for the mutable versions of the methods.

I would suggest the following changes:

Remove the parameter label from symmetricDifference() and formSymmetricDifference() to be consistent with the other methods.

Consider renaming:
subtracting / subtract

to:
difference / formDifference

in order to keep the API consistent.

Thanks

···

On Mar 24, 2016, at 5:35 PM, Xiaodi Wu via swift-evolution <swift-evolution@swift.org> wrote:

Much improved, IMO. A few thoughts:
* typo in "formSymmetricDifference"
* I don't know about the preposition "from" in "form symmetric difference from" (also, inconsistent, because you don't have "form union with")
* "form" is fine, but scans similarly to "from" when reading quickly

On Thu, Mar 24, 2016 at 3:41 PM Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

Just an update:

The naming guidelines working group went back into negotiation over
the shape of SetAlgebra (and thus, Set and OptionSet) for
Swift 3, and reached a new consensus. We intend to bring forward a
proposal for the API shown here:

  SetAlgebra / Math

and to update the guidelines to suggest using the "form" prefix to
create a verb phrase for a mutating method when the operation is
fundamentally non-mutating and described by a noun.

Regards,

--
Dave

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

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

12

Initially, I was 99% happy. My initial reservation had been with subtracting/subtract and thought that subtract/formSubtraction might have been better.

But with your clarification (and vocabulary for the day!) subtract and subtracting make sense and I’m 100% for the proposed SetAlgebra.

···

On Mar 24, 2016, at 7:25 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Thu Mar 24 2016, Ricardo Parada <swift-evolution@swift.org> wrote:

Hi all,

I could get used to the formNoun naming convention for the mutable versions of the methods.

I would suggest the following changes:

Remove the parameter label from symmetricDifference() and formSymmetricDifference() to be consistent with the other methods.

Consider renaming:
subtracting / subtract

to:
difference / formDifference

in order to keep the API consistent.

The problem with “difference” is that it's not symmetrical; you really
need to do something to clarify which is the minuend and which is the
subtrahend (yes, I had to look those terms up to write this post!)

subtract and subtracting make that clear.

13

Much improved, IMO. A few thoughts:
* typo in "formSymmetricDifference"

Thanks, fixed.

* I don't know about the preposition "from" in "form symmetric difference
from" (also, inconsistent, because you don't have "form union with")

Good point. What would you suggest? We could use “with:” everywhere in
the “formXXX” methods...

For the nonmutating method, maybe just `x = y.symmetricDifference(z)`.
Prepositions are useful to have because they clarify the relationship
between two or more things--but here, by construction, it's symmetric.
For the mutating methods, either `y.formXXX(with: z)` or
`y.formXXX(z)` look good to me.

* "form" is fine, but scans similarly to "from" when reading quickly

That's a good point. Maybe that's another good reason to drop “from:”
as a preposition in formSymmetricDifference.

Yup.

···

On Thu, Mar 24, 2016 at 7:23 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Thu Mar 24 2016, Xiaodi Wu <swift-evolution@swift.org> wrote:

14

Can we rename `subtract` to `complement`, since that’s the correct
term? At least, I’m assuming that’s what `subtract` means… if not, I’m
confused.
Set (mathematics) - Wikipedia

It's not just “complement,” because that means inverting set membership
of everything in a finite domain. It would have to be “relative
complement.” But “relative complement” lacks the directional
implication that plagues terms like “difference,” but not “subtracting.”

I think in this case “subtract” works better.

···

on Fri Mar 25 2016, davesweeris-AT-mac.com wrote:

- Dave Sweeris

On Mar 24, 2016, at 3:39 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

Just an update:

The naming guidelines working group went back into negotiation over
the shape of SetAlgebra (and thus, Set and OptionSet) for
Swift 3, and reached a new consensus. We intend to bring forward a
proposal for the API shown here:

SetAlgebra / Math

and to update the guidelines to suggest using the "form" prefix to
create a verb phrase for a mutating method when the operation is
fundamentally non-mutating and described by a noun.

Regards,

--
Dave

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

--
Dave

15

I don't love it but given how long we've spent discussing this and
you've spent thinking about it I can believe it's the answer that
makes the most sense. I do have one question: what are
'element(_:subsumes:)' and 'element(_:isDisjointWith:)' for? Imported
option sets with non-orthogonal options? I know that's not that
uncommon, but I don't know why I would need dedicated operations for
it, especially when these types have Element == Self.

You don't need them; they're there so sensible semantic axioms could be
established for SetAlgebra. Eventually, we'll get rid of Element ==
Self and we can retire those too :-)

···

on Mon Mar 28 2016, Jordan Rose <jordan_rose-AT-apple.com> wrote:

(The naming guidelines also fall down on static methods like this. The
base name doesn't describe the operation at all.)

Jordan

On Mar 24, 2016, at 13:39, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

Just an update:

The naming guidelines working group went back into negotiation over
the shape of SetAlgebra (and thus, Set and OptionSet) for
Swift 3, and reached a new consensus. We intend to bring forward a
proposal for the API shown here:

SetAlgebra / Math

and to update the guidelines to suggest using the "form" prefix to
create a verb phrase for a mutating method when the operation is
fundamentally non-mutating and described by a noun.

Regards,

--
Dave

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

--
Dave

16

So far in each of the naming situations where I have disliked a particular form
("subtracting" here), the final results have been good. Apparently
the strategy of pointing out the bad points and letting magic happen behind
the scenes is a successful one.

Because that's not very helpful:

* excluding
* differenceFrom
* minus
* excepting
* subtractingElementsFrom / subtractingElements(from: or of:

-- E

···

On Mar 24, 2016, at 6:19 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Thu Mar 24 2016, Erica Sadun <swift-evolution@swift.org> wrote:

On Mar 24, 2016, at 2:39 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

Just an update:

The naming guidelines working group went back into negotiation over
the shape of SetAlgebra (and thus, Set and OptionSet) for
Swift 3, and reached a new consensus. We intend to bring forward a
proposal for the API shown here:

SetAlgebra / Math

and to update the guidelines to suggest using the "form" prefix to
create a verb phrase for a mutating method when the operation is
fundamentally non-mutating and described by a noun.

I've got to say, I expected to hate this until I clicked the link and saw the actual
proposed syntax. For the most part, it's good: clear and readable.

Not a fan of "subtracting" (would prefer "bySubtracting"). Other than that
really impressed by how this evolved.

     x by subtracting y

means, “give me x, and get it by subtracting y.” The use of “byXXXing”
in existing Cocoa APIs doesn't really set a precedent because it was
always preceded by a noun that described the result being returned,
e.g. “x.stringByAppending(y),” which is a completely different thing.

17

Fair points… I accidentally left off the argument label. May I amend my suggestion to "rename `subtract(:)` to `complement(relativeTo:)`”? It just seems to me that if we’re going to claim we’re implementing something, we should adopt as much of its “standard" syntax and terminology as possible. It makes Swift easier to use for those coming from other disciplines, IMHO.

- Dave Sweeris

···

On Mar 25, 2016, at 4:45 PM, Dave Abrahams <dabrahams@apple.com> wrote:

on Fri Mar 25 2016, davesweeris-AT-mac.com wrote:

Can we rename `subtract` to `complement`, since that’s the correct
term? At least, I’m assuming that’s what `subtract` means… if not, I’m
confused.
Set (mathematics) - Wikipedia

It's not just “complement,” because that means inverting set membership
of everything in a finite domain. It would have to be “relative
complement.” But “relative complement” lacks the directional
implication that plagues terms like “difference,” but not “subtracting.”

18

Don't forget, you need to come up with a pair of mutating/nonmutating
names.

···

on Thu Mar 24 2016, Erica Sadun <erica-AT-ericasadun.com> wrote:

On Mar 24, 2016, at 6:19 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Thu Mar 24 2016, Erica Sadun <swift-evolution@swift.org> wrote:

On Mar 24, 2016, at 2:39 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

Just an update:

The naming guidelines working group went back into negotiation over
the shape of SetAlgebra (and thus, Set and OptionSet) for
Swift 3, and reached a new consensus. We intend to bring forward a
proposal for the API shown here:

SetAlgebra / Math

and to update the guidelines to suggest using the "form" prefix to
create a verb phrase for a mutating method when the operation is
fundamentally non-mutating and described by a noun.

I've got to say, I expected to hate this until I clicked the link and saw the actual
proposed syntax. For the most part, it's good: clear and readable.

Not a fan of "subtracting" (would prefer "bySubtracting"). Other than that
really impressed by how this evolved.

     x by subtracting y

means, “give me x, and get it by subtracting y.” The use of “byXXXing”
in existing Cocoa APIs doesn't really set a precedent because it was
always preceded by a noun that described the result being returned,
e.g. “x.stringByAppending(y),” which is a completely different thing.

So far in each of the naming situations where I have disliked a particular form
("subtracting" here), the final results have been good. Apparently
the strategy of pointing out the bad points and letting magic happen behind
the scenes is a successful one.

Because that's not very helpful:

* excluding
* differenceFrom
* minus
* excepting
* subtractingElementsFrom / subtractingElements(from: or of:

--
Dave

19

If you took 100 random developers off the street, and showed them code that said:

set1.formRelativeComplement(set2)

and

set1.subtracting(set2)

About 99.5% of them would understand the second better than the first on first read.
The other 0.5 of a developer would be living somewhere near Boulder and growing
his own hemi-pharmaceuticals.

The problem with subtraction is that there isn't really a good noun/formNoun pair
for it. That means either breaking the pair into two words that aren't well matched
or using a noun that isn't that amazing, such as difference.

set1.difference(set2)
set1.formDifference(set2)

In all my attempts at trying to brainstorm up a better word that would (1) retain
the characteristics of mutating/non-mutating pairing while (2) being easy to read
and understand, I could not come up with better than Dave A's subtract/subtracting.
I may not like it aesthetically but when it comes to offering something better,
I've got nothing.

That said, I'd really like to see a Swift Doc markup that allows you to mark
pairs of mutating/nonmutating functions, not from a compiler point of
view but in doc markup.

/// - nonmutatingVersion:
/// - mutatingVersion:

What group handles expansion of the markup keywords and how can I file a
feature request asking for this to be added?

Thanks,

-- E

···

On Mar 28, 2016, at 6:19 PM, Dave via swift-evolution <swift-evolution@swift.org> wrote:

On Mar 25, 2016, at 4:45 PM, Dave Abrahams <dabrahams@apple.com> wrote:

on Fri Mar 25 2016, davesweeris-AT-mac.com wrote:

Can we rename `subtract` to `complement`, since that’s the correct
term? At least, I’m assuming that’s what `subtract` means… if not, I’m
confused.
Set (mathematics) - Wikipedia

It's not just “complement,” because that means inverting set membership
of everything in a finite domain. It would have to be “relative
complement.” But “relative complement” lacks the directional
implication that plagues terms like “difference,” but not “subtracting.”

Fair points… I accidentally left off the argument label. May I amend my suggestion to "rename `subtract(:)` to `complement(relativeTo:)`”? It just seems to me that if we’re going to claim we’re implementing something, we should adopt as much of its “standard" syntax and terminology as possible. It makes Swift easier to use for those coming from other disciplines, IMHO.

20

swift-evolution is the right place for this. As I mentioned in a different thread, I think that having a more general “relatedto:” notion would be useful to have. There are interesting relations between methods other than mutation. One example is the localized vs non-localized versions of string operations, etc.

-Chris

···

On Mar 28, 2016, at 5:34 PM, Erica Sadun via swift-evolution <swift-evolution@swift.org> wrote:

That said, I'd really like to see a Swift Doc markup that allows you to mark
pairs of mutating/nonmutating functions, not from a compiler point of
view but in doc markup.

/// - nonmutatingVersion:
/// - mutatingVersion:

What group handles expansion of the markup keywords and how can I file a
feature request asking for this to be added?