Array.prototype.find()

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

function isBigEnough(element) {
  return element >= 15;
}

[12, 5, 8, 130, 44].find(isBigEnough);  // 130

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

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

Синтаксис

arr.find(callback[, thisArg])

Параметри

callback

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

element

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

index

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

array

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

thisArg Optional

Об'єкт який використовувати як this коли виконується callback.

Вертає

Значення в масиві якщо елемент проходить тест; в іншому випадку, undefined.

Опис

Метод find() виконує callback функцію один раз для кожного елементу в масиві, аж поки не буде знайдено такий, для якого callback повертає значення true. Щойно такий елемент знайдено, find() одразу ж повертає значення цього елементу. В іншому випадку, find() повертає undefined. Функція callback викликається лише для тих індексів масиву, які мають присвоєне значення; вона ніколи не викликається для тих індексів які було видалено або які ніколи не мали присвоєного значення.

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

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

Власне метод find() не змінює масив для на якому він викликаний. Але ніщо не завадить зробити якісь зміни з функції callback.

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

var arr = [111, 222, 333];
var visited = [];

var found = arr.find(function(value, index, array) {
  array.push(999);
  visited.push(value);
  return false;
});

console.log(found);    // виводить undefined
console.log(arr);      // виводить [111, 222, 333, 999, 999, 999]
console.log(visited);  // виводить [111, 222, 333]

Якщо наявні від початку, але ще не відвідані, елементи змінити з функції callback, зміни буде враховано:

var arr = ['old-1', 'old-2', 'old-3'];

var found = arr.find(function(value, index, array) {
  if (index === 1) {
    array[2] = 'new';
  }
  return value === 'new';
});

console.log(found);  // виводить 'new'
console.log(arr);    // ['old-1', 'old-2', 'new']

Втім, змінювання значення елементу під час його відвідин, не вплине на перебіг виконання find():

var arr = ['old-1', 'old-2', 'old-3'];

var found = arr.find(function(value, index, array) {
  if (value === 'old-2') {
    array[index] = 'new';
    return true;
  }

  return false;
});

console.log(found);  // виводить 'old-2'
console.log(arr);    // ['old-1', 'new', 'old-3']

Більш того, видалені елементи все одно буде відвідано:

var arr = [111, 222, 333, 444, 555, 666];
var visited = [];

var found = arr.find(function(value, index, array) {
  visited.push(value);
  if (value === 222) {
    delete array[2];       // 333
    array[4] = undefined;  // 555
  }
  return false;
});

console.log(found);    // виводить undefined
console.log(arr);      // [111, 222, undefined, 444, undefined, 666]
console.log(visited);  // [111, 222, undefined, 444, undefined, 666]

Приклади

Знайти об'єкт в масиві за однією з його властивостей

var inventory = [
    {name: 'apples', quantity: 2},
    {name: 'bananas', quantity: 0},
    {name: 'cherries', quantity: 5}
];

function findCherries(fruit) { 
    return fruit.name === 'cherries';
}

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

Знайти просте число в масиві

Наступний приклад знаходить елемент в масиві, який є простим числом (або повертає 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

Запасний варіант (поліфіл)

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

// https://tc39.github.io/ecma262/#sec-array.prototype.find
if (!Array.prototype.find) {
  Object.defineProperty(Array.prototype, 'find', {
    value: function(predicate) {
     // 1. Let O be ? ToObject(this value).
      if (this == null) {
        throw new TypeError('"this" is null or not defined');
      }

      var o = Object(this);

      // 2. Let len be ? ToLength(? Get(O, "length")).
      var len = o.length >>> 0;

      // 3. If IsCallable(predicate) is false, throw a TypeError exception.
      if (typeof predicate !== 'function') {
        throw new TypeError('predicate must be a function');
      }

      // 4. If thisArg was supplied, let T be thisArg; else let T be undefined.
      var thisArg = arguments[1];

      // 5. Let k be 0.
      var k = 0;

      // 6. Repeat, while k < len
      while (k < len) {
        // a. Let Pk be ! ToString(k).
        // b. Let kValue be ? Get(O, Pk).
        // c. Let testResult be ToBoolean(? Call(predicate, T, « kValue, k, O »)).
        // d. If testResult is true, return kValue.
        var kValue = o[k];
        if (predicate.call(thisArg, kValue, k, o)) {
          return kValue;
        }
        // e. Increase k by 1.
        k++;
      }

      // 7. Return undefined.
      return undefined;
    }
  });
}

Специфікації

Підтримка веб-переглядачами

Див. також

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