Array.prototype.find()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2016.

find() は Array インスタンスのメソッドで、提供されたテスト関数を満たす配列内の最初の要素を返します。 テスト関数を満たす値がない場合は、 undefined を返します。

  • 配列内で見つかった要素のインデックスが必要な場合は、findIndex() を使用してください。
  • 値のインデックスを検索する必要がある場合は、indexOf() を使用してください。(findIndex() と似ていますが、それぞれの要素の等価性はテスト関数ではなく値でチェックします。)
  • 配列内に値が存在するかどうかを調べる必要がある場合は、 includes() を使用してください。
  • 指定したテスト関数を満たす要素があるかどうかを調べる必要がある場合は、 some() を使用してください。

試してみましょう

構文

js
find(callbackFn)
find(callbackFn, thisArg)

引数

callbackFn

配列のそれぞれの要素に対して実行する関数です。一致する要素が得られたことを示すには真値を返し、そうでなければ偽値を返してください。この関数は以下の引数で呼び出されます。

element

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

index

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

array

find() を呼び出した元の配列です。

thisArg 省略可

callbackFn 内で this として使われるオブジェクトです。反復処理メソッドを参照してください。

返値

配列の中で、提供されたテスト関数を満たす最初の要素です。 見つからなかった場合は undefined を返します。

解説

find() メソッドは反復処理メソッドです。配列の要素のそれぞれに対して、インデックスの昇順に一度ずつ callbackFn 関数を実行し、callbackFn 関数が真値を返すまで繰り返します。 find() はその要素を返し、配列の反復処理を停止します。もし callbackFn が真値を返さない場合、 find() は undefined を返します。

callbackFn は、値が割り当てられているものに限らず、配列中のすべてのインデックスに対して呼び出されます。疎配列では、空のスロットは undefined と同じ動作をします。

find() は、呼び出した配列を変更 (mutate) しませんが、callbackFn で提供された関数は変更する可能性があります。しかし、配列の長さは最初に callbackFn が呼び出される前に設定されます。したがって、

  • callbackFn は find() の呼び出しを始めたときの配列の長さを超えて追加された要素にはアクセスしません。
  • 既に訪問した位置を変更しても、 callbackFn が再度呼び出されることはありません。
  • まだ訪問していない既存の配列要素が callbackFn によって変更された場合、 callbackFn に渡される値はその要素が取得される時点の値になります。削除された 要素は undefined であるかのように処理されます。

警告: 上で説明したような同時進行の変更は、理解しにくいコードになることが多いので、（特別な場合を除いて）避けるのが一般的です。

find() メソッドは汎用的です。これは this 値に length プロパティと整数キーのプロパティがあることだけを期待します。

例

配列内のオブジェクトをプロパティの一つで検索

js
const 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 }

アロー関数と分割代入の使用

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

const result = inventory.find(({ name }) => name === "cherries");

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

配列内の素数の検索

次の例は、配列内の素数を探します（配列内に素数が見つからない場合は undefined を返します）。

js
function isPrime(element, index, array) {
  let 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, 見つからない
console.log([4, 5, 8, 12].find(isPrime)); // 5

疎配列における find() の使用

疎配列の空のスロットは処理され、 undefined と同じように扱われます。

js
// インデックスが 2, 3, 4 の位置に要素がない配列を宣言
const array = [0, 1, , , , 5, 6];

// 値が割り当てられているものに限らず、すべてのインデックスを表示
array.find((value, index) => {
  console.log("Visited index", index, "with value", value);
});
// 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 5
// Visited index 6 with value 6

// 削除されたものを含め、すべてのインデックスを表示
array.find((value, index) => {
  // 最初の反復処理で要素 5 を削除
  if (index === 0) {
    console.log("Deleting array[5] with value", array[5]);
    delete array[5];
  }
  // 要素 5 は削除されたが、なお処理対象となる
  console.log("Visited index", index, "with value", value);
});
// 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

配列でないオブジェクトに対する find() の呼び出し

find() メソッドは this の length プロパティを読み込み、次にキーが length より小さい非負の整数である各プロパティにアクセスします。

js
const arrayLike = {
  length: 3,
  "-1": 0.1, // -1 < 0 であるため find() からは無視される
  0: 2,
  1: 7.3,
  2: 4,
};
console.log(Array.prototype.find.call(arrayLike, (x) => !Number.isInteger(x)));
// 7.3

仕様書

Specification
ECMAScript Language Specification
# sec-array.prototype.find

ブラウザーの互換性

BCD tables only load in the browser

関連情報