difference is now a binary function and returns a result without du…

…plicates

dist/lamb.js

@@ -1,7 +1,7 @@
 /**
  * @overview lamb - A lightweight, and docile, JavaScript library to help embracing functional programming.
  * @author Andrea Scartabelli <andrea.scartabelli@gmail.com>
- * @version 0.53.0-alpha.3
+ * @version 0.53.0-alpha.4
  * @module lamb
  * @license MIT
  * @preserve
@@ -44,7 +44,7 @@
          * @readonly
          * @type String
          */
-        "@@lamb/version": {value: "0.53.0-alpha.3"}
+        "@@lamb/version": {value: "0.53.0-alpha.4"}
     });
 
     // prototype shortcuts
@@ -3663,28 +3663,28 @@
     }
 
     /**
-     * Returns an array of items present only in the first of the given array-like objects.<br/>
-     * Note that this function uses the ["SameValueZero" comparison]{@link module:lamb.areSVZ|areSVZ}.
+     * Returns an array of unique items present only in the first of the two given
+     * array-like objects. To determine uniqueness the function uses the
+     * ["SameValueZero" comparison]{@link module:lamb.areSVZ|areSVZ}.
      * @example
-     * var a1 = [1, 2, 3, 4];
-     * var a2 = [2, 4, 5];
-     * var a3 = [4, 5, 3, 1];
+     * var a1 = [1, 2, 1, 3, 4];
+     * var a2 = [2, 4, 5, 6];
+     * var a3 = [3, 4, 5, 2, 1];
      *
      * _.difference(a1, a2) // => [1, 3]
-     * _.difference(a2, a3) // => [2]
-     * _.difference(a1, a2, a3) // => []
+     * _.difference(a2, a3) // => [6]
+     * _.difference(a1, a3) // => []
      *
      * @memberof module:lamb
      * @category Array
      * @param {ArrayLike} arrayLike
-     * @param {...ArrayLike} other
+     * @param {ArrayLike} other
      * @returns {Array}
      */
