underscore.js

underscore.js

Underscore.js 1.4.4
http://underscorejs.org
(c) 2009-2013 Jeremy Ashkenas, DocumentCloud Inc.
Underscore may be freely distributed under the MIT license.

(function() {

¶

基础设定
¶

创建一个root对象，保存对全局对象的引用。在浏览器环境中即为window，在server环境中为global
```
  var root = this;
```
¶

保存原全局对象中的_变量
```
  var previousUnderscore = root._;
```
¶

创建一个特殊的对象，这个对象用于控制在循环中跳出。见each函数
```
  var breaker = {};
```
¶

定义三个变量，分别存储Array、Object以及Function的prototype属性。在压缩时（非gzipped时）可以节省字节
```
  var ArrayProto = Array.prototype, ObjProto = Object.prototype, FuncProto = Function.prototype;
```

定义本地变量，以快速访问核心类的原型方法

 var push             = ArrayProto.push,
      slice            = ArrayProto.slice,
      concat           = ArrayProto.concat,
      toString         = ObjProto.toString,
      hasOwnProperty   = ObjProto.hasOwnProperty;

定义将要实现的 ECMAScript 5 原生方法

  var
    nativeForEach      = ArrayProto.forEach,
    nativeMap          = ArrayProto.map,
    nativeReduce       = ArrayProto.reduce,
    nativeReduceRight  = ArrayProto.reduceRight,
    nativeFilter       = ArrayProto.filter,
    nativeEvery        = ArrayProto.every,
    nativeSome         = ArrayProto.some,
    nativeIndexOf      = ArrayProto.indexOf,
    nativeLastIndexOf  = ArrayProto.lastIndexOf,
    nativeIsArray      = Array.isArray,
    nativeKeys         = Object.keys,
    nativeBind         = FuncProto.bind;

创建Underscore对象的引用，将在后续的代码中调用

  var _ = function(obj) {
    if (obj instanceof _) return obj;
    if (!(this instanceof _)) return new _(obj);
    this._wrapped = obj;
  };

¶

输出Underscore对象。兼容Node.js中旧的require() API。如果是在浏览器环境中，将以字符串标识符的形式输出_[?]，作为全局对象的属性。 for Closure Compiler "advanced" mode.[?]。
```
  if (typeof exports !== 'undefined') {
    if (typeof module !== 'undefined' && module.exports) {
      exports = module.exports = _;
    }
    exports._ = _;
  } else {
    root._ = _;
  }
```
¶

当前版本
```
  _.VERSION = '1.4.4';
```
¶

集合函数
¶

集合函数中的基础函数：each函数，亦称为forEach。使用内建的forEach、数组以及原始对象来处理待迭代对象。当ECMAScript 5原生的forEach函数可用时，将使用这个原生函数来处理。 [注]each接受三个参数：待处理对象，迭代函数，[可选] 迭代函数运行的上下文。
```
  var each = _.each = _.forEach = function(obj, iterator, context) {
    if (obj == null) return;
```

[注] 使用原生的forEach方法

    if (nativeForEach && obj.forEach === nativeForEach) {
      obj.forEach(iterator, context);

[注] 待处理对象为数组。通过obj.length === +obj.length判断

    } else if (obj.length === +obj.length) {
      for (var i = 0, l = obj.length; i < l; i++) {

[注] 通过前面定义的break对象来跳出循环

        if (iterator.call(context, obj[i], i, obj) === breaker) return;
      }

[注] 待处理对象为object，循环obj的own properties

    } else {
      for (var key in obj) {
        if (_.has(obj, key)) {
          if (iterator.call(context, obj[key], key, obj) === breaker) return;
        }
      }
    }
  };

map函数：在对象的每一个元素上执行函数，并返回结果数组。如果ECMAScript 5 原生map函数可用，则使用原生map函数。此函数亦称为collect。

  _.map = _.collect = function(obj, iterator, context) {
    var results = [];
    if (obj == null) return results;
    if (nativeMap && obj.map === nativeMap) return obj.map(iterator, context);

[注] 调用each函数

    each(obj, function(value, index, list) {

[注] 数组添加元素小技巧，与results.push()执行结果一样

      results[results.length] = iterator.call(context, value, index, list);
    });
    return results;
  };

  var reduceError = 'Reduce of empty array with no initial value';

Reduce函数：迭代处理对象的成员并返还一个单一的值。若 ECMAScript 5 原生支持reduce，将调用原生的reduce函数。此函数亦成为inject或者foldl。

  _.reduce = _.foldl = _.inject = function(obj, iterator, memo, context) {
    var initial = arguments.length > 2;
    if (obj == null) obj = [];
    if (nativeReduce && obj.reduce === nativeReduce) {
      if (context) iterator = _.bind(iterator, context);
      return initial ? obj.reduce(iterator, memo) : obj.reduce(iterator);
    }
    each(obj, function(value, index, list) {
      if (!initial) {
        memo = value;
        initial = true;
      } else {
        memo = iterator.call(context, memo, value, index, list);
      }
    });
    if (!initial) throw new TypeError(reduceError);
    return memo;
  };

reduce函数的变形版：从对象的最后一个成员开始向前迭代。若ECMAScript 5的reduceRight可用，将调用reduceRight函数。此函数也称为flodr`。

  _.reduceRight = _.foldr = function(obj, iterator, memo, context) {
    var initial = arguments.length > 2;
    if (obj == null) obj = [];
    if (nativeReduceRight && obj.reduceRight === nativeReduceRight) {
      if (context) iterator = _.bind(iterator, context);
      return initial ? obj.reduceRight(iterator, memo) : obj.reduceRight(iterator);
    }
    var length = obj.length;
    if (length !== +length) {
      var keys = _.keys(obj);
      length = keys.length;
    }
    each(obj, function(value, index, list) {
      index = keys ? keys[--length] : --length;
      if (!initial) {
        memo = obj[index];
        initial = true;
      } else {
        memo = iterator.call(context, memo, obj[index], index, list);
      }
    });
    if (!initial) throw new TypeError(reduceError);
    return memo;
  };

find函数：返回可迭代对象中第一个使得函数返回true的元素。此函数亦称为detect。

  _.find = _.detect = function(obj, iterator, context) {
    var result;
    any(obj, function(value, index, list) {
      if (iterator.call(context, value, index, list)) {
        result = value;
        return true;
      }
    });
    return result;
  };

filter函数：返回待迭代对象中可使函数返回true的元素。若ECMAScript的filter可用，将调用filter函数。此函数亦称为select。

  _.filter = _.select = function(obj, iterator, context) {
    var results = [];
    if (obj == null) return results;
    if (nativeFilter && obj.filter === nativeFilter) return obj.filter(iterator, context);
    each(obj, function(value, index, list) {
      if (iterator.call(context, value, index, list)) results[results.length] = value;
    });
    return results;
  };

reject函数：返回待迭代对象中可使函数返回false的元素。 [注] 与filter相反。

  _.reject = function(obj, iterator, context) {
    return _.filter(obj, function(value, index, list) {
      return !iterator.call(context, value, index, list);
    }, context);
  };

every函数：判断是否待迭代对象的所有元素都可使函数返回true。若ECMAScript 5的every可用，将调用every函数。此函数亦称为all。

  _.every = _.all = function(obj, iterator, context) {
    iterator || (iterator = _.identity);
    var result = true;
    if (obj == null) return result;
    if (nativeEvery && obj.every === nativeEvery) return obj.every(iterator, context);
    each(obj, function(value, index, list) {
      if (!(result = result && iterator.call(context, value, index, list))) return breaker;
    });
    return !!result;
  };

some函数：判断待迭代对象中是否有元素可使函数返回true。若ECMAScript 5的some可用，将调用some函数。此函数亦称为any。

  var any = _.some = _.any = function(obj, iterator, context) {
    iterator || (iterator = _.identity);
    var result = false;
    if (obj == null) return result;
    if (nativeSome && obj.some === nativeSome) return obj.some(iterator, context);
    each(obj, function(value, index, list) {
      if (result || (result = iterator.call(context, value, index, list))) return breaker;
    });
    return !!result;
  };

判断对象或数组中是否包含给定的值。此函数亦称为include。

  _.contains = _.include = function(obj, target) {
    if (obj == null) return false;

[注]调用ECMAScript的indexOf函数。

    if (nativeIndexOf && obj.indexOf === nativeIndexOf) return obj.indexOf(target) != -1;
    return any(obj, function(value) {
      return value === target;
    });
  };

¶

在集合的每个元素上调用方法，方法可带参数。
```
  _.invoke = function(obj, method) {
```

获取参数

    var args = slice.call(arguments, 2);
    var isFunc = _.isFunction(method);
    return _.map(obj, function(value) {

¶

若传入的method类型不是函数，将尝试调用集合元素对象的method方法
```
      return (isFunc ? method : value[method]).apply(value, args);
    });
  };
