Array.prototype.find()

Метод find() повертає значення першого елемента в масиві, що задовільняє передану функцію тестування. Інакше вертається undefined.

The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.

Зверніть увагу також на метод findIndex(), що натомість повертає індекс знайденого елемента масиву, а не значення.

Якщо вам необхідно знайти позицію елемента або дізнатись, чи існує елемент в масиві, використовуйте Array.prototype.indexOf() або Array.prototype.includes().

arr.find(callback(element[, index[, array]])[, thisArg])

callback

Функція, що виконується для кожного значення в масиві і приймає три аргументи:

element

Значення поточного елемента масиву.

indexOptional

Індекс поточного елемента масиву.

arrayOptional

Масив, для якого було викликано find.

thisArg Optional

Необов'язковий об'єкт, що використовується в якості this при виконанні callback.

Значення першого елемента в масиві, який задовольняє надану перевірочну функцію. Інакше повертається undefined.

Метод find виконує функцію callback один раз для кожного елемента в масиві, аж поки не буде знайдено такий, для якого callback повертає правдиве значення. Щойно такий елемент знайдено, find одразу ж повертає значення цього елемента. В іншому випадку, find  повертає undefined. Функція callback викликається для кожного індексу масиву з 0 по length - 1 і виконується для усіх елементів, не лише для тих, які мають присвоєні значення. Це означає, що цей метод може бути менш ефективним для розріджених масивів у порівнянні з методами, які обробляють лише ті, елементи, яким присвоєні значення.

Функція callback викликається з трьома аргументами: значення елемента, індекс елемента і об'єкт Array, перебір якого здійснюється.

Якщо параметр thisArg передано до find, його буде використано як this для кожного виклику callback. Якщо його не передано, тоді використовуватиметься undefined.

Метод find() не змінює масив, для якого викликається.

Діапазон елементів, що їх має обробити find, визначається ще до першого виклику функції callback. Тому callback не обробляє елементи, додані до масиву після того, як почалося виконання find. Якщо існуючий, ще не опрацьований елемент масиву, змінюється функцією callback, його значення, що передається до callback, буде значенням на той момент, коли find доходить до індексу цього елемента. Видалені елементи все одно опрацьовуються.

var inventory = [
    {name: 'яблука', quantity: 2},
    {name: 'банани', quantity: 0},
    {name: 'вишні', quantity: 5}
];

function findCherries(fruit) {
    return fruit.name === 'вишні';
}

console.log(inventory.find(findCherries));
// виводить { name: 'вишні', quantity: 5 }

Використання стрілочної функції ES2015

const inventory = [
    {name: 'яблука', quantity: 2},
    {name: 'банани', quantity: 0},
    {name: 'вишні', quantity: 5}
];

const result = inventory.find( fruit => fruit.name === 'вишні' );

console.log(result) // { name: 'вишні', quantity: 5 }

Наступний приклад знаходить елемент у масиві, який є простим числом (або повертає undefined, якщо простого числа немає):

function isPrime(element, index, array) {
  var start = 2;
  while (start <= Math.sqrt(element)) {
    if (element % start++ < 1) {
      return false;
    }
  }
  return element > 1;
}

[4, 6, 8, 12].find(isPrime);  // вертає undefined, простих чисел не знайдено
[4, 5, 8, 12].find(isPrime);  // вертає 5

Наступні приклади демонструють, що неіснуючі та видалені елементи теж опрацьовуються, і що значення, передане до функції зворотного виклику - це їхнє значення на момент перевірки.

// Створити масив без елементів за індексами 2, 3 та 4
const array = [0,1,,,,5,6];

// Виводить всі індекси, не лише ті, які мають присвоєні значення
array.find(function(value, index) {
  console.log('Індекс ' + index + ' має значення ' + value);
});

// Виводить всі індекси, в тому числі видалені
array.find(function(value, index) {

  // Видалити елемент 5 в першій ітерації
  if (index == 0) {
    console.log('Видалення елемента array[5] зі значенням ' + array[5]);
    delete array[5];
  }
  // Елемент 5 перевіряється, хоч і був видалений
  console.log('Індекс ' + index + ' має значення ' + value);
});
// очікуваний результат:
// Видалення елемента array[5] зі значенням 5
// Індекс 0 має значення 0
// Індекс 1 має значення 1
// Індекс 2 має значення undefined
// Індекс 3 має значення undefined
// Індекс 4 має значення undefined
// Індекс 5 має значення undefined
// Індекс 6 має значення 6

Цей метод був доданий у ECMAScript 2015, тож, можливо, поки наявний не у всякій реалізації JavaScript. Проте, ви можете використати наступний код для забезпечення запасного варіанту Array.prototype.find:

// https://tc39.github.io/ecma262/#sec-array.prototype.find
if (!Array.prototype.find) {
  Object.defineProperty(Array.prototype, 'find', {
    value: function(predicate) {
     // 1. Нехай O дорівнює ? ToObject(this value).
      if (this == null) {
        throw new TypeError('"this" is null or not defined');
      }

      var o = Object(this);

      // 2. Нехай len дорівнює ? ToLength(? Get(O, "length")).
      var len = o.length >>> 0;

      // 3. Якщо IsCallable(predicate) дорівнює false, викинути виняток TypeError.
      if (typeof predicate !== 'function') {
        throw new TypeError('предикат має бути функцією');
      }

      // 4. Якщо надано thisArg, нехай T дорівнює thisArg; інакше нехай T дорівнює undefined.
      var thisArg = arguments[1];

      // 5. Нехай k дорівнює 0.
      var k = 0;

      // 6. Повторювати, поки k < len
      while (k < len) {
        // a. Нехай Pk дорівнює ! ToString(k).
        // b. Нехай kValue дорівнює ? Get(O, Pk).
        // c. Нехай testResult дорівнює ToBoolean(? Call(predicate, T, « kValue, k, O »)).
        // d. Якщо testResult дорівнює true, повернути kValue.
        var kValue = o[k];
        if (predicate.call(thisArg, kValue, k, o)) {
          return kValue;
        }
        // e. Збільшити k на 1.
        k++;
      }

      // 7. Повернути undefined.
      return undefined;
    }
  });
}

Якщо вам потрібно забезпечити підтримку вкрай застарілих рушіїв JavaScript, в яких відсутня підтримка Object.defineProperty, було б краще взагалі не додавати методів до Array.prototype через відсутність можливості заборонити їх перебір.

• Array.prototype.findIndex()
• Array.prototype.every()