From 172cc1ffea213ee1fceec9f76cd8f20020acae29 Mon Sep 17 00:00:00 2001
From: John-David Dalton <john.david.dalton@gmail.com>
Date: Mon, 16 Dec 2013 02:34:20 -0800
Subject: [PATCH] Add `thisArg` to `_.tap`.

---
 dist/lodash.compat.js     | 17 +++++++++--------
 dist/lodash.compat.min.js |  2 +-
 dist/lodash.js            | 17 +++++++++--------
 dist/lodash.min.js        |  2 +-
 lodash.js                 | 13 +++++++------
 test/test.js              | 26 +++++++++++++++++++++-----
 6 files changed, 48 insertions(+), 29 deletions(-)

diff --git a/dist/lodash.compat.js b/dist/lodash.compat.js
index e97c6ce50..261e483e9 100644
--- a/dist/lodash.compat.js
+++ b/dist/lodash.compat.js
@@ -2955,7 +2955,7 @@
      *  per iteration. If a property name or object is provided it will be used
      *  to create a "_.pluck" or "_.where" style callback, respectively.
      * @param {*} [thisArg] The `this` binding of `callback`.
-     * @returns {Array} Returns a new object with values of the results of each `callback` execution.
+     * @returns {Object} Returns a new object with values of the results of each `callback` execution.
      * @example
      *
      * _.mapValues({ 'a': 1, 'b': 2, 'c': 3} , function(num) { return num * 3; });
@@ -4190,7 +4190,7 @@
      * @param {number} [n] The number of elements to sample.
      * @param- {Object} [guard] Allows working with functions like `_.map`
      *  without using their `index` arguments as `n`.
-     * @returns {Array} Returns the random sample(s) of `collection`.
+     * @returns {*} Returns the random sample(s) of `collection`.
      * @example
      *
      * _.sample([1, 2, 3, 4]);
@@ -6825,16 +6825,17 @@
     }
 
     /**
-     * Invokes `interceptor` with the `value` as the first argument and then
-     * returns `value`. The purpose of this method is to "tap into" a method
-     * chain in order to perform operations on intermediate results within
-     * the chain.
+     * This method invokes `interceptor` and returns `value`. The interceptor is
+     * bound to `thisArg` and invoked with one argument; (value). The purpose of
+     * this method is to "tap into" a method chain in order to perform operations
+     * on intermediate results within the chain.
      *
      * @static
      * @memberOf _
      * @category Chaining
      * @param {*} value The value to provide to `interceptor`.
      * @param {Function} interceptor The function to invoke.
+     * @param {*} [thisArg] The `this` binding of `interceptor`.
      * @returns {*} Returns `value`.
      * @example
      *
@@ -6844,8 +6845,8 @@
      *  .value();
      * // => [3, 2, 1]
      */