```

快捷方法，对使用map获取集合元素属性值场景的封装。

  _.pluck = function(obj, key) {
    return _.map(obj, function(value){ return value[key]; });
  };

Convenience version of a common use case of filter: selecting only objects containing specific key:value pairs.

  _.where = function(obj, attrs, first) {
    if (_.isEmpty(attrs)) return first ? null : [];
    return _[first ? 'find' : 'filter'](obj, function(value) {
      for (var key in attrs) {
        if (attrs[key] !== value[key]) return false;
      }
      return true;
    });
  };

¶

Convenience version of a common use case of find: getting the first object containing specific key:value pairs.
```
  _.findWhere = function(obj, attrs) {
    return _.where(obj, attrs, true);
  };
```

Return the maximum element or (element-based computation). Can't optimize arrays of integers longer than 65,535 elements. See: https://bugs.webkit.org/show_bug.cgi?id=80797

  _.max = function(obj, iterator, context) {
    if (!iterator && _.isArray(obj) && obj[0] === +obj[0] && obj.length < 65535) {
      return Math.max.apply(Math, obj);
    }
    if (!iterator && _.isEmpty(obj)) return -Infinity;
    var result = {computed : -Infinity, value: -Infinity};
    each(obj, function(value, index, list) {
      var computed = iterator ? iterator.call(context, value, index, list) : value;
      computed >= result.computed && (result = {value : value, computed : computed});
    });
    return result.value;
  };

Return the minimum element (or element-based computation).

  _.min = function(obj, iterator, context) {
    if (!iterator && _.isArray(obj) && obj[0] === +obj[0] && obj.length < 65535) {
      return Math.min.apply(Math, obj);
    }
    if (!iterator && _.isEmpty(obj)) return Infinity;
    var result = {computed : Infinity, value: Infinity};
    each(obj, function(value, index, list) {
      var computed = iterator ? iterator.call(context, value, index, list) : value;
      computed < result.computed && (result = {value : value, computed : computed});
    });
    return result.value;
  };

数组随机排序

  _.shuffle = function(obj) {
    var rand;
    var index = 0;
    var shuffled = [];
    each(obj, function(value) {
      rand = _.random(index++);
      shuffled[index - 1] = shuffled[rand];
      shuffled[rand] = value;
    });
    return shuffled;
  };

An internal function to generate lookup iterators.

  var lookupIterator = function(value) {
    return _.isFunction(value) ? value : function(obj){ return obj[value]; };
  };

Sort the object's values by a criterion produced by an iterator.

  _.sortBy = function(obj, value, context) {
    var iterator = lookupIterator(value);
    return _.pluck(_.map(obj, function(value, index, list) {
      return {
        value : value,
        index : index,
        criteria : iterator.call(context, value, index, list)
      };
    }).sort(function(left, right) {
      var a = left.criteria;
      var b = right.criteria;
      if (a !== b) {
        if (a > b || a === void 0) return 1;
        if (a < b || b === void 0) return -1;
      }
      return left.index < right.index ? -1 : 1;
    }), 'value');
  };

An internal function used for aggregate "group by" operations.

  var group = function(obj, value, context, behavior) {
    var result = {};
    var iterator = lookupIterator(value == null ? _.identity : value);
    each(obj, function(value, index) {
      var key = iterator.call(context, value, index, obj);
      behavior(result, key, value);
    });
    return result;
  };

Groups the object's values by a criterion. Pass either a string attribute to group by, or a function that returns the criterion.

  _.groupBy = function(obj, value, context) {
    return group(obj, value, context, function(result, key, value) {
      (_.has(result, key) ? result[key] : (result[key] = [])).push(value);
    });
  };

Counts instances of an object that group by a certain criterion. Pass either a string attribute to count by, or a function that returns the criterion.

  _.countBy = function(obj, value, context) {
    return group(obj, value, context, function(result, key) {
      if (!_.has(result, key)) result[key] = 0;
      result[key]++;
    });
  };

Use a comparator function to figure out the smallest index at which an object should be inserted so as to maintain order. Uses binary search.

  _.sortedIndex = function(array, obj, iterator, context) {
    iterator = iterator == null ? _.identity : lookupIterator(iterator);
    var value = iterator.call(context, obj);
    var low = 0, high = array.length;
    while (low < high) {
      var mid = (low + high) >>> 1;
      iterator.call(context, array[mid]) < value ? low = mid + 1 : high = mid;
    }
    return low;
  };

将obj（可能是null、数组、字符串、对象）转换成数组。

  _.toArray = function(obj) {
    if (!obj) return [];
    if (_.isArray(obj)) return slice.call(obj);
    if (obj.length === +obj.length) return _.map(obj, _.identity);
    return _.values(obj);
  };

返回对象的元素个数。

  _.size = function(obj) {
    if (obj == null) return 0;
    return (obj.length === +obj.length) ? obj.length : _.keys(obj).length;
  };

¶

数组相关函数
¶

first函数：获取数组的第一个元素。若提供n参数，将返回数组中从0到n-1的元素。 guard参数标志是否可与_.map函数共同使用。此函数亦称为head或者take
```
  _.first = _.head = _.take = function(array, n, guard) {
    if (array == null) return void 0;
    return (n != null) && !guard ? slice.call(array, 0, n) : array[0];
  };
