From e5555dd26aa7fcb402d2c08923f22d202e69a1a8 Mon Sep 17 00:00:00 2001 From: John-David Dalton Date: Wed, 13 Jun 2012 15:26:46 -0400 Subject: [PATCH] =?UTF-8?q?Move=20`=5F.tap`=20to=20the=20"Chaining"=20cate?= =?UTF-8?q?gory,=20and=20deprecate=20`=5F(=E2=80=A6).chain`,=20`=5F.isNull?= =?UTF-8?q?`,=20`=5F.isUndefined`,=20`=5F.result`,=20and=20`=5F.size`.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Former-commit-id: 64ee67758b8730fd70cbb28af4230bb336b91214 --- doc/README.md | 60 +++++++++++++++++++-------------------- lodash.js | 77 +++++++++++++++++++++++++++------------------------ 2 files changed, 71 insertions(+), 66 deletions(-) diff --git a/doc/README.md b/doc/README.md index b776a9db6..fe0baaaa0 100644 --- a/doc/README.md +++ b/doc/README.md @@ -147,7 +147,7 @@ The `lodash` function. ### `_.VERSION` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3361 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3366 "View in source") [Ⓣ][1] *(String)*: The semantic version number. @@ -270,15 +270,15 @@ jQuery('#lodash_button').on('click', buttonView.onClick); ### `_.chain(value)` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3313 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3291 "View in source") [Ⓣ][1] -Wraps the value in a `lodash` chainable object. +Wraps the value in a `lodash` wrapper object. #### Arguments 1. `value` *(Mixed)*: The value to wrap. #### Returns -*(Object)*: Returns the `lodash` chainable object. +*(Object)*: Returns the wrapper object. #### Example ~~~ js @@ -432,7 +432,7 @@ jQuery(window).on('resize', lazyLayout); ### `_.defaults(object [, defaults1, defaults2, ...])` # [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2275 "View in source") [Ⓣ][1] -Assigns missing properties in `object` with default values from the defaults objects. As soon as a property is set, additional defaults of the same property will be ignored. +Assigns missing properties on `object` with default values from the defaults objects. Once a property is set, additional defaults of the same property will be ignored. #### Arguments 1. `object` *(Object)*: The object to populate. @@ -533,7 +533,7 @@ _.difference([1, 2, 3, 4, 5], [5, 2, 10]); ### `_.escape(string)` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2999 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2976 "View in source") [Ⓣ][1] Escapes a string for inclusion in HTML, replacing `&`, `<`, `"`, and `'` characters. @@ -888,7 +888,7 @@ _.has({ 'a': 1, 'b': 2, 'c': 3 }, 'b'); ### `_.identity(value)` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3018 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2995 "View in source") [Ⓣ][1] This function returns the first argument passed to it. Note: It is used throughout Lo-Dash as a default callback. @@ -1296,7 +1296,7 @@ _.isNaN(undefined); ### `_.isNull(value)` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2786 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2787 "View in source") [Ⓣ][1] Checks if a `value` is `null`. @@ -1323,7 +1323,7 @@ _.isNull(undefined); ### `_.isNumber(value)` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2803 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2804 "View in source") [Ⓣ][1] Checks if a `value` is a number. @@ -1374,7 +1374,7 @@ _.isObject(1); ### `_.isRegExp(value)` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2820 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2821 "View in source") [Ⓣ][1] Checks if a `value` is a regular expression. @@ -1398,7 +1398,7 @@ _.isRegExp(/moe/); ### `_.isString(value)` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2837 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2838 "View in source") [Ⓣ][1] Checks if a `value` is a string. @@ -1422,7 +1422,7 @@ _.isString('moe'); ### `_.isUndefined(value)` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2854 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2856 "View in source") [Ⓣ][1] Checks if a `value` is `undefined`. @@ -1446,7 +1446,7 @@ _.isUndefined(void 0); ### `_.keys(object)` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2871 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2873 "View in source") [Ⓣ][1] Produces an array of object`'s own enumerable property names. @@ -1638,7 +1638,7 @@ _.min([10, 5, 100, 2, 1000]); ### `_.mixin(object)` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3044 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3021 "View in source") [Ⓣ][1] Adds functions properties of `object` to the `lodash` function and chainable wrapper. @@ -1668,7 +1668,7 @@ _('larry').capitalize(); ### `_.noConflict()` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3075 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3052 "View in source") [Ⓣ][1] Reverts the '_' variable to its previous value and returns a reference to the `lodash` function. @@ -1741,7 +1741,7 @@ hi('moe'); ### `_.pick(object [, prop1, prop2, ...])` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2893 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2895 "View in source") [Ⓣ][1] Creates an object composed of the specified properties. Property names may be specified as individual arguments or as arrays of property names. @@ -1942,7 +1942,7 @@ _.rest([3, 2, 1]); ### `_.result(object, property)` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3106 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3084 "View in source") [Ⓣ][1] Resolves the value of `property` on `object`. If `property` is a function it will be invoked and its result returned, else the property value is returned. If `object` is falsey, then `null` is returned. @@ -2001,7 +2001,7 @@ _.shuffle([1, 2, 3, 4, 5, 6]); ### `_.size(value)` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2931 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2934 "View in source") [Ⓣ][1] Gets the size of `value` by returning `value.length` if `value` is a string or array, or the number of own enumerable properties if `value` is an object. @@ -2130,9 +2130,9 @@ _.sortedIndex(['twenty', 'thirty', 'fourty'], 'thirty-five', function(word) { ### `_.tap(value, interceptor)` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2959 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3318 "View in source") [Ⓣ][1] -Invokes `interceptor` with the `value` as the first argument, and then returns `value`. The primary purpose of this method is to "tap into" a method chain, in order to performoperations on intermediate results within the chain. +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. #### Arguments 1. `value` *(Mixed)*: The value to pass to `callback`. @@ -2160,7 +2160,7 @@ _.chain([1,2,3,200]) ### `_.template(text, data, options)` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3167 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3145 "View in source") [Ⓣ][1] A micro-templating method, similar to John Resig's implementation. Lo-Dash templating handles arbitrary delimiters, preserves whitespace, and correctly escapes quotes within interpolated code. @@ -2244,7 +2244,7 @@ jQuery(window).on('scroll', throttled); ### `_.times(n, callback [, thisArg])` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3256 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3234 "View in source") [Ⓣ][1] Executes the `callback` function `n` times. The `callback` is bound to `thisArg` and invoked with `1` argument; *(index)*. @@ -2354,7 +2354,7 @@ _.uniq([1, 2, 1.5, 3, 2.5], function(num) { return this.floor(num); }, Math); ### `_.uniqueId([prefix])` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3283 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3261 "View in source") [Ⓣ][1] Generates a unique id. If `prefix` is passed, the id will be appended to it. @@ -2378,7 +2378,7 @@ _.uniqueId('contact_'); ### `_.values(object)` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2977 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2954 "View in source") [Ⓣ][1] Produces an array of `object`'s own enumerable property values. @@ -2488,12 +2488,12 @@ _.zip(['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]); ### `_.prototype.chain()` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3331 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3336 "View in source") [Ⓣ][1] -Extracts the value from a wrapped chainable object. +Enables method chaining on the wrapper object. #### Returns -*(Mixed)*: Returns the wrapped object. +*(Mixed)*: Returns the wrapper object. #### Example ~~~ js @@ -2509,12 +2509,12 @@ _([1, 2, 3]).value(); ### `_.prototype.value()` -# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3348 "View in source") [Ⓣ][1] +# [Ⓢ](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3353 "View in source") [Ⓣ][1] -Extracts the value from a wrapped chainable object. +Extracts the wrapped value. #### Returns -*(Mixed)*: Returns the wrapped object. +*(Mixed)*: Returns the wrapped value. #### Example ~~~ js diff --git a/lodash.js b/lodash.js index c531b1185..f06744ae3 100644 --- a/lodash.js +++ b/lodash.js @@ -2256,9 +2256,9 @@ } /** - * Assigns missing properties in `object` with default values from the defaults - * objects. As soon as a property is set, additional defaults of the same - * property will be ignored. + * Assigns missing properties on `object` with default values from the defaults + * objects. Once a property is set, additional defaults of the same property + * will be ignored. * * @static * @memberOf _ @@ -2770,6 +2770,7 @@ /** * Checks if a `value` is `null`. * + * @deprecated * @static * @memberOf _ * @category Objects @@ -2841,6 +2842,7 @@ /** * Checks if a `value` is `undefined`. * + * @deprecated * @static * @memberOf _ * @category Objects @@ -2911,6 +2913,7 @@ * Gets the size of `value` by returning `value.length` if `value` is a string * or array, or the number of own enumerable properties if `value` is an object. * + * @deprecated * @static * @memberOf _ * @category Objects @@ -2935,32 +2938,6 @@ : keys(value).length; } - /** - * Invokes `interceptor` with the `value` as the first argument, and then returns - * `value`. The primary purpose of this method is to "tap into" a method chain, - * in order to performoperations on intermediate results within the chain. - * - * @static - * @memberOf _ - * @category Objects - * @param {Mixed} value The value to pass to `callback`. - * @param {Function} interceptor The function to invoke. - * @returns {Mixed} Returns `value`. - * @example - * - * _.chain([1,2,3,200]) - * .filter(function(num) { return num % 2 == 0; }) - * .tap(alert) - * .map(function(num) { return num * num }) - * .value(); - * // => // [2, 200] (alerted) - * // => [4, 40000] - */ - function tap(value, interceptor) { - interceptor(value); - return value; - } - /** * Produces an array of `object`'s own enumerable property values. * @@ -3082,6 +3059,7 @@ * it will be invoked and its result returned, else the property value is * returned. If `object` is falsey, then `null` is returned. * + * @deprecated * @static * @memberOf _ * @category Utilities @@ -3288,13 +3266,13 @@ /*--------------------------------------------------------------------------*/ /** - * Wraps the value in a `lodash` chainable object. + * Wraps the value in a `lodash` wrapper object. * * @static * @memberOf _ * @category Chaining * @param {Mixed} value The value to wrap. - * @returns {Object} Returns the `lodash` chainable object. + * @returns {Object} Returns the wrapper object. * @example * * var stooges = [ @@ -3317,12 +3295,39 @@ } /** - * Extracts the value from a wrapped chainable object. + * 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. * - * @name chain + * @static * @memberOf _ * @category Chaining - * @returns {Mixed} Returns the wrapped object. + * @param {Mixed} value The value to pass to `callback`. + * @param {Function} interceptor The function to invoke. + * @returns {Mixed} Returns `value`. + * @example + * + * _.chain([1,2,3,200]) + * .filter(function(num) { return num % 2 == 0; }) + * .tap(alert) + * .map(function(num) { return num * num }) + * .value(); + * // => // [2, 200] (alerted) + * // => [4, 40000] + */ + function tap(value, interceptor) { + interceptor(value); + return value; + } + + /** + * Enables method chaining on the wrapper object. + * + * @name chain + * @deprecated + * @memberOf _ + * @category Chaining + * @returns {Mixed} Returns the wrapper object. * @example * * _([1, 2, 3]).value(); @@ -3334,12 +3339,12 @@ } /** - * Extracts the value from a wrapped chainable object. + * Extracts the wrapped value. * * @name value * @memberOf _ * @category Chaining - * @returns {Mixed} Returns the wrapped object. + * @returns {Mixed} Returns the wrapped value. * @example * * _([1, 2, 3]).value();