Clarify differences between .head and .first

[AlexDaniel]

Sometimes I use .first when I mean .head, just because I confuse them often. Example:

<AlexDaniel> c: HEAD my @a = <foo bar baz>; my Seq $s = @a.Seq; say $s.first; @a[0] = 20; say $s.first
…
<lizmat> AlexDaniel: not sure why you use .first instead of .head

It made me wonder if I'm not the only one, and indeed:

• \.first; 68 lines, 36 modules: https://gist.github.com/9293e27affd6d158e897650fa9584b02

Moreover, people often use .grep().first too (when they can just use first instead):

• grep.*\.first; 18 lines, 13 modules: https://gist.github.com/b8cc1f7fdbce9163c0a3e7b5a9467710

I think there's something wrong when a specifically dedicated feature is not being used. That being said, I don't see any downside in using .first instead of .head…

[AlexDaniel]

@jnthn @JJ doc issue or language issue? :)

[jnthn]

If you just want the first thing in the list, I don't think there's anything wrong with using first instead of head: their behavior without an argument is the same.

The reason the two exist is because head is about taking a number of elements from the head of the list (and if you don't say how many, we assume 1), whereas first is about finding the first matching thing in the list (and if you don't care what is matched, then the first element will do). If your task is "get the first element in this sequence/list", they're equally good at it, reaching the same outcome, just from a different perspective.

Personally, I feel first reads more naturally than head in many cases, so would make the opposite choice than (I'm assuming) @lizmat does when either work. If you're using tail in the same breath it'd be more fitting to use head/tail rather than first/tail, but that's an issue of art rather than science.

Thus, from a language point of view, I don't see a problem, and from a documentation point of view, I don't think it's worth spilling much ink trying to advocate one over the other, especially when I don't think there's any consensus on which to advocate. :-)

I'd rather any more words spent in the docs go on pointing out - if not already done so - that .first(...) will serve the role of .grep(...).first. That said, seeing this (thanks to laziness, quite minor) mistake doesn't surprise me; I've made the exact same myself in another language before becoming aware that its first could also take a matcher. It's something a linter could maybe point out, though.

[AlexDaniel]

@JJ, feel free to do whatever you want here. Maybe it'll make sense to open a new ticket in the doc repo (so that we still have the decision in this repo in case it comes up again).

[JJ]

I can move it to the doc repo. Maybe it's the best thing. Changing or deprecating a feature is a big thing, but we can just document it better (maybe as a trap) so that they are known and used properly.

[coke]

I agree with @jnthn, closing ticket.