Array.prototype.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() メソッドも参照してください。このメソッドは、配列内で見つかった要素の値ではなく、インデックス を返します。

If you need to find the position of an element or whether an element exists in an array, use Array.prototype.indexOf() or Array.prototype.includes().

構文

arr.find(callback[, thisArg])

引数

callback

配列内の各要素に対して実行する関数です。3 個の引数を取ります:

element

配列内で現在処理されている要素。

indexOptional

配列内で現在処理されている要素のインデックス。

arrayOptional

find を呼び出した元の配列。

thisArg Optional

任意。callback が実行される時に this として使われるオブジェクト。

Return value

A value in the array if an element passes the test; otherwise, undefined.

説明

find メソッドは、callback 関数が true を返す要素が見つかるまで、配列内の各要素に対して callback 関数を実行します。そのような要素が見つかると、find はすぐにその要素の値を返します。配列内に見つからなければ、find は undefined を返します。callback 関数は、値が割り当てられた配列のインデックスに対してのみ実行されます。 削除されたものや割り当てられていないインデックスに対しては実行されません。

callback は、要素の値、要素のインデックス、検索される Array オブジェクトの 3 個の引数で呼び出されます。

find に thisArg 引数を与えた場合、各 callback の呼び出し時に、その与えたオブジェクトが、this として使用されます。この引数を省略した場合、this は undefined になります。

find は、呼び出した配列を変更 (mutate) しません。

find によって処理される要素の範囲は callback の最初の呼び出し前に設定されます。find を呼び出した後に追加された配列の要素は、callback の実行対象になりません。既存のまだ処理されていない配列要素が callback により変更された場合、その要素が処理されるときに callback に渡される値は find がその要素のインデックスにアクセスした時点の値(訳注:要するに変更後の値)になります。削除された要素は処理の対象になりません。

例

Find an object in an array by one of its properties

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

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

console.log(inventory.find(isCherries)); 
// { name: 'cherries', quantity: 5 }

Using ES6 arrow function

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

const result = inventory.find( fruit => fruit.name === 'cherries' );

console.log(result) // { name: 'cherries', 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;
}

console.log([4, 6, 8, 12].find(isPrime)); // undefined, not found
console.log([4, 5, 8, 12].find(isPrime)); // 5

The following examples show that non-existent and deleted elements are visited and that the value passed to the callback is their value when visited.

// Declare array with no element at index 2, 3 and 4
var array = [0,1,,,,5,6];

// Shows all indexes, not just those that have been assigned values
array.find(function(value, index) {
  console.log('Visited index ' + index + ' with value ' + value); 
});

// Shows all indexes, including deleted
array.find(function(value, index) {

  // Delete element 5 on first iteration
  if (index == 0) {
    console.log('Deleting array[5] with value ' + array[5]);
    delete array[5];
  }
  // Element 5 is still visited even though deleted
  console.log('Visited index ' + index + ' with value ' + value); 
});
// expected output:
// Deleting array[5] with value 5 
// Visited index 0 with value 0 
// Visited index 1 with value 1 
// Visited index 2 with value undefined 
// Visited index 3 with value undefined 
// Visited index 4 with value undefined 
// Visited index 5 with value undefined 
// Visited index 6 with value 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. 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;
    },
    configurable: true,
    writable: true
  });
}

If you need to support truly obsolete JavaScript engines that don't support Object.defineProperty, it's best not to polyfill Array.prototype methods at all, as you can't make them non-enumerable.

仕様

ブラウザ実装状況

関連情報

• Array.prototype.findIndex() – find and return an index
• Array.prototype.includes() – test whether a value exists in the array
• Array.prototype.filter() – find all matching elements
• Array.prototype.every() – test all elements together