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

Evolution Announcements
1

Hello Swift community,

The review of SE-0059 "Update API Naming Guidelines and Rewrite Set APIs Accordingly" begins now and runs through April 5, 2016. The proposal is available here:

Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at

https://lists.swift.org/mailman/listinfo/swift-evolution
or, if you would like to keep your feedback private, directly to the review manager. When replying, please try to keep the proposal link at the top of the message:

Proposal link:

Reply text

Other replies
<GitHub - apple/swift-evolution: This maintains proposals for changes and user-visible enhancements to the Swift Programming Language. goes into a review?

The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of Swift. When writing your review, here are some questions you might want to answer in your review:

What is your evaluation of the proposal?
Is the problem being addressed significant enough to warrant a change to Swift?
Does this proposal fit well with the feel and direction of Swift?
If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
More information about the Swift evolution process is available at

Thank you,

Doug Gregor

Review Manager

2

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

A possible mistake in the proposal:

Users needing the old behavior can always use the new replace method, described below.

Then later:

···

A new update(with: newMember) API was added, to provide the previous unconditional insertion semantics of the insert API.

--
Brent Royal-Gordon
Architechies

3

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.

···

On Fri, Apr 1, 2016 at 12:14 AM, Douglas Gregor via swift-evolution < swift-evolution@swift.org> wrote:

Hello Swift community,

The review of SE-0059 "Update API Naming Guidelines and Rewrite Set APIs
Accordingly" begins now and runs through April 5, 2016. The proposal is
available here:

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

Reviews are an important part of the Swift evolution process. All reviews
should be sent to the swift-evolution mailing list at

https://lists.swift.org/mailman/listinfo/swift-evolution

or, if you would like to keep your feedback private, directly to the
review manager. When replying, please try to keep the proposal link at the
top of the message:

Proposal link:

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

Reply text

Other replies

<GitHub - apple/swift-evolution: This maintains proposals for changes and user-visible enhancements to the Swift Programming Language.
goes into a review?

The goal of the review process is to improve the proposal under review
through constructive criticism and, eventually, determine the direction of
Swift. When writing your review, here are some questions you might want to
answer in your review:

   - What is your evaluation of the proposal?
   - Is the problem being addressed significant enough to warrant a
   change to Swift?
   - Does this proposal fit well with the feel and direction of Swift?
   - If you have used other languages or libraries with a similar
   feature, how do you feel that this proposal compares to those?
   - How much effort did you put into your review? A glance, a quick
   reading, or an in-depth study?

More information about the Swift evolution process is available at

https://github.com/apple/swift-evolution/blob/master/process.md

Thank you,

Doug Gregor

Review Manager

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

4

What is your evaluation of the proposal?

I am strongly opposed to the changes to the names of functions implementing set operations, as it is going to introduce a lot of confusion. While I'm a fairly rigid about consistency, I do think that there are acceptable exceptions to any set of rules/guidelines. This represents one of those cases. For example, changing union() to formUnion() for the sake of aligning compliance to API name guidelines simply doesn't make sense to me.

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

No.

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

No.

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

There are plenty of other languages that have API naming guidelines, such as C#, Ruby, and Python. However, they all demonstrate enough lenience to accommodate cases such as this. For example, http://ruby-doc.org/stdlib-2.3.0/libdoc/set/rdoc/Set.html\.

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

In-depth.

5

What is your evaluation of the proposal?

I don't like "form" as a prefix. To me there is no difference between `union` and `formUnion`: both sounds functional-style, and actually the second one perhaps a bit more to my ears. There's basically two dictionary definitions of "form":

1. "bring together parts or combine to create (something)" which to me implies a new value is created, and
2. "make or fashion into a certain shape or form" which would imply that the material you start with is transformed, which is apparently the intended meaning and also the reverse meaning from the above.

I mean, doesn't this make sense as an API?

  let donut = baker.formDonut(dough) // non-mutating

Perhaps instead of "form" we could use "become" as a prefix when the operation is naturally described by a noun. That would seem less ambiguous to me:

  a.becomeUnion(b)
  a.becomeIntersection(b)
  a.becomeSuccessor(b)

It's a bit passive, but I find it fits well when the operation is a noun.

And there's no way the term lends itself to non-mutating cases without things becoming nonsensical:

  let donut = baker.becomeDonut(dough) // non-mutating?

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

I'm still not entirely convinced any of this is better than the `InPlace` suffix we had before. `InPlace` might be ugly visually and grammatically, but seems to be the clearest at expressing the intent.

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

There is no question that using a verb instead of the `InPlace` suffix makes things fits better with the other API guidelines.

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

N/A

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

Read the guideline and API diffs, thought about a few alternative wording, looked in my dictionary.

···

--
Michel Fortin
https://michelf.ca

6

