From 87b7d6d5a0dfc45544d8a4e2a71f6c57aa603372 Mon Sep 17 00:00:00 2001
From: Jonathan Stewmon <jstewmon@rmn.com>
Date: Mon, 21 Mar 2016 09:14:07 -0500
Subject: [PATCH] added items, to_object and zip functions to specification

---
 docs/specification.rst | 100 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)

diff --git a/docs/specification.rst b/docs/specification.rst
index 6bce826..1f276a6 100644
--- a/docs/specification.rst
+++ b/docs/specification.rst
@@ -1275,6 +1275,55 @@ Returns the next lowest integer value by rounding down if necessary.
     - 1
 
 
+.. _func-items:
+
+items
+-----
+
+::
+
+    array[array[any]] items(object $obj)
+
+Returns a an array of key value pairs for the provided object ``$obj``. Each
+pair is a 2-item array with the first item being the key and the second item
+being the value. This function is the inverse of :ref:`func-to-object`.
+Note that because JSON hashes are inheritently unordered, the key value pairs
+of the provided object ``$obj`` are inheritently unordered.  Implementations
+are not required to return values in any specific order.  For example, given
+the input::
+
+    {"a": "first", "b": "second", "c": "third"}
+
+The expression ``items(@)`` could have any of these return values:
+
+* ``[["a", "first"], ["b", "second"], ["c", "third"]]``
+* ``[["a", "first"], ["c", "third"], ["b", "second"]]``
+* ``[["b", "second"], ["a", "first"], ["c", "third"]]``
+* ``[["b", "second"], ["c", "third"], ["a", "first"]]``
+* ``[["c", "third"], ["a", "first"], ["b", "second"]]``
+* ``[["c", "third"], ["b", "second"], ["a", "first"]]``
+
+If you would like a specific order, consider using the ``sort_by`` function.
+
+.. cssclass:: table
+
+.. list-table:: Examples
+  :header-rows: 1
+
+  * - Given
+    - Expression
+    - Result
+  * - ``{"a": "first", "b": "second"}``
+    - ``items(@)``
+    - ``[["b", "second"], ["a", "first"]]``
+  * - ``{"z": "last", "b": "second"}``
+    - ``sort_by(items(@), &[0])``
+    - ``[["b", "second"], ["z", "last"]]``
+  * - ``{"z": "last", "b": "second"}``
+    - ``sort_by(items(@), &[1])``
+    - ``[["z", "last"], ["b", "second"]]``
+
+
 .. _func-join:
 
 join
@@ -1835,6 +1884,31 @@ to_array
     - ``[{"foo": "bar"}]``
 
 
+.. _func-to-object:
+
+to_object
+---------
+
+::
+
+    object to_object(array[array[any]] $arg)
+
+Returns an object from the provided array of key value pairs. This function
+is the inverse of :ref:`func-items`.
+
+.. cssclass:: table
+
+.. list-table:: Examples
+  :header-rows: 1
+
+  * - Given
+    - Expression
+    - Result
+  * - ``[["one", 1], ["two", 2]]``
+    - ``to_object(@)``
+    - ``{"one": 1, "two": 2}``
+
+
 .. _func-to-string:
 
 
@@ -1987,6 +2061,32 @@ If you would like a specific order, consider using the
     - ``<error: invalid-type>``
 
 
+.. _func-zip:
+
+zip
+---
+
+::
+
+    array[array[any]] zip([array[any] $arg, [, array[any] $...]])
+
+Accepts 1 or more arrays as arguments and returns an array of arrays in which
+the *i-th* array contains the *i-th* element from each of the argument arrays.
+The returned array is truncated to the length of the shortest argument array.
+
+.. cssclass:: table
+
+.. list-table:: Examples
+  :header-rows: 1
+
+  * - Expression
+    - Result
+  * - ``zip(`["a", "b"]`, `[1, 2]`)``
+    - ``[["a", 1], ["b", 2]]``
+  * - ``zip(`["a", "b", "c"]`, `[1, 2]`)``
+    - ``[["a", 1], ["b", 2]]``
+
+
 Pipe Expressions
 ================