-    function difference (arrayLike) {
-        var rest = flatMap(_argsTail.apply(null, arguments), drop(0));
-        var isInRest = partial(isIn, [rest, _, 0]);
+    function difference (arrayLike, other) {
+        var isNotInOther = partial(not(isIn), [other]);
 
-        return filter(arrayLike, not(isInRest));
+        return uniques(filter(arrayLike, isNotInOther));
     }
 
     /**

package.json

@@ -34,7 +34,7 @@
     "coveralls": "gulp coverage && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage"
   },
   "tonicExample": "var _ = require('lamb');",
-  "version": "0.53.0-alpha.3",
+  "version": "0.53.0-alpha.4",
   "devDependencies": {
     "coveralls": "^2.12.0",
     "gulp": "^3.9.1",

src/array.js

@@ -38,28 +38,28 @@ function appendTo (arrayLike, value) {
 }
 
 /**
- * Returns an array of items present only in the first of the given array-like objects.<br/>
- * Note that this function uses the ["SameValueZero" comparison]{@link module:lamb.areSVZ|areSVZ}.
+ * Returns an array of unique items present only in the first of the two given
+ * array-like objects. To determine uniqueness the function uses the
+ * ["SameValueZero" comparison]{@link module:lamb.areSVZ|areSVZ}.
  * @example
- * var a1 = [1, 2, 3, 4];
- * var a2 = [2, 4, 5];
- * var a3 = [4, 5, 3, 1];
+ * var a1 = [1, 2, 1, 3, 4];
+ * var a2 = [2, 4, 5, 6];
+ * var a3 = [3, 4, 5, 2, 1];
  *
  * _.difference(a1, a2) // => [1, 3]
- * _.difference(a2, a3) // => [2]
- * _.difference(a1, a2, a3) // => []
+ * _.difference(a2, a3) // => [6]
+ * _.difference(a1, a3) // => []
  *
  * @memberof module:lamb
  * @category Array
  * @param {ArrayLike} arrayLike
- * @param {...ArrayLike} other
+ * @param {ArrayLike} other
  * @returns {Array}
  */
-function difference (arrayLike) {
-    var rest = flatMap(_argsTail.apply(null, arguments), drop(0));
-    var isInRest = partial(isIn, [rest, _, 0]);
+function difference (arrayLike, other) {
+    var isNotInOther = partial(not(isIn), [other]);
 
-    return filter(arrayLike, not(isInRest));
+    return uniques(filter(arrayLike, isNotInOther));
 }
 
 /**

test/spec/arraySpec.js

@@ -75,27 +75,31 @@ describe("lamb.array", function () {
     describe("difference", function () {
         var a1 = [0, 1, 2, 3, 4, NaN];
         var a2 = [-0, 2, 3, 4, 5, NaN];
-        var a3 = [4, 5, 1];
+        var a3 = [4, 5, 1, 4, 5];
         var a4 = [6, 7];
 
-        it("should return an array of items present only in the first of the given arrays", function () {
-            expect(lamb.difference(a1)).toEqual(a1);
+        it("should return a new array with the items present only in the first of the two arrays", function () {
+            var r = lamb.difference(a1, a4);
+
+            expect(r).toEqual(a1);
+            expect(r).not.toBe(a1);
+            expect(lamb.difference(a1, a3)).toEqual([0, 2, 3, NaN]);
+        });
+
+        it("should use the \"SameValueZero\" comparison and keep the first encountered value in case of equality", function () {
             expect(lamb.difference(a1, a2)).toEqual([1]);
-            expect(lamb.difference(a1, a2, a3)).toEqual([]);
-            expect(lamb.difference(a1, a3, a4)).toEqual([0, 2, 3, NaN]);
-            expect(Object.is(0, lamb.difference(a1, a3, a4)[0])).toBe(true);
+            expect(lamb.difference([-0, 1, 0, 2], [1, 3, 2])).toEqual([-0]);
         });
 
-        it("should work with array-like objects", function () {
-            expect(lamb.difference("abc", "bd", ["b", "f"])).toEqual(["a", "c"]);
-            expect(lamb.difference(["a", "b", "c"], "bd", ["b", "f"])).toEqual(["a", "c"]);
+        it("should return an array without duplicates", function () {
+            expect(lamb.difference(a3, a4)).toEqual([4, 5, 1]);
+            expect(lamb.difference(a3, a1)).toEqual([5]);
         });
 
-        it("should always return dense arrays", function () {
-            expect(lamb.difference([1, , 3, 4, 5], [4, 5])).toEqual([1, void 0, 3]);
-            expect(lamb.difference([1, , 3, 4, 5], [4, , 5])).toEqual([1, 3]);
-            expect(lamb.difference([1, , 3, 4, 5], [4, void 0, 5])).toEqual([1, 3]);
-            expect(lamb.difference([1, void 0, 3, 4, 5], [4, , 5])).toEqual([1, 3]);
+        it("should work with array-like objects", function () {
+            expect(lamb.difference("abc", "bd")).toEqual(["a", "c"]);
+            expect(lamb.difference(["a", "b", "c"], "bd")).toEqual(["a", "c"]);
+            expect(lamb.difference("abc", ["b", "d"])).toEqual(["a", "c"]);
         });
 
         it("should throw an exception if called without arguments", function () {
@@ -107,8 +111,7 @@ describe("lamb.array", function () {
             expect(function () { lamb.difference(void 0, a4); }).toThrow();
             expect(function () { lamb.difference(a4, null); }).toThrow();
             expect(function () { lamb.difference(a4, void 0); }).toThrow();
-            expect(function () { lamb.difference(a1, a4, null); }).toThrow();
-            expect(function () { lamb.difference(a1, a4, void 0); }).toThrow();
+            expect(function () { lamb.difference(a4); }).toThrow();
         });
 
         it("should treat every other value in the main parameter as an empty array", function () {
@@ -117,10 +120,10 @@ describe("lamb.array", function () {
             });
         });
 
-        it("should treat every non-array-like value in other parameters as an empty array", function () {
+        it("should treat every non-array-like value in the `other` parameter as an empty array", function () {
             wannabeEmptyArrays.forEach(function (value) {
-                expect(lamb.difference(a1, value, [4, 5], a4)).toEqual([0, 1, 2, 3, NaN]);
-                expect(lamb.difference(wannabeEmptyArrays, value)).toEqual(wannabeEmptyArrays);
+                expect(lamb.difference(a1, value)).toEqual(a1);
+                expect(lamb.difference(wannabeEmptyArrays, value)).toEqual(lamb.uniques(wannabeEmptyArrays));
             });
         });
     });