[Docs] Clarify the behvior of first, last, and nth on empty generators

[mousetail]

I was confused by this behavior so thought it might be good to document it.

[wader]

I wonder if "produces no output" or "outputs no value" is better then "output empty"? seems to be what is used in other places

[mousetail]

I found the documentation for try and break also uses the phrase "output/produce empty". In this case I think it's a bit more explicit than "outputs no value".

[wader]

Ok, i mostly want consistency but i think i personally prefer "no output" as mentioning empty feel a bit confusing, ex would we document the function empty as producing empty? if we want to use the word empty maybe it should not be written as a function but instad be something like "the empty generator" or "empty output" but then i think i prefer "no output" 🤔

[mousetail]

I have updated the docs to say "produce no values" instead

[wader]

👍 let's see what the other maintainers think

But i do wonder what the reasoning was for last/1 to return null?

[mousetail]

One potential "fixed" last that outputs no values for an empty generator would be this:

def last(g): reduce g as $item ([0,null]; [first+1,$item])|if first>0 then last else empty end;

A lot less elagent than the current implementation though.

[itchyny]

See #1869. This is a bug that should be fixed in the future.

[wader]

@itchyny 👍 oh long discussion, seems fascinatingly messy :)

[mousetail]

That branch is 5 years old, I doubt it will still be merged

[itchyny]

It's better to use byte code to avoid boxing like the PR even if it makes more messy.

[itchyny]

Maybe you want to update the docs for last/1 but editing the wrong place. jq "[range(.)] | [[first], [last], [nth(5)]]" <<< "0" yields [[null],[null],[null]].

[mousetail]

@itchyny I moved the doc update to the correct section

[pkoppstein]

My understanding is that PR currently adds the text:

`last` returns `null` instead.

Of course, that is true of the current implementation, but if this behavior is to be documented in the manual, there should be a disclaimer to the effect that the behavior may change in the future.

(As @itchyny recently pointed out:

See #1869. This is a bug that should be fixed in the future.
)

[wader]

I'm debating with myself if it's consistent that first/0 and last/0 output null for an empty array. It makes sense because they operate on an array instead of a generator?

[mousetail]

first/0 having the same behavior as .[0] seems logical to me.

The existence of first/last/nth seems a bit pointless anyways since you can just use .[0], .[-1], .[n] which are shorter. But that's an entirely seperate point.

[pkoppstein]

Thanks for adding a disclaimer. Perhaps, however, it would be better if the documentation were agnostic as to whether it's a bug or not, though I would agree that simply describing the behavior as "unspecified" would be a bit silly. I believe it would be sufficient to say that currently last(empty) evaluates to null, but that in future it is likely to evaluate to the empty stream.

[itchyny]

I submitted a patch for the issue: #3179.