[SR-933] Rename flatten to flattened

Do you also think that trigonometry should be `foo.sined`, `foo.cosined`, and `foo.tangented`?

sine, cosine etc. are all nouns so I think as computed properties they’d be fine as is?

If there is a universally-accepted nomenclature for a particular operation, the clearest thing we can do is to adopt it, even if it doesn't match our normal guidelines.

It still makes me uncomfortable to accept something purely because it is “universal”, as I’d wager that most languages with these terms have chosen them for the same reason, i.e- they're common because they're common, rather than because they’re necessarily the best terms for each language. It’s like a self-fulfilling prophecy; if Swift accepts them because they’re common, then it continues to make them common; as long as that trend continues they’ll never cease to be common.

I know it’s pretty minor in the scheme of things, but I don’t see that we lose anything by naming them consistently.

flatMap is certainly a pain in the ass in this case, but perhaps there’s a better alternative that isn’t comprised of two other method names? i.e- what is it most commonly used to actually achieve, perhaps there’s a more suitable term from that? It’s not a method I’ve ever actually found myself using, as the only cases I’ve come close I’ve always had some kind of hiccup that prevent me from taking advantage of it, so had to use something more complex instead.

···

On 10 Apr 2016, at 22:11, Brent Royal-Gordon <brent@architechies.com> wrote:

Ok. Is it final decision?

No, any API change needs to go through review on the evolution list.
Also, FWIW, I am not particularly keen on changing these names.

···

on Sun Apr 10 2016, Arsen Gasparyan <to.arsen.gasparyan-AT-gmail.com> wrote:

Can I start working on it?

On Sun, 10 Apr 2016 at 23:07, Howard Lovatt via swift-evolution > <swift-evolution@swift.org> wrote:

    Do it to them all: flatMapped, unioned, etc.

    On Monday, 11 April 2016, Dave Abrahams via swift-evolution > <swift-evolution@swift.org> wrote:

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

        >> The 'flatten()' method didn't get the Swift 3 API renaming treatment
        >> it should have, to go along with reversed, sorted, joined, etc.
        >> As I see Dmitri Gribenko already agree with it but we still have to
        >> discuss it here. So what do you think?
        >
        > I'm in favor.
        >
        > Though all of these things are terms of art, not all terms of art are
        created equal. For instance:
        >
        > * `map` is supported by virtually any language which have any of these
        > higher-order functions, and to my knowledge the name `map` is
        > universally used.
        > * `reduce` is not quite as universally supported, but it's still very
        > common, and most (but not quite all) languages with higher-order
        > functions support it.
        > * `filter` is very widely supported, but the *name* `filter` is not
        > quite so consistent. Ruby, for instance, calls it `select`, Perl calls
        > it `grep`, etc.
        > * `takeWhile` lies on the other end of the spectrum, being very
        narrowly supported.
        >
        > In my opinion, it would be a really bad idea to rename `map` or
        > `reduce`; `filter` is probably a bad idea but not terrible; but we
        > should feel relatively free to rename `takeWhile`.
        >
        > `flatten` is nowhere near as weak a term of art as `takeWhile`, but I
        > think it still falls towards that end of the spectrum. We shouldn't
        > worry too much about changing it. `map`, `reduce`, and `filter` are
        > much stronger terms, and we should be more cautious about changing
        > them.

        The problem is flatMap. The semantics of map, flatMap, and flatten are
        inextricably linked. IMO it would be weird to do this to one or two of
        these names and not to all of them.

        --
        Dave

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

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

--
Dave

Do you also think that trigonometry should be `foo.sined`, `foo.cosined`, and `foo.tangented`?

sine, cosine etc. are all nouns so I think as computed properties they’d be fine as is?

So you would favor these?

  _ = number.sine()
  _ = number.cosine()
  _ = number.tangent()
  
  number.formSine()
  number.formCosine()
  number.formTangent()

···

--
Brent Royal-Gordon
Architechies

I don’t particularly like these name changes.