-    function tap(value, interceptor) {
-      interceptor(value);
+    function tap(value, interceptor, thisArg) {
+      interceptor.call(thisArg, value);
       return value;
     }
 
diff --git a/dist/lodash.compat.min.js b/dist/lodash.compat.min.js
index 7a723dde8..765db0c3b 100644
--- a/dist/lodash.compat.min.js
+++ b/dist/lodash.compat.min.js
@@ -44,7 +44,7 @@ if(typeof t!="number"&&null!=t){var o=u;for(t=v.createCallback(t,r,3);o--&&t(n[o
 });return o},v.omit=function(n,t,r){var e={};if(typeof t!="function"){var u=[];Zr(n,function(n,t){u.push(t)});for(var u=rt(u,ot(arguments,true,false,1)),o=-1,a=u.length;++o<a;){var i=u[o];e[i]=n[i]}}else t=v.createCallback(t,r,3),Zr(n,function(n,r,u){t(n,r,u)||(e[r]=n)});return e},v.once=function(n){var t,r;if(!Ot(n))throw new sr;return function(){return t?r:(t=true,r=n.apply(this,arguments),n=null,r)}},v.pairs=function(n){for(var t=-1,r=Hr(n),e=r.length,u=er(e);++t<e;){var o=r[t];u[t]=[o,n[o]]}return u
 },v.partial=function(n){return pt(n,16,s(arguments,1))},v.partialRight=function(n){return pt(n,32,null,s(arguments,1))},v.pick=function(n,t,r){var e={};if(typeof t!="function")for(var u=-1,o=ot(arguments,true,false,1),a=Et(n)?o.length:0;++u<a;){var i=o[u];i in n&&(e[i]=n[i])}else t=v.createCallback(t,r,3),Zr(n,function(n,r,u){t(n,r,u)&&(e[r]=n)});return e},v.pluck=ue,v.property=tr,v.pull=function(n){for(var t=arguments,r=0,e=t.length,u=n?n.length:0;++r<e;)for(var o=-1,a=t[r];++o<u;)n[o]===a&&(Ar.call(n,o--,1),u--);
 return n},v.range=function(n,t,r){n=+n||0,r=typeof r=="number"?r:+r||1,null==t&&(t=n,n=0);var e=-1;t=qr(0,wr((t-n)/(r||1)));for(var u=er(t);++e<t;)u[e]=n,n+=r;return u},v.reject=function(n,t,r){return t=v.createCallback(t,r,3),Pt(n,function(n,r,e){return!t(n,r,e)})},v.remove=function(n,t,r){var e=-1,u=n?n.length:0,o=[];for(t=v.createCallback(t,r,3);++e<u;)r=n[e],t(r,e,n)&&(o.push(r),Ar.call(n,e--,1),u--);return o},v.rest=Vt,v.shuffle=Wt,v.sortBy=function(n,t,r){var e=-1,o=Ur(t),a=n?n.length:0,l=er(typeof a=="number"?a:0);
-for(o||(t=v.createCallback(t,r,3)),Dt(n,function(n,r,u){var a=l[++e]=f();o?a.i=Ft(t,function(t){return n[t]}):(a.i=i())[0]=t(n,r,u),a.j=e,a.k=n}),a=l.length,l.sort(u);a--;)n=l[a],l[a]=n.k,o||c(n.i),p(n);return l},v.tap=function(n,t){return t(n),n},v.throttle=function(n,t,r){var e=true,u=true;if(!Ot(n))throw new sr;return false===r?e=false:Et(r)&&(e="leading"in r?r.leading:e,u="trailing"in r?r.trailing:u),H.leading=e,H.maxWait=t,H.trailing=u,Xt(n,t,H)},v.times=function(n,t,r){n=-1<(n=+n)?n:0;var e=-1,u=er(n);
+for(o||(t=v.createCallback(t,r,3)),Dt(n,function(n,r,u){var a=l[++e]=f();o?a.i=Ft(t,function(t){return n[t]}):(a.i=i())[0]=t(n,r,u),a.j=e,a.k=n}),a=l.length,l.sort(u);a--;)n=l[a],l[a]=n.k,o||c(n.i),p(n);return l},v.tap=function(n,t,r){return t.call(r,n),n},v.throttle=function(n,t,r){var e=true,u=true;if(!Ot(n))throw new sr;return false===r?e=false:Et(r)&&(e="leading"in r?r.leading:e,u="trailing"in r?r.trailing:u),H.leading=e,H.maxWait=t,H.trailing=u,Xt(n,t,H)},v.times=function(n,t,r){n=-1<(n=+n)?n:0;var e=-1,u=er(n);
 for(t=nt(t,r,1);++e<n;)u[e]=t(e);return u},v.toArray=function(n){return n&&typeof n.length=="number"?Mr.unindexedChars&&It(n)?n.split(""):s(n):At(n)},v.transform=function(n,t,r,e){var u=Ur(n);if(null==r)if(u)r=[];else{var o=n&&n.constructor;r=Z(o&&o.prototype)}return t&&(t=v.createCallback(t,e,4),(u?ut:wt)(n,function(n,e,u){return t(r,n,e,u)})),r},v.union=function(){return lt(ot(arguments,true,true))},v.uniq=Gt,v.values=At,v.where=Pt,v.without=function(n){return rt(n,s(arguments,1))},v.wrap=function(n,t){return pt(t,16,[n])
 },v.xor=function(){for(var n=-1,t=arguments.length;++n<t;){var r=arguments[n];if(Ur(r)||dt(r))var e=e?rt(e,r).concat(rt(r,e)):r}return e?lt(e):[]},v.zip=Ht,v.zipObject=Jt,v.collect=Ft,v.drop=Vt,v.each=Dt,v.eachRight=$t,v.extend=bt,v.methods=xt,v.object=Jt,v.select=Pt,v.tail=Vt,v.unique=Gt,v.unzip=Ht,Zt(bt({},v)),v.clone=function(n,t,r,e){return typeof t!="boolean"&&null!=t&&(e=r,r=t,t=false),X(n,t,typeof r=="function"&&nt(r,e,1))},v.cloneDeep=function(n,t,r){return X(n,true,typeof t=="function"&&nt(t,r,1))
 },v.contains=Nt,v.escape=function(n){return null==n?"":pr(n).replace(Yr,gt)},v.every=Rt,v.find=Tt,v.findIndex=function(n,t,r){var e=-1,u=n?n.length:0;for(t=v.createCallback(t,r,3);++e<u;)if(t(n[e],e,n))return e;return-1},v.findKey=function(n,t,r){var e;return t=v.createCallback(t,r,3),wt(n,function(n,r,u){return t(n,r,u)?(e=r,false):void 0}),e},v.findLast=function(n,t,r){var e;return t=v.createCallback(t,r,3),$t(n,function(n,r,u){return t(n,r,u)?(e=n,false):void 0}),e},v.findLastIndex=function(n,t,r){var e=n?n.length:0;
diff --git a/dist/lodash.js b/dist/lodash.js
index b2e71a249..bdcb8df25 100644
--- a/dist/lodash.js
+++ b/dist/lodash.js
@@ -2646,7 +2646,7 @@
      *  per iteration. If a property name or object is provided it will be used
      *  to create a "_.pluck" or "_.where" style callback, respectively.
      * @param {*} [thisArg] The `this` binding of `callback`.
-     * @returns {Array} Returns a new object with values of the results of each `callback` execution.
+     * @returns {Object} Returns a new object with values of the results of each `callback` execution.
      * @example
      *
      * _.mapValues({ 'a': 1, 'b': 2, 'c': 3} , function(num) { return num * 3; });
@@ -3875,7 +3875,7 @@
      * @param {number} [n] The number of elements to sample.
      * @param- {Object} [guard] Allows working with functions like `_.map`
      *  without using their `index` arguments as `n`.
-     * @returns {Array} Returns the random sample(s) of `collection`.
+     * @returns {*} Returns the random sample(s) of `collection`.
      * @example
      *
      * _.sample([1, 2, 3, 4]);
@@ -6506,16 +6506,17 @@
     }
 
     /**
-     * Invokes `interceptor` with the `value` as the first argument and then
-     * returns `value`. The purpose of this method is to "tap into" a method
-     * chain in order to perform operations on intermediate results within
-     * the chain.
+     * This method invokes `interceptor` and returns `value`. The interceptor is
+     * bound to `thisArg` and invoked with one argument; (value). The purpose of
+     * this method is to "tap into" a method chain in order to perform operations
+     * on intermediate results within the chain.
      *
      * @static
      * @memberOf _
      * @category Chaining
      * @param {*} value The value to provide to `interceptor`.
      * @param {Function} interceptor The function to invoke.
+     * @param {*} [thisArg] The `this` binding of `interceptor`.
      * @returns {*} Returns `value`.
      * @example
      *
@@ -6525,8 +6526,8 @@
      *  .value();
      * // => [3, 2, 1]
      */
-    function tap(value, interceptor) {
-      interceptor(value);
+    function tap(value, interceptor, thisArg) {
+      interceptor.call(thisArg, value);
       return value;
     }
 
diff --git a/dist/lodash.min.js b/dist/lodash.min.js
index f07cde8bc..0aa5a8439 100644
--- a/dist/lodash.min.js
+++ b/dist/lodash.min.js
@@ -39,7 +39,7 @@ return t=d.createCallback(t,e,3),bt(n,function(n,e,u){r[e]=t(n,e,u)}),r},d.max=$
 return l(o),l(i),n},d.min=function(n,t,e){var u=1/0,o=u;if(typeof t!="function"&&e&&e[t]===n&&(t=null),null==t&&qe(n)){e=-1;for(var i=n.length;++e<i;){var a=n[e];a<o&&(o=a)}}else t=null==t&&Ot(n)?r:d.createCallback(t,e,3),Tt(n,function(n,e,r){e=t(n,e,r),e<u&&(u=e,o=n)});return o},d.omit=function(n,t,e){var r={};if(typeof t!="function"){var u=[];v(n,function(n,t){u.push(t)});for(var u=et(u,rt(arguments,true,false,1)),o=-1,i=u.length;++o<i;){var a=u[o];r[a]=n[a]}}else t=d.createCallback(t,e,3),v(n,function(n,e,u){t(n,e,u)||(r[e]=n)
 });return r},d.once=function(n){var t,e;if(!kt(n))throw new le;return function(){return t?e:(t=true,e=n.apply(this,arguments),n=null,e)}},d.pairs=function(n){for(var t=-1,e=ze(n),r=e.length,u=ne(r);++t<r;){var o=e[t];u[t]=[o,n[o]]}return u},d.partial=function(n){return lt(n,16,p(arguments,1))},d.partialRight=function(n){return lt(n,32,null,p(arguments,1))},d.pick=function(n,t,e){var r={};if(typeof t!="function")for(var u=-1,o=rt(arguments,true,false,1),i=xt(n)?o.length:0;++u<i;){var a=o[u];a in n&&(r[a]=n[a])
 }else t=d.createCallback(t,e,3),v(n,function(n,e,u){t(n,e,u)&&(r[e]=n)});return r},d.pluck=Je,d.property=Yt,d.pull=function(n){for(var t=arguments,e=0,r=t.length,u=n?n.length:0;++e<r;)for(var o=-1,i=t[e];++o<u;)n[o]===i&&(xe.call(n,o--,1),u--);return n},d.range=function(n,t,e){n=+n||0,e=typeof e=="number"?e:+e||1,null==t&&(t=n,n=0);var r=-1;t=Te(0,ye((t-n)/(e||1)));for(var u=ne(t);++r<t;)u[r]=n,n+=e;return u},d.reject=function(n,t,e){return t=d.createCallback(t,e,3),Rt(n,function(n,e,r){return!t(n,e,r)
-})},d.remove=function(n,t,e){var r=-1,u=n?n.length:0,o=[];for(t=d.createCallback(t,e,3);++r<u;)e=n[r],t(e,r,n)&&(o.push(e),xe.call(n,r--,1),u--);return o},d.rest=Kt,d.shuffle=Wt,d.sortBy=function(n,t,e){var r=-1,o=qe(t),i=n?n.length:0,p=ne(typeof i=="number"?i:0);for(o||(t=d.createCallback(t,e,3)),Tt(n,function(n,e,u){var i=p[++r]=f();o?i.i=Dt(t,function(t){return n[t]}):(i.i=a())[0]=t(n,e,u),i.j=r,i.k=n}),i=p.length,p.sort(u);i--;)n=p[i],p[i]=n.k,o||l(n.i),c(n);return p},d.tap=function(n,t){return t(n),n
+})},d.remove=function(n,t,e){var r=-1,u=n?n.length:0,o=[];for(t=d.createCallback(t,e,3);++r<u;)e=n[r],t(e,r,n)&&(o.push(e),xe.call(n,r--,1),u--);return o},d.rest=Kt,d.shuffle=Wt,d.sortBy=function(n,t,e){var r=-1,o=qe(t),i=n?n.length:0,p=ne(typeof i=="number"?i:0);for(o||(t=d.createCallback(t,e,3)),Tt(n,function(n,e,u){var i=p[++r]=f();o?i.i=Dt(t,function(t){return n[t]}):(i.i=a())[0]=t(n,e,u),i.j=r,i.k=n}),i=p.length,p.sort(u);i--;)n=p[i],p[i]=n.k,o||l(n.i),c(n);return p},d.tap=function(n,t,e){return t.call(e,n),n
 },d.throttle=function(n,t,e){var r=true,u=true;if(!kt(n))throw new le;return false===e?r=false:xt(e)&&(r="leading"in e?e.leading:r,u="trailing"in e?e.trailing:u),V.leading=r,V.maxWait=t,V.trailing=u,Ht(n,t,V)},d.times=function(n,t,e){n=-1<(n=+n)?n:0;var r=-1,u=ne(n);for(t=Z(t,e,1);++r<n;)u[r]=t(r);return u},d.toArray=function(n){return n&&typeof n.length=="number"?p(n):Et(n)},d.transform=function(n,t,e,r){var u=qe(n);if(null==e)if(u)e=[];else{var o=n&&n.constructor;e=Y(o&&o.prototype)}return t&&(t=d.createCallback(t,r,4),(u?Tt:bt)(n,function(n,r,u){return t(e,n,r,u)
 })),e},d.union=function(){return at(rt(arguments,true,true))},d.uniq=Mt,d.values=Et,d.where=Rt,d.without=function(n){return et(n,p(arguments,1))},d.wrap=function(n,t){return lt(t,16,[n])},d.xor=function(){for(var n=-1,t=arguments.length;++n<t;){var e=arguments[n];if(qe(e)||gt(e))var r=r?et(r,e).concat(et(e,r)):e}return r?at(r):[]},d.zip=Vt,d.zipObject=Ut,d.collect=Dt,d.drop=Kt,d.each=Tt,d.eachRight=At,d.extend=yt,d.methods=_t,d.object=Ut,d.select=Rt,d.tail=Kt,d.unique=Mt,d.unzip=Vt,Qt(yt({},d)),d.clone=function(n,t,e,r){return typeof t!="boolean"&&null!=t&&(r=e,e=t,t=false),X(n,t,typeof e=="function"&&Z(e,r,1))
 },d.cloneDeep=function(n,t,e){return X(n,true,typeof t=="function"&&Z(t,e,1))},d.contains=Nt,d.escape=function(n){return null==n?"":fe(n).replace(Me,ct)},d.every=It,d.find=St,d.findIndex=function(n,t,e){var r=-1,u=n?n.length:0;for(t=d.createCallback(t,e,3);++r<u;)if(t(n[r],r,n))return r;return-1},d.findKey=function(n,t,e){var r;return t=d.createCallback(t,e,3),bt(n,function(n,e,u){return t(n,e,u)?(r=e,false):void 0}),r},d.findLast=function(n,t,e){var r;return t=d.createCallback(t,e,3),At(n,function(n,e,u){return t(n,e,u)?(r=n,false):void 0
diff --git a/lodash.js b/lodash.js
index 696f7c994..06a699346 100644
--- a/lodash.js
+++ b/lodash.js
@@ -6842,16 +6842,17 @@
     }
 
     /**
-     * Invokes `interceptor` with the `value` as the first argument and then
-     * returns `value`. The purpose of this method is to "tap into" a method
-     * chain in order to perform operations on intermediate results within
-     * the chain.
+     * This method invokes `interceptor` and returns `value`. The interceptor is
+     * bound to `thisArg` and invoked with one argument; (value). The purpose of
+     * this method is to "tap into" a method chain in order to perform operations
+     * on intermediate results within the chain.
      *
      * @static
      * @memberOf _
      * @category Chaining
      * @param {*} value The value to provide to `interceptor`.
      * @param {Function} interceptor The function to invoke.
+     * @param {*} [thisArg] The `this` binding of `interceptor`.
      * @returns {*} Returns `value`.
      * @example
      *
@@ -6861,8 +6862,8 @@
      *  .value();
      * // => [3, 2, 1]
      */
-    function tap(value, interceptor) {
-      interceptor(value);
+    function tap(value, interceptor, thisArg) {
+      interceptor.call(thisArg, value);
       return value;
     }
 
diff --git a/test/test.js b/test/test.js
index 703697082..d3c76e64c 100644
--- a/test/test.js
+++ b/test/test.js
@@ -6994,14 +6994,15 @@
   (function() {
     test('should intercept and return the given value', 2, function() {
       if (!isNpm) {
-        var intercepted;
+        var intercepted,
+            array = [1, 2, 3];
 
-        var actual = _.tap('a', function(value) {
+        var actual = _.tap(array, function(value) {
           intercepted = value;
         });
 
-        equal(actual, 'a');
-        equal(intercepted, 'a');
+        strictEqual(actual, array);
+        strictEqual(intercepted, array);
       }
       else {
         skipTest(2);
@@ -7011,7 +7012,7 @@
     test('should return intercept unwrapped values and return wrapped values when chaining', 2, function() {
       if (!isNpm) {
         var intercepted,
-            array = [1, 2, 3, 4];
+            array = [1, 2, 3];
 
         var actual = _(array).tap(function(value) {
           intercepted = value;
@@ -7025,6 +7026,21 @@
         skipTest(2);
       }
     });
+
+    test('should support the `thisArg` argument', 1, function() {
+      if (!isNpm) {
+        var array = [1, 2];
+
+        var actual = _(array.slice()).tap(function(value) {
+          value.push(this[0]);
+        }, array);
+
+        deepEqual(actual.value(), [1, 2, 1]);
+      }
+      else {
+        skipTest();
+      }
+    });
   }());
 
   /*--------------------------------------------------------------------------*/