// Array Functions  // ---------------  // Get the first element of an array. Passing **n** will return the first N  // values in the array. Aliased as `head` and `take`. The **guard** check  // allows it to work with `_.map`.  /*    返回array（数组）的第一个元素。传递 n参数将返回数组中从第一个元素开始的n个元素  */  _.first = _.head = _.take = function(array, n, guard) {    if (array == null || array.length < 1) return void 0;    if (n == null || guard) return array[0];    return _.initial(array, array.length - n);  };  // Returns everything but the last entry of the array. Especially useful on  // the arguments object. Passing **n** will return all the values in  // the array, excluding the last N.  /*    返回数组中除了最后一个元素外的其他全部元素。 在arguments对象上特别有用。传递 n参数将从结果中排除从最后一个开始的n个元素  */  _.initial = function(array, n, guard) {    return slice.call(array, 0, Math.max(0, array.length - (n == null || guard ? 1 : n)));  };  // Get the last element of an array. Passing **n** will return the last N  // values in the array.  /*    返回array（数组）的最后一个元素。传递 n参数将返回数组中从最后一个元素开始的n个元素  */  _.last = function(array, n, guard) {    if (array == null || array.length < 1) return void 0;    if (n == null || guard) return array[array.length - 1];    return _.rest(array, Math.max(0, array.length - n));  };  // Returns everything but the first entry of the array. Aliased as `tail` and `drop`.  // Especially useful on the arguments object. Passing an **n** will return  // the rest N values in the array.  /*    返回数组中除了第一个元素外的其他全部元素。传递n参数将返回从n开始的剩余所有元素 。  */  _.rest = _.tail = _.drop = function(array, n, guard) {    return slice.call(array, n == null || guard ? 1 : n);  };  // Trim out all falsy values from an array.  /*    返回一个除去所有false值的array副本。 在javascript中, false, null, 0, "", undefined 和 NaN 都是false值.  */  _.compact = function(array) {    return _.filter(array, Boolean);  };  // Internal implementation of a recursive `flatten` function.  /*    内部的flatten函数  */  var flatten = function(input, shallow, strict, output) {    output = output || [];    var idx = output.length;    for (var i = 0, length = getLength(input); i < length; i++) {      var value =http://www.mamicode.com/ input[i];      // 如果value还是数组或类数组      // _.isArguments(value)实现原理是判断value中是否有callee方法      if (isArrayLike(value) && (_.isArray(value) || _.isArguments(value))) {        // Flatten current level of array or arguments object.        //如果有shallow参数，则只打开一层        if (shallow) {          var j = 0, len = value.length;          while (j < len) output[idx++] = value[j++];        } else {// 否则，递归调用此函数，将结果数组output传入          flatten(value, shallow, strict, output);          idx = output.length;        }      } else if (!strict) {        output[idx++] = value;      }    }    return output;  };  // Flatten out an array, either recursively (by default), or just one level.  /*    将一个嵌套多层的数组 array（数组） (嵌套可以是任何层数)转换为只有一层的数组。 如果你传递 shallow参数，数组将只减少一维的嵌套。  */  _.flatten = function(array, shallow) {    return flatten(array, shallow, false);  };  // Return a version of the array that does not contain the specified value(s).  /*    返回一个删除所有values值后的 array副本。  */  _.without = restArgs(function(array, otherArrays) {    return _.difference(array, otherArrays);  });  // 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`.  /*    返回 array去重后的副本, 如果您确定 array 已经排序, 那么给 isSorted 参数传递 true值, 此函数将运行的更快的算法. 如果要处理对象元素, 传递 iteratee函数来获取要对比的属性  */  _.uniq = _.unique = function(array, isSorted, iteratee, context) {    // 如果没有传递或传递的isSorted不为布尔值，后面两个参数前移    if (!_.isBoolean(isSorted)) {      context = iteratee;      iteratee = isSorted;      isSorted = false;    }    if (iteratee != null) iteratee = cb(iteratee, context);    var result = [];    var seen = [];// 表示已经有了的    for (var i = 0, length = getLength(array); i < length; i++) {// 遍历数组      var value =http://www.mamicode.com/ array[i],          computed = iteratee ? iteratee(value, i, array) : value;      if (isSorted) {// 如果数组已经是排序好的，只需判断前后两个值是否相等（效率高）        if (!i || seen !== computed) result.push(value);        seen = computed;      } else if (iteratee) {// 如果有iteratee函数，将值先push到seen中，再把value push到result中        if (!_.contains(seen, computed)) {          seen.push(computed);          result.push(value);        }      } else if (!_.contains(result, value)) {        result.push(value);      }    }    return result;  };  // Produce an array that contains the union: each distinct element from all of  // the passed-in arrays.  /*    返回传入的 arrays（数组）并集：按顺序返回，返回数组的元素是唯一的，可以传入一个或多个 arrays（数组）  */  _.union = restArgs(function(arrays) {    return _.uniq(flatten(arrays, true, true));  });  // Produce an array that contains every item shared between all the  // passed-in arrays.  /*    返回传入 arrays（数组）交集。结果中的每个值是存在于传入的每个arrays（数组）里    这个函数的效率是数组长度的乘积  */  _.intersection = function(array) {    var result = [];    var argsLength = arguments.length;    for (var i = 0, length = getLength(array); i < length; i++) {      var item = array[i];      if (_.contains(result, item)) continue;      var j;      for (j = 1; j < argsLength; j++) {        if (!_.contains(arguments[j], item)) break;      }      if (j === argsLength) result.push(item);    }    return result;  };  // Take the difference between one array and a number of other arrays.  // Only the elements present in just the first array will remain.  /*    类似于without，但返回的值来自array参数数组，并且不存在于other 数组  */  _.difference = restArgs(function(array, rest) {    rest = flatten(rest, true, true);    return _.filter(array, function(value){      return !_.contains(rest, value);// 用indexOf() > 0来判断    });  });  // Complement of _.zip. Unzip accepts an array of arrays and groups  // each array‘s elements on shared indices.  /*    与zip功能相反的函数，给定若干arrays，返回一串联的新数组，其第一元素个包含所有的输入数组的第一元素，其第二包含了所有的第二元素，依此类推。  */  _.unzip = function(array) {    var length = array && _.max(array, getLength).length || 0;// 返回数组中的元素的最长长度    var result = Array(length);    for (var index = 0; index < length; index++) {      result[index] = _.pluck(array, index);// map(array, _.property(index))    }    return result;  };  // Zip together multiple lists into a single array -- elements that share  // an index go together.  /*    将 每个arrays中相应位置的值合并在一起。在合并分开保存的数据时很有用. 如果你用来处理矩阵嵌套数组时, _.zip.apply 可以做类似的效果。  */  _.zip = restArgs(_.unzip);  // 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.  /*    将数组转换为对象。传递任何一个单独[key, value]对的列表，或者一个键的列表和一个值得列表。 如果存在重复键，最后一个值将被返回。  */  _.object = function(list, values) {    var result = {};    for (var i = 0, length = getLength(list); i < length; i++) {      if (values) {// 传入第二个参数        result[list[i]] = values[i];      } else {// 单独的[key,value]对        result[list[i][0]] = list[i][1];      }    }    return result;  };  // Generator function to create the findIndex and findLastIndex functions.  /*    遍历数组，找出符合predicate的项的index，找不到返回-1  */  var createPredicateIndexFinder = function(dir) {    return function(array, predicate, context) {      predicate = cb(predicate, context);      var length = getLength(array);      var index = dir > 0 ? 0 : length - 1;      for (; index >= 0 && index < length; index += dir) {        if (predicate(array[index], index, array)) return index;      }      return -1;    };  };  // Returns the first index on an array-like that passes a predicate test.  /*    类似于_.indexOf    和_.findIndex类似，但反向迭代数组  */  _.findIndex = createPredicateIndexFinder(1);  _.findLastIndex = createPredicateIndexFinder(-1);  // 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.  /*    使用二分查找确定value在list中的位置序号，value按此序号插入能保持list原有的排序。如果提供iterator函数，iterator将作为list排序的依据，包括你传递的value 。iterator也可以是字符串的属性名用来排序(比如length)。  */  _.sortedIndex = function(array, obj, iteratee, context) {    iteratee = cb(iteratee, context, 1);    var value =http://www.mamicode.com/ iteratee(obj);    var low = 0, high = getLength(array);    while (low < high) {// 二分查找      var mid = Math.floor((low + high) / 2);      if (iteratee(array[mid]) < value) low = mid + 1; else high = mid;    }    return low;  };  // Generator function to create the indexOf and lastIndexOf functions.  /*    求元素在数组中的位置  */  var createIndexFinder = function(dir, predicateFind, sortedIndex) {    return function(array, item, idx) {      var i = 0, length = getLength(array);      if (typeof idx == ‘number‘) {// 如果传入了idx        if (dir > 0) {// 正向          i = idx >= 0 ? idx : Math.max(idx + length, i);        } else {// 反向          length = idx >= 0 ? Math.min(idx + 1, length) : idx + length + 1;        }      } else if (sortedIndex && idx && length) {// 如果没传入，但是数组有序，直接调用sortedIndex(array, item)        idx = sortedIndex(array, item);        return array[idx] === item ? idx : -1;      }      if (item !== item) {// 如果item为NaN,说明要找出是NaN的元素        idx = predicateFind(slice.call(array, i, length), _.isNaN);        return idx >= 0 ? idx + i : -1;      }      for (idx = dir > 0 ? i : length - 1; idx >= 0 && idx < length; idx += dir) {        if (array[idx] === item) return idx;      }      return -1;    };  };  // Return the position of the first occurrence of an item in an array,  // or -1 if the item is not included in the array.  // If the array is large and already in sort order, pass `true`  // for **isSorted** to use binary search.  /*    返回value在该 array 中的索引值，如果value不存在 array中就返回-1。使用原生的indexOf 函数，除非它失效。如果您正在使用一个大数组，你知道数组已经排序，传递true给isSorted将更快的用二进制搜索..,或者，传递一个数字作为第三个参数，为了在给定的索引的数组中寻找第一个匹配值。  */  _.indexOf = createIndexFinder(1, _.findIndex, _.sortedIndex);  _.lastIndexOf = createIndexFinder(-1, _.findLastIndex);  // Generate an integer Array containing an arithmetic progression. A port of  // the native Python `range()` function. See  // [the Python documentation](http://docs.python.org/library/functions.html#range).  /*    一个用来创建整数灵活编号的列表的函数，便于each 和 map循环。如果省略start则默认为 0；step 默认为 1.返回一个从start 到stop的整数的列表，用step来增加 （或减少）独占。值得注意的是，如果stop值在start前面（也就是stop值小于start值），那么负增长。(这个地方中文文档的解释是错的)  */  _.range = function(start, stop, step) {    if (stop == null) {      stop = start || 0;      start = 0;    }    if (!step) {      step = stop < start ? -1 : 1;    }    var length = Math.max(Math.ceil((stop - start) / step), 0);    var range = Array(length);    for (var idx = 0; idx < length; idx++, start += step) {      range[idx] = start;    }    return range;  };  // Split an **array** into several arrays containing **count** or less elements  // of initial array.  /*    把数组arr从index=0处开始，分成长度为没有重复部分的长度小于count的数组所组成的数组  */  _.chunk = function(array, count) {    if (count == null || count < 1) return [];    var result = [];    var i = 0, length = array.length;    while (i < length) {      result.push(slice.call(array, i, i += count));// slice(s, e)方法当e大于数组最末尾位置时，返回从i到最后    }    return result;  };