Underscore.js

Функции для коллекций (массивов или объектов)

each_.each(list, iteratee, [context]) Псевдоним: forEach
Перебирает список элементов, передавая каждый из них в функцию-итератор. Функция-итератор связывается с объектом контекста, если он передан. Каждый вызов функции-итератора получает три аргумента: (элемент, индекс, список). Если список — JavaScript-объект, аргументы функции-итератора будут (значение, ключ, список). Возвращает список для цепочки вызовов.

_.each([1, 2, 3], alert);
=> alerts each number in turn...
_.each({one: 1, two: 2, three: 3}, alert);
=> alerts each number value in turn...

Примечание: Функции для коллекций работают с массивами, объектами и массивоподобными объектами, такими как arguments, NodeList и аналогичными. Но они работают по принципу «утиной типизации», поэтому избегайте передачи объектов с числовым свойством length. Также следует отметить, что цикл each нельзя прервать — для прерывания используйте функцию _.find.

map_.map(list, iteratee, [context]) Псевдоним: collect
Создаёт новый массив значений, применяя функцию преобразования (iteratee) к каждому значению в списке. Функция-итератор получает три аргумента: значение, затем индекс (или ключ) итерации и, наконец, ссылку на весь список.

_.map([1, 2, 3], function(num){ return num * 3; });
=> [3, 6, 9]
_.map({one: 1, two: 2, three: 3}, function(num, key){ return num * 3; });
=> [3, 6, 9]
_.map([[1, 2], [3, 4]], _.first);
=> [1, 3]

reduce_.reduce(list, iteratee, [memo], [context]) Псевдонимы: inject, foldl
Также известная как inject и foldl, функция reduce сводит список значений к одному значению. Memo — начальное состояние редукции, и каждый последующий шаг должен возвращаться функцией-итератором. Функция-итератор получает четыре аргумента: memo, затем значение и индекс (или ключ) итерации, и, наконец, ссылку на весь список.

Если memo не передаётся при первом вызове reduce, функция-итератор не вызывается для первого элемента списка. Вместо этого первый элемент передаётся как memo при вызове функции-итератора для следующего элемента списка.

var sum = _.reduce([1, 2, 3], function(memo, num){ return memo + num; }, 0);
=> 6

reduceRight_.reduceRight(list, iteratee, [memo], [context]) Псевдоним: foldr
Правоассоциативная версия reduce. Foldr не так полезна в JavaScript, как в языках с ленивой оценкой.

var list = [[0, 1], [2, 3], [4, 5]];
var flat = _.reduceRight(list, function(a, b) { return a.concat(b); }, []);
=> [4, 5, 2, 3, 0, 1]

find_.find(list, predicate, [context]) Псевдоним: detect
Просматривает каждый элемент в списке, возвращая первый элемент, который проходит проверку истинности (predicate), или undefined, если ни один элемент не проходит проверку. Функция возвращает результат сразу после нахождения подходящего элемента и не обходит весь список. Функция predicate преобразуется с помощью iteratee для упрощения синтаксиса.

