Merge branch 'master' into join

Author: mattbaileyuk

docs/array-functions.md

@@ -10,18 +10,18 @@ Returns the number of items in the `array` parameter.  If the `array` parameter
 
 If `array` is not specified, then the context value is used as the value of `array`.
 
-__Examples__  
-- `$count([1,2,3,1])` => `4`  
+__Examples__
+- `$count([1,2,3,1])` => `4`
 - `$count("hello")` => 1
 
 ## `$append()`
 __Signature:__ `$append(array1, array2)`
 
 Returns and array containing the values in `array1` followed by the values in `array2`.  If either parameter is not an array, then it is treated as a singleton array containing that value.
 
-__Examples__  
-- `$append([1,2,3], [4,5,6])` => `[1,2,3,4,5,6]`  
-- `$append([1,2,3], 4)` => `[1,2,3,4]`  
+__Examples__
+- `$append([1,2,3], [4,5,6])` => `[1,2,3,4,5,6]`
+- `$append([1,2,3], 4)` => `[1,2,3,4]`
 - `$append("Hello", "World")` => `["Hello", "World"]`
 
 
@@ -52,19 +52,26 @@ __Signature:__ `$reverse(array)`
 
 Returns an array containing all the values from the `array` parameter, but in reverse order.
 
-__Examples__  
-- `$reverse(["Hello", "World"])` => `["World", "Hello"]`  
+__Examples__
+- `$reverse(["Hello", "World"])` => `["World", "Hello"]`
 - `[1..5] ~> $reverse()` => `[5, 4, 3, 2, 1]`
 
 ## `$shuffle()`
 __Signature:__ `$shuffle(array)`
 
 Returns an array containing all the values from the `array` parameter, but shuffled into random order.
 
-__Examples__  
+__Examples__
 - `$shuffle([1..9])` => `[6, 8, 2, 3, 9, 5, 1, 4, 7]`
 
+## `$distinct()`
+__Signature__ `$distinct(array)`
 