Hi Doug,

What is your evaluation of the proposal?

+1

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

Yes. Swift needs strong Set API’s that play nicey-nicey with the API Guidelines and this proposal is a firm effort in that direction.

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

Yes. This proposal takes nouns that have no commonly used verb form and forms them into verbs, e.g. ‘union’ into ‘formUnion’. It may not look especially pretty to some, but is effective.

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

While not languages, the proposal provides SetAlgebra API that is at least as understandable as Mathematica and much more so than Matlab.

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

I’ve been following this discussion since it’s inception back in…what, early February? I have read the API’s and diff’s. Many times.

···

On Apr 1, 2016, at 12:14 AM, Douglas Gregor via swift-evolution <swift-evolution@swift.org> wrote:

Hello Swift community,

The review of SE-0059 "Update API Naming Guidelines and Rewrite Set APIs Accordingly" begins now and runs through April 5, 2016. The proposal is available here:

https://github.com/apple/swift-evolution/blob/master/proposals/0059-updated-set-apis.md
Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at

https://lists.swift.org/mailman/listinfo/swift-evolution
or, if you would like to keep your feedback private, directly to the review manager. When replying, please try to keep the proposal link at the top of the message:

Proposal link:

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

Other replies
<GitHub - apple/swift-evolution: This maintains proposals for changes and user-visible enhancements to the Swift Programming Language. goes into a review?

The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of Swift. When writing your review, here are some questions you might want to answer in your review:

What is your evaluation of the proposal?
Is the problem being addressed significant enough to warrant a change to Swift?
Does this proposal fit well with the feel and direction of Swift?
If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
More information about the Swift evolution process is available at

https://github.com/apple/swift-evolution/blob/master/process.md
Thank you,

Doug Gregor

Review Manager

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

7

Brent Royal-Gordon via swift-evolution <swift-evolution@...> writes:

A possible mistake in the proposal:

Fixed, thanks!

-Dave

8

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

9

For example, changing union() to formUnion() for the sake of aligning compliance to API name guidelines simply doesn't make sense to me.

Given the need for separate names for the functional and imperative forms of this operation, what sorts of names would be better? Pseudo-verbs like `unioning`? An `InPlace` suffix?

(Everyone else, please don't take this as an invitation to start the bikeshedding again. I'm trying to understand what *this reviewer* prefers.)

···

--
Brent Royal-Gordon
Architechies

10

I also am having difficulty coming to terms with the use of "form" (I am a
native English speaker). As you note "form" can imply the creation of
something from parts (more like assembling a new thing) as well as the
creation of something out of a material say a of block clay (more like
molding something out of an existing thing). It doesn't seem clear cut to
me to imply in place mutation.

Additionally my eyes / brain keep seeing "from" instead of "form". This
type of issue is generally true with any short word made up of the same set
of letters (made worse since "from" is more common in programming then
"form"). The mind quickly narrows in on a set of possible words given the
letters we see and then uses context to help get the correct one and/or
additional visual parsing to understand the exact ordering of letters (more
energy expended). Anyway since I keep seeing "from" instead of "form" I
keep going in the direction of thinking it returns something made from the
two (or more) items involved (not really sure why "from" goes that
direction in my head, it could also go the in place direction).

I would prefer something other then "form" (note I just typed "from" by
mistake)... I think your suggestion of "become" has merit.

y.becomeUnion(x) --reads to me as--> "y become union with x"
y.formUnion(x) --read to me as--> "y from oops... y forming a union of x"
y.becomeIntersection(x) --reads to me as--> "y become intersection with x"
y.formIntersection(x) --read to me as--> "y from oops... y forming an
intersection with x"

In the "forming" situations it – to me – is ambiguous on if that is in
place or not. To me it implies more of giving something new back.

I am -1 on "form" aspect of this proposal. ...of course things are
learnable as long as things are fairly consistent and not to far out of the
norm for typical language use. Personally I don't see "form" as that
typical in English.

-Shawn

···

On Sun, Apr 3, 2016 at 6:41 AM Michel Fortin via swift-evolution < swift-evolution@swift.org> wrote:

> What is your evaluation of the proposal?

I don't like "form" as a prefix. To me there is no difference between
`union` and `formUnion`: both sounds functional-style, and actually the
second one perhaps a bit more to my ears. There's basically two dictionary
definitions of "form":

1. "bring together parts or combine to create (something)" which to me
implies a new value is created, and
2. "make or fashion into a certain shape or form" which would imply that
the material you start with is transformed, which is apparently the
intended meaning and also the reverse meaning from the above.

I mean, doesn't this make sense as an API?

        let donut = baker.formDonut(dough) // non-mutating

Perhaps instead of "form" we could use "become" as a prefix when the
operation is naturally described by a noun. That would seem less ambiguous
to me:

        a.becomeUnion(b)
        a.becomeIntersection(b)
        a.becomeSuccessor(b)

