Document json_object_pack (geldata#5154)

Author: raddevon

docs/stdlib/json.rst

@@ -44,6 +44,9 @@ JSON
     * - :eql:func:`json_array_unpack`
       - :eql:func-desc:`json_array_unpack`
 
+    * - :eql:func:`json_object_pack`
+      - :eql:func-desc:`json_object_pack`
+
     * - :eql:func:`json_object_unpack`
       - :eql:func-desc:`json_object_unpack`
 
@@ -76,6 +79,17 @@ Any value in EdgeDB can be cast to a :eql:type:`json` type as well:
     db> select <json>cal::to_local_date(datetime_current(), 'UTC');
     {Json("\"2022-11-21\"")}
 
+.. versionadded:: 3.0
+
+    The :eql:func:`json_object_pack` function provides one more way to
+    construct JSON. It constructs a JSON object from an array of key/value
+    tuples:
+
+    .. code-block:: edgeql-repl
+
+        db> select json_object_pack({("hello", <json>"world")});
+        {Json("{\"hello\": \"world\"}")}
+
 Additionally, any :eql:type:`Object` in EdgeDB can be cast as a
 :eql:type:`json` type. This produces the same JSON value as the
 JSON-serialized result of that said object. Furthermore, this result will
@@ -457,6 +471,37 @@ reversible (i.e., it is not possible to cast a JSON value directly into a
 ----------
 
 
+.. eql:function:: std::json_object_pack(pairs: SET OF tuple<str, json>) -> \
+                  json
+
+    .. versionadded:: 3.0
+
+    Returns the given set of key/value tuples as a JSON object.
+
+    .. code-block:: edgeql-repl
+
+        db> select json_object_pack({
+        ...     ("foo", to_json("1")),
+        ...     ("bar", to_json("null")),
+        ...     ("baz", to_json("[]"))
+        ... });
+        {Json("{\"bar\": null, \"baz\": [], \"foo\": 1}")}
+
+    If the key/value tuples being packed have common keys, the last value for
+    each key will make the final object.
+
+    .. code-block:: edgeql-repl
+
+        db> select json_object_pack({
+        ...     ("hello", <json>"world"),
+        ...     ("hello", <json>true)
+        ... });
+        {Json("{\"hello\": true}")}
+
+
+----------
+
+
 .. eql:function:: std::json_object_unpack(json: json) -> \
                   set of tuple<str, json>