+Returns an array containing all the values from the `array` parameter, but with any duplicates removed.  Values are tested for deep equality as if by using the [equality operator](comparison-operators#equals).
+
+__Examples__
+- `$distinct([1,2,3,3,4,3,5])` => `[1, 2, 3, 4, 5]`
+- `$distinct(Account.Order.Product.Description.Colour)` => `[ "Purple", "Orange", "Black" ]`
 
 ## `$zip()`
 __Signature:__ `$zip(array1, ...)`
@@ -73,6 +80,6 @@ Returns a convolved (zipped) array containing grouped arrays of values from the
 
 This function accepts a variable number of arguments.  The length of the returned array is equal to the length of the shortest array in the arguments.
 
-__Examples__  
-- `$zip([1,2,3], [4,5,6])` => `[[1,4] ,[2,5], [3,6]]`  
+__Examples__
+- `$zip([1,2,3], [4,5,6])` => `[[1,4] ,[2,5], [3,6]]`
 - `$zip([1,2,3],[4,5],[7,8,9])` => `[[1,4,7], [2,5,8]]`

docs/comparison-operators.md

@@ -6,20 +6,20 @@ sidebar_label: Comparison Operators
 
 ## `=` (Equals)
 
-The equality operator returns Boolean `true` if both operands are the same (type and value).  Otherwise it returns `false`.
+The equality operator returns Boolean `true` if both operands are the same (type and value).  Arrays and objects are checked for deep equality.  Arrays must have the same values in the same order. Objects must have the same key/value pairs (order is not relevant).  Otherwise it returns `false`.
 
 __Examples__
 
-- `1+1 = 2` => `true`   
+- `1+1 = 2` => `true`
 - `"Hello" = "World"` => `false`
 
 ## `!=` (Not equals)
 
-The inequality operator returns Boolean `false` if both operands are the same (type and value).  Otherwise it returns `true`.
+The inequality operator returns Boolean `false` if both operands are the same (type and value, deep equality).  Otherwise it returns `true`.
 
 __Examples__
 
-- `1+1 != 3` => `true`   
+- `1+1 != 3` => `true`
 - `"Hello" != "World"` => `true`
 
 ## `>` (Greater than)
@@ -28,7 +28,7 @@ The 'greater than' operator returns Boolean `true` if the LHS is numerically gre
 
 __Examples__
 
-- `22 / 7 > 3` => `true`   
+- `22 / 7 > 3` => `true`
 - `5 > 5` => `false`
 
 ## `<` (Less than)
@@ -37,7 +37,7 @@ The 'less than' operator returns Boolean `true` if the LHS is numerically less t
 
 __Examples__
 
-- `22 / 7 < 3` => `false`   
+- `22 / 7 < 3` => `false`
 - `5 < 5` => `false`
 
 
@@ -47,7 +47,7 @@ The 'greater than or equals' operator returns Boolean `true` if the LHS is numer
 
 __Examples__
 
-- `22 / 7 >= 3` => `true`   
+- `22 / 7 >= 3` => `true`
 - `5 >= 5` => `true`
 
 
@@ -57,7 +57,7 @@ The 'less than or equals' operator returns Boolean `true` if the LHS is numerica
 
 __Examples__
 
-- `22 / 7 <= 3` => `false`   
+- `22 / 7 <= 3` => `false`
 - `5 <= 5` => `true`
 
 ## `in` (Inclusion)
@@ -66,7 +66,7 @@ The array (sequence) inclusion operator returns Boolean `true` if the value of t
 
 __Examples__
 
-- `"world" in ["hello", "world"]` => `true`   
-- `"hello" in "hello"` => `true`   
+- `"world" in ["hello", "world"]` => `true`
+- `"hello" in "hello"` => `true`
 - `library.books["Aho" in authors].title`
 

src/functions.js

@@ -13,10 +13,12 @@ const functions = (() => {
     var isArrayOfStrings = utils.isArrayOfStrings;
     var isArrayOfNumbers = utils.isArrayOfNumbers;
     var createSequence = utils.createSequence;
+    var isSequence = utils.isSequence;
     var isFunction = utils.isFunction;
     var isLambda = utils.isLambda;
     var isIterable = utils.isIterable;
     var getFunctionArity = utils.getFunctionArity;
+    var deepEquals = utils.isDeepEqual;
 
     /**
      * Sum function
@@ -1923,6 +1925,40 @@ const functions = (() => {
         return result;
     }
 
+    /**
+     * Returns the values that appear in a sequence, with duplicates eliminated.
+     * @param {Array} arr - An array or sequence of values
+     * @returns {Array} - sequence of distinct values
+     */
+    function distinct(arr) {
+        // undefined inputs always return undefined
+        if (typeof arr === 'undefined') {
+            return undefined;
+        }
+
+        if(!Array.isArray(arr) || arr.length <= 1) {
+            return arr;
+        }
+
+        var results = isSequence(arr) ? createSequence() : [];
+
+        for(var ii = 0; ii < arr.length; ii++) {
+            var value = arr[ii];
+            // is this value already in the result sequence?
+            var includes = false;
+            for(var jj = 0; jj < results.length; jj++) {
+                if (deepEquals(value, results[jj])) {
+                    includes = true;
+                    break;
+                }
+            }
+            if(!includes) {
+                results.push(value);
+            }
+        }
+        return results;
+    }
+
     /**
      * Applies a predicate function to each key/value pair in an object, and returns an object containing
      * only the key/value pairs that passed the predicate
@@ -1959,7 +1995,7 @@ const functions = (() => {
         formatNumber, formatBase, number, floor, ceil, round, abs, sqrt, power, random,
         boolean, not,
         map, zip, filter, single, foldLeft, sift,
-        keys, lookup, append, exists, spread, merge, reverse, each, error, sort, shuffle,
+        keys, lookup, append, exists, spread, merge, reverse, each, error, sort, shuffle, distinct,
         base64encode, base64decode,  encodeUrlComponent, encodeUrl, decodeUrlComponent, decodeUrl
     };
 })();

src/jsonata.js

@@ -33,6 +33,7 @@ var jsonata = (function() {
     var isLambda = utils.isLambda;
     var isIterable = utils.isIterable;
     var getFunctionArity = utils.getFunctionArity;
+    var isDeepEqual = utils.isDeepEqual;
 
     // Start of Evaluator code
 
@@ -720,10 +721,10 @@ var jsonata = (function() {
 
         switch (op) {
             case '=':
-                result = lhs === rhs;
+                result = isDeepEqual(lhs, rhs);
                 break;
             case '!=':
-                result = (lhs !== rhs);
+                result = !isDeepEqual(lhs, rhs);
                 break;
         }
         return result;
@@ -1859,6 +1860,7 @@ var jsonata = (function() {
     staticFrame.bind('error', defineFunction(fn.error, '<s?:x>'));
     staticFrame.bind('sort', defineFunction(fn.sort, '<af?:a>'));
     staticFrame.bind('shuffle', defineFunction(fn.shuffle, '<a:a>'));
+    staticFrame.bind('distinct', defineFunction(fn.distinct, '<x:x>'));
     staticFrame.bind('base64encode', defineFunction(fn.base64encode, '<s-:s>'));
     staticFrame.bind('base64decode', defineFunction(fn.base64decode, '<s-:s>'));
     staticFrame.bind('encodeUrlComponent', defineFunction(fn.encodeUrlComponent, '<s-:s>'));

src/utils.js

@@ -125,6 +125,57 @@ const utils = (() => {
         );
     }
 
+    /**
+     * Compares two values for equality
+     * @param {*} lhs first value
+     * @param {*} rhs second value
+     * @returns {boolean} true if they are deep equal
+     */
+    function isDeepEqual(lhs, rhs) {
+        if (lhs === rhs) {
+            return true;
+        }
+        if(typeof lhs === 'object' && typeof rhs === 'object' && lhs !== null && rhs !== null) {
+            if(Array.isArray(lhs) && Array.isArray(rhs)) {
+                // both arrays (or sequences)
+                // must be the same length
+                if(lhs.length !== rhs.length) {
+                    return false;
+                }
+                // must contain same values in same order
+                for(var ii = 0; ii < lhs.length; ii++) {
+                    if(!isDeepEqual(lhs[ii], rhs[ii])) {
+                        return false;
+                    }
+                }
+                return true;
+            }
+            // both objects
+            // must have the same set of keys (in any order)
+            var lkeys = Object.getOwnPropertyNames(lhs);
+            var rkeys = Object.getOwnPropertyNames(rhs);
+            if(lkeys.length !== rkeys.length) {
+                return false;
+            }
+            lkeys = lkeys.sort();
+            rkeys = rkeys.sort();
+            for(ii=0; ii < lkeys.length; ii++) {
+                if(lkeys[ii] !== rkeys[ii]) {
+                    return false;
+                }
+            }
+            // must have the same values
+            for(ii=0; ii < lkeys.length; ii++) {
+                var key = lkeys[ii];
+                if(!isDeepEqual(lhs[key], rhs[key])) {
+                    return false;
+                }
+            }
+            return true;
+        }
+        return false;
+    }
+
     return {
         isNumeric,
         isArrayOfStrings,
@@ -134,7 +185,8 @@ const utils = (() => {
         isFunction,
         isLambda,
         isIterable,
-        getFunctionArity
+        getFunctionArity,
+        isDeepEqual
     };
 })();