// Collection Functions
// --------------------
// The cornerstone, an `each` implementation, aka `forEach`.
// Handles raw objects in addition to array-likes. Treats all
// sparse array-likes as if they were dense.
/*
params: 数组、对象或类数组对象,函数，函数执行环境
*/
_.each = _.forEach = function(obj, iteratee, context) {
iteratee = optimizeCb(iteratee, context);
var i, length;
if (isArrayLike(obj)) {// 数组或类数组
for (i = 0, length = obj.length; i < length; i++) {
iteratee(obj[i], i, obj);// item index obj
}
} else {// 对象
var keys = _.keys(obj);// 返回键的数组
for (i = 0, length = keys.length; i < length; i++) {
iteratee(obj[keys[i]], keys[i], obj);
}
}
return obj;
};
// Return the results of applying the iteratee to each element.
/*
通过转换函数(iteratee迭代器)映射列表中的每个值产生价值的新数组
这个函数很简洁的处理类数组与对象的不同情况，值得学习！！！！！！！！！！！！！！！！！！！
*/
_.map = _.collect = function(obj, iteratee, context) {
iteratee = cb(iteratee, context);
var keys = !isArrayLike(obj) && _.keys(obj),//如果是数组，返回false；否则返回对象的keys数组
length = (keys || obj).length,
results = Array(length);
for (var index = 0; index < length; index++) {
var currentKey = keys ? keys[index] : index;// 如果是对象，返回key; 数组返回index
results[index] = iteratee(obj[currentKey], currentKey, obj);
}
return results;
};
// Create a reducing function iterating left or right.
/*
创建迭代
params：方向(-1为左，1为右)
*/
var createReduce = function(dir) {
// Wrap code that reassigns argument variables in a separate function than
// the one that accesses `arguments.length` to avoid a perf hit. (#1991)
/*
params: obj,执行函数,起始值,起始值和context
*/
var reducer = function(obj, iteratee, memo, initial) {
var keys = !isArrayLike(obj) && _.keys(obj),
length = (keys || obj).length,
index = dir > 0 ? 0 : length - 1;
if (!initial) {// 如果没有起始值这个参数
memo = obj[keys ? keys[index] : index];
index += dir;
}
for (; index >= 0 && index < length; index += dir) {
var currentKey = keys ? keys[index] : index;
memo = iteratee(memo, obj[currentKey], currentKey, obj);
}
return memo;
};
return function(obj, iteratee, memo, context) {
var initial = arguments.length >= 3;
return reducer(obj, optimizeCb(iteratee, context, 4), memo, initial);
};
};
// **Reduce** builds up a single result from a list of values, aka `inject`,
// or `foldl`.
_.reduce = _.foldl = _.inject = createReduce(1);
// The right-associative version of reduce, also known as `foldr`.
_.reduceRight = _.foldr = createReduce(-1);
// Return the first value which passes a truth test. Aliased as `detect`.
/*
在list中逐项查找，返回第一个通过predicate迭代函数真值检测的元素值，如果没有值传递给测试迭代器将返回
*/
_.find = _.detect = function(obj, predicate, context) {
var keyFinder = isArrayLike(obj) ? _.findIndex : _.findKey;
var key = keyFinder(obj, predicate, context);
if (key !== void 0 && key !== -1) return obj[key];
};
// Return all the elements that pass a truth test.
// Aliased as `select`.
/*
遍历list中的每个值，返回包含所有通过predicate真值检测的元素值
与原生的filter函数作用相同，有原生的时候可以使用原生的filter
*/
_.filter = _.select = function(obj, predicate, context) {
var results = [];
predicate = cb(predicate, context);
_.each(obj, function(value, index, list) {//遍历所有元素，返回符合条件的value
if (predicate(value, index, list)) results.push(value);
});
return results;
};
// Return all the elements for which a truth test fails.
/*
返回list中没有通过predicate真值检测的元素集合，与filter相反
*/
_.reject = function(obj, predicate, context) {
return _.filter(obj, _.negate(cb(predicate)), context);
};
// Determine whether all of the elements match a truth test.
// Aliased as `all`.
/*
如果list中的所有元素都通过predicate的真值检测就返回true
与原生的every函数作用相同，有原生的时候可以使用原生的every
*/
_.every = _.all = function(obj, predicate, context) {
predicate = cb(predicate, context);
var keys = !isArrayLike(obj) && _.keys(obj),
length = (keys || obj).length;
for (var index = 0; index < length; index++) {
var currentKey = keys ? keys[index] : index;
if (!predicate(obj[currentKey], currentKey, obj)) return false;//如果找到一个不符合，直接中断函数
}
return true;
};
// Determine if at least one element in the object matches a truth test.
// Aliased as `any`.
/*
如果list中有任何一个元素通过 predicate 的真值检测就返回true。一旦找到了符合条件的元素, 就直接中断对list的遍历
*/
_.some = _.any = function(obj, predicate, context) {
predicate = cb(predicate, context);
var keys = !isArrayLike(obj) && _.keys(obj),
length = (keys || obj).length;
for (var index = 0; index < length; index++) {
var currentKey = keys ? keys[index] : index;
if (predicate(obj[currentKey], currentKey, obj)) return true;
}
return false;
};
// Determine if the array or object contains a given item (using `===`).
// Aliased as `includes` and `include`.
/*
如果list包含指定的value则返回true
*/
_.contains = _.includes = _.include = function(obj, item, fromIndex, guard) {
if (!isArrayLike(obj)) obj = _.values(obj);//将对象中所有value压入一个数组
if (typeof fromIndex != 'number' || guard) fromIndex = 0;
return _.indexOf(obj, item, fromIndex) >= 0;
};
// Invoke a method (with arguments) on every item in a collection.
/*
在list的每个元素上执行methodName方法
*/
_.invoke = restArgs(function(obj, method, args) {// 将多余三个之外的参数合并为一个数组传入到参数函数中
var isFunc = _.isFunction(method);
return _.map(obj, function(value) {
var func = isFunc ? method : value[method];
return func == null ? func : func.apply(value, args);
});
});
// Convenience version of a common use case of `map`: fetching a property.
_.pluck = function(obj, key) {
return _.map(obj, _.property(key));//property() 返回获取obj[key]的函数
};
// Convenience version of a common use case of `filter`: selecting only objects
// containing specific `key:value` pairs.
/*
遍历list中的每一个值，返回一个数组，这个数组包含properties所列出的属性的所有的 键 - 值对
*/
_.where = function(obj, attrs) {
return _.filter(obj, _.matcher(attrs));
};
/*
遍历整个list，返回匹配 properties参数所列出的所有 键 - 值 对的第一个值。
*/
// Convenience version of a common use case of `find`: getting the first object
// containing specific `key:value` pairs.
_.findWhere = function(obj, attrs) {
return _.find(obj, _.matcher(attrs));
};
// Return the maximum element (or element-based computation).
/*
返回list中的最大值。如果传递iteratee参数，iteratee将作为list中每个值的排序依据。如果list为空，将返回-Infinity
*/
_.max = function(obj, iteratee, context) {
var result = -Infinity, lastComputed = -Infinity,
value, computed;
if (iteratee == null || (typeof iteratee == 'number' && typeof obj[0] != 'object') && obj != null) {
// 不存在iteratee参数,或者iteratee为数字类型m,obj[0]是object类型??????????????????????????????????????????
obj = isArrayLike(obj) ? obj : _.values(obj);// 判断obj是不是数组或类数组（有没有正确类型的length）
for (var i = 0, length = obj.length; i < length; i++) {
value = obj[i];
if (value != null && value > result) {
result = value;
}
}
} else {
// 存在iteratee参数
iteratee = cb(iteratee, context);
// 利用each对整个数组进行操作
_.each(obj, function(v, index, list) {
computed = iteratee(v, index, list);
if (computed > lastComputed || computed === -Infinity && result === -Infinity) {
result = v;
lastComputed = computed;
}
});
}
return result;
};
// Return the minimum element (or element-based computation).
/*
返回list中的最小值。如果传递iteratee参数，iteratee将作为list中每个值的排序依据。如果list为空，将返回-Infinity
实现与上述一致
*/
_.min = function(obj, iteratee, context) {
var result = Infinity, lastComputed = Infinity,
value, computed;
if (iteratee == null || (typeof iteratee == 'number' && typeof obj[0] != 'object') && obj != null) {
obj = isArrayLike(obj) ? obj : _.values(obj);
for (var i = 0, length = obj.length; i < length; i++) {
value = obj[i];
if (value != null && value < result) {
result = value;
}
}
} else {
iteratee = cb(iteratee, context);
_.each(obj, function(v, index, list) {
computed = iteratee(v, index, list);
if (computed < lastComputed || computed === Infinity && result === Infinity) {
result = v;
lastComputed = computed;
}
});
}
return result;
};
// Shuffle a collection.
/*
返回一个随机乱序的 list 副本, 使用 Fisher-Yates shuffle 来进行随机乱序
*/
_.shuffle = function(obj) {
return _.sample(obj, Infinity);
};
// Sample **n** random values from a collection using the modern version of the
// [Fisher-Yates shuffle](http://en.wikipedia.org/wiki/Fisher–Yates_shuffle).
// If **n** is not specified, returns a single random element.
// The internal `guard` argument allows it to work with `map`.
/*
从 list中产生一个随机样本。传递一个数字表示从list中返回n个随机元素。否则将返回一个单一的随机项
*/
_.sample = function(obj, n, guard) {
if (n == null || guard) {// 没传递n或者是传递了guard参数
if (!isArrayLike(obj)) obj = _.values(obj);
return obj[_.random(obj.length - 1)];// _.random()利用Math.random返回随机数组下标的值
}
var sample = isArrayLike(obj) ? _.clone(obj) : _.values(obj);
var length = getLength(sample);
n = Math.max(Math.min(n, length), 0);// 取n和length的最小值
var last = length - 1;
// 选出数量为n的随机数
// 这里不用arr.sort()方法是因为利用数组排序进行随机排列会有分布不均的现象，具体见https://www.h5jun.com/post/array-shuffle.html
for (var index = 0; index < n; index++) {
var rand = _.random(index, last);
var temp = sample[index];
sample[index] = sample[rand];
sample[rand] = temp;
}
return sample.slice(0, n);
};
// Sort the object's values by a criterion produced by an iteratee.
/*
返回一个排序后的list拷贝副本。如果传递iteratee参数，iteratee将作为list中每个值的排序依据。
*/
_.sortBy = function(obj, iteratee, context) {
var index = 0;
iteratee = cb(iteratee, context);
// _.pluck()返回对象数组中所有对象的value属性组成的数组
return _.pluck(_.map(obj, function(value, key, list) {// 把数组中每个值包装成一个对象，返回一个对象数组
return {
value: value,
index: index++,
criteria: iteratee(value, key, 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;
}), 'value');
};
// An internal function used for aggregate "group by" operations.
/*
params: 执行函数，是否分成两份？？？？？？？？？？？？？？？？？？？？？？？？？？？？
*/
var group = function(behavior, partition) {
// 返回一个接受三个参数的函数
// 对传入数组每一项执行iteratee并将结果传入behavior执行
return function(obj, iteratee, context) {
var result = partition ? [[], []] : {};
iteratee = cb(iteratee, context);
_.each(obj, function(value, index) {
var new_val = iteratee(value, index, obj);// 这里参数名称改为new_val感觉更好理解一点
behavior(result, value, new_val);
});
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.
/*
把一个集合分组为多个集合，通过 iterator 返回的结果进行分组. 如果 iterator 是一个字符串而不是函数, 那么将使用 iterator 作为各元素的属性名来对比进行分组
params： [[], []]或{}，每一项的value与对应iteratee(value, index, obj)的结果
*/
_.groupBy = group(function(result, value, key) {
if (_.has(result, key)) result[key].push(value); else result[key] = [value];// 如果result中已经有了key属性，则push(value)；否则新增属性key
});
// Indexes the object's values by a criterion, similar to `groupBy`, but for
// when you know that your index values will be unique.
/*
给定一个list，和 一个用来返回一个在列表中的每个元素键 的iterator 函数（或属性名）， 返回一个每一项索引的对象。
*/
_.indexBy = group(function(result, value, key) {
result[key] = 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.
/*
排序一个列表组成一个组，并且返回各组中的对象的数量的计数。
类似groupBy，但是不是返回列表的值，而是返回在该组中值的数目。
*/
_.countBy = group(function(result, value, key) {
if (_.has(result, key)) result[key]++; else result[key] = 1;
});
/*
第一个表示不包含代理对代码点的所有字符
第二个表示合法的代理对的所有字符
第三个表示代理对的代码点（本身不是合法的Unicode字符）
意思就是所有字符，'hello'.match(reStrSymbol); ==> ['h','e','l','l','o']
*/
var reStrSymbol = /[^ud800-udfff]|[ud800-udbff][udc00-udfff]|[ud800-udfff]/g;
// Safely create a real, live array from anything iterable.
/*
把obj(任何可以迭代的对象)转换成一个数组，在转换 arguments 对象时非常有用
*/
_.toArray = function(obj) {
if (!obj) return [];
if (_.isArray(obj)) return slice.call(obj);// 如果是纯数组，直接用slice.call()
if (_.isString(obj)) {//如果是字符串
// Keep surrogate pair characters together
return obj.match(reStrSymbol);
}
if (isArrayLike(obj)) return _.map(obj, _.identity);// 如果是对象类似于_.kets(obj)
return _.values(obj);
};
// Return the number of elements in an object.
/*
返回list的长度。
*/
_.size = function(obj) {
if (obj == null) return 0;
return isArrayLike(obj) ? obj.length : _.keys(obj).length;
};
// Split a collection into two arrays: one whose elements all satisfy the given
// predicate, and one whose elements all do not satisfy the predicate.
/*
拆分一个数组（array）为两个数组： 第一个数组其元素都满足predicate迭代函数， 而第二个的所有元素均不能满足predicate迭代函数。
pass为传入迭代函数的返回值
*/
_.partition = group(function(result, value, pass) {
result[pass ? 0 : 1].push(value);
}, true);