add skip/2 as the counterpart to limit/2

docs/content/manual/dev/manual.yml

@@ -3037,16 +3037,26 @@ sections:
  input: '[1,2,3]'
  output: ['false']
 
- - title: "`limit(n; exp)`"
+ - title: "`limit(n; expr)`"
  body: |
 
- The `limit` function extracts up to `n` outputs from `exp`.
+ The `limit` function extracts up to `n` outputs from `expr`.
 
  examples:
  - program: '[limit(3;.[])]'
  input: '[0,1,2,3,4,5,6,7,8,9]'
  output: ['[0,1,2]']
 
+ - title: "`skip(n; expr)`"
+ body: |
+
+ The `skip` function skips the first `n` outputs from `expr`.
+
+ examples:
+ - program: '[skip(3;.[])]'
+ input: '[0,1,2,3,4,5,6,7,8,9]'
+ output: ['[3,4,5,6,7,8,9]']
+
  - title: "`first(expr)`, `last(expr)`, `nth(n; expr)`"
  body: |
 

src/builtin.jq

@@ -149,10 +149,14 @@ def until(cond; next):
  def _until:
  if cond then . else (next|_until) end;
  _until;
-def limit($n; exp):
- if $n > 0 then label $out | foreach exp as $item ($n; .-1; $item, if . <= 0 then break $out else empty end)
+def limit($n; expr):
+ if $n > 0 then label $out | foreach expr as $item ($n; . - 1; $item, if . <= 0 then break $out else empty end)
  elif $n == 0 then empty
- else exp end;
+ else error("limit doesn't support negative indices") end;
+def skip($n; expr):
+ if $n > 0 then foreach expr as $item ($n; . - 1; if . < 0 then $item else empty end)
+ elif $n == 0 then expr
+ else error("skip doesn't support negative indices") end;
 # range/3, with a `by` expression argument
 def range($init; $upto; $by):
  if $by > 0 then $init|while(. < $upto; . + $by)

tests/jq.test

@@ -334,6 +334,38 @@ null
 "badness"
 [1]
 
+try limit(-1; error) catch .
+null
+"limit doesn't support negative indices"
+
+[skip(3; .[])]
+[1,2,3,4,5,6,7,8,9]
+[4,5,6,7,8,9]
+
+[skip(3; .[])]
+[]
+[]
+
+[skip(0; .[])]
+[1,2,3]
+[1,2,3]
+
+[skip(2; .[])]
+[1,2,3]
+[3]
+
+[skip(3; .[])]
+[1,2,3]
+[]
+
+[skip(4; .[])]
+[1,2,3]
+[]
+
+try skip(-1; error) catch .
+null
+"skip doesn't support negative indices"
+
 [first(range(.)), last(range(.))]
 10
 [0,9]