Array.prototype.find()
======================

**`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 with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Array.prototype.find` のポリフィル (`core-js`)
* インデックス付きコレクションのガイド
* `Array`
* `Array.prototype.findIndex()`
* `Array.prototype.findLast()`
* `Array.prototype.findLastIndex()`
* `Array.prototype.includes()`
* `Array.prototype.filter()`
* `Array.prototype.every()`
* `Array.prototype.some()`
* `TypedArray.prototype.find()`