var even = _.find([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
=> 2

filter_.filter(list, predicate, [context]) Псевдоним: select
Просматривает каждый элемент в списке, возвращая массив всех элементов, которые проходят проверку истинности (predicate). Функция predicate преобразуется с помощью iteratee для упрощения синтаксиса.

var evens = _.filter([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
=> [2, 4, 6]

findWhere_.findWhere(list, properties)
Просматривает список и возвращает первое значение, которое соответствует всем парам ключ-значение в properties.

Если совпадение не найдено или список пустой, будет возвращено undefined.

_.findWhere(publicServicePulitzers, {newsroom: "The New York Times"});
=> {year: 1918, newsroom: "The New York Times",
  reason: "For its public service in publishing in full so many official reports,
  documents and speeches by European statesmen relating to the progress and
  conduct of the war."}

where_.where(list, properties)
Просматривает каждый элемент в списке, возвращая массив всех элементов, которые соответствуют парам ключ-значение в properties.

_.where(listOfPlays, {author: "Shakespeare", year: 1611});
=> [{title: "Cymbeline", author: "Shakespeare", year: 1611},
    {title: "The Tempest", author: "Shakespeare", year: 1611}]

reject_.reject(list, predicate, [context])
Возвращает элементы из списка, исключая те, которые проходят проверку истинности (predicate). Противоположность filter. Функция predicate преобразуется с помощью iteratee для упрощения синтаксиса.

var odds = _.reject([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
=> [1, 3, 5]

every_.every(list, [predicate], [context]) Псевдоним: all
Возвращает true, если все элементы списка проходят проверку истинности predicate. Прерывает и прекращает обработку списка, если найден ложный элемент. Функция predicate преобразуется с помощью iteratee для упрощения синтаксиса.

_.every([2, 4, 5], function(num) { return num % 2 == 0; });
=> false

some_.some(list, [predicate], [context]) Псевдоним: any
Возвращает true, если хотя бы один элемент списка проходит проверку истинности predicate. Прерывает и прекращает обработку списка, если найден истинный элемент. Функция predicate преобразуется с помощью iteratee для упрощения синтаксиса.

_.some([null, 0, 'yes', false]);
=> true

contains_.contains(list, value, [fromIndex]) Псевдонимы: include, includes
Возвращает true, если значение присутствует в списке. Внутри использует indexOf, если список является массивом. Используйте fromIndex, чтобы начать поиск с определённого индекса.

_.contains([1, 2, 3], 3);
=> true

invoke_.invoke(list, methodName, *arguments)
Вызывает метод, имя которого задано в methodName, для каждого элемента в списке. Любые дополнительные аргументы, переданные в invoke, будут переданы методу.

_.invoke([[5, 1, 7], [3, 2, 1]], 'sort');
=> [[1, 5, 7], [1, 2, 3]]

pluck_.pluck(list, propertyName)
Удобный вариант наиболее распространённого использования map: извлечение списка значений свойств.

var stooges = [{name: 'moe', age: 40}, {name: 'larry', age: 50}, {name: 'curly', age: 60}];
_.pluck(stooges, 'name');
=> ["moe", "larry", "curly"]

max_.max(list, [iteratee], [context])
Возвращает максимальное значение в списке. Если функция-итератор iteratee предоставлена, она будет использоваться для каждого значения для определения критерия ранжирования. Возвращает -Infinity, если список пуст, поэтому может потребоваться проверка на пустоту с помощью isEmpty. Данная функция может надёжно сравнивать только числа. В этой функции используется оператор < (примечание).

var stooges = [{name: 'moe', age: 40}, {name: 'larry', age: 50}, {name: 'curly', age: 60}];
_.max(stooges, function(stooge){ return stooge.age; });
=> {name: 'curly', age: 60};

min_.min(list, [iteratee], [context])
Возвращает минимальное значение в списке. Если функция-итератор iteratee предоставлена, она будет использоваться для каждого значения для определения критерия ранжирования. Возвращает Infinity, если список пуст, поэтому может потребоваться проверка на пустоту с помощью isEmpty. Данная функция может надёжно сравнивать только числа. В этой функции используется оператор < (примечание).

var numbers = [10, 5, 100, 2, 1000];
_.min(numbers);
=> 2

sortBy_.sortBy(list, iteratee, [context])
Возвращает (стабильно) отсортированную копию списка, отсортированную в порядке возрастания по результатам применения функции iteratee к каждому значению. Функция iteratee также может быть именем свойства для сортировки (например, length). В этой функции используется оператор < (примечание).

_.sortBy([1, 2, 3, 4, 5, 6], function(num){ return Math.sin(num); });
=> [5, 4, 6, 3, 1, 2]

var stooges = [{name: 'moe', age: 40}, {name: 'larry', age: 50}, {name: 'curly', age: 60}];
_.sortBy(stooges, 'name');
=> [{name: 'curly', age: 60}, {name: 'larry', age: 50}, {name: 'moe', age: 40}];

groupBy_.groupBy(list, iteratee, [context])
Разбивает коллекцию на наборы, сгруппированные по результату применения функции iteratee к каждому значению. Если iteratee — строка вместо функции, то группирует по свойству, заданному именем iteratee, для каждого значения.

_.groupBy([1.3, 2.1, 2.4], function(num){ return Math.floor(num); });
=> {1: [1.3], 2: [2.1, 2.4]}

_.groupBy(['one', 'two', 'three'], 'length');
=> {3: ["one", "two"], 5: ["three"]}

indexBy_.indexBy(list, iteratee, [context])
Принимая список и функцию-итератор iteratee, которая возвращает ключ для каждого элемента в списке (или имя свойства), возвращает объект с индексом каждого элемента. Похоже на groupBy, но когда ключи уникальны.

var stooges = [{name: 'moe', age: 40}, {name: 'larry', age: 50}, {name: 'curly', age: 60}];
_.indexBy(stooges, 'age');
=> {
  "40": {name: 'moe', age: 40},
  "50": {name: 'larry', age: 50},
  "60": {name: 'curly', age: 60}
}

countBy_.countBy(list, iteratee, [context])
Группирует список и возвращает количество элементов в каждой группе. Похоже на groupBy, но вместо возврата списка значений возвращает счётчик количества значений в каждой группе.

_.countBy([1, 2, 3, 4, 5], function(num) {
  return num % 2 == 0 ? 'even': 'odd';
});
=> {odd: 3, even: 2}

shuffle_.shuffle(list)
Возвращает перемешанную копию списка, используя алгоритм Fisher-Yates.

_.shuffle([1, 2, 3, 4, 5, 6]);
=> [4, 1, 6, 3, 5, 2]

sample_.sample(list, [n])
Возвращает случайную выборку из списка. Передайте число, чтобы получить n случайных элементов из списка. В противном случае будет возвращён один случайный элемент.

_.sample([1, 2, 3, 4, 5, 6]);
=> 4

_.sample([1, 2, 3, 4, 5, 6], 3);
=> [1, 6, 2]

toArray_.toArray(list)
Создаёт настоящий массив из списка (любого объекта, по которому можно выполнить итерацию). Полезно для преобразования объекта arguments.

(function(){ return _.toArray(arguments).slice(1); })(1, 2, 3, 4);
=> [2, 3, 4]

size_.size(list)
Возвращает количество элементов в списке.

_.size([1, 2, 3, 4, 5]);
=> 5

_.size({one: 1, two: 2, three: 3});
=> 3

partition_.partition(list, predicate)
Разделяет список на два массива: один, элементы которого удовлетворяют условию predicate, и один, элементы которого не удовлетворяют predicate. Функция predicate преобразуется с помощью iteratee для упрощения синтаксиса.

_.partition([0, 1, 2, 3, 4, 5], isOdd);
=> [[1, 3, 5], [0, 2, 4]]

compact_.compact(list)
Возвращает копию списка со всеми ложными значениями, удалёнными. В JavaScript ложными являются false, null, 0, "", undefined и NaN.

_.compact([0, 1, false, 2, '', 3]);
=> [1, 2, 3]

Функции для массивов

Примечание: Все функции для массивов также будут работать с объектом arguments. Однако функции Underscore не предназначены для работы с «разреженными» массивами.

first_.first(array, [n]) Псевдонимы: head, take
Возвращает первый элемент массива. Передача n вернёт первые n элементов массива.

_.first([5, 4, 3, 2, 1]);
=> 5

initial_.initial(array, [n])
Возвращает все элементы, кроме последнего, в массиве. Особенно полезно с объектом arguments. Передача n исключит последние n элементов из результата.

_.initial([5, 4, 3, 2, 1]);
=> [5, 4, 3, 2]

last_.last(array, [n])
Возвращает последний элемент массива. Передача n вернёт последние n элементов массива.

_.last([5, 4, 3, 2, 1]);
=> 1

rest_.rest(array, [index]) Псевдонимы: tail, drop
Возвращает оставшиеся элементы в массиве. Передача index вернёт элементы массива, начиная с указанного индекса.

_.rest([5, 4, 3, 2, 1]);
=> [4, 3, 2, 1]

flatten_.flatten(array, [depth])
Разглаживает вложенный массив. Если вы передаёте true или 1 в качестве depth, массив будет разглажен только на один уровень. Передача большего числа вызовет разглаживание на более глубоких уровнях вложенности. Пропуск аргумента depth или передача false или Infinity разгладит массив до самого глубокого уровня вложенности.

_.flatten([1, [2], [3, [[4]]]]);
=> [1, 2, 3, 4];

_.flatten([1, [2], [3, [[4]]]], true);
=> [1, 2, 3, [[4]]];

_.flatten([1, [2], [3, [[4]]]], 2);
=> [1, 2, 3, [4]];

without_.without(array, *values)
Возвращает копию массива со всеми вхождениями значений удаленными.

_.without([1, 2, 1, 0, 3, 1, 4], 0, 1);
=> [2, 3, 4]

union_.union(*arrays)
Вычисляет объединение переданных массивов: список уникальных элементов в порядке их появления, присутствующих в одном или нескольких массивах.

_.union([1, 2, 3], [101, 2, 1, 10], [2, 1]);
=> [1, 2, 3, 101, 10]

intersection_.intersection(*arrays)
Вычисляет список значений, являющихся пересечением всех массивов. Каждое значение в результате присутствует в каждом из массивов.

_.intersection([1, 2, 3], [101, 2, 1, 10], [2, 1]);
=> [1, 2]

difference_.difference(array, *others)
Аналогично without, но возвращает значения из массива, которые отсутствуют в других массивах.

_.difference([1, 2, 3, 4, 5], [5, 2, 10]);
=> [1, 3, 4]

uniq_.uniq(array, [isSorted], [iteratee]) Псевдоним: unique
Создаёт версию массива без дубликатов, используя === для проверки равенства объектов. В частности, сохраняется только первое вхождение каждого значения. Если вы заранее знаете, что массив отсортирован, передача true для isSorted запустит значительно более быстрый алгоритм. Если вы хотите вычислить уникальные элементы на основе преобразования, передайте функцию iteratee.

_.uniq([1, 2, 1, 4, 1, 3]);
=> [1, 2, 4, 3]

zip_.zip(*arrays)
Объединяет значения каждого из массивов со значениями в соответствующей позиции. Полезно, когда у вас есть отдельные источники данных, которые координируются с помощью соответствующих индексов массивов.

_.zip(['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]);
=> [["moe", 30, true], ["larry", 40, false], ["curly", 50, false]]

unzip_.unzip(array) Псевдоним: transpose
Обратная функция zip. Принимая на вход массив массивов, возвращает серию новых массивов, первый из которых содержит все первые элементы в массивах-ввода, второй — все вторые элементы и так далее. Если вы работаете с матрицей вложенных массивов, это можно использовать для транспонирования матрицы.

_.unzip([["moe", 30, true], ["larry", 40, false], ["curly", 50, false]]);
=> [['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]]

object_.object(list, [values])
Преобразует массивы в объекты. Передайте либо один список пар [ключ, значение], либо список ключей и список значений. Передача пар — обратное преобразованию с помощью pairs. Если существуют дублирующие ключи, последнее значение выигрывает.

_.object(['moe', 'larry', 'curly'], [30, 40, 50]);
=> {moe: 30, larry: 40, curly: 50}

_.object([['moe', 30], ['larry', 40], ['curly', 50]]);
=> {moe: 30, larry: 40, curly: 50}

chunk_.chunk(array, length)
Разбивает массив на несколько массивов, каждый из которых содержит length или меньше элементов.

var partners = _.chunk(_.shuffle(kindergarten), 2);
=> [["Tyrone", "Elie"], ["Aidan", "Sam"], ["Katrina", "Billie"], ["Little Timmy"]]

indexOf_.indexOf(array, value, [isSorted])
Возвращает индекс, в котором можно найти значение в массиве, или -1, если значение не присутствует в массиве. Если вы работаете с большим массивом и знаете, что массив уже отсортирован, передайте true для isSorted, чтобы использовать более быстрый двоичный поиск... или передайте число в качестве третьего аргумента, чтобы найти первое соответствующее значение в массиве после данного индекса. Если isSorted равно true, эта функция использует оператор < (примечание).

_.indexOf([1, 2, 3], 2);
=> 1

lastIndexOf_.lastIndexOf(array, value, [fromIndex])
Возвращает индекс последнего вхождения значения в массиве или -1, если значение отсутствует. Передайте fromIndex, чтобы начать поиск с данного индекса.

_.lastIndexOf([1, 2, 3, 1, 2, 3], 2);
=> 4

sortedIndex_.sortedIndex(array, value, [iteratee], [context])
Использует двоичный поиск для определения наименьшего индекса, в котором значение должно быть вставлено в массив для сохранения сортировки массива. Если предоставлена функция iteratee, она будет использоваться для вычисления ранжирования каждого значения, включая переданное вами значение. Функция iteratee также может быть именем свойства для сортировки (например, length). Эта функция использует оператор < (примечание).

_.sortedIndex([10, 20, 30, 40, 50], 35);
=> 3

var stooges = [{name: 'moe', age: 40}, {name: 'curly', age: 60}];
_.sortedIndex(stooges, {name: 'larry', age: 50}, 'age');
=> 1

findIndex_.findIndex(array, predicate, [context])
Аналогично _.indexOf, возвращает первый индекс, где истинно условие предиката; в противном случае возвращает -1.

_.findIndex([4, 6, 8, 12], isPrime);
=> -1 // not found
_.findIndex([4, 6, 7, 12], isPrime);
=> 2

findLastIndex_.findLastIndex(array, predicate, [context])
Подобно _.findIndex, но итерирует массив в обратном порядке, возвращая индекс, наиболее близкий к концу, где истинно условие предиката.

var users = [{'id': 1, 'name': 'Bob', 'last': 'Brown'},
             {'id': 2, 'name': 'Ted', 'last': 'White'},
             {'id': 3, 'name': 'Frank', 'last': 'James'},
             {'id': 4, 'name': 'Ted', 'last': 'Jones'}];
_.findLastIndex(users, {
  name: 'Ted'
});
=> 3

range_.range([start], stop, [step])
Функция для создания гибких списков целых чисел, удобных для циклов each и map. start, если опущено, по умолчанию равно 0; step по умолчанию равно 1. Возвращает список целых чисел от start (включительно) до stop (исключительно), увеличенный (или уменьшенный) на step. Обратите внимание, что диапазоны, которые stop до start, считаются нулевой длины, а не отрицательной — если вам нужен отрицательный диапазон, используйте отрицательный step.

_.range(10);
=> [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
_.range(1, 11);
=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
_.range(0, 30, 5);
=> [0, 5, 10, 15, 20, 25]
_.range(0, -10, -1);
=> [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
_.range(0);
=> []

Функции (хм, ага) Функции

bind_.bind(function, object, *arguments)
Связывает функцию с объектом, что означает, что каждый раз при вызове функции значение this будет равно объекту. При необходимости передайте аргументы для предварительной заполнения функции, также известной как частичное применение. Для частичного применения без привязки контекста используйте partial.

var func = function(greeting){ return greeting + ': ' + this.name };
func = _.bind(func, {name: 'moe'}, 'hi');
func();
=> 'hi: moe'

bindAll_.bindAll(object, *methodNames)
Связывает несколько методов на объекте, указанные methodNames, для выполнения в контексте этого объекта при их вызове. Очень удобно для привязки функций, которые будут использоваться в качестве обработчиков событий, которые в противном случае будут вызваны с довольно бесполезным значением this. methodNames обязательны.

var buttonView = {
  label  : 'underscore',
  onClick: function(){ alert('clicked: ' + this.label); },
  onHover: function(){ console.log('hovering: ' + this.label); }
};
_.bindAll(buttonView, 'onClick', 'onHover');
// When the button is clicked, this.label will have the correct value.
jQuery('#underscore_button').on('click', buttonView.onClick);

partial_.partial(function, *arguments)
Частично применяет функцию, заполняя любое количество её аргументов, не изменяя значение динамического this. Ближайший родственник bind. Вы можете передать _ в свой список аргументов, чтобы указать аргумент, который не должен быть предварительно заполнен, но должен быть предоставлен во время вызова.

var subtract = function(a, b) { return b - a; };
sub5 = _.partial(subtract, 5);
sub5(20);
=> 15

// Using a placeholder
subFrom20 = _.partial(subtract, _, 20);
subFrom20(5);
=> 15

memoize_.memoize(function, [hashFunction])
Кэширует результат вычислений переданной функции. Полезно для ускорения медленных вычислений. Если передана необязательная hashFunction, она будет использоваться для вычисления ключа хэша для хранения результата на основе аргументов исходной функции. По умолчанию hashFunction использует первый аргумент вызываемой мемоизированной функции в качестве ключа. Кэш мемоизированных значений доступен в виде свойства cache на возвращаемой функции.

var fibonacci = _.memoize(function(n) {
  return n < 2 ? n: fibonacci(n - 1) + fibonacci(n - 2);
});

delay_.delay(function, wait, *arguments)
Подобно setTimeout, вызывает функцию через wait миллисекунд. Если вы передадите необязательные аргументы, они будут переданы в функцию при её вызове.

var log = _.bind(console.log, console);
_.delay(log, 1000, 'logged later');
=> 'logged later' // Appears after one second.

defer_.defer(function, *arguments)
Откладывает вызов функции до момента, когда текущая стек вызовов очистится, аналогично использованию setTimeout с задержкой 0. Полезно для выполнения дорогостоящих вычислений или рендеринга HTML частями без блокирования потока обновления пользовательского интерфейса. Если вы передадите необязательные аргументы, они будут переданы в функцию при её вызове.

_.defer(function(){ alert('deferred'); });
// Returns from the function before the alert runs.

throttle_.throttle(function, wait, [options])
Создаёт и возвращает новую, ограниченную по времени версию переданной функции, которая, при вызове повторно, будет вызывать исходную функцию не более одного раза в каждые wait миллисекунд. Полезно для ограничения скорости событий, происходящих быстрее, чем вы можете их обрабатывать.

По умолчанию throttle выполнит функцию сразу же при первом вызове и, если вы её вызовете снова в течение периода wait, как только этот период закончится. Если вы хотите отключить вызов ведущей части, передайте {leading: false}, а если хотите отключить выполнение в конечной части, передайте
{trailing: false}.

var throttled = _.throttle(updatePosition, 100);
$(window).scroll(throttled);

Если вам нужно отменить запланированное ограничение по времени, вы можете вызвать .cancel() на ограниченной по времени функции.

debounce_.debounce(function, wait, [immediate])
Создаёт и возвращает новую, отложенную версию переданной функции, которая отложит своё выполнение до истечения wait миллисекунд с момента последнего вызова. Полезно для реализации поведения, которое должно произойти после того, как ввод прекратился. Например: рендеринг предварительного просмотра комментария Markdown, перерасчёт макета после того, как окно перестало изменяться в размерах и так далее.

В конце периода wait функция будет вызвана с аргументами, которые были переданы самым последним раз в отложенную функцию.

Передайте true для аргумента immediate, чтобы заставить debounce запустить функцию на ведущем, а не на конечном краю периода wait. Полезно в ситуациях, подобных предотвращению случайных двойных щелчков по кнопке «Отправить», чтобы предотвратить запуск второй раз.

var lazyLayout = _.debounce(calculateLayout, 300);
$(window).resize(lazyLayout);

Если вам нужно отменить запланированную отсрочку, вы можете вызвать .cancel() на отложенной функции.

once_.once(function)
Создаёт версию функции, которую можно вызвать только один раз. Повторные вызовы изменённой функции не имеют эффекта, возвращая значение из оригинального вызова. Полезно для функций инициализации вместо того, чтобы устанавливать флаг булевой переменной и затем проверять его позже.

var initialize = _.once(createApplication);
initialize();
initialize();
// Application is only created once.

after_.after(count, function)
Создаёт обёртку функции, которая ничего не делает с самого начала. Начиная с count-го вызова, она начинает фактически вызывать функцию. Полезно для группировки асинхронных ответов, где вы хотите убедиться, что все асинхронные вызовы завершились, прежде чем продолжать.

var renderNotes = _.after(notes.length, render);
_.each(notes, function(note) {
  note.asyncSave({success: renderNotes});
});
// renderNotes is run once, after all notes have saved.

before_.before(count, function)
Создаёт обёртку функции, которая кэширует её возвращаемое значение. Начиная с count-го вызова, кэшированный результат последнего вызова возвращается сразу же вместо повторного вызова функции. Таким образом, обёртка вызовет функцию не более count - 1 раз.

var monthlyMeeting = _.before(3, askForRaise);
monthlyMeeting();
monthlyMeeting();
monthlyMeeting();
// the result of any subsequent calls is the same as the second call

wrap_.wrap(function, wrapper)
Оборачивает первую функцию внутри wrapper функции, передавая её в качестве первого аргумента. Это позволяет wrapper выполнить код до и после выполнения функции, изменить аргументы и выполнить её условно.

var hello = function(name) { return "hello: " + name; };
hello = _.wrap(hello, function(func) {
  return "before, " + func("moe") + ", after";
});
hello();
=> 'before, hello: moe, after'

negate_.negate(predicate)
Возвращает новую отрицательную версию функции предиката.

var isFalsy = _.negate(Boolean);
_.find([-2, -1, 0, 1, 2], isFalsy);
=> 0

compose_.compose(*functions)
Возвращает композицию списка функций, где каждая функция потребляет возвращаемое значение следующей функции. В математических терминах, композиция функций f(), g() и h() даёт f(g(h())).

var greet    = function(name){ return "hi: " + name; };
var exclaim  = function(statement){ return statement.toUpperCase() + "!"; };
var welcome = _.compose(greet, exclaim);
welcome('moe');
=> 'hi: MOE!'

restArguments_.restArguments(function, [startIndex])
Возвращает версию функции, которая, при вызове, получает все аргументы с и после startIndex, собранные в один массив. Если вы не передадите явное startIndex, оно будет определено по количеству аргументов самой функции. Аналогично синтаксису ES6 rest parameters.

var raceResults = _.restArguments(function(gold, silver, bronze, everyoneElse) {
  _.each(everyoneElse, sendConsolations);
});

raceResults("Dopey", "Grumpy", "Happy", "Sneezy", "Bashful", "Sleepy", "Doc");

Функции объектов

keys_.keys(object)
Возвращает все имена собственных перечисляемых свойств объекта.

_.keys({one: 1, two: 2, three: 3});
=> ["one", "two", "three"]

allKeys_.allKeys(object)
Возвращает все имена собственных и унаследованных свойств объекта.

function Stooge(name) {
  this.name = name;
}
Stooge.prototype.silly = true;
_.allKeys(new Stooge("Moe"));
=> ["name", "silly"]

values_.values(object)
Возвращает все значения собственных свойств объекта.

_.values({one: 1, two: 2, three: 3});
=> [1, 2, 3]

mapObject_.mapObject(object, iteratee, [context])
Подобно map, но для объектов. Преобразует значение каждого свойства по очереди.

_.mapObject({start: 5, end: 12}, function(val, key) {
  return val + 5;
});
=> {start: 10, end: 17}

pairs_.pairs(object)
Преобразует объект в список пар [ключ, значение]. Обратная функция к object.

_.pairs({one: 1, two: 2, three: 3});
=> [["one", 1], ["two", 2], ["three", 3]]

invert_.invert(object)
Возвращает копию объекта, где ключи стали значениями, а значения — ключами. Для этого все значения вашего объекта должны быть уникальными и сериализуемыми в строку.

_.invert({Moe: "Moses", Larry: "Louis", Curly: "Jerome"});
=> {Moses: "Moe", Louis: "Larry", Jerome: "Curly"};

create_.create(prototype, props)
Создаёт новый объект с заданным прототипом, необязательно прикрепляя props в качестве собственных свойств. По сути, Object.create, но без описателей свойств.

var moe = _.create(Stooge.prototype, {name: "Moe"});

функции_.functions(object) Псевдоним: методы
Возвращает отсортированный список имён каждого метода в объекте — то есть имя каждой функциональной (функции) собственности объекта.

_.functions(_);
=> ["all", "any", "bind", "bindAll", "clone", "compact", "compose" ...

findKey_.findKey(object, predicate, [context])
Аналогично _.findIndex, но для ключей в объектах. Возвращает ключ, где предикат истинен, или undefined. predicate преобразуется через iteratee для удобства использования кратких синтаксисов.

extend_.extend(destination, *sources)
Поверхностно копирует все свойства из источника в назначение, и возвращает назначение. Вложенные объекты или массивы будут скопированы по ссылке, а не дублированы. Порядок важен: последний источник переопределяет свойства с тем же именем в предыдущих аргументах.

_.extend({name: 'moe'}, {age: 50});
=> {name: 'moe', age: 50}

extendOwn_.extendOwn(destination, *sources) Псевдоним: assign
Как extend, но копирует только собственные свойства в целевой объект.

pick_.pick(object, *keys)
Возвращает копию объекта, отфильтрованную, чтобы содержать только значения для разрешённых ключей (или массива допустимых ключей). В качестве альтернативы принимает предикат, указывающий, какие ключи выбрать.

_.pick({name: 'moe', age: 50, userid: 'moe1'}, 'name', 'age');
=> {name: 'moe', age: 50}
_.pick({name: 'moe', age: 50, userid: 'moe1'}, function(value, key, object) {
  return _.isNumber(value);
});
=> {age: 50}

omit_.omit(object, *keys)
Возвращает копию объекта, отфильтрованную, чтобы исключить запрещённые ключи (или массив ключей). В качестве альтернативы принимает предикат, указывающий, какие ключи исключить.

_.omit({name: 'moe', age: 50, userid: 'moe1'}, 'userid');
=> {name: 'moe', age: 50}
_.omit({name: 'moe', age: 50, userid: 'moe1'}, function(value, key, object) {
  return _.isNumber(value);
});
=> {name: 'moe', userid: 'moe1'}

defaults_.defaults(object, *defaults)
Возвращает объект после заполнения его свойств undefined первым значением из следующего списка defaults объектов.

var iceCream = {flavor: "chocolate"};
_.defaults(iceCream, {flavor: "vanilla", sprinkles: "lots"});
=> {flavor: "chocolate", sprinkles: "lots"}

clone_.clone(object)
Создаёт поверхностную копию простого объекта. Любые вложенные объекты или массивы будут скопированы по ссылке, а не дублированы.

_.clone({name: 'moe'});
=> {name: 'moe'};

tap_.tap(object, interceptor)
Вызывает interceptor с объектом, а затем возвращает объект. Основное назначение этого метода — "вставить" в цепочку методов, чтобы выполнить операции над промежуточными результатами в цепочке.

_.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]

toPath_.toPath(path)
Убеждается, что path является массивом. Если path — строка, она оборачивается в массив с одним элементом; если это уже массив, он возвращается без изменений.

_.toPath('key');
=> ['key']
_.toPath(['a', 0, 'b']);
=> ['a', 0, 'b'] // (same array)

_.toPath используется внутри has, get, invoke, property, propertyOf и result, а также в iteratee и всех зависимых от него функциях для нормализации путей глубоких свойств. Вы можете переопределить _.toPath, если хотите настроить это поведение, например, для включения лодашовских сокращённых путей в строках. Имейте в виду, что изменение _.toPath неизбежно приведёт к тому, что некоторые ключи станут недоступны; переопределяйте на свой страх и риск.

// Support dotted path shorthands.
var originalToPath = _.toPath;
_.mixin({
  toPath: function(path) {
    return _.isString(path) ? path.split('.') : originalToPath(path);
  }
});
_.get({a: [{b: 5}]}, 'a.0.b');
=> 5

get_.get(object, path, [default])
Возвращает указанное свойство объекта. path может быть указан как простой ключ или как массив ключей объекта или индексов массива для глубокого извлечения свойств. Если свойство не существует или равно undefined, возвращается необязательный default.

_.get({a: 10}, 'a');
=> 10
_.get({a: [{b: 2}]}, ['a', 0, 'b']);
=> 2
_.get({a: 10}, 'b', 100);
=> 100

has_.has(object, key)
Содержит ли объект данный ключ? Идентично object.hasOwnProperty(key), но использует безопасную ссылку на функцию hasOwnProperty на случай, если она была случайно переопределена.

_.has({a: 1, b: 2, c: 3}, "b");
=> true

property_.property(path)
Возвращает функцию, которая будет возвращать указанное свойство любого переданного объекта. path может быть указан как простой ключ или как массив ключей объекта или индексов массива для глубокого извлечения свойств.

var stooge = {name: 'moe'};
'moe' === _.property('name')(stooge);
=> true

var stooges = {moe: {fears: {worst: 'Spiders'}}, curly: {fears: {worst: 'Moe'}}};
var curlysWorstFear = _.property(['curly', 'fears', 'worst']);
curlysWorstFear(stooges);
=> 'Moe'

propertyOf_.propertyOf(object)
Обратная функция к _.property. Принимает объект и возвращает функцию, которая вернёт значение указанного свойства.

var stooge = {name: 'moe'};
_.propertyOf(stooge)('name');
=> 'moe'

matcher_.matcher(attrs) Псевдоним: matches
Возвращает предикатную функцию, которая покажет, содержит ли переданный объект все пары ключ/значение из attrs.

var ready = _.matcher({selected: true, visible: true});
var readyToGoList = _.filter(list, ready);

isEqual_.isEqual(object, other)
Выполняет оптимизированное глубокое сравнение двух объектов, чтобы определить, равны ли они.

var stooge = {name: 'moe', luckyNumbers: [13, 27, 34]};
var clone  = {name: 'moe', luckyNumbers: [13, 27, 34]};
stooge == clone;
=> false
_.isEqual(stooge, clone);
=> true

isMatch_.isMatch(object, properties)
Указывает, содержатся ли ключи и значения в properties в объекте.

var stooge = {name: 'moe', age: 32};
_.isMatch(stooge, {age: 32});
=> true

isEmpty_.isEmpty(collection)
Возвращает true, если collection не имеет элементов. Для строк и массивоподобных объектов _.isEmpty проверяет, равно ли свойство длины 0. Для других объектов он возвращает true, если объект не имеет перечисляемых собственных свойств. Заметьте, что примитивные числа, булевы значения и символы всегда пустые по этому определению.

_.isEmpty([1, 2, 3]);
=> false
_.isEmpty({});
=> true

isElement_.isElement(object)
Возвращает true, если объект является элементом DOM.

_.isElement(jQuery('body')[0]);
=> true

isArray_.isArray(object)
Возвращает true, если объект является массивом.

(function(){ return _.isArray(arguments); })();
=> false
_.isArray([1,2,3]);
=> true

isObject_.isObject(value)
Возвращает true, если значение является объектом. Обратите внимание, что массивы JavaScript и функции являются объектами, в то время как (обычные) строки и числа таковыми не являются.

_.isObject({});
=> true
_.isObject(1);
=> false

isArguments_.isArguments(object)
Возвращает true, если объект является объектом Arguments.

(function(){ return _.isArguments(arguments); })(1, 2, 3);
=> true
_.isArguments([1,2,3]);
=> false

isFunction_.isFunction(object)
Возвращает true, если объект является функцией.

_.isFunction(alert);
=> true

isString_.isString(object)
Возвращает true, если объект является строкой.

_.isString("moe");
=> true

isNumber_.isNumber(object)
Возвращает true, если объект является числом (включая NaN).

_.isNumber(8.4 * 5);
=> true

isFinite_.isFinite(object)
Возвращает true, если объект является конечным числом.

_.isFinite(-101);
=> true

_.isFinite(-Infinity);
=> false

isBoolean_.isBoolean(object)
Возвращает true, если объект равен true или false.

_.isBoolean(null);
=> false

isDate_.isDate(object)
Возвращает true, если объект является датой.

_.isDate(new Date());
=> true

isRegExp_.isRegExp(object)
Возвращает true, если объект является регулярным выражением.

_.isRegExp(/moe/);
=> true

isError_.isError(object)
Возвращает true, если объект унаследован от Error.

try {
  throw new TypeError("Example");
} catch (o_O) {
  _.isError(o_O);
}
=> true

isSymbol_.isSymbol(object)
Возвращает true, если объект является символом.

_.isSymbol(Symbol());
=> true

isMap_.isMap(object)
Возвращает true, если объект является Map.

_.isMap(new Map());
=> true

isWeakMap_.isWeakMap(object)
Возвращает true, если объект является WeakMap.

_.isWeakMap(new WeakMap());
=> true

isSet_.isSet(object)
Возвращает true, если объект является Set.

_.isSet(new Set());
=> true

isWeakSet_.isWeakSet(object)
Возвращает true, если объект является WeakSet.

_.isWeakSet(WeakSet());
=> true

isArrayBuffer_.isArrayBuffer(object)
Возвращает true, если объект является ArrayBuffer.

_.isArrayBuffer(new ArrayBuffer(8));
=> true

isDataView_.isDataView(object)
Возвращает true, если объект является DataView.

_.isDataView(new DataView(new ArrayBuffer(8)));
=> true

isTypedArray_.isTypedArray(object)
Возвращает true, если объект является TypedArray.

_.isTypedArray(new Int8Array(8));
=> true

isNaN_.isNaN(object)
Возвращает true, если объект равен NaN.
Примечание: это не то же самое, что встроенная функция isNaN, которая также вернёт true для многих других значений, не являющихся числами, таких как undefined.

_.isNaN(NaN);
=> true
isNaN(undefined);
=> true
_.isNaN(undefined);
=> false

isNull_.isNull(object)
Возвращает true, если значение объекта равно null.

_.isNull(null);
=> true
_.isNull(undefined);
=> false

isUndefined_.isUndefined(value)
Возвращает true, если значение равно undefined.

_.isUndefined(window.missingVariable);
=> true

Функции утилиты

noConflict_.noConflict()
Возвращает контроль над глобальной переменной _ предыдущему владельцу. Возвращает ссылку на объект Underscore.

var underscore = _.noConflict();

Функция _.noConflict отсутствует, если вы используете систему модулей EcmaScript 6, AMD или CommonJS для импорта Underscore.

identity_.identity(value)
Возвращает то же значение, что и переданное в качестве аргумента. В математике: f(x) = x
Эта функция кажется бесполезной, но используется в Underscore в качестве значения по умолчанию для итератора.

var stooge = {name: 'moe'};
stooge === _.identity(stooge);
=> true

constant_.constant(value)
Создаёт функцию, которая возвращает то же значение, что и переданное в качестве аргумента функции _.constant.

var stooge = {name: 'moe'};
stooge === _.constant(stooge)();
=> true

noop_.noop()
Возвращает undefined, независимо от переданных в неё аргументов. Полезно в качестве значения по умолчанию для необязательных аргументов обратного вызова.

obj.initialize = _.noop;

times_.times(n, iteratee, [context])
Вызывает переданную функцию-итератор n раз. Каждый вызов итератора вызывается с аргументом index. Возвращает массив из возвращаемых значений.

_.times(3, function(n){ genie.grantWishNumber(n); });

random_.random(min, max)
Возвращает случайное целое число между min и max включительно. Если вы передаёте только один аргумент, возвращает число между 0 и этим числом.

_.random(0, 100);
=> 42

mixin_.mixin(object)
Позволяет расширить Underscore своими собственными функциями утилиты. Передайте хеш {name: function} определений, чтобы добавить ваши функции в объект Underscore, а также в оберточку OOP. Возвращает объект Underscore для облегчения цепочки вызовов.

_.mixin({
  capitalize: function(string) {
    return string.charAt(0).toUpperCase() + string.substring(1).toLowerCase();
  }
});
_("fabio").capitalize();
=> "Fabio"

iteratee_.iteratee(value, [context])
Создаёт функцию обратного вызова, которая может быть применена к каждому элементу коллекции. _.iteratee поддерживает ряд сокращённых синтаксисов для распространённых случаев использования обратного вызова. В зависимости от типа value, _.iteratee вернёт:

// No value
_.iteratee();
=> _.identity()

// Function
_.iteratee(function(n) { return n * 2; });
=> function(n) { return n * 2; }

// Object
_.iteratee({firstName: 'Chelsea'});
=> _.matcher({firstName: 'Chelsea'});

// Anything else
_.iteratee('firstName');
=> _.property('firstName');

Следующие методы Underscore преобразуют свои предикаты через _.iteratee: countBy, every, filter, find, findIndex, findKey, findLastIndex, groupBy, indexBy, map, mapObject, max, min, partition, reject, some, sortBy, sortedIndex и uniq

Вы можете перезаписать _.iteratee своей пользовательской функцией, если хотите дополнительные или другие сокращённые синтаксисы:

// Support `RegExp` predicate shorthand.
var builtinIteratee = _.iteratee;
_.iteratee = function(value, context) {
  if (_.isRegExp(value)) return function(obj) { return value.test(obj) };
  return builtinIteratee(value, context);
};

uniqueId_.uniqueId([prefix])
Генерирует глобально уникальный идентификатор для клиентских моделей или элементов DOM, которые его нуждаются. Если передан prefix, id будет добавлен к нему.

_.uniqueId('contact_');
=> 'contact_104'

escape_.escape(string)
Экранирует строку для вставки в HTML, заменяя символы &, <, >, ", ` и '.

_.escape('Curly, Larry & Moe');
=> "Curly, Larry & Moe"

unescape_.unescape(string)
Обратная функция escape, заменяет &amp;, &lt;, &gt;, &quot;, &#96; и &#x27; на их неэкранированные аналоги.

_.unescape('Curly, Larry & Moe');
=> "Curly, Larry & Moe"

result_.result(object, property, [defaultValue])
Если значение указанного свойства является функцией, вызовите её с объектом в качестве контекста; в противном случае верните его. Если предоставлено значение по умолчанию и свойство не существует или равно undefined, вернётся значение по умолчанию. Если defaultValue является функцией, вернётся результат её выполнения.

var object = {cheese: 'crumpets', stuff: function(){ return 'nonsense'; }};
_.result(object, 'cheese');
=> "crumpets"
_.result(object, 'stuff');
=> "nonsense"
_.result(object, 'meat', 'ham');
=> "ham"

now_.now()
Возвращает целочисленную метку времени для текущего момента, используя самый быстрый доступный метод в среде выполнения. Полезно для реализации функций тайминга/анимации.

_.now();
=> 1392066795351

template_.template(templateString, [settings])
Компилирует JavaScript-шаблоны в функции, которые могут быть оценены для рендеринга. Полезно для рендеринга сложных фрагментов HTML из источников данных JSON. Функции шаблонов могут интерполировать значения, используя <%= … %>, а также выполнять произвольный JavaScript-код, используя <% … %>. Если вы хотите интерполировать значение и сделать его HTML-экранированным, используйте <%- … %>. При вычислении функции шаблона передайте объект данных с имеющимися свойствами, соответствующими свободным переменным шаблона. Аргумент параметры должен быть хешем, содержащим любые _.templateSettings, которые должны быть переопределены.

var compiled = _.template("hello: <%= name %>");
compiled({name: 'moe'});
=> "hello: moe"

var template = _.template("<b><%- value %></b>");
template({value: '<script>'});
=> "<b>&lt;script&gt;</b>"

Вы также можете использовать print изнутри JavaScript-кода. Это иногда удобнее, чем использование <%= ... %>.

var compiled = _.template("<% print('Hello ' + epithet); %>");
compiled({epithet: "stooge"});
=> "Hello stooge"

Если разделители в стиле ERB вам не подходят, вы можете изменить настройки шаблонов Underscore, чтобы использовать разные символы для обозначения интерполируемого кода. Определите регулярное выражение interpolate для соответствия выражениям, которые должны быть интерполированы дословно, регулярное выражение escape для соответствия выражениям, которые должны быть вставлены после HTML-экранирования, и регулярное выражение evaluate для соответствия выражениям, которые должны быть оценены без вставки в результирующую строку. Обратите внимание, что если часть вашего шаблона соответствует более чем одному из этих регулярных выражений, первое будет применено в следующем порядке приоритетов: (1) escape, (2) interpolate, (3) evaluate. Вы можете определить или опустить любую комбинацию из трёх. Например, для выполнения шаблонизации в стиле Mustache.js:

_.templateSettings = {
  interpolate: /\{\{(.+?)\}\}/g
};

var template = _.template("Hello {{ name }}!");
template({name: "Mustache"});
=> "Hello Mustache!"

По умолчанию шаблон помещает значения из ваших данных в локальную область видимости с помощью оператора with. Однако вы можете указать имя одной переменной с помощью настройки variable. Это может значительно повысить скорость рендеринга шаблона.

_.template("Using 'with': ", {variable: 'data'})({answer: 'no'});
=> "Using 'with': no"

Предварительная компиляция шаблонов может быть очень полезна при отладке ошибок, которые невозможно воспроизвести. Это связано с тем, что предварительно скомпилированные шаблоны могут предоставлять номера строк и стек вызовов, чего невозможно добиться при компиляции шаблонов на клиенте. Свойство source доступно в скомпилированной функции шаблона для упрощения предварительной компиляции.

<script>
  JST.project = ;
</script>

Объектно-ориентированный стиль

Вы можете использовать Underscore в объектно-ориентированном или функциональном стиле, в зависимости от ваших предпочтений. Следующие две строки кода являются идентичными способами удвоить список чисел.

_.map([1, 2, 3], function(n){ return n * 2; });
_([1, 2, 3]).map(function(n){ return n * 2; });

Цепочки вызовов

Вызов chain заставит все последующие вызовы методов возвращать обернутые объекты. Когда вы завершите вычисление, вызовите value, чтобы получить окончательное значение. Вот пример цепочки map/flatten/reduce, чтобы получить количество слов в каждой строке песни.

var lyrics = [
  {line: 1, words: "I'm a lumberjack and I'm okay"},
  {line: 2, words: "I sleep all night and I work all day"},
  {line: 3, words: "He's a lumberjack and he's okay"},
  {line: 4, words: "He sleeps all night and he works all day"}
];

_.chain(lyrics)
  .map(function(line) { return line.words.split(' '); })
  .flatten()
  .reduce(function(counts, word) {
    counts[word] = (counts[word] || 0) + 1;
    return counts;
  }, {})
  .value();

=> {lumberjack: 2, all: 4, night: 2 ... }

Кроме того, методы прототипа массива Array prototype's methods проксируются через обернутый объект Underscore, поэтому вы можете вставить reverse или push в свою цепочку и продолжать изменять массив.

chain_.chain(obj)
Возвращает обернутый объект. Вызов методов этого объекта будет продолжать возвращать обернутые объекты до вызова value.

var stooges = [{name: 'curly', age: 25}, {name: 'moe', age: 21}, {name: 'larry', age: 23}];
var youngest = _.chain(stooges)
  .sortBy(function(stooge){ return stooge.age; })
  .map(function(stooge){ return stooge.name + ' is ' + stooge.age; })
  .first()
  .value();
=> "moe is 21"

value_.chain(obj).value()
Извлекает значение обернутого объекта.

_.chain([1, 2, 3]).reverse().value();
=> [3, 2, 1]