```
¶

initial函数：返回数组中除最后一个以外的所有元素。特别适用于arguments对象。若传递n变量，将返回最后N个意外的所有元素。 guard参数标志是否可与._map共用
```
  _.initial = function(array, n, guard) {
    return slice.call(array, 0, array.length - ((n == null) || guard ? 1 : n));
  };
```

last函数：返回数组的最后一个元素。若提供n变量，将返回最后的n个元素。 guard参数标志此函数是否可与_.map共用。

  _.last = function(array, n, guard) {
    if (array == null) return void 0;
    if ((n != null) && !guard) {
      return slice.call(array, Math.max(array.length - n, 0));
    } else {
      return array[array.length - 1];
    }
  };

¶

rest函数：返回除数组中第一个元素以外的所有元素。特别适用于arguments对象。若提供n变量，将返回除数组中前n个以外的元素。 guard参数标志此函数是否可与_.map共用。
```
  _.rest = _.tail = _.drop = function(array, n, guard) {
    return slice.call(array, (n == null) || guard ? 1 : n);
  };
```

compact函数：过滤掉所有值等于false的元素

  _.compact = function(array) {
    return _.filter(array, _.identity);
  };

内部函数flatten，将数组（可能是多维）转化成一维数组

  var flatten = function(input, shallow, output) {
        each(input, function(value) {
            if (_.isArray(value)) {
                shallow ? push.apply(output, value) : flatten(value, shallow, output);
            } else {
                output.push(value);
            }
        });
        return output;
    };

flatten函数：将数组（可能包含数组）转化成一维数组

  _.flatten = function(array, shallow) {
    return flatten(array, shallow, []);
  };

without函数：返回未包含指定值的数组。

  _.without = function(array) {
    return _.difference(array, slice.call(arguments, 1));
  };

Produce a duplicate-free version of the array. If the array has already been sorted, you have the option of using a faster algorithm. Aliased as unique.

  _.uniq = _.unique = function(array, isSorted, iterator, context) {
    if (_.isFunction(isSorted)) {
      context = iterator;
      iterator = isSorted;
      isSorted = false;
    }
    var initial = iterator ? _.map(array, iterator, context) : array;
    var results = [];
    var seen = [];
    each(initial, function(value, index) {
      if (isSorted ? (!index || seen[seen.length - 1] !== value) : !_.contains(seen, value)) {
        seen.push(value);
        results.push(array[index]);
      }
    });
    return results;
  };

¶

Produce an array that contains the union: each distinct element from all of the passed-in arrays.
```
  _.union = function() {
    return _.uniq(concat.apply(ArrayProto, arguments));
  };
