GROUPS_BY(s;f) with test and documentation.

./jqtest => 307 of 307 tests passed (0 malformed)

Author: pkoppstein

docs/content/3.manual/manual.yml

@@ -1312,6 +1312,20 @@ sections:
             input: '[{"foo":1, "bar":10}, {"foo":3, "bar":100}, {"foo":1, "bar":1}]'
             output: ['[[{"foo":1, "bar":10}, {"foo":1, "bar":1}], [{"foo":3, "bar":100}]]']
 
+      - title: "`GROUPS_BY(stream; path_expression)`"
+        body: |
+
+          `GROUPS_BY/2` is a stream-oriented version of group_by/1: it takes as input the items
+	  in `stream`, and emits a stream of arrays, one per group as defined by
+	  `path_expression`, which must evaluate to a string for all items in the stream.
+
+        examples:
+          - program: 'GROUPS_BY(1,2,1; tostring)'
+            input: 'null'
+            output:
+	      - ['[1,1]']
+              - ['[2]']
+
       - title: "`min`, `max`, `min_by(path_exp)`, `max_by(path_exp)`"
         body: |
 

src/builtin.jq

@@ -303,3 +303,6 @@ def JOIN($idx; stream; idx_expr; join_expr):
   stream | [., $idx[idx_expr]] | join_expr;
 def IN(s): . as $in | first( if (s == $in) then true else empty end ) // false;
 def IN(src; s): any( src|IN(s); .);
+
+# f should always evaluate to a string:
+def GROUPS_BY(stream; f): reduce stream as $x ({}; .[$x|f] += [$x] ) | .[];

tests/jq.test

@@ -1420,4 +1420,7 @@ isempty(1,error("foo"))
 null
 false
 
-
+GROUPS_BY(1,1,2; tostring)
+null
+[1,1]
+[2]