# New Ticket Created by Sam S.
# Please include the string: [perl #130520]
# in the subject line of all future correspondence about this issue.
# <URL: https://rt.perl.org/Ticket/Display.html?id=130520 >
So, Perl 6 has a built-in `flatmap` routine:
.flatmap({ ... })
Show of hands: Who is reasonably sure, without testing it or looking
it up, which of the following four expressions it corresponds to?
.flat.map({ ... })
.map({ ... }).flat
.flat.map({ ... }).flat
.map({ slip ... })
And if Perl 6 regulars and core developers can't tell, do you think a
typical Perl 6 newbie will guess correctly, and that code reviewers
will notice when the wrong behavior was assumed?
Note that the four behaviors are the same (or at least easy to
confuse) for many simple cases - so it's quite possible to assume the
wrong one even after a quick test, if one didn't test the more
complicated inputs for which where they do differ.
---
Second strike: Whoever wrote the p6doc entry
<https://docs.perl6.org/routine/flatmap> assumed the wrong behavior as
well, and no one else seems to have noticed or cared. (See my initial
report at <https://github.com/perl6/doc/issues/851>.)
Third strike: Its behavior isn't actually tested in Roast. The single
Roast test that exists for it
<https://github.com/perl6/roast/blob/master/S03-metaops/hyper.t#L410>
merely tests that it is nodal, and doesn't distinguish between the
four possible behaviors listed above.
Fourth strike: Whereas `deepmap` and `duckmap` differ from plain `map`
in how they iterate the input and how often they call the lambda,
`flatmap` is the same as `map` in those regards and differs, rather,
in how it collects the output. Users who take the naming scheme
"deepmap, duckmap, flatmap" as an indication that these are three of a
kind, will assume the wrong behavior for `flatmap`.
---
Is all that confusion (and the needless proliferation of the Perl 6
core setting) worth it, just to save typing a single character in a
specific circumstance?
Unless I'm missing something vital, I'd say it's hard to argue that
the answer is "yes".
I therefore suggest initiating the deprecation cycle in order to
eventually drop of this routine from the Perl 6 language and Rakudo
implementation.
