Documented the group_by() function.

Author: springcomp

functions/group_by.yml

@@ -0,0 +1,77 @@
+name: group_by
+topic: collections
+args:
+  required:
+  - name: elements
+    type: ['array[object]']
+    desc: ''
+  - name: expr
+    type: [expression->string]
+    desc: ''
+  optional: []
+returns:
+  type: object
+  desc: ''
+desc: |
+  Groups an array of objects `$elements` using an expression `$expr` as the group key.
+  The `$expr` expression is applied to each element in the array `$elements` and the 
+  resulting value is used as a group key.
+
+  The result is an object whose keys are the unique set of string keys and whose respective values are an array of objects array matching the group criteria.
+
+  Objects that do not match the group criteria are discarded from the output.
+  This includes objects for which applying the `$expr` expression evaluates to `null`.
+
+  If the result of applying the `$expr` expression against the current array element
+  results in type other than `string` or `null`, a type error MUST be raised.
+examples:
+  group_by:
+    context:
+      items:
+        - spec:
+            nodeName: node_01
+            other: values_01
+        - spec:
+            nodeName: node_02
+            other: values_02
+        - spec:
+            nodeName: node_03
+            other: values_03
+        - spec:
+            nodeName: node_01
+            other: values_04
+    args: [items, '&nodeName']
+    returns: 
+      nodeName:
+        node_01:
+          - spec:
+              nodeName: node_01
+              other: values_01
+          - spec:
+              nodeName: node_01
+              other: values_04
+        node_02:
+          - spec:
+              nodeName: node_02
+              other: values_02
+        node_03:
+          - spec:
+              nodeName: node_03
+              other: values_03
+  group_by_discards_null_keyed_objects:
+    context: &data
+      array:
+      - b: true
+        name: one
+      - b: false
+        name: two
+      - b: false
+    args: [array, '&name']
+    returns: [{age: 10, age_str: '10', bool: true, name: 3}, {age: 20, age_str: '20',
+        bool: true, name: a, extra: foo}, {age: 30, age_str: '30', bool: true, name: c},
+      {age: 40, age_str: '40', bool: false, name: b, extra: bar}, {age: 50, age_str: '50',
+        bool: false, name: d}]
+  group_by_errs_invalid_type:
+    context: *data
+    args: [array, '&b']
+    error: invalid-type

jep-018-grouping.md

@@ -17,7 +17,7 @@ This JEP introduces a new `group_by()` function.
 ### group_by
 
 ```
-object group_by(array[object] $elements, expression->expression->string) $expr)
+object group_by(array[object] $elements, expression->string) $expr)
 ```
 
 Groups an array of objects `$elements` using an expression `$expr` as the group key.