```

Produce an array that contains every item shared between all the passed-in arrays.

  _.intersection = function(array) {
    var rest = slice.call(arguments, 1);
    return _.filter(_.uniq(array), function(item) {
      return _.every(rest, function(other) {
        return _.indexOf(other, item) >= 0;
      });
    });
  };

Take the difference between one array and a number of other arrays. Only the elements present in just the first array will remain.

  _.difference = function(array) {
    var rest = concat.apply(ArrayProto, slice.call(arguments, 1));
    return _.filter(array, function(value){ return !_.contains(rest, value); });
  };

将多个数组合并成一个数字，各数组中索引值相同的元素将合并在一起。例如：_.zip([1, 2, 3], ["a", "b", "c"]) => [[1, "a"], [2, "b"], [3, "c"]]。对于长度不同是数组，会出现undefined的元素。

  _.zip = function() {
    var args = slice.call(arguments);
    var length = _.max(_.pluck(args, 'length'));
    var results = new Array(length);
    for (var i = 0; i < length; i++) {
      results[i] = _.pluck(args, "" + i);
    }
    return results;
  };

Converts lists into objects. Pass either a single array of [key, value] pairs, or two parallel arrays of the same length -- one of keys, and one of the corresponding values.

  _.object = function(list, values) {
    if (list == null) return {};
    var result = {};
    for (var i = 0, l = list.length; i < l; i++) {
      if (values) {
        result[list[i]] = values[i];
      } else {
        result[list[i][0]] = list[i][1];
      }
    }
    return result;
  };

获取元素在数组中第一次出现的索引值。若ECMAScript 5原生的indexOf可用，将调用原生方法。 isSorted表示对已排好序的大数组使用二分查找

  _.indexOf = function(array, item, isSorted) {
    if (array == null) return -1;
    var i = 0, l = array.length;
    if (isSorted) {
      if (typeof isSorted == 'number') {
        i = (isSorted < 0 ? Math.max(0, l + isSorted) : isSorted);
      } else {
        i = _.sortedIndex(array, item);
        return array[i] === item ? i : -1;
      }
    }
    if (nativeIndexOf && array.indexOf === nativeIndexOf) return array.indexOf(item, isSorted);
    for (; i < l; i++) if (array[i] === item) return i;
    return -1;
  };

搜索元素在数组中最后一次出现的索引值。若ECMAScript 5原生的lastIndexOf可用，将调用原生方法。

  _.lastIndexOf = function(array, item, from) {
    if (array == null) return -1;
    var hasIndex = from != null;
    if (nativeLastIndexOf && array.lastIndexOf === nativeLastIndexOf) {
      return hasIndex ? array.lastIndexOf(item, from) : array.lastIndexOf(item);
    }
    var i = (hasIndex ? from : array.length);
    while (i--) if (array[i] === item) return i;
    return -1;
  };

¶

创建一个包含一等差数列的整型数组。Python range()的一个等价实现。见： the Python documentation.
```
  _.range = function(start, stop, step) {
```
¶

若参数个数少于或者等于1时，起步值start设置为0 参数个数一个：终止值为此参数start 参数个数为0：终止值为0
```
    if (arguments.length <= 1) {
      stop = start || 0;
      start = 0;
    }
```

步长默认为1

    step = arguments[2] || 1;

    var len = Math.max(Math.ceil((stop - start) / step), 0);
    var idx = 0;
    var range = new Array(len);

    while(idx < len) {
      range[idx++] = start;
      start += step;
    }

    return range;
  };

¶

Function (ahem) Functions
¶

Reusable constructor function for prototype setting.
```
  var ctor = function(){};
```

bing函数：将函数绑定到指定对象上。若ECMAScript 5的Function.bind可用，将调用Function.bind。

  _.bind = function(func, context) {
    var args, bound;
    if (func.bind === nativeBind && nativeBind) return nativeBind.apply(func, slice.call(arguments, 1));
    if (!_.isFunction(func)) throw new TypeError;
    args = slice.call(arguments, 2);
    return bound = function() {
      if (!(this instanceof bound)) return func.apply(context, args.concat(slice.call(arguments)));
      ctor.prototype = func.prototype;
      var self = new ctor;
      ctor.prototype = null;
      var result = func.apply(self, args.concat(slice.call(arguments)));
      if (Object(result) === result) return result;
      return self;
    };
  };

Partially apply a function by creating a version that has had some of its arguments pre-filled, without changing its dynamic this context.

  _.partial = function(func) {
    var args = slice.call(arguments, 1);
    return function() {
      return func.apply(this, args.concat(slice.call(arguments)));
    };
  };

Bind all of an object's methods to that object. Useful for ensuring that all callbacks defined on an object belong to it.

  _.bindAll = function(obj) {
    var funcs = slice.call(arguments, 1);
    if (funcs.length === 0) throw new Error("bindAll must be passed function names");
    each(funcs, function(f) { obj[f] = _.bind(obj[f], obj); });
    return obj;
  };

Memoize an expensive function by storing its results.

  _.memoize = function(func, hasher) {
    var memo = {};
    hasher || (hasher = _.identity);
    return function() {
      var key = hasher.apply(this, arguments);
      return _.has(memo, key) ? memo[key] : (memo[key] = func.apply(this, arguments));
    };
  };

delay函数：延迟wait毫秒之后执行func。

  _.delay = function(func, wait) {
    var args = slice.call(arguments, 2);
    return setTimeout(function(){ return func.apply(null, args); }, wait);
  };

Defers a function, scheduling it to run after the current call stack has cleared.

  _.defer = function(func) {
    return _.delay.apply(_, [func, 1].concat(slice.call(arguments, 1)));
  };

Returns a function, that, when invoked, will only be triggered at most once during a given window of time.

  _.throttle = function(func, wait, immediate) {
    var context, args, timeout, result;
    var previous = 0;
    var later = function() {
      previous = new Date;
      timeout = null;
      result = func.apply(context, args);
    };
    return function() {
      var now = new Date;
      if (!previous && immediate === false) previous = now;
      var remaining = wait - (now - previous);
      context = this;
      args = arguments;
      if (remaining <= 0) {
        clearTimeout(timeout);
        timeout = null;
        previous = now;
        result = func.apply(context, args);
      } else if (!timeout) {
        timeout = setTimeout(later, remaining);
      }
      return result;
    };
  };

Returns a function, that, as long as it continues to be invoked, will not be triggered. The function will be called after it stops being called for N milliseconds. If immediate is passed, trigger the function on the leading edge, instead of the trailing.

  _.debounce = function(func, wait, immediate) {
    var timeout, result;
    return function() {
      var context = this, args = arguments;
      var later = function() {
        timeout = null;
        if (!immediate) result = func.apply(context, args);
      };
      var callNow = immediate && !timeout;
      clearTimeout(timeout);
      timeout = setTimeout(later, wait);
      if (callNow) result = func.apply(context, args);
      return result;
    };
  };

Returns a function that will be executed at most one time, no matter how often you call it. Useful for lazy initialization.

  _.once = function(func) {
    var ran = false, memo;
    return function() {
      if (ran) return memo;
      ran = true;
      memo = func.apply(this, arguments);
      func = null;
      return memo;
    };
  };

Returns the first function passed as an argument to the second, allowing you to adjust arguments, run code before and after, and conditionally execute the original function.

  _.wrap = function(func, wrapper) {
    return function() {
      var args = [func];
      push.apply(args, arguments);
      return wrapper.apply(this, args);
    };
  };

Returns a function that is the composition of a list of functions, each consuming the return value of the function that follows.

  _.compose = function() {
    var funcs = arguments;
    return function() {
      var args = arguments;
      for (var i = funcs.length - 1; i >= 0; i--) {
        args = [funcs[i].apply(this, args)];
      }
      return args[0];
    };
  };

Returns a function that will only be executed after being called N times.

  _.after = function(times, func) {
    if (times <= 0) return func();
    return function() {
      if (--times < 1) {
        return func.apply(this, arguments);
      }
    };
  };

¶

对象相关的函数

keys函数：返回对象所有的键。若ECMAScript 5的Object.keys可用，将调用Object.keys.

  _.keys = nativeKeys || function(obj) {
    if (obj !== Object(obj)) throw new TypeError('Invalid object');
    var keys = [];
    for (var key in obj) if (_.has(obj, key)) keys[keys.length] = key;
    return keys;
  };

values函数：返回对象所有键对应的值

  _.values = function(obj) {
    var values = [];
    for (var key in obj) if (_.has(obj, key)) values.push(obj[key]);
    return values;
  };

paris函数：返回包含对象转换成[key, value]的数组

  _.pairs = function(obj) {
    var pairs = [];
    for (var key in obj) if (_.has(obj, key)) pairs.push([key, obj[key]]);
    return pairs;
  };

转换对象的键值对。

  _.invert = function(obj) {
    var result = {};
    for (var key in obj) if (_.has(obj, key)) result[obj[key]] = key;
    return result;
  };

functions函数：返回对象的所有方法（已排序）此函数亦称为methods

  _.functions = _.methods = function(obj) {
    var names = [];
    for (var key in obj) {
      if (_.isFunction(obj[key])) names.push(key);
    }
    return names.sort();
  };

extend函数：扩展给定的对象。可接收多个参数。

  _.extend = function(obj) {
    each(slice.call(arguments, 1), function(source) {
      if (source) {
        for (var prop in source) {
          obj[prop] = source[prop];
        }
      }
    });
    return obj;
  };

pick函数：返回一个新对象，包含参数所给定键的键值对

  _.pick = function(obj) {
    var copy = {};
    var keys = concat.apply(ArrayProto, slice.call(arguments, 1));
    each(keys, function(key) {
      if (key in obj) copy[key] = obj[key];
    });
    return copy;
  };

omit函数：返回一个新对象，包含参数指定键以外的键值对

  _.omit = function(obj) {
    var copy = {};
    var keys = concat.apply(ArrayProto, slice.call(arguments, 1));
    for (var key in obj) {
      if (!_.contains(keys, key)) copy[key] = obj[key];
    }
    return copy;
  };

defaults函数：给指定对象填充默认值。

  _.defaults = function(obj) {
    each(slice.call(arguments, 1), function(source) {
      if (source) {
        for (var prop in source) {
          if (obj[prop] === void 0) obj[prop] = source[prop];
        }
      }
    });
    return obj;
  };

浅复制 obj。obj若非对象，返回obj。

  _.clone = function(obj) {
    if (!_.isObject(obj)) return obj;
    return _.isArray(obj) ? obj.slice() : _.extend({}, obj);
  };

¶

Invokes interceptor with the obj, and then returns obj. The primary purpose of this method is to "tap into" a method chain, in order to perform operations on intermediate results within the chain.
```
  _.tap = function(obj, interceptor) {
    interceptor(obj);
    return obj;
  };
```
¶

Internal recursive comparison function for isEqual.
```
  var eq = function(a, b, aStack, bStack) {
```
¶

Identical objects are equal. 0 === -0, but they aren't identical. See the Harmony egal proposal: http://wiki.ecmascript.org/doku.php?id=harmony:egal.
```
    if (a === b) return a !== 0 || 1 / a == 1 / b;
```
¶

A strict comparison is necessary because null == undefined.
```
    if (a == null || b == null) return a === b;
```

Unwrap any wrapped objects.

    if (a instanceof _) a = a._wrapped;
    if (b instanceof _) b = b._wrapped;

Compare [[Class]] names.

    var className = toString.call(a);
    if (className != toString.call(b)) return false;
    switch (className) {

¶

Strings, numbers, dates, and booleans are compared by value.
```
      case '[object String]':
```
¶

Primitives and their corresponding object wrappers are equivalent; thus, "5" is equivalent to new String("5").
```
        return a == String(b);
      case '[object Number]':
```

NaNs are equivalent, but non-reflexive. An egal comparison is performed for other numeric values.

        return a != +a ? b != +b : (a == 0 ? 1 / a == 1 / b : a == +b);
      case '[object Date]':
      case '[object Boolean]':

¶

Coerce dates and booleans to numeric primitive values. Dates are compared by their millisecond representations. Note that invalid dates with millisecond representations of NaN are not equivalent.
```
        return +a == +b;
```

RegExps are compared by their source patterns and flags.

      case '[object RegExp]':
        return a.source == b.source &&
               a.global == b.global &&
               a.multiline == b.multiline &&
               a.ignoreCase == b.ignoreCase;
    }
    if (typeof a != 'object' || typeof b != 'object') return false;

¶

Assume equality for cyclic structures. The algorithm for detecting cyclic structures is adapted from ES 5.1 section 15.12.3, abstract operation JO.
```
    var length = aStack.length;
    while (length--) {
```
¶

Linear search. Performance is inversely proportional to the number of unique nested structures.
```
      if (aStack[length] == a) return bStack[length] == b;
    }
```

Add the first object to the stack of traversed objects.

    aStack.push(a);
    bStack.push(b);
    var size = 0, result = true;

Recursively compare objects and arrays.

    if (className == '[object Array]') {

Compare array lengths to determine if a deep comparison is necessary.

      size = a.length;
      result = size == b.length;
      if (result) {

Deep compare the contents, ignoring non-numeric properties.

        while (size--) {
          if (!(result = eq(a[size], b[size], aStack, bStack))) break;
        }
      }
    } else {

Objects with different constructors are not equivalent, but Objects from different frames are.

      var aCtor = a.constructor, bCtor = b.constructor;
      if (aCtor !== bCtor && !(_.isFunction(aCtor) && (aCtor instanceof aCtor) &&
                               _.isFunction(bCtor) && (bCtor instanceof bCtor))) {
        return false;
      }

Deep compare objects.

      for (var key in a) {
        if (_.has(a, key)) {

¶

Count the expected number of properties.
```
          size++;
```

Deep compare each member.

          if (!(result = _.has(b, key) && eq(a[key], b[key], aStack, bStack))) break;
        }
      }

Ensure that both objects contain the same number of properties.

      if (result) {
        for (key in b) {
          if (_.has(b, key) && !(size--)) break;
        }
        result = !size;
      }
    }

Remove the first object from the stack of traversed objects.

    aStack.pop();
    bStack.pop();
    return result;
  };

Perform a deep comparison to check if two objects are equal.

  _.isEqual = function(a, b) {
    return eq(a, b, [], []);
  };

isEmpty函数：判断给定的数组、字符串或者对象是否为空。一个空的对象意味这个对象未包含任何实例属性(own-properties)。

  _.isEmpty = function(obj) {
    if (obj == null) return true;
    if (_.isArray(obj) || _.isString(obj)) return obj.length === 0;
    for (var key in obj) if (_.has(obj, key)) return false;
    return true;
  };

isElement函数：判断给定的值是否是一个DOM元素。

  _.isElement = function(obj) {
    return !!(obj && obj.nodeType === 1);
  };

¶

isArray函数：判断给定的值是否是一个数组。若ECMAScript 5的Array.isArray可用，将调用Array.isArray。
```
  _.isArray = nativeIsArray || function(obj) {
    return toString.call(obj) == '[object Array]';
  };
```

isObject函数：判断给定的值是否为对象。

  _.isObject = function(obj) {
    return obj === Object(obj);
  };

类型判断函数： isArguments, isFunction, isString, isNumber, isDate, isRegExp。

  each(['Arguments', 'Function', 'String', 'Number', 'Date', 'RegExp'], function(name) {
    _['is' + name] = function(obj) {
      return toString.call(obj) == '[object ' + name + ']';
    };
  });

Define a fallback version of the method in browsers (ahem, IE), where there isn't any inspectable "Arguments" type.

  if (!_.isArguments(arguments)) {
    _.isArguments = function(obj) {
      return !!(obj && _.has(obj, 'callee'));
    };
  }

Optimize isFunction if appropriate.

  if (typeof (/./) !== 'function') {
    _.isFunction = function(obj) {
      return typeof obj === 'function';
    };
  }

¶

判断给定的变量是否有限数字，非NaN，Infinity，-Infinity。 [注] 由于原声的isFinite("")会返回true，所以这里通过&&判断obj是否是有效的数字。
```
  _.isFinite = function(obj) {
    return isFinite(obj) && !isNaN(parseFloat(obj));
  };
```

判断给定的变量是否是NaN。NaN是唯一个不等于其自身的数值。

  _.isNaN = function(obj) {
    return _.isNumber(obj) && obj != +obj;
  };

判断给定的变量是否是布尔类型值。

  _.isBoolean = function(obj) {
    return obj === true || obj === false || toString.call(obj) == '[object Boolean]';
  };

判断给定的变量是否等于null。

  _.isNull = function(obj) {
    return obj === null;
  };

¶

判断给定的变量是否等于undefined。[注] 与void操作符的返回值比对。
```
  _.isUndefined = function(obj) {
    return obj === void 0;
  };
```
¶

判断key是否是obj的实例属性（也就是说，key非obj原型链上的属性）。
```
  _.has = function(obj, key) {
    return hasOwnProperty.call(obj, key);
  };
```
¶

工具函数
¶

以noConfilct模式运行Underscore.js，_变量将存放之间定义的对象。函数执行返回Underscore对象的引用
```
  _.noConflict = function() {
    root._ = previousUnderscore;
    return this;
  };
```
¶

identity函数：返回参数的值。作为默认的迭代函数，用于类似_.filter迭代类型函数的参数。
```
  _.identity = function(value) {
    return value;
  };
```

执行函数n次，返回函数每次执行返回值组成的数组

  _.times = function(n, iterator, context) {
    var accum = Array(n);
    for (var i = 0; i < n; i++) accum[i] = iterator.call(context, i);
    return accum;
  };

返回min与max之间的随机数字（包括min和max）

  _.random = function(min, max) {
    if (max == null) {
      max = min;
      min = 0;
    }
    return min + Math.floor(Math.random() * (max - min + 1));
  };

HTML 实体转义表

  var entityMap = {
    escape: {
      '&': '&amp;',
      '<': '&lt;',
      '>': '&gt;',
      '"': '&quot;',
      "'": '&#x27;',
      '/': '&#x2F;'
    }
  };
  entityMap.unescape = _.invert(entityMap.escape);

Regexes containing the keys and values listed immediately above.

  var entityRegexes = {
    escape:   new RegExp('[' + _.keys(entityMap.escape).join('') + ']', 'g'),
    unescape: new RegExp('(' + _.keys(entityMap.unescape).join('|') + ')', 'g')
  };

Functions for escaping and unescaping strings to/from HTML interpolation.

  _.each(['escape', 'unescape'], function(method) {
    _[method] = function(string) {
      if (string == null) return '';
      return ('' + string).replace(entityRegexes[method], function(match) {
        return entityMap[method][match];
      });
    };
  });

If the value of the named property is a function then invoke it with the object as context; otherwise, return it.

  _.result = function(object, property) {
    if (object == null) return void 0;
    var value = object[property];
    return _.isFunction(value) ? value.call(object) : value;
  };

Add your own custom functions to the Underscore object.

  _.mixin = function(obj) {
    each(_.functions(obj), function(name){
      var func = _[name] = obj[name];
      _.prototype[name] = function() {
        var args = [this._wrapped];
        push.apply(args, arguments);
        return result.call(this, func.apply(_, args));
      };
    });
  };

Generate a unique integer id (unique within the entire client session). Useful for temporary DOM ids.

  var idCounter = 0;
  _.uniqueId = function(prefix) {
    var id = ++idCounter + '';
    return prefix ? prefix + id : id;
  };

By default, Underscore uses ERB-style template delimiters, change the following template settings to use alternative delimiters.

  _.templateSettings = {
    evaluate    : /<%([\s\S]+?)%>/g,
    interpolate : /<%=([\s\S]+?)%>/g,
    escape      : /<%-([\s\S]+?)%>/g
  };

¶

When customizing templateSettings, if you don't want to define an interpolation, evaluation or escaping regex, we need one that is guaranteed not to match.
```
  var noMatch = /(.)^/;
```

Certain characters need to be escaped so that they can be put into a string literal.

  var escapes = {
    "'":      "'",
    '\\':     '\\',
    '\r':     'r',
    '\n':     'n',
    '\t':     't',
    '\u2028': 'u2028',
    '\u2029': 'u2029'
  };

  var escaper = /\\|'|\r|\n|\t|\u2028|\u2029/g;

¶

JavaScript micro-templating, similar to John Resig's implementation. Underscore templating handles arbitrary delimiters, preserves whitespace, and correctly escapes quotes within interpolated code.
```
  _.template = function(text, data, settings) {
    var render;
    settings = _.defaults({}, settings, _.templateSettings);
```

Combine delimiters into one regular expression via alternation.

    var matcher = new RegExp([
      (settings.escape || noMatch).source,
      (settings.interpolate || noMatch).source,
      (settings.evaluate || noMatch).source
    ].join('|') + '|$', 'g');

Compile the template source, escaping string literals appropriately.

    var index = 0;
    var source = "__p+='";
    text.replace(matcher, function(match, escape, interpolate, evaluate, offset) {
      source += text.slice(index, offset)
        .replace(escaper, function(match) { return '\\' + escapes[match]; });

      if (escape) {
        source += "'+\n((__t=(" + escape + "))==null?'':_.escape(__t))+\n'";
      }
      if (interpolate) {
        source += "'+\n((__t=(" + interpolate + "))==null?'':__t)+\n'";
      }
      if (evaluate) {
        source += "';\n" + evaluate + "\n__p+='";
      }
      index = offset + match.length;
      return match;
    });
    source += "';\n";

If a variable is not specified, place data values in local scope.

    if (!settings.variable) source = 'with(obj||{}){\n' + source + '}\n';

    source = "var __t,__p='',__j=Array.prototype.join," +
      "print=function(){__p+=__j.call(arguments,'');};\n" +
      source + "return __p;\n";

    try {
      render = new Function(settings.variable || 'obj', '_', source);
    } catch (e) {
      e.source = source;
      throw e;
    }

    if (data) return render(data, _);
    var template = function(data) {
      return render.call(this, data, _);
    };

Provide the compiled function source as a convenience for precompilation.

    template.source = 'function(' + (settings.variable || 'obj') + '){\n' + source + '}';

    return template;
  };

Add a "chain" function, which will delegate to the wrapper.

  _.chain = function(obj) {
    return _(obj).chain();
  };

¶

OOP
¶

If Underscore is called as a function, it returns a wrapped object that can be used OO-style. This wrapper holds altered versions of all the underscore functions. Wrapped objects may be chained.

Helper function to continue chaining intermediate results.
```
  var result = function(obj) {
    return this._chain ? _(obj).chain() : obj;
  };
```
¶

Add all of the Underscore functions to the wrapper object.
```
  _.mixin(_);
```

Add all mutator Array functions to the wrapper.

  each(['pop', 'push', 'reverse', 'shift', 'sort', 'splice', 'unshift'], function(name) {
    var method = ArrayProto[name];
    _.prototype[name] = function() {
      var obj = this._wrapped;
      method.apply(obj, arguments);
      if ((name == 'shift' || name == 'splice') && obj.length === 0) delete obj[0];
      return result.call(this, obj);
    };
  });

Add all accessor Array functions to the wrapper.

  each(['concat', 'join', 'slice'], function(name) {
    var method = ArrayProto[name];
    _.prototype[name] = function() {
      return result.call(this, method.apply(this._wrapped, arguments));
    };
  });

  _.extend(_.prototype, {

Start chaining a wrapped Underscore object.

    chain: function() {
      this._chain = true;
      return this;
    },

Extracts the result from a wrapped and chained object.

    value: function() {
      return this._wrapped;
    }

  });

}).call(this);

underscore.js

基础设定

集合函数

数组相关函数

Function (ahem) Functions

对象相关的函数

工具函数

OOP