I would even go as far as saying that these recent discussions about renaming flatten, map, filter, reduce has made me question the original Swift 3 API renaming. What I mostly like about the current (2.2) naming is that the non-mutating version is the default (for example `sort`/`sortInPlace` compared to `sorted`/`sort`). I feel that switching the default version to be the mutating variant is quite a strong statement on the languages behalf with regards to mutability vs immutability.

- David

···

on Sun Apr 10 2016, Arsen Gasparyan<to.arsen.gasparyan-AT-gmail.com>wrote:

> Ok. Is it final decision?
No, any API change needs to go through review on the evolution list.
Also, FWIW, I am not particularly keen on changing these names.

> Can I start working on it?
>
> On Sun, 10 Apr 2016 at 23:07, Howard Lovatt via swift-evolution > > <swift-evolution@swift.org>wrote:
>
> Do it to them all: flatMapped, unioned, etc.
>
> On Monday, 11 April 2016, Dave Abrahams via swift-evolution > > <swift-evolution@swift.org>wrote:
>
> on Fri Apr 08 2016, Brent Royal-Gordon<swift-evolution@swift.org> > > wrote:
>
> > > The 'flatten()' method didn't get the Swift 3 API renaming treatment
> > > it should have, to go along with reversed, sorted, joined, etc.
> > > As I see Dmitri Gribenko already agree with it but we still have to
> > > discuss it here. So what do you think?
> >
> > I'm in favor.
> >
> > Though all of these things are terms of art, not all terms of art are
> created equal. For instance:
> >
> > * `map` is supported by virtually any language which have any of these
> > higher-order functions, and to my knowledge the name `map` is
> > universally used.
> > * `reduce` is not quite as universally supported, but it's still very
> > common, and most (but not quite all) languages with higher-order
> > functions support it.
> > * `filter` is very widely supported, but the *name* `filter` is not
> > quite so consistent. Ruby, for instance, calls it `select`, Perl calls
> > it `grep`, etc.
> > * `takeWhile` lies on the other end of the spectrum, being very
> narrowly supported.
> >
> > In my opinion, it would be a really bad idea to rename `map` or
> > `reduce`; `filter` is probably a bad idea but not terrible; but we
> > should feel relatively free to rename `takeWhile`.
> >
> > `flatten` is nowhere near as weak a term of art as `takeWhile`, but I
> > think it still falls towards that end of the spectrum. We shouldn't
> > worry too much about changing it. `map`, `reduce`, and `filter` are
> > much stronger terms, and we should be more cautious about changing
> > them.
>
> The problem is flatMap. The semantics of map, flatMap, and flatten are
> inextricably linked. IMO it would be weird to do this to one or two of
> these names and not to all of them.
>
> --
> Dave
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution@swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
>
> --
> -- Howard.
> _______________________________________________
> swift-evolution mailing list
> swift-evolution@swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
--
Dave

Totally agree with Brent, too. And I wouldn't rename flatten either.

-Thorsten

···

Am 11.04.2016 um 08:03 schrieb David Hart via swift-evolution <swift-evolution@swift.org>:

Totally agree with Brent, map/flatMap are terms of art.

Sent from my iPad

On 10 Apr 2016, at 23:11, Brent Royal-Gordon via swift-evolution <swift-evolution@swift.org> wrote:

I still don’t see what’s being lost here, it’s not like the proposal is to radically rename them, all we’d end up with is .mapped(), .flattened(), .filtered() etc., which any good search engine should still be able to find, and will still come up in auto-completion if you start typing .map, .flatten and so-on. I just don’t see the point of even having naming conventions if we allow outside influences to force exceptions for IMO fairly weak reasons; it amounts to the “because everyone else is doing it” reasoning, but again, it’s not as if someone used to using .map is going to be suddenly lost and confused when presented with .mapped() instead.

As someone who has been using `map` for virtually my entire programming career, across languages as different as Perl, Haskell, Ruby, Objective-C (with my own categories) and now Swift, I would be as surprised by a `map` named `mapped` as I would be by a letter addressed to "Brented".

The naming exception is simple and principled: When other languages have universally adopted a given name, and there's nothing particularly wrong with that name except that it doesn't match Swift conventions, don't fight the trend just to be different, or just to be self-consistent. People would figure out `mapped`, sure, but `map` causes not even a moment of confusion.