It's a bit passive, but I find it fits well when the operation is a noun.

And there's no way the term lends itself to non-mutating cases without
things becoming nonsensical:

        let donut = baker.becomeDonut(dough) // non-mutating?

11

What is your evaluation of the proposal?

I don't like "form" as a prefix. To me there is no difference between
`union` and `formUnion`: both sounds functional-style, and actually
the second one perhaps a bit more to my ears. There's basically two
dictionary definitions of "form":

1. "bring together parts or combine to create (something)" which to me
implies a new value is created, and
2. "make or fashion into a certain shape or form" which would imply
that the material you start with is transformed, which is apparently
the intended meaning and also the reverse meaning from the above.

When you tell a group of people to “form a circle,” you're asking them
to assume the shape of a circle, not to create a new identity. That's
the way I view “formUnion.”

I mean, doesn't this make sense as an API?

  let donut = baker.formDonut(dough) // non-mutating

Not if you account for the rule that verb phrases and side-effects are
always linked.

Perhaps instead of "form" we could use "become" as a prefix when the
operation is naturally described by a noun. That would seem less
ambiguous to me:

  a.becomeUnion(b)
  a.becomeIntersection(b)
  a.becomeSuccessor(b)

It's a bit passive, but I find it fits well when the operation is a
noun.

The latter one doesn't work at all for the actual use case. It sounds
like you're telling a to become the successor of b. In fact, it's

     someCollection.formSuccessor(&someIndex)

which is updating someIndex to point at its successor position.

And there's no way the term lends itself to non-mutating cases without
things becoming nonsensical:

  let donut = baker.becomeDonut(dough) // non-mutating?

I agree that is more unambiguous.

···

on Sun Apr 03 2016, Michel Fortin <swift-evolution@swift.org> wrote:

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

I'm still not entirely convinced any of this is better than the
`InPlace` suffix we had before. `InPlace` might be ugly visually and
grammatically, but seems to be the clearest at expressing the intent.

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

There is no question that using a verb instead of the `InPlace` suffix
makes things fits better with the other API guidelines.

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

N/A

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

Read the guideline and API diffs, thought about a few alternative wording, looked in my dictionary.

--
Dave

12

Personally, I don't like any of the options. However, I mentioned this during the review of the API naming guidelines. Using the English language to construct function names that distinguish between functional and imperative forms of the operation places constraints on API designers that produce undesirable results. The operations on an algebraic set is merely one example. My preference is a symbol appended to the function name (e.g., the exclamation point in Ruby). However, it was pointed out at the time that introducing this syntax was out-of-scope for Swift 3. What does this mean? We'll revisit this later and have to endure the rigor of another API renaming exercise?

Without rehashing the utility of a symbol to distinguish between functional and imperative, what is my preference?

Pseudo-verbs? I don't know if this is any better.

A suffix, such as "InPlace", has some appeal for two reasons:

1) It is descriptive and doesn't obfuscate the meaning of the operation.

2) If at sometime later the community sees a practical need to introduce syntax to distinguish between functional and imperative forms of an operation, removing such a suffix and replacing it with the symbol will mitigate confusion of another renaming transition.

Cheers,
-Patrick

···

On Apr 2, 2016, at 5:15 PM, Brent Royal-Gordon <brent@architechies.com> wrote:

For example, changing union() to formUnion() for the sake of aligning compliance to API name guidelines simply doesn't make sense to me.

Given the need for separate names for the functional and imperative forms of this operation, what sorts of names would be better? Pseudo-verbs like `unioning`? An `InPlace` suffix?

(Everyone else, please don't take this as an invitation to start the bikeshedding again. I'm trying to understand what *this reviewer* prefers.)

--
Brent Royal-Gordon
Architechies

13

After stepping away for a bit and looking at it from the POV of the API of
Set and not in the context of "y" I could read things in the abstract as...

"becomeUnion(with other:Self)" --> "I become a union with other"
"formUnion(with other:Self)" --> "I form a union with other"

No clear winner to me however when used in code "become" still feels more
strongly mutating then "form": y.formUnion(with:x) or y.becomeUnion(with:x)

All in all the API would have mutating in front of it (at least for
structs) and it wouldn't have a return type. It would become clear fairly
quickly as a result (hence learned).

Just still not that happy with "form" but with use my mind would likely
quickly adapt.

-Shawn

···

On Sun, Apr 3, 2016 at 1:27 PM Shawn Erickson <shawnce@gmail.com> wrote:

On Sun, Apr 3, 2016 at 6:41 AM Michel Fortin via swift-evolution < > swift-evolution@swift.org> wrote:

> What is your evaluation of the proposal?

