Is flat another way to say |? Why do we only document one?

[shadowcat-mst]

https://docs.perl6.org/language/containers

"Flatteing, items and containers" mentions flat.

> say (flat @foo, 8, 9).elems
5
> say (|@foo, 8, 9).elems
5

seem to be equivalent but there's no mention of the slip syntax

[timo]

in an actual call, like say(1, 2, 3) the "flat" will not cause items of the array to become multiple positional parameters. That's why the prefix | ought to also be explained, at the very least in that context with a note pointing from here to there.

[JJ]

I have the hunch that the "single argument rule" has something to do with them not being the same. But it's true this will have to be documented.

[zoffixznet]

There isn't that much similarity between the two, let alone equivalence.

<Zoffix_> m: my @l := 1, 2, (3, 4, (5, 6)), [7, 8, (9, 10)]; say (|@l, 11, 12); say (flat @l, 11, 12)
<camelia> rakudo-moar f6756bb4d: OUTPUT: «(1 2 (3 4 (5 6)) [7 8 (9 10)] 11 12)␤(1 2 3 4 5 6 7 8 (9 10) 11 12)␤»
<Zoffix_> m: my @l := 1, 2; dd ($@l, $@l).flat
<camelia> rakudo-moar f6756bb4d: OUTPUT: «($(1, 2), $(1, 2)).Seq␤»
<Zoffix_> m: my @l := 1, 2; dd ($@l, $@l).map: |*
<camelia> rakudo-moar f6756bb4d: OUTPUT: «(1, 2, 1, 2).Seq␤»
<Zoffix_> m: my @l := 1, 2; dd [flat(@l), flat(@l)]
<camelia> rakudo-moar f6756bb4d: OUTPUT: «[(1, 2).Seq, (1, 2).Seq]␤»
<Zoffix_> m: my @l := 1, 2; dd [|@l, |@l]
<camelia> rakudo-moar f6756bb4d: OUTPUT: «[1, 2, 1, 2]␤»
<Zoffix_> m: my @l := 1, 2; dd [foo => |@l]
<camelia> rakudo-moar f6756bb4d: OUTPUT: «[:foo(slip(1, 2))]␤»
<Zoffix_> m: my @l := 1, 2; dd [foo => @l.flat]
<camelia> rakudo-moar f6756bb4d: OUTPUT: «[:foo((1, 2).Seq)]␤»
<Zoffix_> m: my @l := 1, 2; my %h = foo => |@l; dd [%h<foo>]
<camelia> rakudo-moar f6756bb4d: OUTPUT: «[slip(1, 2),]␤»
<Zoffix_> m: my @l := 1, 2; my %h := foo => |@l; dd [%h<foo>]
<camelia> rakudo-moar f6756bb4d: OUTPUT: «[1, 2]␤»

flat

• Creates a Seq that's generated by flattening all non-containerized Iterables, which includes the contents of such Iterables; all the way until they're entirely flattented or you descend up to a containerized Iterable

prefix:<|>

• Creates a Slip. That's it. The rest of the observed behaviour is the behaviour of Slips, not of prefix:<|>, and that behaviour causes only the given Iterable to be flattened into the containing Iterable and that won't occur if the Slip is containerized

(this doesn't comment on the | used in to flatten argument lists, which has nothing at all to do with Slips at all and is a special-cased compiler feature).

[JJ]

I'll try to summarize that and improve the documentation in that area.