Do you also think that trigonometry should be `foo.sined`, `foo.cosined`, and `foo.tangented`? Or maybe `foo.sine`, `foo.cosine`, and `foo.tangent`, with corresponding `foo.formSine`, `foo.formCosine`, and `foo.formTangent` functions?

Remember the first and most important sentence in the API Guidelines: "Clarity at the point of use is your most important goal." If there is a universally-accepted nomenclature for a particular operation, the clearest thing we can do is to adopt it, even if it doesn't match our normal guidelines.

Consistency is a powerful and satisfying goal, but we must be careful not to be seduced by it. "A foolish consistency is the hobgoblin of little minds." When there is a compelling reason to deviate from the guidelines, we should be prepared to do so.*

Consistency in API naming is a means to convey semantics, not an end in itself. We must not let the cart be put before the horse.

(Besides, since they take arguments, we should favor `mapping`, `filtering`, `flatMapping`, etc. Or perhaps even `mappingFlattened` for the last one. Can you see the rabbit hole we're beginning to tumble down?)

* Well, as the people writing the guidelines, we should try to modify the guidelines to write a general rule accommodating the deviation, because any situation we encounter is likely to be encountered by others as well. We've done that in this case by writing the "term of art" rule.

--
Brent Royal-Gordon
Architechies

_______________________________________________
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

With regard to trig they are functions:

let s = sin(x)

so not really relevant. But if the were made members then:

  let s = x.sined
  x.sin()

Would read well.

···

On Tuesday, 12 April 2016, Brent Royal-Gordon via swift-evolution < swift-evolution@swift.org> wrote:

>> Do you also think that trigonometry should be `foo.sined`,
`foo.cosined`, and `foo.tangented`?
>
> sine, cosine etc. are all nouns so I think as computed properties they’d
be fine as is?

So you would favor these?

        _ = number.sine()
        _ = number.cosine()
        _ = number.tangent()

        number.formSine()
        number.formCosine()
        number.formTangent()

--
Brent Royal-Gordon
Architechies

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

--
-- Howard.

I agree with this and add that the 2.2 naming is unambiguous. There’s no doubt what is meant by sortInPlace().

···

On Apr 14, 2016, at 9:26 AM, David Rönnqvist via swift-evolution <swift-evolution@swift.org> wrote:

I don’t particularly like these name changes.

I would even go as far as saying that these recent discussions about renaming flatten, map, filter, reduce has made me question the original Swift 3 API renaming. What I mostly like about the current (2.2) naming is that the non-mutating version is the default (for example `sort`/`sortInPlace` compared to `sorted`/`sort`). I feel that switching the default version to be the mutating variant is quite a strong statement on the languages behalf with regards to mutability vs immutability.

- David

on Sun Apr 10 2016, Arsen Gasparyan<to.arsen.gasparyan-AT-gmail.com>wrote:

Ok. Is it final decision?

No, any API change needs to go through review on the evolution list.
Also, FWIW, I am not particularly keen on changing these names.

Can I start working on it?

On Sun, 10 Apr 2016 at 23:07, Howard Lovatt via swift-evolution >>> <swift-evolution@swift.org>wrote:

Do it to them all: flatMapped, unioned, etc.

On Monday, 11 April 2016, Dave Abrahams via swift-evolution >>> <swift-evolution@swift.org>wrote:

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

The 'flatten()' method didn't get the Swift 3 API renaming treatment
it should have, to go along with reversed, sorted, joined, etc.
As I see Dmitri Gribenko already agree with it but we still have to
discuss it here. So what do you think?

I'm in favor.

Though all of these things are terms of art, not all terms of art are

created equal. For instance:

* `map` is supported by virtually any language which have any of these
higher-order functions, and to my knowledge the name `map` is
universally used.
* `reduce` is not quite as universally supported, but it's still very
common, and most (but not quite all) languages with higher-order
functions support it.
* `filter` is very widely supported, but the *name* `filter` is not
quite so consistent. Ruby, for instance, calls it `select`, Perl calls
it `grep`, etc.
* `takeWhile` lies on the other end of the spectrum, being very

narrowly supported.

In my opinion, it would be a really bad idea to rename `map` or
`reduce`; `filter` is probably a bad idea but not terrible; but we
should feel relatively free to rename `takeWhile`.

`flatten` is nowhere near as weak a term of art as `takeWhile`, but I
think it still falls towards that end of the spectrum. We shouldn't
worry too much about changing it. `map`, `reduce`, and `filter` are
much stronger terms, and we should be more cautious about changing
them.

The problem is flatMap. The semantics of map, flatMap, and flatten are
inextricably linked. IMO it would be weird to do this to one or two of
these names and not to all of them.

--
Dave

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

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

--
Dave

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

Totally agree with Brent, too. And I wouldn't rename flatten either.

A brief postscript on terms of art:

I wrote my first Python this week. I was very glad that `map` was named `map`. I just had to glance at the docs to see whether it was a function or a method and which argument came first. It took less time and involved less doubt than learning their closure syntax did.

···

--
Brent Royal-Gordon
Architechies

Although I personally don't feel this is right decision(renaming) for a number of reasons, but the new API Design Guidelines were already accepted and it seems like nothing can be changed already:

API Design Guidelines (SE-0023)

It seems like most of us like and support these changes. Even if some have IMO strong arguments against it.

So we just have to accept all these mapped/sorted, and following the API Design Guidelines we just *must* to have *flattened* instead of *flatten*

Don't see any possibilities to discuss this. Opinions?

···

On 19.04.2016 12:30, Thorsten Seitz via swift-evolution wrote:

Totally agree with Brent, too. And I wouldn't rename flatten either.

-Thorsten

Am 11.04.2016 um 08:03 schrieb David Hart via swift-evolution <swift-evolution@swift.org>:

Totally agree with Brent, map/flatMap are terms of art.

Sent from my iPad

On 10 Apr 2016, at 23:11, Brent Royal-Gordon via swift-evolution <swift-evolution@swift.org> wrote:

I still don’t see what’s being lost here, it’s not like the proposal is to radically rename them, all we’d end up with is .mapped(), .flattened(), .filtered() etc., which any good search engine should still be able to find, and will still come up in auto-completion if you start typing .map, .flatten and so-on. I just don’t see the point of even having naming conventions if we allow outside influences to force exceptions for IMO fairly weak reasons; it amounts to the “because everyone else is doing it” reasoning, but again, it’s not as if someone used to using .map is going to be suddenly lost and confused when presented with .mapped() instead.

As someone who has been using `map` for virtually my entire programming career, across languages as different as Perl, Haskell, Ruby, Objective-C (with my own categories) and now Swift, I would be as surprised by a `map` named `mapped` as I would be by a letter addressed to "Brented".

The naming exception is simple and principled: When other languages have universally adopted a given name, and there's nothing particularly wrong with that name except that it doesn't match Swift conventions, don't fight the trend just to be different, or just to be self-consistent. People would figure out `mapped`, sure, but `map` causes not even a moment of confusion.

Do you also think that trigonometry should be `foo.sined`, `foo.cosined`, and `foo.tangented`? Or maybe `foo.sine`, `foo.cosine`, and `foo.tangent`, with corresponding `foo.formSine`, `foo.formCosine`, and `foo.formTangent` functions?

Remember the first and most important sentence in the API Guidelines: "Clarity at the point of use is your most important goal." If there is a universally-accepted nomenclature for a particular operation, the clearest thing we can do is to adopt it, even if it doesn't match our normal guidelines.

Consistency is a powerful and satisfying goal, but we must be careful not to be seduced by it. "A foolish consistency is the hobgoblin of little minds." When there is a compelling reason to deviate from the guidelines, we should be prepared to do so.*

Consistency in API naming is a means to convey semantics, not an end in itself. We must not let the cart be put before the horse.

(Besides, since they take arguments, we should favor `mapping`, `filtering`, `flatMapping`, etc. Or perhaps even `mappingFlattened` for the last one. Can you see the rabbit hole we're beginning to tumble down?)

* Well, as the people writing the guidelines, we should try to modify the guidelines to write a general rule accommodating the deviation, because any situation we encounter is likely to be encountered by others as well. We've done that in this case by writing the "term of art" rule.

--
Brent Royal-Gordon
Architechies

_______________________________________________
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

Totally agree with Brent, too. And I wouldn't rename flatten either.

A brief postscript on terms of art:

I wrote my first Python this week. I was very glad that `map` was named `map`. I just had to glance at the docs to see whether it was a function or a method and which argument came first. It took less time and involved less doubt than learning their closure syntax did.

Are you suggesting that if it had been named “mapped” or “mapping” that you would have been unable to find it? Any decent search engine and/or auto-complete should get you to the correct function just as quickly, again, I don’t think anyone is suggesting that these functions be radically renamed, just that their tense be altered to match the new naming convention, which doesn’t change the root word from which they are derived.

···

On 19 Apr 2016, at 10:40, Brent Royal-Gordon via swift-evolution <swift-evolution@swift.org> wrote:

On 15 Apr 2016, at 12:49, Daniel Steinberg via swift-evolution <swift-evolution@swift.org> wrote:

I agree with this and add that the 2.2 naming is unambiguous. There’s no doubt what is meant by sortInPlace().

I’m normally in favour of more explicit meaning rather than less, but this where Swift’s type system and the @warn_unused_result attribute come into play to eliminate the need for it:

  myCollection.sorted() // Warning, unused result
  let sorted = myCollectioned.sort() // Void return type

A more explicit term is only needed for functions where there is ambiguity in how they are used IMO, i.e- if a function is both mutating and has a return type. The fact that .sort() doesn’t return anything does a pretty good job of clarifying what it does.

Although I personally don't feel this is right decision(renaming) for
a number of reasons, but the new API Design Guidelines were already
accepted and it seems like nothing can be changed already:

API Design Guidelines (SE-0023)
https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
https://swift.org/documentation/api-design-guidelines/

It seems like most of us like and support these changes. Even if some
have IMO strong arguments against it.

So we just have to accept all these mapped/sorted, and following the
API Design Guidelines we just *must* to have *flattened* instead of
*flatten*

Don't see any possibilities to discuss this. Opinions?

Cases like this are exactly why the API guidelines have a “Use
terminology well” section. “map” is provided for by that section.

···

on Tue Apr 19 2016, "Vladimir.S via swift-evolution" <swift-evolution@swift.org> wrote:

On 19.04.2016 12:30, Thorsten Seitz via swift-evolution wrote:

Totally agree with Brent, too. And I wouldn't rename flatten either.

-Thorsten

Am 11.04.2016 um 08:03 schrieb David Hart via swift-evolution <swift-evolution@swift.org>:

Totally agree with Brent, map/flatMap are terms of art.

Sent from my iPad

On 10 Apr 2016, at 23:11, Brent Royal-Gordon via swift-evolution <swift-evolution@swift.org> wrote:

I still don’t see what’s being lost here, it’s not like the

proposal is to radically rename them, all we’d end up with is
.mapped(), .flattened(), .filtered() etc., which any good search
engine should still be able to find, and will still come up in
auto-completion if you start typing .map, .flatten and so-on. I
just don’t see the point of even having naming conventions if we
allow outside influences to force exceptions for IMO fairly weak
reasons; it amounts to the “because everyone else is doing it”
reasoning, but again, it’s not as if someone used to using .map is
going to be suddenly lost and confused when presented with
.mapped() instead.

As someone who has been using `map` for virtually my entire
programming career, across languages as different as Perl,
Haskell, Ruby, Objective-C (with my own categories) and now Swift,
I would be as surprised by a `map` named `mapped` as I would be by
a letter addressed to "Brented".

The naming exception is simple and principled: When other
languages have universally adopted a given name, and there's
nothing particularly wrong with that name except that it doesn't
match Swift conventions, don't fight the trend just to be
different, or just to be self-consistent. People would figure out
`mapped`, sure, but `map` causes not even a moment of confusion.

Do you also think that trigonometry should be `foo.sined`,
`foo.cosined`, and `foo.tangented`? Or maybe `foo.sine`,
`foo.cosine`, and `foo.tangent`, with corresponding
`foo.formSine`, `foo.formCosine`, and `foo.formTangent` functions?

Remember the first and most important sentence in the API
Guidelines: "Clarity at the point of use is your most important
goal." If there is a universally-accepted nomenclature for a
particular operation, the clearest thing we can do is to adopt it,
even if it doesn't match our normal guidelines.

Consistency is a powerful and satisfying goal, but we must be
careful not to be seduced by it. "A foolish consistency is the
hobgoblin of little minds." When there is a compelling reason to
deviate from the guidelines, we should be prepared to do so.*

Consistency in API naming is a means to convey semantics, not an end in itself. We must not let the cart be put before the horse.

(Besides, since they take arguments, we should favor `mapping`,
`filtering`, `flatMapping`, etc. Or perhaps even
`mappingFlattened` for the last one. Can you see the rabbit hole
we're beginning to tumble down?)

* Well, as the people writing the guidelines, we should try to
modify the guidelines to write a general rule accommodating the
deviation, because any situation we encounter is likely to be
encountered by others as well. We've done that in this case by
writing the "term of art" rule.

--
Brent Royal-Gordon
Architechies

_______________________________________________
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

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

--
Dave

Dave, could you clarify your message with more details please.
Are you saying that "map" will be "map" in Swift 3.0 and that "flatten" is the same kind of special case when we don't need to rename it?

Just checked. Don't understand. In Swift 3.0 (mar 24) there are "map" "filter" "reduce", not "mapped" etc as I though. IMO all this renaming is becoming more and more strange. IMO We'll have inconsistent language at the end. Or this is just old version of Swift 3.0 and newer have "mapped" etc ? Confused.

Now in 3.0(mar 24), we have arr.sorted() but arr.map (not .mapped()) arr.filter (! I expect a mutating filtering of the arr itself according to API Design Guidelines) etc.

OK.. Could someone point to where "we" decided that map/filter/reduce (and probably others) will not be renamed according Guidelines or clarify the situation with renaming of map/filter/reduce ? Thank you.

···

On 20.04.2016 2:00, Dave Abrahams via swift-evolution wrote:

Cases like this are exactly why the API guidelines have a “Use
terminology well” section. “map” is provided for by that section.

I wrote my first Python this week. I was very glad that `map` was named `map`. I just had to glance at the docs to see whether it was a function or a method and which argument came first. It took less time and involved less doubt than learning their closure syntax did.

Are you suggesting that if it had been named “mapped” or “mapping” that you would have been unable to find it? Any decent search engine and/or auto-complete should get you to the correct function just as quickly, again, I don’t think anyone is suggesting that these functions be radically renamed, just that their tense be altered to match the new naming convention, which doesn’t change the root word from which they are derived.

I'm suggesting that if it had been named `mapped` or (especially) `mapping`, I would have been a lot less certain I was looking at the list function and not a type or method that was unrelated to the traditional `map`. I probably would have still found it, but I wouldn't have been immediately sure it was right.

···

Sent from my iPad

On keeping map() as map() but keeping the -ed and -ing guideline for other APIs:
What defines prior art really? I’m fairly new to functional programming, but I imagine there is a plethora of other API designs that can be copied. In Swift, do they all take on the past-particle naming?
Which consistency is more important, consistency with other popular libraries, or with the Swift naming guidelines recommending -ed and -ing?
What happens if new API designs are created from here on, are they considered to be prior art or not?
On why is there a need for -ed and -ing in the first place?:
Naming is called one of the hardest things in computer science for a reason. Swift is meant to make programming easier, so why doesn’t it make naming easier? Just keep things simple. Who cares if it’s not proper english (you will never achieve perfect sentences), as the APIs are far superior in readability and comprehension than either strcat() or stringByAppendingString() of old.
Objective-C was derided for its overly verbose naming, and now Swift wants to introduce a new quirk to again set it apart from other languages?

A divide in naming
In functional programming, the emphasis is on what is returned. filter returns an affected copy.
In object oriented programming, the emphasis is usually the target. NSMutableArray.removeLastObject() affects the receiver, and returns nothing.
They are both verbs in present tense, yet behave differently.
We have two worlds coming together in Swift, and somehow they have to meet up. So I see why the -ed and -ing rule was created, especially as it suits the Cocoa framework well with the newly shortened API naming. But still, I think it’s somewhat messy (and potentially unfortunate as Cocoa and its dependence on reference types will one day be the past).
The guidelines affect both functional and object-oriented approaches (the Swift standard library includes pieces of both), and they affect both value and reference types. They are broad rules for a varied landscape.
Patrick Smith

···

On Apr 19 2016, at 7:56 pm, Haravikk via swift-evolution <swift-evolution@swift.org> wrote:
      
On 19 Apr 2016, at 10:40, Brent Royal-Gordon via swift-evolution <swift-evolution@swift.org> wrote:
Totally agree with Brent, too. And I wouldn't rename flatten either.

A brief postscript on terms of art:

I wrote my first Python this week. I was very glad that `map` was named `map`. I just had to glance at the docs to see whether it was a function or a method and which argument came first. It took less time and involved less doubt than learning their closure syntax did.
Are you suggesting that if it had been named “mapped” or “mapping” that you would have been unable to find it? Any decent search engine and/or auto-complete should get you to the correct function just as quickly, again, I don’t think anyone is suggesting that these functions be radically renamed, just that their tense be altered to match the new naming convention, which doesn’t change the root word from which they are derived.
On 15 Apr 2016, at 12:49, Daniel Steinberg via swift-evolution <swift-evolution@swift.org> wrote:
I agree with this and add that the 2.2 naming is unambiguous. There’s no doubt what is meant by sortInPlace().

I’m normally in favour of more explicit meaning rather than less, but this where Swift’s type system and the @warn_unused_result attribute come into play to eliminate the need for it:
  myCollection.sorted() // Warning, unused result let sorted = myCollectioned.sort() // Void return type
A more explicit term is only needed for functions where there is ambiguity in how they are used IMO, i.e- if a function is both mutating and has a return type. The fact that .sort() doesn’t return anything does a pretty good job of clarifying what it does.

If we’re assuming you’re totally new to Swift and the first thing you do is go looking for a map function, then you’d still need to double check exactly what you’re doing anyway (how to write the closure etc.) so I’m not sure a few extra letters is going to make a meaningful difference in speed as you’ll be double checking documentation anyway to be sure you use the function correctly.

Meanwhile if you’ve been through a few Swift tutorials or whatever with the current API guidelines adhered to, then you should be used to, or at least aware of, the form for mutating vs non-mutating method names, so seeing mapped shouldn't cause much pause either.

I just don’t think it can possibly have a meaningful impact on time; it’s not as if developers are going to be off wandering the streets with their whole world turned upside-down, unable to figure out what to do with themselves because they’re suddenly unable to find a map method, only some bewildering, alien method named “mapped” that could be anything.

I’ll grant that switching to mapped is relatively minor, but if everything else is named following one set of rules I think a better case needs to be made for why some functions should have their own set of rules, especially if it amounts to “that’s what others call it”, in particular if those others call it that because that’s what others call it and so-on ;)

···

On 19 Apr 2016, at 17:19, Brent Royal-Gordon <brent@architechies.com> wrote:

I wrote my first Python this week. I was very glad that `map` was named `map`. I just had to glance at the docs to see whether it was a function or a method and which argument came first. It took less time and involved less doubt than learning their closure syntax did.

Are you suggesting that if it had been named “mapped” or “mapping” that you would have been unable to find it? Any decent search engine and/or auto-complete should get you to the correct function just as quickly, again, I don’t think anyone is suggesting that these functions be radically renamed, just that their tense be altered to match the new naming convention, which doesn’t change the root word from which they are derived.

I'm suggesting that if it had been named `mapped` or (especially) `mapping`, I would have been a lot less certain I was looking at the list function and not a type or method that was unrelated to the traditional `map`. I probably would have still found it, but I wouldn't have been immediately sure it was right.

Dave, could you clarify your message with more details please.
Are you saying that "map" will be "map" in Swift 3.0

That is the current plan of record.

and that "flatten" is the same kind of special case when we don't need
to rename it?

Yes, “flatten” is in the same category because of its very close
semantic relationship to “map” and “flatMap.”

If it were not in this category I would want to rename it to
“flattenOneLevel” or “concatenateElements” or something, as I have
always felt the name “flatten” was insufficiently specific about its
semantics. But it is, like “map,” “flatMap,” and “reduce,” a term of
art that many people would not recognize if we renamed it.

Just checked. Don't understand. In Swift 3.0 (mar 24) there are "map"
"filter" "reduce", not "mapped" etc as I though. IMO all this renaming
is becoming more and more strange. IMO We'll have inconsistent
language at the end. Or this is just old version of Swift 3.0 and
newer have "mapped" etc ? Confused.

Now in 3.0(mar 24), we have arr.sorted() but arr.map (not .mapped())
arr.filter (! I expect a mutating filtering of the arr itself
according to API Design Guidelines) etc.

I don't understand what you say you expect.

OK.. Could someone point to where "we" decided that map/filter/reduce
(and probably others) will not be renamed according Guidelines or
clarify the situation with renaming of map/filter/reduce ? Thank you.

“We” decided it when the changes to the standard library to make it
conform to the API guidelines were put up for review and the changes
were accepted. In those changes, map/filter/reduce/flatMap/flatten all
retained their names.

···

on Tue Apr 19 2016, "Vladimir.S" <svabox-AT-gmail.com> wrote:

On 20.04.2016 2:00, Dave Abrahams via swift-evolution wrote:

Cases like this are exactly why the API guidelines have a “Use
terminology well” section. “map” is provided for by that section.

--
Dave

Dave, could you clarify your message with more details please.
Are you saying that "map" will be "map" in Swift 3.0

That is the current plan of record.

Oh, thank you for clarifying this.

and that "flatten" is the same kind of special case when we don't need
to rename it?

Yes, “flatten” is in the same category because of its very close
semantic relationship to “map” and “flatMap.”

If it were not in this category I would want to rename it to
“flattenOneLevel” or “concatenateElements” or something, as I have
always felt the name “flatten” was insufficiently specific about its
semantics. But it is, like “map,” “flatMap,” and “reduce,” a term of
art that many people would not recognize if we renamed it.

Just checked. Don't understand. In Swift 3.0 (mar 24) there are "map"
"filter" "reduce", not "mapped" etc as I though. IMO all this renaming
is becoming more and more strange. IMO We'll have inconsistent
language at the end. Or this is just old version of Swift 3.0 and
newer have "mapped" etc ? Confused.

Now in 3.0(mar 24), we have arr.sorted() but arr.map (not .mapped())
arr.filter (! I expect a mutating filtering of the arr itself
according to API Design Guidelines) etc.

I don't understand what you say you expect.

Well..
arr.sort() - mutating method. verb.
arr.sorted() - non-mutating. "..ed"
and..
arr.filter() - non-mutating. verb. I think a user who read API Design Guidelines can expect arr.filter() will be a mutating method.

OK.. Could someone point to where "we" decided that map/filter/reduce
(and probably others) will not be renamed according Guidelines or
clarify the situation with renaming of map/filter/reduce ? Thank you.

“We” decided it when the changes to the standard library to make it
conform to the API guidelines were put up for review and the changes
were accepted. In those changes, map/filter/reduce/flatMap/flatten all
retained their names.

Is it "SE-0006" ?

Could you please point me to lines in this document where it says that "map/filter/reduce" are exceptions and we don't need to rename them to mapped/filtered/reduced ? Thank you.

···

On 20.04.2016 20:47, Dave Abrahams wrote:

on Tue Apr 19 2016, "Vladimir.S" <svabox-AT-gmail.com> wrote:

On 20.04.2016 2:00, Dave Abrahams via swift-evolution wrote:

Cases like this are exactly why the API guidelines have a “Use
terminology well” section. “map” is provided for by that section.

Swift.org - API Design Guidelines , see "Stick to the established meaning” and “Embrace precedent"

-DW

···

On Apr 21, 2016, at 1:08 AM, Vladimir.S via swift-evolution <swift-evolution@swift.org> wrote:

Is it "SE-0006" ?
https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.md

Could you please point me to lines in this document where it says that "map/filter/reduce" are exceptions and we don't need to rename them to mapped/filtered/reduced ? Thank you.