I don't like "form" as a prefix. To me there is no difference between
`union` and `formUnion`: both sounds functional-style, and actually the
second one perhaps a bit more to my ears. There's basically two dictionary
definitions of "form":

1. "bring together parts or combine to create (something)" which to me
implies a new value is created, and
2. "make or fashion into a certain shape or form" which would imply that
the material you start with is transformed, which is apparently the
intended meaning and also the reverse meaning from the above.

I mean, doesn't this make sense as an API?

        let donut = baker.formDonut(dough) // non-mutating

Perhaps instead of "form" we could use "become" as a prefix when the
operation is naturally described by a noun. That would seem less ambiguous
to me:

        a.becomeUnion(b)
        a.becomeIntersection(b)
        a.becomeSuccessor(b)

It's a bit passive, but I find it fits well when the operation is a noun.

And there's no way the term lends itself to non-mutating cases without
things becoming nonsensical:

        let donut = baker.becomeDonut(dough) // non-mutating?

I also am having difficulty coming to terms with the use of "form" (I am a
native English speaker). As you note "form" can imply the creation of
something from parts (more like assembling a new thing) as well as the
creation of something out of a material say a of block clay (more like
molding something out of an existing thing). It doesn't seem clear cut to
me to imply in place mutation.

Additionally my eyes / brain keep seeing "from" instead of "form". This
type of issue is generally true with any short word made up of the same set
of letters (made worse since "from" is more common in programming then
"form"). The mind quickly narrows in on a set of possible words given the
letters we see and then uses context to help get the correct one and/or
additional visual parsing to understand the exact ordering of letters (more
energy expended). Anyway since I keep seeing "from" instead of "form" I
keep going in the direction of thinking it returns something made from the
two (or more) items involved (not really sure why "from" goes that
direction in my head, it could also go the in place direction).

I would prefer something other then "form" (note I just typed "from" by
mistake)... I think your suggestion of "become" has merit.

y.becomeUnion(x) --reads to me as--> "y become union with x"
y.formUnion(x) --read to me as--> "y from oops... y forming a union of x"
y.becomeIntersection(x) --reads to me as--> "y become intersection with x"
y.formIntersection(x) --read to me as--> "y from oops... y forming an
intersection with x"

14

I think Michel and Shawn did raise some good points here.

-Thorsten

···

Am 03.04.2016 um 22:27 schrieb Shawn Erickson via swift-evolution <swift-evolution@swift.org>:

On Sun, Apr 3, 2016 at 6:41 AM Michel Fortin via swift-evolution <swift-evolution@swift.org> wrote:
> What is your evaluation of the proposal?

I don't like "form" as a prefix. To me there is no difference between `union` and `formUnion`: both sounds functional-style, and actually the second one perhaps a bit more to my ears. There's basically two dictionary definitions of "form":

1. "bring together parts or combine to create (something)" which to me implies a new value is created, and
2. "make or fashion into a certain shape or form" which would imply that the material you start with is transformed, which is apparently the intended meaning and also the reverse meaning from the above.

I mean, doesn't this make sense as an API?

        let donut = baker.formDonut(dough) // non-mutating

Perhaps instead of "form" we could use "become" as a prefix when the operation is naturally described by a noun. That would seem less ambiguous to me:

        a.becomeUnion(b)
        a.becomeIntersection(b)
        a.becomeSuccessor(b)

It's a bit passive, but I find it fits well when the operation is a noun.

And there's no way the term lends itself to non-mutating cases without things becoming nonsensical:

        let donut = baker.becomeDonut(dough) // non-mutating?

I also am having difficulty coming to terms with the use of "form" (I am a native English speaker). As you note "form" can imply the creation of something from parts (more like assembling a new thing) as well as the creation of something out of a material say a of block clay (more like molding something out of an existing thing). It doesn't seem clear cut to me to imply in place mutation.

Additionally my eyes / brain keep seeing "from" instead of "form". This type of issue is generally true with any short word made up of the same set of letters (made worse since "from" is more common in programming then "form"). The mind quickly narrows in on a set of possible words given the letters we see and then uses context to help get the correct one and/or additional visual parsing to understand the exact ordering of letters (more energy expended). Anyway since I keep seeing "from" instead of "form" I keep going in the direction of thinking it returns something made from the two (or more) items involved (not really sure why "from" goes that direction in my head, it could also go the in place direction).

I would prefer something other then "form" (note I just typed "from" by mistake)... I think your suggestion of "become" has merit.

y.becomeUnion(x) --reads to me as--> "y become union with x"
y.formUnion(x) --read to me as--> "y from oops... y forming a union of x"
y.becomeIntersection(x) --reads to me as--> "y become intersection with x"
y.formIntersection(x) --read to me as--> "y from oops... y forming an intersection with x"

