jq icon indicating copy to clipboard operation
jq copied to clipboard

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

Open mousetail opened this issue 1 year ago • 5 comments

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

mousetail avatar Sep 14 '24 06:09 mousetail

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]].

itchyny avatar Sep 14 '24 13:09 itchyny

@itchyny I moved the doc update to the correct section

mousetail avatar Sep 15 '24 12:09 mousetail

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 https://github.com/jqlang/jq/pull/1869. This is a bug that should be fixed in the future. )

pkoppstein avatar Sep 16 '24 20:09 pkoppstein

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.

mousetail avatar Sep 17 '24 07:09 mousetail

I submitted a patch for the issue: #3179.

itchyny avatar Sep 18 '24 03:09 itchyny