In the "forming" situations it – to me – is ambiguous on if that is in place or not. To me it implies more of giving something new back.

I am -1 on "form" aspect of this proposal. ...of course things are learnable as long as things are fairly consistent and not to far out of the norm for typical language use. Personally I don't see "form" as that typical in English.

-Shawn

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

15

In my opinion these operators would be perfectly appropriate for Sets.
They have exactly the right semantic implications and relationships.
This is the same reason we use + for both scalars and vectors in math,
even though they're different in some ways.

If someone else would like to write a proposal for making these
operators available on sets, I'd support it.

···

on Fri Apr 01 2016, Brent Royal-Gordon <swift-evolution@swift.org> wrote:

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.

--
Dave

16

    > What is your evaluation of the proposal?

    I don't like "form" as a prefix. To me there is no difference between `union
    ` and `formUnion`: both sounds functional-style, and actually the second one
    perhaps a bit more to my ears. There's basically two dictionary definitions
    of "form":

    1. "bring together parts or combine to create (something)" which to me
    implies a new value is created, and
    2. "make or fashion into a certain shape or form" which would imply that the
    material you start with is transformed, which is apparently the intended
    meaning and also the reverse meaning from the above.

    I mean, doesn't this make sense as an API?

    let donut = baker.formDonut(dough) // non-mutating

    Perhaps instead of "form" we could use "become" as a prefix when the
    operation is naturally described by a noun. That would seem less ambiguous
    to me:

    a.becomeUnion(b)
    a.becomeIntersection(b)
    a.becomeSuccessor(b)

    It's a bit passive, but I find it fits well when the operation is a noun.

    And there's no way the term lends itself to non-mutating cases without
    things becoming nonsensical:

    let donut = baker.becomeDonut(dough) // non-mutating?

I also am having difficulty coming to terms with the use of "form" (I
am a native English speaker). As you note "form" can imply the
creation of something from parts (more like assembling a new thing) as
well as the creation of something out of a material say a of block
clay (more like molding something out of an existing thing). It
doesn't seem clear cut to me to imply in place mutation.

Additionally my eyes / brain keep seeing "from" instead of
"form". This type of issue is generally true with any short word made
up of the same set of letters (made worse since "from" is more common
in programming then "form"). The mind quickly narrows in on a set of
possible words given the letters we see and then uses context to help
get the correct one and/or additional visual parsing to understand the
exact ordering of letters (more energy expended). Anyway since I keep
seeing "from" instead of "form" I keep going in the direction of
thinking it returns something made from the two (or more) items
involved (not really sure why "from" goes that direction in my head,
it could also go the in place direction).

These are all good points.

I would prefer something other then "form" (note I just typed "from" by
mistake)... I think your suggestion of "become" has merit.

y.becomeUnion(x) --reads to me as--> "y become union with x"
y.formUnion(x) --read to me as--> "y from oops... y forming a union of x"
y.becomeIntersection(x) --reads to me as--> "y become intersection with x"
y.formIntersection(x) --read to me as--> "y from oops... y forming an
intersection with x"

I don't like its verbosity, but it does solve the "from" problem.

···

on Sun Apr 03 2016, Shawn Erickson <swift-evolution@swift.org> wrote:

On Sun, Apr 3, 2016 at 6:41 AM Michel Fortin via swift-evolution > <swift-evolution@swift.org> wrote:

In the "forming" situations it – to me – is ambiguous on if that is in
place or not. To me it implies more of giving something new back.

I am -1 on "form" aspect of this proposal. ...of course things are
learnable as long as things are fairly consistent and not to far out
of the norm for typical language use. Personally I don't see "form" as
that typical in English.

-Shawn

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

--
Dave

17

I think the best English verb for this construction is “emplace”:

  EMPLACE Definition & Usage Examples | Dictionary.com

It means “to put in position”, and is always used with an object (the noun). It’s basically free from incorrect connotations because it’s obscure enough that most English speakers won’t know it, and is easily searchable for English- and non-English speakers alike.

  - Doug

···

On Apr 3, 2016, at 1:56 PM, Shawn Erickson <shawnce@gmail.com> wrote:

On Sun, Apr 3, 2016 at 1:27 PM Shawn Erickson <shawnce@gmail.com <mailto:shawnce@gmail.com>> wrote:
On Sun, Apr 3, 2016 at 6:41 AM Michel Fortin via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:
> What is your evaluation of the proposal?

I don't like "form" as a prefix. To me there is no difference between `union` and `formUnion`: both sounds functional-style, and actually the second one perhaps a bit more to my ears. There's basically two dictionary definitions of "form":

1. "bring together parts or combine to create (something)" which to me implies a new value is created, and
2. "make or fashion into a certain shape or form" which would imply that the material you start with is transformed, which is apparently the intended meaning and also the reverse meaning from the above.

I mean, doesn't this make sense as an API?

        let donut = baker.formDonut(dough) // non-mutating

Perhaps instead of "form" we could use "become" as a prefix when the operation is naturally described by a noun. That would seem less ambiguous to me:

        a.becomeUnion(b)
        a.becomeIntersection(b)
        a.becomeSuccessor(b)

It's a bit passive, but I find it fits well when the operation is a noun.

And there's no way the term lends itself to non-mutating cases without things becoming nonsensical:

        let donut = baker.becomeDonut(dough) // non-mutating?

I also am having difficulty coming to terms with the use of "form" (I am a native English speaker). As you note "form" can imply the creation of something from parts (more like assembling a new thing) as well as the creation of something out of a material say a of block clay (more like molding something out of an existing thing). It doesn't seem clear cut to me to imply in place mutation.

Additionally my eyes / brain keep seeing "from" instead of "form". This type of issue is generally true with any short word made up of the same set of letters (made worse since "from" is more common in programming then "form"). The mind quickly narrows in on a set of possible words given the letters we see and then uses context to help get the correct one and/or additional visual parsing to understand the exact ordering of letters (more energy expended). Anyway since I keep seeing "from" instead of "form" I keep going in the direction of thinking it returns something made from the two (or more) items involved (not really sure why "from" goes that direction in my head, it could also go the in place direction).

I would prefer something other then "form" (note I just typed "from" by mistake)... I think your suggestion of "become" has merit.

y.becomeUnion(x) --reads to me as--> "y become union with x"
y.formUnion(x) --read to me as--> "y from oops... y forming a union of x"
y.becomeIntersection(x) --reads to me as--> "y become intersection with x"
y.formIntersection(x) --read to me as--> "y from oops... y forming an intersection with x"

After stepping away for a bit and looking at it from the POV of the API of Set and not in the context of "y" I could read things in the abstract as...

"becomeUnion(with other:Self)" --> "I become a union with other"
"formUnion(with other:Self)" --> "I form a union with other"

No clear winner to me however when used in code "become" still feels more strongly mutating then "form": y.formUnion(with:x) or y.becomeUnion(with:x)

All in all the API would have mutating in front of it (at least for structs) and it wouldn't have a return type. It would become clear fairly quickly as a result (hence learned).

Just still not that happy with "form" but with use my mind would likely quickly adapt.

18

Looking at other languages:

   1. A Java like API would be:
      - mutating func remove(T) -> Void
      - mutating func remove<S: SequenceType ...>(all: S) -> Void
      - func removed(T) -> Self
      - func removed<S...>(all: S) -> Self
      - Similarly for retain and add
      2. In Scala they primarily use operators, so a Scala like API would
   be:
      - func -=(inout Self, T) -> Void
      - func -=<S: SequenceType ...>(inout Self, S) -> Void
      - func -(T) -> Self
      - func -<S...>(all: S) -> Self
      - Similarly for & and +

Either of these naming patterns seems better than those proposed :(.

  -- Howard.

···

On 4 April 2016 at 15:49, Thorsten Seitz via swift-evolution < swift-evolution@swift.org> wrote:

I think Michel and Shawn did raise some good points here.

-Thorsten

Am 03.04.2016 um 22:27 schrieb Shawn Erickson via swift-evolution < > swift-evolution@swift.org>:

On Sun, Apr 3, 2016 at 6:41 AM Michel Fortin via swift-evolution < > swift-evolution@swift.org> wrote:

> What is your evaluation of the proposal?

I don't like "form" as a prefix. To me there is no difference between
`union` and `formUnion`: both sounds functional-style, and actually the
second one perhaps a bit more to my ears. There's basically two dictionary
definitions of "form":

1. "bring together parts or combine to create (something)" which to me
implies a new value is created, and
2. "make or fashion into a certain shape or form" which would imply that
the material you start with is transformed, which is apparently the
intended meaning and also the reverse meaning from the above.

I mean, doesn't this make sense as an API?

        let donut = baker.formDonut(dough) // non-mutating

Perhaps instead of "form" we could use "become" as a prefix when the
operation is naturally described by a noun. That would seem less ambiguous
to me:

        a.becomeUnion(b)
        a.becomeIntersection(b)
        a.becomeSuccessor(b)

It's a bit passive, but I find it fits well when the operation is a noun.

And there's no way the term lends itself to non-mutating cases without
things becoming nonsensical:

        let donut = baker.becomeDonut(dough) // non-mutating?

I also am having difficulty coming to terms with the use of "form" (I am a
native English speaker). As you note "form" can imply the creation of
something from parts (more like assembling a new thing) as well as the
creation of something out of a material say a of block clay (more like
molding something out of an existing thing). It doesn't seem clear cut to
me to imply in place mutation.

Additionally my eyes / brain keep seeing "from" instead of "form". This
type of issue is generally true with any short word made up of the same set
of letters (made worse since "from" is more common in programming then
"form"). The mind quickly narrows in on a set of possible words given the
letters we see and then uses context to help get the correct one and/or
additional visual parsing to understand the exact ordering of letters (more
energy expended). Anyway since I keep seeing "from" instead of "form" I
keep going in the direction of thinking it returns something made from the
two (or more) items involved (not really sure why "from" goes that
direction in my head, it could also go the in place direction).

I would prefer something other then "form" (note I just typed "from" by
mistake)... I think your suggestion of "become" has merit.

y.becomeUnion(x) --reads to me as--> "y become union with x"
y.formUnion(x) --read to me as--> "y from oops... y forming a union of x"
y.becomeIntersection(x) --reads to me as--> "y become intersection with x"
y.formIntersection(x) --read to me as--> "y from oops... y forming an
intersection with x"

In the "forming" situations it – to me – is ambiguous on if that is in
place or not. To me it implies more of giving something new back.

I am -1 on "form" aspect of this proposal. ...of course things are
learnable as long as things are fairly consistent and not to far out of the
norm for typical language use. Personally I don't see "form" as that
typical in English.

-Shawn

_______________________________________________
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

19

My read on the API guidelines is that the mutating/non-mutating distinction
is made by verbs vs. nouns. The verb itself doesn't have to "suggest" or
"feel" mutating, it just has to be clearly a verb. Thus, IMO, `form` is as
good a verb as any, although if we're going to return to bikeshedding I
would suggest that `do` is even shorter.

···

On Mon, Apr 4, 2016 at 1:20 AM Howard Lovatt via swift-evolution < swift-evolution@swift.org> wrote:

Looking at other languages:

   1. A Java like API would be:
      - mutating func remove(T) -> Void
      - mutating func remove<S: SequenceType ...>(all: S) -> Void
      - func removed(T) -> Self
      - func removed<S...>(all: S) -> Self
      - Similarly for retain and add
      2. In Scala they primarily use operators, so a Scala like API would
   be:
      - func -=(inout Self, T) -> Void
      - func -=<S: SequenceType ...>(inout Self, S) -> Void
      - func -(T) -> Self
      - func -<S...>(all: S) -> Self
      - Similarly for & and +

Either of these naming patterns seems better than those proposed :(.

  -- Howard.

On 4 April 2016 at 15:49, Thorsten Seitz via swift-evolution < > swift-evolution@swift.org> wrote:

I think Michel and Shawn did raise some good points here.

-Thorsten

Am 03.04.2016 um 22:27 schrieb Shawn Erickson via swift-evolution < >> swift-evolution@swift.org>:

On Sun, Apr 3, 2016 at 6:41 AM Michel Fortin via swift-evolution < >> swift-evolution@swift.org> wrote:

> What is your evaluation of the proposal?

I don't like "form" as a prefix. To me there is no difference between
`union` and `formUnion`: both sounds functional-style, and actually the
second one perhaps a bit more to my ears. There's basically two dictionary
definitions of "form":

1. "bring together parts or combine to create (something)" which to me
implies a new value is created, and
2. "make or fashion into a certain shape or form" which would imply that
the material you start with is transformed, which is apparently the
intended meaning and also the reverse meaning from the above.

I mean, doesn't this make sense as an API?

        let donut = baker.formDonut(dough) // non-mutating

Perhaps instead of "form" we could use "become" as a prefix when the
operation is naturally described by a noun. That would seem less ambiguous
to me:

        a.becomeUnion(b)
        a.becomeIntersection(b)
        a.becomeSuccessor(b)

It's a bit passive, but I find it fits well when the operation is a noun.

And there's no way the term lends itself to non-mutating cases without
things becoming nonsensical:

        let donut = baker.becomeDonut(dough) // non-mutating?

I also am having difficulty coming to terms with the use of "form" (I am
a native English speaker). As you note "form" can imply the creation of
something from parts (more like assembling a new thing) as well as the
creation of something out of a material say a of block clay (more like
molding something out of an existing thing). It doesn't seem clear cut to
me to imply in place mutation.

Additionally my eyes / brain keep seeing "from" instead of "form". This
type of issue is generally true with any short word made up of the same set
of letters (made worse since "from" is more common in programming then
"form"). The mind quickly narrows in on a set of possible words given the
letters we see and then uses context to help get the correct one and/or
additional visual parsing to understand the exact ordering of letters (more
energy expended). Anyway since I keep seeing "from" instead of "form" I
keep going in the direction of thinking it returns something made from the
two (or more) items involved (not really sure why "from" goes that
direction in my head, it could also go the in place direction).

I would prefer something other then "form" (note I just typed "from" by
mistake)... I think your suggestion of "become" has merit.

y.becomeUnion(x) --reads to me as--> "y become union with x"
y.formUnion(x) --read to me as--> "y from oops... y forming a union of x"
y.becomeIntersection(x) --reads to me as--> "y become intersection with
x"
y.formIntersection(x) --read to me as--> "y from oops... y forming an
intersection with x"

In the "forming" situations it – to me – is ambiguous on if that is in
place or not. To me it implies more of giving something new back.

I am -1 on "form" aspect of this proposal. ...of course things are
learnable as long as things are fairly consistent and not to far out of the
norm for typical language use. Personally I don't see "form" as that
typical in English.

-Shawn

_______________________________________________
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

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

20

Hmm, "emplace" looks like more or less a synonym for "install." I
don't think it suggests that the object is being put in place of the
subject. The latest example in the Oxford English Dictionary, from
2010, is:
"Insurgents would hastily emplace victim-activated IEDs...after
Pathfinder came through."
Here, the IEDs are not taking the place of the insurgents.

···

On Mon, Apr 4, 2016 at 11:14 AM, Douglas Gregor via swift-evolution <swift-evolution@swift.org> wrote:

On Apr 3, 2016, at 1:56 PM, Shawn Erickson <shawnce@gmail.com> wrote:

On Sun, Apr 3, 2016 at 1:27 PM Shawn Erickson <shawnce@gmail.com> wrote:

On Sun, Apr 3, 2016 at 6:41 AM Michel Fortin via swift-evolution >> <swift-evolution@swift.org> wrote:

> What is your evaluation of the proposal?

I don't like "form" as a prefix. To me there is no difference between
`union` and `formUnion`: both sounds functional-style, and actually the
second one perhaps a bit more to my ears. There's basically two dictionary
definitions of "form":

1. "bring together parts or combine to create (something)" which to me
implies a new value is created, and
2. "make or fashion into a certain shape or form" which would imply that
the material you start with is transformed, which is apparently the intended
meaning and also the reverse meaning from the above.

I mean, doesn't this make sense as an API?

        let donut = baker.formDonut(dough) // non-mutating

Perhaps instead of "form" we could use "become" as a prefix when the
operation is naturally described by a noun. That would seem less ambiguous
to me:

        a.becomeUnion(b)
        a.becomeIntersection(b)
        a.becomeSuccessor(b)

It's a bit passive, but I find it fits well when the operation is a noun.

And there's no way the term lends itself to non-mutating cases without
things becoming nonsensical:

        let donut = baker.becomeDonut(dough) // non-mutating?

I also am having difficulty coming to terms with the use of "form" (I am a
native English speaker). As you note "form" can imply the creation of
something from parts (more like assembling a new thing) as well as the
creation of something out of a material say a of block clay (more like
molding something out of an existing thing). It doesn't seem clear cut to me
to imply in place mutation.

Additionally my eyes / brain keep seeing "from" instead of "form". This
type of issue is generally true with any short word made up of the same set
of letters (made worse since "from" is more common in programming then
"form"). The mind quickly narrows in on a set of possible words given the
letters we see and then uses context to help get the correct one and/or
additional visual parsing to understand the exact ordering of letters (more
energy expended). Anyway since I keep seeing "from" instead of "form" I keep
going in the direction of thinking it returns something made from the two
(or more) items involved (not really sure why "from" goes that direction in
my head, it could also go the in place direction).

I would prefer something other then "form" (note I just typed "from" by
mistake)... I think your suggestion of "become" has merit.

y.becomeUnion(x) --reads to me as--> "y become union with x"
y.formUnion(x) --read to me as--> "y from oops... y forming a union of x"
y.becomeIntersection(x) --reads to me as--> "y become intersection with x"
y.formIntersection(x) --read to me as--> "y from oops... y forming an
intersection with x"

After stepping away for a bit and looking at it from the POV of the API of
Set and not in the context of "y" I could read things in the abstract as...

"becomeUnion(with other:Self)" --> "I become a union with other"
"formUnion(with other:Self)" --> "I form a union with other"

No clear winner to me however when used in code "become" still feels more
strongly mutating then "form": y.formUnion(with:x) or y.becomeUnion(with:x)

All in all the API would have mutating in front of it (at least for structs)
and it wouldn't have a return type. It would become clear fairly quickly as
a result (hence learned).

Just still not that happy with "form" but with use my mind would likely
quickly adapt.

I think the best English verb for this construction is “emplace”:

EMPLACE Definition & Usage Examples | Dictionary.com

It means “to put in position”, and is always used with an object (the noun).
It’s basically free from incorrect connotations because it’s obscure enough
that most English speakers won’t know it, and is easily searchable for
English- and non-English speakers alike.

- Doug

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