String.prototype.isWellFormed() - JavaScript

String.prototype.isWellFormed()
===============================

**`isWellFormed()`** は `String` 値のメソッドで、この文字列に孤立サロゲートがあるかどうかを示す論理値を返します。

構文
--

```js
isWellFormed()
```

### 返値

この文字列に孤立サロゲートがある場合は `true`、そうでなれば `false`。

解説
--

JavaScript の文字列は UTF-16 エンコードです。UTF-16 エンコーディングには「サロゲートペア」の概念があり、UTF-16 文字、Unicode コードポイント、書記素クラスターの節で詳しく紹介されています。

`isWellFormed()` を使うと、文字列が整形式であるかどうか（つまり、孤立サロゲートを含まないかどうか）をテストすることができます。 カスタム実装と比べると、`isWellFormed()` は、エンジンが文字列の内部表現に直接アクセスできるので、より効率的です。 文字列を整形式文字列に変換する必要がある場合は、`toWellFormed()` メソッドを使ってください。 `isWellFormed()` を使うと、整形式でない文字列を整形式文字列とは異なる形で扱うことができ、例えば、エラーを発生させたり、無効としたりすることができます。

例
-

### isWellFormed() の使用

```js
const strings = [
  // 孤立高サロゲート
  "ab\uD800",
  "ab\uD800c",
  // 孤立低サロゲート
  "\uDFFFab",
  "c\uDFFFab",
  // 整形式
  "abc",
  "ab\uD83D\uDE04c",
];

for (const str of strings) {
  console.log(str.isWellFormed());
}
// Logs:
// false
// false
// false
// false
// true
// true
```

### encodeURI() のエラーを回避

`encodeURI` は渡された文字列が整形式でなかった場合にエラーが発生します。これは `isWellFormed()` を使用して、文字列を `encodeURI()` に渡す前に検査することで回避できます。

```js
const illFormed = "https://example.com/search?q=\uD800";

try {
  encodeURI(illFormed);
} catch (e) {
  console.log(e); // URIError: URI malformed
}

if (illFormed.isWellFormed()) {
  console.log(encodeURI(illFormed));
} else {
  console.warn("整形式でない文字列に遭遇しました。"); // 整形式でない文字列に遭遇しました。
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.iswellformed |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.isWellFormed` のポリフィル (`core-js`)
* `String.prototype.toWellFormed()`
* `String.prototype.normalize()`


String.prototype.fontcolor() - JavaScript

String.prototype.fontcolor()
============================

**非推奨:** この機能は非推奨になりました。まだ対応しているブラウザーがあるかもしれませんが、すでに関連するウェブ標準から削除されているか、削除の手続き中であるか、互換性のためだけに残されている可能性があります。使用を避け、できれば既存のコードは更新してください。このページの下部にある互換性一覧表を見て判断してください。この機能は突然動作しなくなる可能性があることに注意してください。

**`fontcolor()`** メソッドは、文字列を `<font>` 要素に埋め込み (`<font color="...">str</font>`)、文字列が指定されたフォント色で表示されるようにする文字列を生成します。

**メモ:** HTML ラッパーメソッドはすべて非推奨となっており、互換性目的のみで標準化されています。`fontcolor()` の場合、`<font>` 要素は HTML5 で廃止されており、今後使用するべきではありません。代わりにウェブ開発者は CSS プロパティを使用してください。

構文
--

```js
fontcolor(color);
```

### 引数

`color`

16 進数の RGB 値または文字列リテラルで色を表す文字列です。 CSS 色リファレンスに、色名の文字列リテラルの一覧があります。

### 返値

開始タグ `<font color="color">` （`color` の中の二重引用符は `"` に置き換えられます）、`str` のテキストが来て、終了タグ `</font>` が来る文字列です。

解説
--

`fontcolor()` メソッド自体は、単純に文字列の部品を検証や正規化せずに接続するだけです。しかし、妥当な `<font>` 要素を作成するには、16 進数の RGB で表現する場合は、 `rrggbb` の書式を使用する必要があります。例えば、サーモン色は red=FA, green=80, blue=72 であるため、サーモン色の RGB 値は "`FA8072`" です。

例
-

### fontcolor() の使用

以下の例は `fontcolor()` メソッドを使用して、 HTML の `<font>` 要素を伴う文字列を生成することで文字列の色を変更しています。

```js
const worldString = "Hello, world";

console.log(`${worldString.fontcolor("red")} is red in this line`);
// '<font color="red">Hello, world</font> is red in this line'

console.log(
  `${worldString.fontcolor("FF00")} is red in hexadecimal in this line`,
);
// '<font color="FF00">Hello, world</font> is red in hexadecimal in this line'
```

`element.style` オブジェクトを使用すると、要素の `style` 属性を使用して、次のようにもっと汎用的に操作することができます。

```js
document.getElementById("yourElemId").style.color = "red";
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.fontcolor |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.fontcolor` のポリフィル (`core-js`)
* `String.prototype.fontsize()`


String.prototype.trimEnd() - JavaScript

String.prototype.trimEnd()
==========================

**`trimEnd()`** メソッドは、元の文字列を変更せずに、文字列の末尾のホワイトスペースを削除した新しい文字列を返します。`trimRight()` はこのメソッドの別名です。

試してみましょう
--------

構文
--

```js
trimEnd()

trimRight()
```

### 返値

`str` の末尾のホワイトスペースを取り除いた新しい文字列です。ホワイトスペースはホワイトスペース文字と改行文字で定義します。

`str` の末尾にホワイトスペースがなかった場合でも、新しい文字列が返されます（基本的には `str` のコピー）。

### 別名

`trim()` が標準化された後、エンジンは標準外の `trimRight` メソッドも実装しました。しかし `padEnd()` との整合を取るため、このメソッドが標準化された際、`trimEnd` という名前が選択されました。ウェブの互換性の理由から、`trimRight` も `trimEnd` の別名として残っており、全く同じ関数オブジェクトを示します。エンジンによっては次のような意味になります。

```js
String.prototype.trimRight.name === "trimEnd";
```

例
-

### trimEnd() の使用

次の例は `str` の末尾から空白を取り除きますが、先頭からは取り除きません。

```js
let str = " foo ";

console.log(str.length); // 8

str = str.trimEnd();
console.log(str.length); // 6
console.log(str); // ' foo'
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.trimend |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.trimEnd` のポリフィル (`core-js`)
* `String.prototype.trim()`
* `String.prototype.trimStart()`


String.prototype.match() - JavaScript

String.prototype.match()
========================

**`match()`** メソッドは、正規表現に対する文字列の照合結果を受け取ります。

試してみましょう
--------

構文
--

```js
match(regexp)
```

### 引数

`regexp`

正規表現オブジェクト、または `Symbol.match` を持つ任意のオブジェクトです。

`regexp` が `RegExp` 以外のオブジェクトであった場合、暗黙的に `RegExp` への変換が `new RegExp(regexp)` を使用して行われます。

一切引数を与えずに `match()` メソッドを使った場合、空文字列 1 つを持つ `Array`、`[""]` が得られます。これは `match(/(?:)/)` と同じになるからです。

### 返値

`Array` を返します。これはグローバル (`g`) フラグの有無によって内容が変わります。一致するものが見つからなかった場合は `null` を返します。

* `g` フラグがあった場合は、正規表現全体に一致したすべての結果を返しますが、キャプチャグループは返しません。
* `g` フラグがなかった場合、最初に完全に一致したものと、それに関するキャプチャグループを返します。この場合、`match()` は `RegExp.prototype.exec()` と同じ結果になります（追加のプロパティ付きの配列）。
解説
--

`String.prototype.match` 自体の実装はとてもシンプルです。引数の文字列を最初の引数として `Symbol.match` メソッドを呼び出すだけです。実際の実装は `RegExp.prototype[@@match]()` から来ています。

* ある文字列が正規表現 `RegExp` に一致するかどうかを知る必要がある場合は、 `RegExp.prototype.test()` を使用してください。
* 一番最初に一致したものだけが欲しい場合は、代わりに `RegExp.prototype.exec()` を使ったほうが良いかもしれません。
* キャプチャグループを取得する場合でグローバルフラグを設定する場合は、 `RegExp.prototype.exec()` を使用してください。

正規表現が渡されたときの `match()` の意味についての詳しい情報は、`RegExp.prototype[@@match]()` を参照してください。

例
-

### match() の使用

以下の例において、 `match()` は `"Chapter"` とそれに続く 1 桁以上の数字、それに続く 0 回以上の小数点と数字を見つけるために使われています。

正規表現が `i` フラグを含んでいるので、大文字と小文字の違いは無視されます。

```js
const str = "For more information, see Chapter 3.4.5.1";
const re = /see (chapter \d+(\.\d)\*)/i;
const found = str.match(re);

console.log(found);
// [
// 'see Chapter 3.4.5.1',
// 'Chapter 3.4.5.1',
// '.1',
// index: 22,
// input: 'For more information, see Chapter 3.4.5.1',
// groups: undefined
// ]
```

上の照合結果では、`'see Chapter 3.4.5.1'` が一致する文字列全体です。 `'Chapter 3.4.5.1'` は `(chapter \d+(\.\d)*)` によって捕捉されました。 `'.1'` は `(\.\d)` によって捕捉された最後の値です。 `index` プロパティ (`22`) は一致する文字列全体の 0 基点のインデックスです。 `input` プロパティは解釈できた元の文字列です。

### match() での global と ignoreCase フラグの使用

以下の例は、 g と i フラグを `match()` で使用した実例です。 `A` から `E` までと、 `a` から `e` までのすべての文字が返され、それぞれが配列の個々の要素に入ります。

```js
const str = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
const regexp = /[A-E]/gi;
const matches = str.match(regexp);

console.log(matches);
// ['A', 'B', 'C', 'D', 'E', 'a', 'b', 'c', 'd', 'e']
```

**メモ:** `String.prototype.matchAll()` とフラグを用いた高度な検索も参照してください。

### 名前付きキャプチャグループの使用

名前付きキャプチャグループに対応しているブラウザーでは、次のコードは `"fox"` または `"cat"` を `animal` という名前のグループに入れます。

```js
const paragraph = "The quick brown fox jumps over the lazy dog. It barked.";

const capturingRegex = /(?<animal>fox|cat) jumps over/;
const found = paragraph.match(capturingRegex);
console.log(found.groups); // {animal: "fox"}
```

### 引数なしの match() の使用

```js
const str = "Nothing will come of nothing.";

str.match(); // returns [""]
```

### RegExp ではないオブジェクトを引数にする

オブジェクトに `Symbol.match` メソッドがある場合、カスタムマッチャーとして使用することができます。 `Symbol.match` の返値が `match()` の返値になります。

```js
const str = "Hmm, this is interesting.";

str.match({
  [Symbol.match](str) {
    return ["Yes, it's interesting."];
  },
}); // returns ["Yes, it's interesting."]
```

### RegExp 以外を引数として取る

正規表現 `regexp` 引数が文字列または数値の場合、`RegExp` に `new RegExp(regexp)` を使用して暗黙的に変換されます。

```js
const str1 =
  "NaN means not a number. Infinity contains -Infinity and +Infinity in JavaScript.";
const str2 =
  "My grandfather is 65 years old and My grandmother is 63 years old.";
const str3 = "The contract was declared null and void.";
str1.match("number"); // "number" は文字列です。 ["number"] を返します。
str1.match(NaN); // NaN の型は数値です。 ["NaN"] を返します。
str1.match(Infinity); // Infinity の方は数値です。 ["Infinity"] を返します。
str1.match(+Infinity); // ["Infinity"] を返します
str1.match(-Infinity); // ["-Infinity"] を返します
str2.match(65); // ["65"] を返します
str2.match(+65); // 正の符号が付いた数値です。 ["65"] を返します
str3.match(null); // ["null"] を返します。
```

特殊文字が適切にエスケープされていないと、予期しない結果になることがあります。

```js
console.log("123".match("1.3")); // [ "123" ]
```

正規表現中の `.` はどのような文字にも一致するので、これは一致します。 ドット文字にのみ一致するようにするには、入力文字列をエスケープする必要があります。

```js
console.log("123".match("1\\.3")); // null
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.match |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.match` のポリフィル (`core-js`) （`Symbol.match` 対応のような現代の動作の実装付き）
* `String.prototype.matchAll()`
* `RegExp`
* `RegExp.prototype.exec()`
* `RegExp.prototype.test()`


String.prototype.charCodeAt() - JavaScript

String.prototype.charCodeAt()
=============================

**`charCodeAt()`** メソッドは、指定された位置にある UTF-16 コード単位を表す `0` から `65535` までの整数を返します。

`charCodeAt()` は常に UTF-16 コード単位の並びとして文字列をインデックスするので、孤立サロゲートを返すかもしれません。コードポイント値全体を取得したい場合は、 `codePointAt()` を使用してください。

試してみましょう
--------

構文
--

```js
charCodeAt(index)
```

### 引数

`index`

返す文字の 0 基点のインデックスです。整数に変換され、`undefined` は 0 に変換されます。

### 返値

`0` から `65535` までの整数を返します。これは `index` で指定された位置の UTF-16 コード単位の値を表します。`index` が `0` ～ `str.length - 1` の範囲外であった場合、`charCodeAt()` は `NaN` を返します。

解説
--

文字列の中の文字は、左から右に向けてインデックス付けされています。最初の文字の添字は `0` であり、最後の文字の添字は `str` という名前の文字列であれば `str.length - 1` です。

Unicode のコードポイントは `0` から `1114111` (`0x10FFFF`) までの範囲です。`charCodeAt()` は常に `65536` より小さい値を返しますが、これは上位のコードポイントは 16 ビットのサロゲート擬似文字のペアによって表されているからです。したがって、`65535` より大きい値を持つ完全な文字を取得するには、`charCodeAt(i)` だけでなく `charCodeAt(i + 1)` も取得するか（2 つの文字を持つ文字列を操作する場合と同じです）、または `codePointAt(i)` を使用する必要があります。Unicode に関する情報はUTF-16 文字、Unicode コードポイント、書記素クラスターを参照してください。

例
-

### charCodeAt() の使用

以下の例では、 Unicode 文字の A である `65` を返します。

```js
"ABC".charCodeAt(0); // returns 65
```

`charCodeAt()` は妥当な Unicode 文字ではない、孤立サロゲートを返す可能性があります。

```js
const str = "𠮷𠮾";
console.log(str.charAt(0)); // 55362、または d842、これは妥当な Unicode 文字ではない
console.log(str.charAt(1)); // 57271、または dfb7、これは妥当な Unicode 文字ではない
```

指定された位置の完全な Unicode コードポイントを取得するには、`String.prototype.codePointAt()` を使用してください。

```js
const str = "𠮷𠮾";
console.log(str.codePointAt(0)); // 134071
```

**メモ:** `charCodeAt()` を使用して `codePointAt()` を再実装することは避けてください。孤立サロゲートの検出とそのペアリングは複雑で、文字列の内部表現を直接使用する組み込み API の方がパフォーマンスが高いかもしれません。必要であれば、`codePointAt()` のポリフィルをインストールしてください。

以下は Unicode FAQ から引用した、UTF-16 コードユニットのペアを Unicode コードポイントに変換する可能なアルゴリズムです。

```js
// constants
const LEAD\_OFFSET = 0xd800 - (0x10000 >> 10);
const SURROGATE\_OFFSET = 0x10000 - (0xd800 << 10) - 0xdc00;

function utf16ToUnicode(lead, trail) {
  return (lead << 10) + trail + SURROGATE\_OFFSET;
}
function unicodeToUTF16(codePoint) {
  const lead = LEAD\_OFFSET + (codePoint >> 10);
  const trail = 0xdc00 + (codePoint & 0x3ff);
  return [lead, trail];
}

const str = "𠮷";
console.log(utf16ToUnicode(str.charCodeAt(0), str.charCodeAt(1))); // 134071
console.log(str.codePointAt(0)); // 134071
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.charcodeat |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.fromCharCode()`
* `String.prototype.charAt()`
* `String.fromCodePoint()`
* `String.prototype.codePointAt()`


String.prototype.startsWith() - JavaScript

String.prototype.startsWith()
=============================

**`startsWith()`** メソッドは文字列が引数で指定された文字列で始まるかを判定して `true` か `false` を返します。

試してみましょう
--------

構文
--

```js
startsWith(searchString)
startsWith(searchString, position)
```

### 引数

`searchString`

`str` の先頭で検索される文字の集合です。正規表現にすることはできません。正規表現ではない値はすべて文字列に変換されますので、省略したり `undefined` を渡したりすると、`startsWith()` は `"undefined"` という文字列を検索します。これはおそらく望むところではないでしょう。

`position` 省略可

`searchString` が見つかると期待される開始位置（`searchString` の先頭の文字のインデックス）です。既定値は `0` です。

### 返値

文字列が指定された文字列で始まる場合、`searchString` が空文字列の場合は **`true`**、それ以外の場合は **`false`** です。

### 例外

`TypeError`

`searchString` が正規表現であった場合。

解説
--

文字列が特定の文字列で終わるかどうかを判断できます。このメソッドでは（英文字の）大文字小文字は区別されます。

例
-

### startsWith() の使用

```js
const str = "To be, or not to be, that is the question.";

console.log(str.startsWith("To be")); // true
console.log(str.startsWith("not to be")); // false
console.log(str.startsWith("not to be", 10)); // true
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.startswith |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.startsWith` のポリフィル (`core-js`)
* `String.prototype.endsWith()`
* `String.prototype.includes()`
* `String.prototype.indexOf()`
* `String.prototype.lastIndexOf()`


String.prototype.substr() - JavaScript

String.prototype.substr()
=========================

**非推奨:** この機能は非推奨になりました。まだ対応しているブラウザーがあるかもしれませんが、すでに関連するウェブ標準から削除されているか、削除の手続き中であるか、互換性のためだけに残されている可能性があります。使用を避け、できれば既存のコードは更新してください。このページの下部にある互換性一覧表を見て判断してください。この機能は突然動作しなくなる可能性があることに注意してください。

**`substr()`** メソッドは、文字列の一部を、指定した位置から後方向に指定した文字数だけ返します。

**メモ:** `substr()` は ECMAScript 仕様書の主要部にはありません。付録 B: ウェブブラウザーのための追加 ECMAScript 機能 で定義されており、ブラウザー以外のランタイムでは通常オプションです。従って、コードのクロスプラットフォームの親和性を最大にするには、代わりに標準の `String.prototype.substring()` または `String.prototype.slice()` メソッドを使用するよう勧められています。これら 3 つのメソッドの比較が `String.prototype.substring()` page にあります。

試してみましょう
--------

構文
--

```js
substr(start)
substr(start, length)
```

### 引数

`start`

返却する部分文字列に含まれる最初の文字の位置です。

`length` 省略可

取り出す文字の数です。

### 返値

指定された文字列の指定された部分が入った新しい文字列です。

解説
--

文字列の `substr()` メソッドは、その文字列の `start` のインデックスから `length` 文字分を数えて抽出します。

* `start >= str.length` である場合、空文字列が返されます。
* `start < 0` である場合、文字列の末尾から数えたインデックスになります。厳密には、この場合は `max(start + str.length, 0)` で始まる部分文字列になります。
* `start` が省略されたか `undefined` であった場合、`0` として扱われます。
* `length` が省略されたか `undefined` であった場合、または`start + length >= str.length` であった場合、`substr()` は文字列の末尾まで文字を抽出します。
* `length < 0` の場合、空文字列が返されます。
* `start` と `length` のどちらでも、`NaN` は `0` として扱われます。

`substr()` の使用を避けることが推奨されますが、レガシーコードにおいて `substr()` を `slice()` または `substring()` に移行する簡単な方法はありません。例えば、`str = "01234", a = 1, l = -2` の場合、`str.substr(a, l)`, `str.slice(a, a + l)`, `str.substring(a, a + l)` はすべて異なる結果を返します。 `substr()` は空文字列を返し、`slice()` は `"123"` を返し、`substring()` は `"0"` を返します。実際のリファクタリング方法は、`a` と `l` の範囲に関する知識に依存します。

例
-

### substr() の使用

```js
const aString = "Mozilla";

console.log(aString.substr(0, 1)); // 'M'
console.log(aString.substr(1, 0)); // ''
console.log(aString.substr(-1, 1)); // 'a'
console.log(aString.substr(1, -1)); // ''
console.log(aString.substr(-3)); // 'lla'
console.log(aString.substr(1)); // 'ozilla'
console.log(aString.substr(-20, 2)); // 'Mo'
console.log(aString.substr(20, 2)); // ''
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.substr |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.substr` のポリフィル (`core-js`)
* `String.prototype.slice()`
* `String.prototype.substring()`


String.prototype[@@iterator]() - JavaScript

String.prototype[@@iterator]()
==============================

**`[@@iterator]()`** は `String` 値のメソッドで、反復可能プロトコルを実装しており、スプレッド構文や`for...of`ループ
 文字列値のコードポイントを走査し、それぞれのコードポイントを文字列値として返すイテレーターオブジェクトを返します。

試してみましょう
--------

構文
--

```js
string[Symbol.iterator]()
```

### 返値

新しい反復可能なイテレーターオブジェクトで、この文字列の各 Unicode コードポイントを、独立した文字列として生成します。

解説
--

文字列は Unicode コードポイントで反復処理されます。つまり、書記素クラスターは分割されますが、サロゲートペアは保持されます。

```js
// "Backhand Index Pointing Right: Dark Skin Tone"
[..."👉🏿"]; // ['👉', '🏿']
// 基本的な "Backhand Index Pointing Right" の絵文字と
// "Dark skin tone" の絵文字に分割

// "Family: Man, Boy"
[..."👨👦"]; // [ '👨', '', '👦' ]
// "Man" と "Boy" の絵文字に分割され、 ZWJ で結合されます。
```

例
-

### for...of ループを用いた反復処理

このメソッドを直接呼び出す必要はほとんどないことに注意してください。`iterator` メソッドが存在することで、文字列は反復可能になり、`for...of` ループのような反復処理構文は自動的にこのメソッドを呼び出して、ループするイテレーターを取得します。

```js
const str = "A\uD835\uDC68B\uD835\uDC69C\uD835\uDC6A";

for (const v of str) {
  console.log(v);
}
// "A"
// "\uD835\uDC68"
// "B"
// "\uD835\uDC69"
// "C"
// "\uD835\uDC6A"
```

### イテレーターを手動で手繰る

反復処理を最大限に制御するために、返すイテレーターオブジェクトの `next()` メソッドを手動で呼び出すこともできます。

```js
const str = "A\uD835\uDC68";

const strIter = str[Symbol.iterator]();

console.log(strIter.next().value); // "A"
console.log(strIter.next().value); // "\uD835\uDC68"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype-@@iterator |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype[@@iterator]` のポリフィル (`core-js`)
* 反復処理プロトコル


String.prototype.concat() - JavaScript

String.prototype.concat()
=========================

**`concat()`** メソッドは、文字列引数を呼び出し文字列に連結して、新しい文字列を返します。

試してみましょう
--------

構文
--

```js
concat(str1)
concat(str1, str2)
concat(str1, str2, /\* …, \*/ strN)
```

### 引数

`strN`

`str` に連結する 1 つ以上の文字列です。

### 返値

提供された文字列を結合したテキストの入った新しい文字列です。

解説
--

`concat()` 関数は、文字列引数を呼び出し文字列に連結し、新しい文字列を返します。元の文字列または返された文字列を変更しても、他の文字列には影響しません。

引数が文字列型でない場合は、連結前に文字列値に変換されます。

`concat()` メソッドは加算/文字列結合演算子 (`+`, `+=`) にとても似ていますが、`concat()` は引数を直接文字列に変換するのに対し、加算演算子はオペランドをまずプリミティブに変換します。詳しくは、 `+` 演算子のリファレンスページを参照してください。

例
-

### concat() の使用

複数の文字列を連結してコンソールに表示する例を以下に示します。

```js
const hello = "こんにちは、";
console.log(hello.concat("鈴木さん", "。良い日を。"));
// Hello, Kevin. Have a nice day.

const greetList = ["こんにちは", " ", "佐藤さん", "!"];
"".concat(...greetList); // "こんにちは 佐藤さん!"

"".concat({}); // "[object Object]"
"".concat([]); // ""
"".concat(null); // "null"
"".concat(true); // "true"
"".concat(4, 5); // "45"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.concat |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Array.prototype.concat()`
* 加算演算子


String.prototype.toLocaleUpperCase() - JavaScript

String.prototype.toLocaleUpperCase()
====================================

**`toLocaleUpperCase()`** メソッドは、呼び出した文字列の値を、ロケールに依存した対応付けに基づいて大文字に変換して返します。

試してみましょう
--------

構文
--

```js
toLocaleUpperCase()
toLocaleUpperCase(locales)
```

### 引数

`locale` 省略可

BCP 47 言語タグを持つ文字列、またはそのような文字列の配列です。 ロケール固有の大文字小文字の対応付けに従って大文字に変換するために使用するロケールを示します。 引数 `locales` の一般的な形成と解釈については、`Intl` メインページの引数の説明 を参照してください。

引数 `locales` を使用する他のメソッドとは異なり、`toLocaleLowerCase()` はロケールの照合を許可しません。 そのため、引数 `locales` の有効性を調べた後、 `toLocaleLowerCase()` は常にリストの最初のロケール（リストが空の場合は既定値）を、そのロケールに実装で対応していない場合でも使用します。

### 返値

呼び出した文字列をロケールに依存した対応に基づいて大文字に変換したものを表す新しい文字列です。

解説
--

`toLocaleUpperCase()` メソッドは、ロケール固有の大文字小文字の対応付けに従って大文字に変換された文字列の値を返します。 `toLocaleUpperCase()` はその文字列自体に影響を与えません。ほとんどの場合は `toUpperCase()` と同じ結果が得られますが、トルコ語のように大文字小文字のマッピングが Unicode 既定の大文字小文字のマッピングに従っていないロケールの場合は、異なる結果が得られる可能性があります。

 また、変換は必ずしも文字の 1:1 の対応付けであるとは限らず、一部の文字は大文字に変換されたときに 2 文字 (それ以上の場合も) になる可能性があることに注意してください。そのため，結果の文字列の長さは入力の長さと異なる場合があります。これは変換が安定していないことも意味します。すなわち、次の式は `false` を返す可能性があります。
 `x.toLocaleLowerCase() === x.toLocaleUpperCase().toLocaleLowerCase()`

例
-

### toLocaleUpperCase() の使用

```js
"alphabet".toLocaleUpperCase(); // 'ALPHABET'

"Gesäß".toLocaleUpperCase(); // 'GESÄSS'

"i\u0307".toLocaleUpperCase("lt-LT"); // 'I'

const locales = ["lt", "LT", "lt-LT", "lt-u-co-phonebk", "lt-x-lietuva"];
"i\u0307".toLocaleUpperCase(locales); // 'I'
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.tolocaleuppercase |
| ECMAScript Internationalization API Specification # sup-string.prototype.tolocaleuppercase |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.toLocaleLowerCase()`
* `String.prototype.toLowerCase()`
* `String.prototype.toUpperCase()`


String.prototype.trim() - JavaScript

String.prototype.trim()
=======================

**`trim()`** メソッドは、文字列の両端からホワイトスペースを取り除き、元の文字列を変更せずに新しい文字列を返す。

一方の端からのみホワイトスペースを取り除いた新しい文字列を返したい場合は、`trimStart()` または `trimEnd()` を使用してください。

試してみましょう
--------

構文
--

```js
trim()
```

### 返値

`str` の先頭と末尾のホワイトスペースを取り除いた新しい文字列を表します。 ホワイトスペースはホワイトスペース文字と改行文字で定義します。

`str` の先頭にも末尾にもホワイトスペースがなかった場合でも、新しい文字列が返されます（基本的には `str` のコピー）。

例
-

### trim() の使用

次の例は、`str` の両端からホワイトペースを取り除きます。

```js
const str = " foo ";
console.log(str.trim()); // 'foo'
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.trim |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.trimStart()`
* `String.prototype.trimEnd()`


String.prototype.toWellFormed() - JavaScript

String.prototype.toWellFormed()
===============================

**`toWellFormed()`** は `String` 値のメソッドで、この文字列のすべての孤立サロゲートを Unicode 置換文字 U+FFFD に置き換えた文字列を返します。

構文
--

```js
toWellFormed()
```

### 返値

この文字列のコピーで、孤立サロゲートをすべて Unicode 置換文字 U+FFFD に置き換えた新しい文字列です。 もし `str` が整形式 であれば、やはり新しい文字列が返されます（基本的には `str` のコピーです）。

解説
--

JavaScript の文字列は UTF-16 でエンコードされています。UTF-16 エンコーディングにはサロゲートペアという概念があり、これは UTF-16 文字、Unicode コードポイント、書記素クラスターで詳しく紹介されています。

`toWellFormed()` はこの文字列のコード単位を走査し、すべての孤立サロゲートをUnicode 置換文字 U+FFFD `&#fffd;` に置き換えます。これは、返す文字列が整形式であることを保証し、`encodeURI` のような整形式文字列を期待する関数で使用することができます。カスタム実装と比較して、`toWellFormed()` は、エンジンが文字列の内部表現に直接アクセスすることができるので、より効率的です。

整形式ではない文字列が `TextEncoder` のような特定の文脈で使用された場合、自動的に同じ置換文字を使って整形された文字列に変換されます。孤立サロゲートがレンダリングされるとき、それらは置換文字（疑問符が内側にある菱形）としてもレンダリングされます。

例
-

### toWellFormed() の使用

```js
const strings = [
  // 孤立高サロゲート
  "ab\uD800",
  "ab\uD800c",
  // 孤立低サロゲート
  "\uDFFFab",
  "c\uDFFFab",
  // 整形式
  "abc",
  "ab\uD83D\uDE04c",
];

for (const str of strings) {
  console.log(str.toWellFormed());
}
// Logs:
// "ab�"
// "ab�c"
// "�ab"
// "c�ab"
// "abc"
// "ab😄c"
```

### encodeURI() のエラーを防止

`encodeURI` は渡された文字列が整形式でない場合、エラーを発生させます。これは `toWellFormed()` によって文字列を最初に整形式文字列に変換しておくことで防ぐことができます。

```js
const illFormed = "https://example.com/search?q=\uD800";

try {
  encodeURI(illFormed);
} catch (e) {
  console.log(e); // URIError: URI malformed
}

console.log(encodeURI(illFormed.toWellFormed())); // "https://example.com/search?q=%EF%BF%BD"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.towellformed |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.toWellFormed` のポリフィル (`core-js`)
* `String.prototype.isWellFormed()`
* `String.prototype.normalize()`


String.prototype.codePointAt() - JavaScript

String.prototype.codePointAt()
==============================

**`codePointAt()`** は `String` のメソッドで、指定されたインデックスから始まる文字の Unicode コードポイント値である非負の整数を返します。インデックスは Unicode コードポイントではなく、UTF-16 コード単位に基づくことに注意してください。

試してみましょう
--------

構文
--

```js
codePointAt(index)
```

### 引数

`index`

返す文字の 0 基点のインデックスです。整数に変換され、`undefined` は 0 に変換されます。

### 返値

指定された位置 `index` にある文字のコードポイント値を表す非負の整数値です。

* `index` が `0` – `str.length - 1` の範囲外であれば、`codePointAt()` は `undefined` を返します。
* `index` の位置の要素が UTF-16 高サロゲートであった場合、そのコードポイントのサロゲートペアを返します。
* `index` の位置の要素が UTF-16 低サロゲートであった場合、低サロゲートコードポイントのみを返します。
解説
--

文字列の中の文字は、左から右に向けてインデックス付けされています。最初の文字の添字は `0` であり、最後の文字の添字は `str` という名前の文字列であれば `str.length - 1` です。

Unicode のコードポイントは `0` から `1114111` (`0x10FFFF`) までの範囲です。UTF-16 では、それぞれの文字列のインデックスは `0` ～ `65536` のコード単位です。上位のコードポイントは 16 ビットのサロゲート擬似文字のペアによって表されます。したがって、`codePointAt()` は文字列の 2 つのインデックスにまたがるコードポイントを返す可能性があります。Unicode に関する情報はUTF-16 文字、Unicode コードポイント、書記素クラスターを参照してください。

例
-

### codePointAt() の使用

```js
"ABC".codePointAt(0); // 65
"ABC".codePointAt(0).toString(16); // 41

"😍".codePointAt(0); // 128525
"\ud83d\ude0d".codePointAt(0); // 128525
"\ud83d\ude0d".codePointAt(0).toString(16); // 1f60d

"😍".codePointAt(1); // 56845
"\ud83d\ude0d".codePointAt(1); // 56845
"\ud83d\ude0d".codePointAt(1).toString(16); // de0d

"ABC".codePointAt(42); // undefined
```

### codePointAt() の繰り返し

要素が UTF-16 の低サロゲートである `index` へのインデックス付けは、低サロゲートのみを返すので、文字列のインデックスをループに使わない方がよいでしょう。

```js
const str = "\ud83d\udc0e\ud83d\udc71\u2764";

for (let i = 0; i < str.length; i++) {
  console.log(str.codePointAt(i).toString(16));
}
// '1f40e', 'dc0e', '1f471', 'dc71', '2764'
```

代わりに、`for...of` 文やスプレッド構文を使用してください。どちらも文字列の `@@iterator` を呼び出し、コードポイント単位で反復処理をします。それから、`codePointAt(0)` でそれぞれの要素のコードポイントを取得してください。

```js
for (const codePoint of str) {
  console.log(codePoint.codePointAt(0).toString(16));
}
// '1f40e', '1f471', '2764'

[...str].map((cp) => cp.codePointAt(0).toString(16));
// ['1f40e', '1f471', '2764']
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.codepointat |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.codePointAt` のポリフィル (`core-js`)
* `String.fromCodePoint()`
* `String.fromCharCode()`
* `String.prototype.charCodeAt()`
* `String.prototype.charAt()`


String.prototype.sub() - JavaScript

String.prototype.sub()
======================

**非推奨:** この機能は非推奨になりました。まだ対応しているブラウザーがあるかもしれませんが、すでに関連するウェブ標準から削除されているか、削除の手続き中であるか、互換性のためだけに残されている可能性があります。使用を避け、できれば既存のコードは更新してください。このページの下部にある互換性一覧表を見て判断してください。この機能は突然動作しなくなる可能性があることに注意してください。

**`sub()`** メソッドは、文字列を `<sub>` 要素に埋め込んだ文字列 (`<sub>str</sub>`) を生成し、文字列が下付き文字として表示されるようにします。

**警告:** HTML ラッパーメソッドはすべて非推奨となっており、互換性目的のみで標準化されています。代わりに DOM API の `document.createElement()` などを使用してください。

構文
--

```js
sub()
```

### 返値

開始タグ `<sub>` で始まり、テキスト `str` が来て、終了タグ `</sub>` が来る文字列です。

例
-

### sub() および sup() メソッドの使用

以下の例は、 `sub()` と `sup()` メソッドを使用して文字列を整形しています。

```js
const superText = "上付き文字";
const subText = "下付き文字";

console.log(`これは ${superText.sup()} の見え方を示しています。`);
// "これは<sup>上付き文字</sup>の見え方を示しています。"

console.log(`これは ${subText.sub()} の見え方を示しています。`);
// "これは<sub>下付き文字</sub>の見え方を示しています。"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.sub |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.sub` のポリフィル (`core-js`)
* `String.prototype.sup()`


String.prototype.toUpperCase() - JavaScript

String.prototype.toUpperCase()
==============================

**`toUpperCase()`** メソッドは、呼び出す文字列の値を（文字列でない場合、文字列に変換して）大文字に変換して返します。

試してみましょう
--------

構文
--

```js
toUpperCase()
```

### 返値

呼び出す文字列の値を大文字に変換した新しい文字列です。

解説
--

`toUpperCase()` メソッドは、大文字に変換された文字列の値を返します。このメソッドは、文字列自身の値に影響を与えません（JavaScript の文字列は不変です）。

例
-

### 基本的な使用

```js
console.log("alphabet".toUpperCase()); // 'ALPHABET'
```

### 文字列でない `this` 値を文字列に変換する

このメソッドは `this` に文字列でない値を設定した場合、文字列に変換します。

```js
const a = String.prototype.toUpperCase.call({
  toString() {
    return "abcdef";
  },
});

const b = String.prototype.toUpperCase.call(true);

// 'ABCDEF TRUE' と表示
console.log(a, b);
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.touppercase |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.toLocaleLowerCase()`
* `String.prototype.toLocaleUpperCase()`
* `String.prototype.toLowerCase()`


String.prototype.small() - JavaScript

String.prototype.small()
========================

**非推奨:** この機能は非推奨になりました。まだ対応しているブラウザーがあるかもしれませんが、すでに関連するウェブ標準から削除されているか、削除の手続き中であるか、互換性のためだけに残されている可能性があります。使用を避け、できれば既存のコードは更新してください。このページの下部にある互換性一覧表を見て判断してください。この機能は突然動作しなくなる可能性があることに注意してください。

**`small()`** メソッドは、文字列を `<small>` 要素に埋め込んだ文字列 (`<small>str</small>`) を生成し、文字列が小さなフォントで表示されるようにします。

**警告:** HTML ラッパーメソッドはすべて非推奨となっており、互換性目的のみで標準化されています。代わりに DOM API の `document.createElement()` などを使用してください。

構文
--

```js
small()
```

### 返値

開始タグ `<small>` で始まり、テキスト `str` が来て、終了タグ `</small>` が来る文字列です。

例
-

### small() の使用

以下の例では文字列のメソッドを使用して、文字列の大きさを変更しています。

```js
const worldString = "Hello, world";

console.log(worldString.small()); // <small>Hello, world</small>
console.log(worldString.big()); // <big>Hello, world</big>
console.log(worldString.fontsize(7)); // <font size="7">Hello, world</fontsize>
```

`element.style` オブジェクトを使用すると、要素の `style` 属性を使用して、次のようにもっと汎用的に操作することができます。

```js
document.getElementById("yourElemId").style.fontSize = "0.7em";
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.small |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.small` のポリフィル (`core-js`)
* `String.prototype.fontsize()`
* `String.prototype.big()`


String.prototype.blink() - JavaScript

String.prototype.blink()
========================

**非推奨:** この機能は非推奨になりました。まだ対応しているブラウザーがあるかもしれませんが、すでに関連するウェブ標準から削除されているか、削除の手続き中であるか、互換性のためだけに残されている可能性があります。使用を避け、できれば既存のコードは更新してください。このページの下部にある互換性一覧表を見て判断してください。この機能は突然動作しなくなる可能性があることに注意してください。

**`blink()`** メソッドは、文字列を (`<blink>str</blink>`) に埋め込んだ文字列を生成し、古いブラウザーにおいて文字列を点滅させるために使用します。

**警告:** HTML ラッパーメソッドはすべて非推奨となっており、互換性目的のみで標準化されています。`blink()` の場合、`<blink>` 要素自体が現代のブラウザーから削除されており、テキストを点滅させることは、複数のアクセシビリティ標準で忌避されています。この要素を使用することは避けてください。

構文
--

```js
blink()
```

### 返値

`<blink>` 開始タグで始まり、`str` のテキストが来て、 `</blink>` 終了タグが来る文字列です。

例
-

### blink() の使用

以下の例では文字列のメソッドを使用して、文字列の整形方法を変化させています。

```js
const worldString = "Hello, world";

console.log(worldString.blink()); // <blink>Hello, world</blink>
console.log(worldString.bold()); // <b>Hello, world</b>
console.log(worldString.italics()); // <i>Hello, world</i>
console.log(worldString.strike()); // <strike>Hello, world</strike>
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.blink |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.blink` のポリフィル (`core-js`)
* `String.prototype.bold()`
* `String.prototype.italics()`
* `String.prototype.strike()`


String.prototype.strike() - JavaScript

String.prototype.strike()
=========================

**非推奨:** この機能は非推奨になりました。まだ対応しているブラウザーがあるかもしれませんが、すでに関連するウェブ標準から削除されているか、削除の手続き中であるか、互換性のためだけに残されている可能性があります。使用を避け、できれば既存のコードは更新してください。このページの下部にある互換性一覧表を見て判断してください。この機能は突然動作しなくなる可能性があることに注意してください。

**`strike()`** メソッドは、文字列を `<strike>` 要素に埋め込んだ文字列 (`<strike>str</strike>`) を生成し、文字列が取り消されたテキストとして表示されるようにします。

**警告:** HTML ラッパーメソッドはすべて非推奨となっており、互換性目的のみで標準化されています。代わりに DOM API の `document.createElement()` などを使用してください。

構文
--

```js
strike()
```

### 返値

開始タグ `<strike>` で始まり、テキスト `str` が来て、終了タグ `</strike>` が来る文字列です。

例
-

### strike() の使用

以下の例では文字列のメソッドを使用して、文字列の形式を変更しています。

```js
const worldString = "Hello, world";

console.log(worldString.blink()); // <blink>Hello, world</blink>
console.log(worldString.bold()); // <b>Hello, world</b>
console.log(worldString.italics()); // <i>Hello, world</i>
console.log(worldString.strike()); // <strike>Hello, world</strike>
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.strike |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.strike` のポリフィル (`core-js`)
* `String.prototype.blink()`
* `String.prototype.bold()`
* `String.prototype.italics()`


String.fromCharCode() - JavaScript

String.fromCharCode()
=====================

**`String.fromCharCode()`** 静的メソッドは、指定された UTF-16 コード単位の並びから生成された文字列を返します。

試してみましょう
--------

構文
--

```js
String.fromCharCode(num1)
String.fromCharCode(num1, num2)
String.fromCharCode(num1, num2, /\* …, \*/ numN)
```

### 引数

`numN`

UTF-16 コード単位を表す数値の並びです。範囲は `0` から `65535` (`0xFFFF`) までです。数値が `0xFFFF` を超えた場合は切り捨てられます。妥当性チェックは行われません。

### 返値

指定された `N` 個の UTF-16 コード単位から生成された、長さ `N` の文字列です。

解説
--

`fromCharCode()` は `String` の静的メソッドなので、自分で生成した `String` オブジェクトのメソッドではなく、常に `String.fromCharCode()` として使用するようにしてください。

Unicode のコードポイントは `0` から `1114111` (`0x10FFFF`) までの範囲です。`charAt()` は常に `65536` より小さい値を返しますが、これは上位のコードポイントは 16 ビットのサロゲート擬似文字のペアによって表されているからです。したがって、`65535` より大きい値を持つ完全な文字を取得するには、`charAt(i)` だけでなく `charAt(i + 1)` も取得するか（2 つの文字を持つ文字列を操作する場合と同じです）、または `codePointAt(i)` と `String.fromCodePoint()` を使用する必要があります。Unicode に関する情報はUTF-16 文字、Unicode コードポイント、書記素クラスターを参照してください。

`fromCharCode()` は 16 ビット値のみで動作するため（`\u` エスケープシーケンスと同様）、補助文字を返すためにはサロゲートペアが必要です。例えば、`String.fromCharCode(0xD83C, 0xDF03)` と `\uD83C\uDF03` はコードポイント `U+1F303` "Night with Stars" です。補助コードポイントの値（例: `0x1f303`）とそれを表す両方のサロゲート値（例: `0xd83c` や `0xdf03`）との間には数学的な関係がありますが、補助コードポイントを使用するたびにサロゲートペアの値を計算したり参照したりする、余分なステップが必要になります。このため、実際のコードポイント値に基づいて補助文字を返すことができる `String.fromCodePoint()` を使用した方が便利です。例えば、 `String.fromCodePoint(0x1f303)` はコードポイント `U+1F303` "Night with Stars" を返します。

例
-

### fromCharCode() の使用

BMP 文字は、 UTF-16 では単一のコード単位を使用します。

```js
String.fromCharCode(65, 66, 67); // "ABC" を返す
String.fromCharCode(0x2014); // "—" を返す
String.fromCharCode(0x12014); // これも "—" を返す。1 の桁は削除され無視される
String.fromCharCode(8212); // これも "—" を返す。8212 は 0x2014 の 10 進数形
```

補助文字は、 UTF-16 では、 2 つのコード単位（すなわちサロゲートペア）を必要とします。

```js
String.fromCharCode(0xd83c, 0xdf03); // Code Point U+1F303 "Night with
String.fromCharCode(55356, 57091); // Stars" === "\uD83C\uDF03"

String.fromCharCode(0xd834, 0xdf06, 0x61, 0xd834, 0xdf07); // "\uD834\uDF06a\uD834\uDF07"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.fromcharcode |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.fromCodePoint()`
* `String.prototype.charAt()`
* `String.prototype.charCodeAt()`
* `String.prototype.codePointAt()`


String.prototype.charAt() - JavaScript

String.prototype.charAt()
=========================

**`charAt()`** は `String` 値のメソッドは、指定されたインデックスにある単一の UTF-16 コード単位からなる新しい文字列を返します。

`charAt()` は常に文字列を UTF-16 コード単位の並びとして索引付けます。そのため、孤立したサロゲートを返す可能性があります。指定されたインデックスの完全な Unicode コードポイントを取得するには、`String.prototype.codePointAt()` および `String.fromCodePoint()` を使用してください。

試してみましょう
--------

構文
--

```js
charAt(index)
```

### 引数

`index`

返される文字のゼロから始まる文字のインデックスです。整数に変換されます。`undefined` は 0 に変換されます。

### 返値

指定された `index` の位置にある文字（厳密に 1 つの UTF-16 コードポイント）を表す文字列です。`index` の位置が文字列の範囲を外れていた場合は、`charAt()` は空文字列を返します。

解説
--

文字列の中の文字は、左から右に向けてインデックス付けされています。最初の文字の添字は `0` であり、最後の文字の添字は `str` という名前の文字列であれば `str.length - 1` です。

Unicode のコードポイントは `0` から `1114111` (`0x10FFFF`) までの範囲です。`charAt()` は常に `65536` より小さい値を返しますが、これは上位のコードポイントは 16 ビットのサロゲート擬似文字のペアによって表されているからです。したがって、`65535` より大きい値を持つ完全な文字を取得するには、`charAt(i)` だけでなく `charAt(i + 1)` も取得するか（2 つの文字を持つ文字列を操作する場合と同じです）、または `codePointAt(i)` と `String.fromCodePoint()` を使用する必要があります。Unicode に関する情報はUTF-16 文字、Unicode コードポイント、書記素クラスターを参照してください。

`charAt()` は ブラケット記法を使用して指定された位置の文字にアクセスするのにとても似ています。主な違いは次の通りです。

* `charAt()` は `index` を整数に変換しようとしますが、ブラケット記法はそうせずに、直接 `index` をプロパティ名として使用します。
* `charAt()` は `index` が範囲外であったときに空文字列を返しますが、ブラケット記法は `undefined` を返します。
例
-

### 文字列の中の様々な位置の文字の表示

次の例は、`"Brave new world"`` という文字列の中の様々な位置の文字を表示します。

```js
const anyString = "Brave new world";
console.log(`The character at index 0 is '${anyString.charAt()}'`);
// No index was provided, used 0 as default

console.log(`The character at index 0 is '${anyString.charAt(0)}'`);
console.log(`The character at index 1 is '${anyString.charAt(1)}'`);
console.log(`The character at index 2 is '${anyString.charAt(2)}'`);
console.log(`The character at index 3 is '${anyString.charAt(3)}'`);
console.log(`The character at index 4 is '${anyString.charAt(4)}'`);
console.log(`The character at index 999 is '${anyString.charAt(999)}'`);
```

これらの行は以下のように表示されます。
```

The character at index 0   is 'B'

The character at index 0   is 'B'
The character at index 1   is 'r'
The character at index 2   is 'a'
The character at index 3   is 'v'
The character at index 4   is 'e'
The character at index 999 is ''
```

`charAt()` は妥当な Unicode 文字ではない、孤立サロゲートを返す可能性があります。

```js
const str = "𠮷𠮾";
console.log(str.charAt(0)); // "\ud842"、これは妥当な Unicode 文字ではない
console.log(str.charAt(1)); // "\udfb7"、これは妥当な Unicode 文字ではない
```

指定された位置の完全な Unicode コードポイントを取得するには、`String.prototype.codePointAt()` やスプレッド構文のように、Unicode コードポイントで分割して Unicode コードポイントの配列にするインデックスメソッドを使用してください

```js
const str = "𠮷𠮾";
console.log(String.fromCodePoint(str.codePointAt(0))); // "𠮷"
console.log([...str][0]); // "𠮷"
```

**メモ:** `charAt()` を使用して上記の解決策を再実装することは避けてください。孤立サロゲートの検出とそのペアリングは複雑で、文字列の内部表現を直接使用する組み込み API の方がパフォーマンスが高いかもしれません。必要であれば、上記の API のポリフィルをインストールしてください。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.charat |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.indexOf()`
* `String.prototype.lastIndexOf()`
* `String.prototype.charCodeAt()`
* `String.prototype.codePointAt()`
* `String.prototype.split()`
* `String.fromCodePoint()`
* JavaScript has a Unicode problem – Mathias Bynens


String.prototype.indexOf() - JavaScript

String.prototype.indexOf()
==========================

**`indexOf()`** は `String` 値のメソッドで、この文字列を検索し、指定した部分文字列が最初に出現するインデックスを返します。 オプションで開始位置を取り、指定した数値以上のインデックスで指定した部分文字列が最初に出現するインデックスを返します。

試してみましょう
--------

構文
--

```js
indexOf(searchString)
indexOf(searchString, position)
```

### 引数

* `searchString`
    + : 検索する値を表す文字列です。すべての値は文字列に変換されますので、省略したり `undefined` を渡したりすると、`indexOf()` は `"undefined"` という文字列を検索します。これはおそらく望むところではないでしょう。
* `position` 省略可
    + : このメソッドは、`position`（既定値は `0`）以上の位置で、指定した部分文字列が最初に現れるインデックスを返します。`position` が呼び出された文字列の長さよりも大きい場合、このメソッドは呼び出される文字列をまったく検索しません。`position` が 0 以上の場合、このメソッドは `0` と同じように動作します。
        - `'hello world hello'.indexOf('o', -5)` は `4` を返します。これは第 2 引数が `0` であるかのように動作し、`o` が `0` 以上の位置で最初に現れるのが `4` だからです。
    + `'hello world hello'.indexOf('world', 12)` は `-1` を返します。実際に部分文字列 `world` が現れるのは `6` のインデックスですが、その位置は `12` 以上ではないからです。
    + `'hello world hello'.indexOf('o', 99)` は `-1` を返します。`99` が `hello world hello` の長さよりも大きいため、メソッドが全く文字列を検索しなくなるからです。
### 返値

`searchString` が最初に見つかったインデックス、または見つからなかった場合は `-1` です。

#### 空の検索文字列を使用した場合の返値

空の検索文字列で検索すると、奇妙な結果になります。第 2 引数がなかった場合や、第 2 引数の値が呼び出した文字列の長さよりも小さかった場合、返値は第 2 引数と同じになります。

```js
"hello world".indexOf(""); // 0 を返す
"hello world".indexOf("", 0); // 0 を返す
"hello world".indexOf("", 3); // 3 を返す
"hello world".indexOf("", 8); // 8 を返す
```

しかし、第 2 引数の値が文字列の長さ以上であった場合、返値は文字列の長さになります。

```js
"hello world".indexOf("", 11); // 11 を返す
"hello world".indexOf("", 13); // 11 を返す
"hello world".indexOf("", 22); // 11 を返す
```

前者の例では、メソッドは第 2 引数で指定した位置の直後に空文字列を見つけたかのように動作します。 後者の例では、メソッドは呼び出した文字列の終わりに空文字列を見つけたかのように動作します。

解説
--

文字列は 0 基点です。文字列の最初の文字のインデックスは `0` で、文字列の最後の文字のインデックスは文字列の長さから 1 を引いたものになります。

```js
"Blue Whale".indexOf("Blue"); // 0 を返す
"Blue Whale".indexOf("Blute"); // -1 を返す
"Blue Whale".indexOf("Whale", 0); // 5 を返す
"Blue Whale".indexOf("Whale", 5); // 5 を返す
"Blue Whale".indexOf("Whale", 7); // -1 を返す
"Blue Whale".indexOf(""); // 0 を返す
"Blue Whale".indexOf("", 9); // 9 を返す
"Blue Whale".indexOf("", 10); // 10 を返す
"Blue Whale".indexOf("", 11); // 10 を返す
```

`indexOf()` メソッドは大文字と小文字を区別します。例えば、以下の式は `-1` を返します。

```js
"Blue Whale".indexOf("blue"); // -1 を返す
```

### 出現のチェック

文字列の中に特定の部分文字列があるかどうかを調べる場合、返値が `-1` であるかどうかを調べるのが正しい方法です。

```js
"Blue Whale".indexOf("Blue") !== -1; // true。'Blue' が 'Blue Whale' の中で見つかった
"Blue Whale".indexOf("Bloe") !== -1; // false。 'Bloe' が 'Blue Whale' の中で見つからなかった
```

例
-

### indexOf() の使用

以下の例は `indexOf()` を使用して、`"Brave new world"` という文字列において指定された値の位置を求めています。

```js
const str = "Brave new world";

console.log(str.indexOf("w")); // 8
console.log(str.indexOf("new")); // 6
```

### indexOf() と 大文字と小文字の区別

以下の例は 2 つの文字列の変数を定義しています。

それらの変数は、2 番目の文字列が大文字を含んでいることを除けば、同じ文字列を含んでいます。1 番目の `console.log()` メソッドは `19` を表示します。しかし、`indexOf()` メソッドは大文字と小文字を区別するので、`"cheddar"` という文字列は `myCapString` では見つけられません。ですから、 `console.log()` メソッドは `-1` を表示します。

```js
const myString = "brie, pepper jack, cheddar";
const myCapString = "Brie, Pepper Jack, Cheddar";

console.log(myString.indexOf("cheddar")); // 19
console.log(myCapString.indexOf("cheddar")); // -1
```

### indexOf() を使って文字列中である文字が現れる回数を数える

以下の例は、 `count` に、 `str` という文字列中で `e` という文字が出現する回数を設定します。

```js
const str = "To be, or not to be, that is the question.";
let count = 0;
let position = str.indexOf("e");

while (position !== -1) {
  count++;
  position = str.indexOf("e", position + 1);
}

console.log(count); // 4
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.indexof |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `String.prototype.charAt()`
* `String.prototype.lastIndexOf()`
* `String.prototype.includes()`
* `String.prototype.split()`
* `Array.prototype.indexOf()`


Array.prototype.some() - JavaScript

Array.prototype.some()
======================

**`some()`** は `Array` インスタンスのメソッドで、指定された関数で実装されているテストに、配列の中の少なくとも 1 つの要素が合格するかどうかを判定します。配列の中で指定された関数が true を返す要素を見つけた場合は true を返し、そうでない場合は false を返します。配列は変更しません。

試してみましょう
--------

構文
--

```js
some(callbackFn)
some(callbackFn, thisArg)
```

### 引数

`callbackFn`

配列のそれぞれの要素に対して実行する関数です。この関数は、要素がテストに合格したことを示すには真値を、そうでない場合は偽値を返します。この関数は以下の引数で呼び出されます。

`element`

配列内で処理中の現在の要素です。

`index`

配列内で処理中の現在の要素のインデックスです。

`array`

`some()` が呼び出された配列です。

`thisArg` 省略可

`callbackFn` を実行する際に `this` として使用される値。反復処理メソッドを参照してください。

### 返値

配列の要素のいずれかで `callbackFn` が真値を返した場合は、直ちに `true` を返します。それ以外の場合は `false` です。

解説
--

`some()` メソッドは反復処理メソッドです。指定された `callbackFn` 関数を配列の各要素に対して一度ずつ、 `callbackFn` が真値を返すまで呼び出します。該当する要素が見つかった場合は、 `some()` は直ちに `true` を返し、配列の反復処理を中止します。一方、 `callbackFn` がすべての要素に対して偽値を返した場合、 `some()` は `false` を返します。

`some()` は数学の量化子 "there exists" のような働きをします。特に、空配列の場合、どのような条件でも `false` を返します。

`callbackFn` は値が割り当てられている配列インデックスに対してのみ呼び出されます。疎配列の空のスロットに対しては呼び出されません。

`some()` は呼び出し元の配列を変更しませんが、 `callbackFn` として指定された関数は配列を変更することができます。ただし、配列の長さは `callbackFn` を最初に呼び出す前に保存されることに注意してください。したがって、

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

**警告:** 上記のように進行中の配列に対して変更を行うと、理解しにくいコードになることが多いので、（特別な場合を除いて）避けるのが一般的です。

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

例
-

### 配列要素の値のテスト

次の例は、配列のいずれかの要素に 10 よりも大きいものがあるかどうかをテストします。

```js
function isBiggerThan10(element, index, array) {
  return element > 10;
}

[2, 5, 8, 1, 4].some(isBiggerThan10); // false
[12, 5, 8, 1, 4].some(isBiggerThan10); // true
```

### アロー関数を使った配列要素のテスト

アロー関数は、より短い構文で同じテストを提供します。

```js
[2, 5, 8, 1, 4].some((x) => x > 10); // false
[12, 5, 8, 1, 4].some((x) => x > 10); // true
```

### ある値が配列に存在するかどうかのチェック

`includes()` メソッドを真似て、このカスタム関数は配列にその要素が存在する場合に `true` を返します。

```js
const fruits = ["apple", "banana", "mango", "guava"];

function checkAvailability(arr, val) {
  return arr.some((arrVal) => val === arrVal);
}

checkAvailability(fruits, "kela"); // false
checkAvailability(fruits, "banana"); // true
```

### 任意の値の論理値への変換

```js
const TRUTHY\_VALUES = [true, "true", 1];

function getBoolean(value) {
  if (typeof value === "string") {
    value = value.toLowerCase().trim();
  }

  return TRUTHY\_VALUES.some((t) => t === value);
}

getBoolean(false); // false
getBoolean("false"); // false
getBoolean(1); // true
getBoolean("true"); // true
```

### 疎配列に対する some() の使用

`some()` は空のスロットでは処理を実行しません。

```js
console.log([1, , 3].some((x) => x === undefined)); // false
console.log([1, , 1].some((x) => x !== 1)); // false
console.log([1, undefined, 1].some((x) => x !== 1)); // true
```

### 配列以外のオブジェクトに対する some() の呼び出し

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

```js
const arrayLike = {
  length: 3,
  0: "a",
  1: "b",
  2: "c",
  3: 3, // length が 3 .なので some() 空は無視される
};
console.log(Array.prototype.some.call(arrayLike, (x) => typeof x === "number"));
// false
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.prototype.some |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

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


Array.of() - JavaScript

Array.of()
==========

**`Array.of()`** 静的メソッドは、引数の数や型にかかわらず、可変長引数から、新しい `Array` インスタンスを生成します。

試してみましょう
--------

構文
--

```js
Array.of()
Array.of(element1)
Array.of(element1, element2)
Array.of(element1, element2, /\* …, \*/ elementN)
```

### 引数

`element1`, …, `elementN`

生成する配列の要素。

### 返値

新しい `Array` インスタンス。

解説
--

`Array.of()` と `Array()` コンストラクターの違いは整数引数の扱いにあります。 `Array.of(7)` は単一の要素、`7` を持つ配列を作成しますが、 `Array(7)` は `length` プロパティが 7 の空の配列を作成します（これは `undefined` の値を持つ実在のスロットではなく、7 つの空のスロットの配列を意味します）。

```js
Array.of(7); // [7]
Array(7); // 7 つの空スロットの配列

Array.of(1, 2, 3); // [1, 2, 3]
Array(1, 2, 3); // [1, 2, 3]
```

`Array.of()` メソッドは汎用ファクトリーメソッドです。例えば、 `Array` のサブクラスが `of()` メソッドを継承した場合、継承した `of()` メソッドは `Array` インスタンスではなく、サブクラスの新しいインスタンスを返します。実際には、 `this` 値には新しい配列の長さを表す単一の引数を受け入れる任意のコンストラクタ関数を指定することができ、コンストラクタは `of()` に渡された引数の数だけ呼び出されます。最終的な `length` は、すべての要素が代入されたときに再度設定されます。もし `this` の値がコンストラクター関数でない場合、代わりにプレーンな `Array` コンストラクターが使用されます。

例
-

### Array.of() の使用

```js
Array.of(1); // [1]
Array.of(1, 2, 3); // [1, 2, 3]
Array.of(undefined); // [undefined]
```

### 配列以外のコンストラクターに対する of() の呼び出し

`of()` メソッドは、新しい配列の長さを表す単一の引数を受け入れるコンストラクター関数で呼び出すことができます。

```js
function NotArray(len) {
  console.log("NotArray called with length", len);
}

console.log(Array.of.call(NotArray, 1, 2, 3));
// NotArray called with length 3
// NotArray { '0': 1, '1': 2, '2': 3, length: 3 }

console.log(Array.of.call(Object)); // [Number: 0] { length: 0 }
```

`this` の値がコンストラクターでない場合は、プレーンな `Array` オブジェクトを返します。

```js
console.log(Array.of.call({}, 1)); // [ 1 ]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.of |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Array.of` のポリフィル (`core-js`)
* インデックス付きコレクションのガイド
* `Array`
* `Array()`
* `Array.from()`
* `TypedArray.of()`


Array.prototype.find() - JavaScript

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()`


Array.prototype[@@iterator]() - JavaScript

Array.prototype[@@iterator]()
=============================

**`[@@iterator]()`** は `Array` インスタンスのメソッドで、反復可能プロトコル を実装しており、スプレッド構文 や `for...of` ループのような反復可能オブジェクトを期待するほとんどの構文で配列を利用することができます。配列の各インデックスの値を返す配列イテレーターオブジェクトを返します。

このプロパティの初期値は `Array.prototype.values` プロパティの初期値と同じ関数オブジェクトです。

試してみましょう
--------

構文
--

```js
array[Symbol.iterator]()
```

### 引数

なし。

### 返値

`Array.prototype.values()` の返値と同じです。これは配列内のすべてのインデックスの値を生成する新しい反復可能イテレーターオブジェクトです。

例
-

### for...of ループを用いた反復処理

このメソッドを直接呼び出す必要はほとんどないことに注意してください。 `@@iterator` メソッドが存在することで、配列を反復処理可能にすることができ、 `for...of` ループのような反復処理構文では、自動的にこのメソッドを呼び出して、ループするイテレーターを取得します。

#### HTML

```html
<ul id="letterResult"></ul>
```

#### JavaScript

```js
const arr = ["a", "b", "c"];
const letterResult = document.getElementById("letterResult");
for (const letter of arr) {
  const li = document.createElement("li");
  li.textContent = letter;
  letterResult.appendChild(li);
}
```

#### 結果

### イテレーターを手動で手繰る

返されたイテレーターオブジェクトの `next()` メソッドを手動で呼び出すことで、反復処理を最大限に制御することもできます。

```js
const arr = ["a", "b", "c", "d", "e"];
const arrIter = arr[Symbol.iterator]();
console.log(arrIter.next().value); // a
console.log(arrIter.next().value); // b
console.log(arrIter.next().value); // c
console.log(arrIter.next().value); // d
console.log(arrIter.next().value); // e
```

### 文字列と文字列配列を同じ関数で処理

文字列と配列はどちらもイテレータープロトコルを実装しているので、汎用関数は両方の入力を同じ方法で処理するように設計することができます。これは、 `Array.prototype.values()` を直接呼び出すよりも優れており、入力が配列であるか、少なくともそのようなメソッドを持つオブジェクトであることを要求されます。

```js
function logIterable(it) {
  if (typeof it[Symbol.iterator] !== "function") {
    console.log(it, "is not iterable.");
    return;
  }
  for (const letter of it) {
    console.log(letter);
  }
}

// Array
logIterable(["a", "b", "c"]);
// a
// b
// c

// String
logIterable("abc");
// a
// b
// c

// Number
logIterable(123);
// 123 is not iterable.
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.prototype-@@iterator |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Array.prototype[@@iterator]` のポリフィル (`core-js`)
* インデックス付きコレクションガイド
* `Array`
* `Array.prototype.keys()`
* `Array.prototype.entries()`
* `Array.prototype.values()`
* `TypedArray.prototype[@@iterator]()`
* `String.prototype[@@iterator]()`
* `Symbol.iterator`
* 反復処理プロトコル


Array.prototype.lastIndexOf() - JavaScript

Array.prototype.lastIndexOf()
=============================

**`lastIndexOf()`** は `Array` インスタンスのメソッドで、配列中で与えられた要素が見つかった最後の添字を返します。もし存在しなければ -1 を返します。配列は `fromIndex` から逆向きに検索されます。

試してみましょう
--------

構文
--

```js
lastIndexOf(searchElement)
lastIndexOf(searchElement, fromIndex)
```

### 引数

`searchElement`

検索する配列要素です。

`fromIndex` 省略可

検索し始める位置のゼロから始まるインデックスで、整数に変換されます。

* インデックスが負の場合、配列の末尾からさかのぼって数えます。 `fromIndex < 0` の場合、 `fromIndex + array.length` が使用されます。
* `fromIndex < -array.length` の場合、配列は検索が行われず、 `-1` が返されます。概念的には、配列の先頭より前の存在しない位置から始めて、そこから逆方向に進むと考えることができます。途中には配列要素はないので、 `searchElement` は決して見つかりません。
* `fromIndex >= array.length` または `fromIndex` が省略された場合、 `array.length - 1` が使用され、配列全体が検索されます。概念的には、配列の末尾の先にある存在しない位置から始めて、そこから後方に進むと考えることができます。最終的に配列の本当の末尾に到達し、この点から実在する配列要素を逆探索し始めます。

### 返値

配列内の最後の `searchElement` のインデックスです。見つからなかった場合は `-1` です。

解説
--

`lastIndexOf()` メソッドは `searchElement` と配列の要素を厳密な等価性（`===` 演算子を使用するアルゴリズムと同じ）を使用して比較します。 `NaN` 値が等しいものとして比較されることはないので、 `searchElement` が `NaN` の場合、`lastIndexOf()` は常に `-1` を返します。

`lastIndexOf()` メソッドは疎配列の空スロットをスキップします。

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

例
-

### lastIndexOf() の使用

`lastIndexOf()` を使って配列中のある値の位置を探す例を以下に示します。

```js
const numbers = [2, 5, 9, 2];
numbers.lastIndexOf(2); // 3
numbers.lastIndexOf(7); // -1
numbers.lastIndexOf(2, 3); // 3
numbers.lastIndexOf(2, 2); // 0
numbers.lastIndexOf(2, -2); // 0
numbers.lastIndexOf(2, -1); // 3
```

`lastIndexOf()` を使用して `NaN` を検索することはできません。

```js
const array = [NaN];
array.lastIndexOf(NaN); // -1
```

### ある要素の存在をすべて見つける

以下の例は `lastIndexOf` を使って、与えられた配列中のある値の添字すべてを探しています。`push` を使って、値が見つかる度に別の配列にその添字を追加しています。

```js
const indices = [];
const array = ["a", "b", "a", "c", "a", "d"];
const element = "a";
let idx = array.lastIndexOf(element);
while (idx !== -1) {
  indices.push(idx);
  idx = idx > 0 ? array.lastIndexOf(element, idx - 1) : -1;
}

console.log(indices);
// [4, 2, 0]
```

 ここで `idx == 0` の場合を分けて扱わないといけないことに注意してください。
 なぜなら、もし検索する値が配列の最初の要素にあると、その値は `fromIndex` パラメータにかかわらずいつもヒットしてしまうのです。
 これは `indexOf()` メソッドとは異なります。

### 疎配列に対する lastIndexOf() の使用

疎配列の空のスロットを検索するために `lastIndexOf()` を使用することはできません。

```js
console.log([1, , 3].lastIndexOf(undefined)); // -1
```

### 配列以外のオブジェクトに対する lastIndexOf() の呼び出し

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

```js
const arrayLike = {
  length: 3,
  0: 2,
  1: 3,
  2: 2,
  3: 5, // length が 3 なので lastIndexOf() からは無視される
};
console.log(Array.prototype.lastIndexOf.call(arrayLike, 2));
// 2
console.log(Array.prototype.lastIndexOf.call(arrayLike, 5));
// -1
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.prototype.lastindexof |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Array.prototype.lastIndexOf` のポリフィル (`core-js`)
* インデックス付きコレクションのガイド
* `Array`
* `Array.prototype.findIndex()`
* `Array.prototype.findLastIndex()`
* `Array.prototype.indexOf()`
* `TypedArray.prototype.lastIndexOf()`
* `String.prototype.lastIndexOf()`


Array.prototype.with() - JavaScript

Array.prototype.with()
======================

**`with()`** は `Array` インスタンスのメソッドで、ブラケット記法に対応するコピーメソッドです。これは、指定された位置の要素を指定された値で置き換えた新しい配列を返します。

構文
--

```js
arrayInstance.with(index, value)
```

### 引数

`index`

配列を変更するゼロ基点のインデックスで、整数に変換されます。

* インデックスが負の場合は、配列の末尾から逆に数えます。 `index < 0` の場合、 `index + array.length` が使用されます。
* 正規化後のインデックスが範囲を超えていた場合は、 `RangeError` 例外が発生します。

`value`

指定された位置に割り当てる値です。

### 返値

インデックス `index` の要素を `value` に置き換えた新しい配列です。

### 例外

`RangeError`

`index >= array.length` または `index < -array.length` の場合に発生します。

解説
--

`with()` メソッドは、配列の指定された位置の値を変更し、指定されたインデックスの要素を指定された値で置き換えた新しい配列を返します。元の配列は変更しません。これにより、配列メソッドを連鎖させながら操作を行うことができます。

`with()` と `at()` を組み合わせることで、負のインデックスを用いた配列の書き込みと読み込み（それぞれ）ができます。

`with()` メソッドは決して疎配列を生成しません。疎配列の場合、空のスロットは新しい配列の `undefined` に置き換わります。

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

例
-

### 単一の要素を変更した新しい配列を作成

```js
const arr = [1, 2, 3, 4, 5];
console.log(arr.with(2, 6)); // [1, 2, 6, 4, 5]
console.log(arr); // [1, 2, 3, 4, 5]
```

### 配列メソッドの連鎖

`with()` メソッドを使用すると、配列の単一の要素を更新してから、他の配列メソッドを適用することができます。

```js
const arr = [1, 2, 3, 4, 5];
console.log(arr.with(2, 6).map((x) => x \*\* 2)); // [1, 4, 36, 16, 25]
```

### 疎配列に対する with() の使用

`with()` メソッドは常に密配列を生成します。

```js
const arr = [1, , 3, 4, , 6];
console.log(arr.with(0, 2)); // [2, undefined, 3, 4, undefined, 6]
```

### 配列以外のオブジェクトに対する with() の呼び出し

`with()` メソッドは新しい配列を生成して返します。このメソッドは `this` の `length` プロパティを読み込み、次にキーが `length` より小さい非負の整数である各プロパティにアクセスします。`this` の各プロパティにアクセスすると、プロパティのキーに等しいインデックスの配列要素がプロパティの値に設定されます。最後に、配列の `index` の値が `value` に設定されます。

```js
const arrayLike = {
  length: 3,
  unrelated: "foo",
  0: 5,
  2: 4,
  3: 3, // length が 3 なので toSorted() からは無視される
};
console.log(Array.prototype.with.call(arrayLike, 0, 1));
// [ 1, undefined, 4 ]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.prototype.with |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Array.prototype.with` のポリフィル (`core-js`)
* インデックス付きコレクションのガイド
* `Array.prototype.toReversed()`
* `Array.prototype.toSorted()`
* `Array.prototype.toSpliced()`
* `Array.prototype.at()`
* `TypedArray.prototype.with()`


Array.prototype.findLastIndex() - JavaScript

Array.prototype.findLastIndex()
===============================

**`findLastIndex()`** は `Array` のメソッドで、この配列を逆順に反復処理し、指定されたテスト関数を満たす配列の最後の要素のインデックスを返します。
 テスト関数を満たす要素がなかった場合は、 -1 を返します。

`findLast()` メソッドも参照してください。こちらはテスト関数を満たす最後の要素の（位置ではなく）値を返します。

試してみましょう
--------

構文
--

```js
findLastIndex(callbackFn)
findLastIndex(callbackFn, thisArg)
```

### 引数

`callbackFn`

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

`element`

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

`index`

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

`array`

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

`thisArg` 省略可

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

### 返値

 配列内で、テストを満たした最後の（最も大きな）要素のインデックス。
 それ以外の場合は，一致する要素が見つからなければ `-1` となります。

解説
--

`findLastIndex()` メソッドは反復処理メソッドです。配列のそれぞれの要素に対して、インデックスの降順に一度ずつ指定された `callbackFn` 関数を実行し、 `callbackFn` が真値を返すまで続けます。そして、 `findLastIndex()` がその要素のインデックスを返し、配列のイテレーターを停止します。もし `callbackFn` が真値を返さなかった場合、 `findLastIndex()` は `-1` を返します。

`callbackFn` は値が割り当てられている要素だけではなく、配列の「すべての」インデックスに対して呼び出されます。疎配列で空のスロットは `undefined` と同じ動作をします。

`findLastIndex()` メソッドは呼び出し元の配列を変更しませんが、 `callbackFn` に指定された関数は変更することがあります。ただし、配列の長さは `callbackFn` を最初に呼び出す前に保存されることに注意してください。したがって、

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

**警告:** 前項で説明したような、参照中の配列の同時進行での変更は（特殊な場合を除いて）普通は避けるべきです。多くの場合、理解しにくいコードになります。

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

例
-

### 配列内の最後の素数の位置を探す

以下の例では、配列の最後の要素が素数である場合のインデックスを返します。素数が存在しない場合は `-1` を返します。

```js
function isPrime(element) {
  if (element % 2 === 0 || element < 2) {
    return false;
  }
  for (let factor = 3; factor <= Math.sqrt(element); factor += 2) {
    if (element % factor === 0) {
      return false;
    }
  }
  return true;
}

console.log([4, 6, 8, 12].findLastIndex(isPrime)); // -1, not found
console.log([4, 5, 7, 8, 9, 11, 12].findLastIndex(isPrime)); // 5
```

### 疎配列に対する findLastIndex() の使用

疎配列から `undefined` を検索し、空のスロットのインデックスを取得することができます。

```js
console.log([1, , 3].findLastIndex((x) => x === undefined)); // 1
```

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

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

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

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.prototype.findlastindex |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

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


Array.prototype.includes() - JavaScript

Array.prototype.includes()
==========================

**`includes()`** は `Array` インスタンスのメソッドで、特定の要素が配列に含まれているかどうかを `true` または `false` で返します。

試してみましょう
--------

構文
--

```js
includes(searchElement)
includes(searchElement, fromIndex)
```

### 引数

`searchElement`

検索する値です。

`fromIndex` 省略可

検索し始める位置のゼロから始まるインデックスで、整数に変換されます。

* インデックスが負の場合、配列の末尾からさかのぼって数えます。 `fromIndex < 0` の場合、 `fromIndex + array.length` が使用されます。ただし、この場合でも配列は前から後ろに向けて検索されます。
* `fromIndex < -array.length` または `fromIndex` が省略された場合は `0` が使用され、配列全体に対して検索が行われます。
* `fromIndex >= array.length` の場合、配列の検索は行われず、 `false` が返されます。

### 返値

論理値で、`searchElement` の値が配列内（`fromIndex` が指定されていた場合は、配列のその位置以降の部分）にあった場合は `true` を返します。

解説
--

`includes()` は `searchElement` を SameValueZero アルゴリズムを使用して比較します。ゼロの値は符号に関わらず、すべて等しい（すなわち、`-0` は `0` と等しい）とみなされますが、`false` は `0` と同じとはみなされ*ません*。 `NaN` は正しく検索することができます。

疎配列で使用する場合、 `includes()` メソッドは空のスロットを `undefined` という値があるかのように反復処理します。

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

例
-

### includes() の使用

```js
[1, 2, 3].includes(2); // true
[1, 2, 3].includes(4); // false
[1, 2, 3].includes(3, 3); // false
[1, 2, 3].includes(3, -1); // true
[1, 2, NaN].includes(NaN); // true
["1", "2", "3"].includes(3); // false
```

### fromIndex が配列の長さと同じか大きい場合

`fromIndex` が配列の長さと同じか大きい場合は、配列を検索せずに `false` を返します。

```js
const arr = ["a", "b", "c"];

arr.includes("c", 3); // false
arr.includes("c", 100); // false
```

### 計算された位置が 0 より小さい場合

`fromIndex` が負の値である場合、`searchElement` の検索を開始するための配列内の位置として、計算により位置が算出されます。計算された位置が `0` 以下の場合は、配列全体が検索されます。

```js
// 配列の長さは 3
// fromIndex は -100
// 補正されたインデックスは 3 + (-100) = -97

const arr = ["a", "b", "c"];

arr.includes("a", -100); // true
arr.includes("b", -100); // true
arr.includes("c", -100); // true
arr.includes("a", -2); // false
```

### 疎配列に対する includes() の使用

疎配列で `undefined` を検索して `true` を取得することができます。

```js
console.log([1, , 3].includes(undefined)); // true
```

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

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

```js
const arrayLike = {
  length: 3,
  0: 2,
  1: 3,
  2: 4,
  3: 1, // length が 3 なので includes() からは無視される
};
console.log(Array.prototype.includes.call(arrayLike, 2));
// true
console.log(Array.prototype.includes.call(arrayLike, 1));
// false
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.prototype.includes |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

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


Array.prototype.flatMap() - JavaScript

Array.prototype.flatMap()
=========================

Baseline Widely available
-------------------------

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

* Learn more
* See full compatibility
* Report feedback
**`flatMap()`** は `Array` インスタンスのメソッドで、最初にマッピング関数を使用してそれぞれの要素をマップした後、結果を新しい配列内に平坦化します。これは、 `map()` の後に深さ 1 の `flat()` を行うのと同じですが (`arr.map(...args).flat()`)、これら 2 つのメソッドを別々に呼び出すよりもわずかに効率的です。

試してみましょう
--------

構文
--

```js
flatMap(callbackFn)
flatMap(callbackFn, thisArg)
```

### 引数

`callbackFn`

配列のそれぞれの要素に対して実行する関数。この関数は、新しい配列の要素を格納した配列を返すか、新しい配列に追加する 1 つの配列以外の値を返します。この関数は、以下の引数で呼び出されます。

`element`

配列で現在処理中の要素です。

`index`

配列で現在処理中の要素のインデックスです。

`array`

`flatMap()` が呼び出された配列です。

`thisArg` 省略可

`callbackFn` を実行するときに `this` として使用する値です。反復処理メソッドを参照してください。

### 返値

各要素がコールバック関数の結果であり、深さが 1 に平坦化された新しい配列です。

解説
--

`flatMap()` メソッドは反復処理メソッドです。コールバック関数の詳細な説明は `Array.prototype.map()` を参照してください。`flatMap()` メソッドは、`map(callbackFn, thisArg)` の後にの `flat(1)` を呼び出すのと同じです。要素ごとに、新しい要素の配列を生成し、できた配列を連結して新しい配列を形成します。

`flatMap()` メソッドは汎用的です。これは `this` 値に `length` プロパティと整数キーのプロパティがあることだけを期待します。ただし、 `callbackFn` から返される値は、平坦化する場合は配列でなければなりません。

### 代替手段

#### 事前割り当てと明示的な反復処理

```js
const arr = [1, 2, 3, 4];

arr.flatMap((x) => [x, x \* 2]);
// is equivalent to
const n = arr.length;
const acc = new Array(n \* 2);
for (let i = 0; i < n; i++) {
  const x = arr[i];
  acc[i \* 2] = x;
  acc[i \* 2 + 1] = x \* 2;
}
// [1, 2, 2, 4, 3, 6, 4, 8]
```

この場合、 `flatMap` の手法は for ループの手法よりも遅いことに注意してください。これは、ガベージコレクションが必要な一時的な配列が生成されるためと、返される配列のサイズを頻繁に変更する必要がないためです。しかし、柔軟性と可読性が求められる場合には、 `flatMap` が正しい解決策となる可能性があります。

例
-

### `map()` と `flatMap()`

```js
const arr1 = [1, 2, 3, 4];

arr1.map((x) => [x \* 2]);
// [[2], [4], [6], [8]]

arr1.flatMap((x) => [x \* 2]);
// [2, 4, 6, 8]

// only one level is flattened
arr1.flatMap((x) => [[x \* 2]]);
// [[2], [4], [6], [8]]
```

上記は map を使用することでも実現できますが、ここでは `flatMap()` の使用方法をよりよく示す例を紹介します。

文章のリストから単語のリストを生成してみましょう。

```js
const arr1 = ["it's Sunny in", "", "California"];

arr1.map((x) => x.split(" "));
// [["it's","Sunny","in"],[""],["California"]]

arr1.flatMap((x) => x.split(" "));
// ["it's","Sunny","in", "", "California"]
```

出力リストの長さは入力リストの長さとは異なる場合があることに注意してください。

### map() のアイテムの追加と削除

`flatMap` は、`map` 中にアイテムの追加と削除（アイテムの数を変更）を行う方法として利用できます。
 つまり、常に*一対一*ではなく、*多くのアイテムを多くのアイテムに*（入力されたアイテムを個別に扱うことで）マップできるようになります。
 この意味では、 filter の逆のような働きをします。
 単純に、アイテムを保持するには 1 要素の配列を返し、アイテムを追加するには複数要素の配列を返し、アイテムを削除するには 0 要素の配列を返します。

```js
// 例えば、すべての負の数を取り除き、
// 奇数を偶数と 1 に分割したいとします。
const a = [5, 4, -3, 20, 17, -33, -4, 18];
// |\ \ x | | \ x x |
// [4,1, 4, 20, 16, 1, 18]

const result = a.flatMap((n) => {
  if (n < 0) {
    return [];
  }
  return n % 2 === 0 ? [n] : [n - 1, 1];
});
console.log(result); // [4, 1, 4, 20, 16, 1, 18]
```

### 疎配列に対する flatMap() の使用

`map()` は呼び出されず、 `flat()` は返す配列の空のスロットを無視するので、 `callbackFn` は元の配列の空のスロットに対しては呼び出されません。

```js
console.log([1, 2, , 4, 5].flatMap((x) => [x, x \* 2])); // [1, 2, 2, 4, 4, 8, 5, 10]
console.log([1, 2, 3, 4].flatMap((x) => [, x \* 2])); // [2, 4, 6, 8]
```

### 配列以外のオブジェクトに対する flatMap() の呼び出し

`flatMap()` メソッドは `this` の `length` プロパティを読み込み、次にキーが `length` より小さい非負の整数である各プロパティにアクセスします。コールバック関数の返り値が配列でない場合は、常に結果の配列に直接追加されます。

```js
const arrayLike = {
  length: 3,
  0: 1,
  1: 2,
  2: 3,
  3: 4, // length が 3 であるため flatMap() から無視される
};
console.log(Array.prototype.flatMap.call(arrayLike, (x) => [x, x \* 2]));
// [1, 2, 2, 4, 3, 6]

// コールバックから返された配列風のオブジェクトは平坦化されない
console.log(
  Array.prototype.flatMap.call(arrayLike, (x) => ({
    length: 1,
    0: x,
  })),
);
// [ { '0': 1, length: 1 }, { '0': 2, length: 1 }, { '0': 3, length: 1 } ]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.prototype.flatmap |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Array.prototype.flatMap` のポリフィル (`core-js`)
* インデックス付きコレクションのガイド
* `Array`
* `Array.prototype.concat()`
* `Array.prototype.flat()`
* `Array.prototype.map()`
* `Array.prototype.reduce()`


Array.isArray() - JavaScript

Array.isArray()
===============

**`Array.isArray()`** 静的メソッドは、渡された値が `Array` かどうかを判断します。

試してみましょう
--------

構文
--

```js
Array.isArray(value)
```

### 引数

`value`

チェックするオブジェクト。

### 返値

`value` が `Array` の場合は `true` です。そうでなければ `false` を返します。 `value` が `TypedArray` インスタンスであった場合は常に `false` を返します。

解説
--

`Array.isArray()` は、渡された値が `Array` であるかどうかを調べます。値のプロトタイプチェーンを調べたり、 `Array` コンストラクターに頼っているわけではありません。配列リテラル構文または `Array` コンストラクターを使用して作成した値に対しては `true` を返します。このため、 `Array` コンストラクターの ID が異なり、`instanceof Array` が失敗してしまうような領域を超えるオブジェクトでも安全に使用することができます。

詳しくは、 "Determining with absolute accuracy whether or not a JavaScript object is an array" を参照してください。

また、 `Array.isArray()` は `Array.prototype` をプロトタイプチェーンに持つオブジェクトも拒否しますが、 `instanceof Array` が受け入れる実際の配列ではありません。

例
-

### Array.isArray() の使用

```js
// 以下の呼び出しはすべて true を返します
Array.isArray([]);
Array.isArray([1]);
Array.isArray(new Array());
Array.isArray(new Array("a", "b", "c", "d"));
Array.isArray(new Array(3));
// あまり知られていないものの Array.prototype は配列です
Array.isArray(Array.prototype);

// 以下の呼び出しはすべて false を返します
Array.isArray();
Array.isArray({});
Array.isArray(null);
Array.isArray(undefined);
Array.isArray(17);
Array.isArray("Array");
Array.isArray(true);
Array.isArray(false);
Array.isArray(new Uint8Array(32));
// これは配列ではありません。配列リテラルを使用した構文でも、
// Array コンストラクターでもないからです。
Array.isArray({ \_\_proto\_\_: Array.prototype });
```

### instanceof と Array.isArray()

`Array` のインスタンスをチェックする際、 `Array.isArray` は領域を超えても動作するので、 `instanceof` よりも推奨されます。

```js
const iframe = document.createElement("iframe");
document.body.appendChild(iframe);
const xArray = window.frames[window.frames.length - 1].Array;
const arr = new xArray(1, 2, 3); // [1, 2, 3]

// 配列を正しくチェックできます
Array.isArray(arr); // true
// arr のプロトタイプは xArray.prototype であり、
// Array.prototype とは異なるオブジェクトです。
arr instanceof Array; // false
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.isarray |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Array.isArray` のポリフィル (`core-js`)
* インデックス付きコレクションのガイド
* `Array`


Array.prototype.entries() - JavaScript

Array.prototype.entries()
=========================

**`entries()`** は `Array` インスタンスのメソッドで、配列内の各要素に対するキー/値のペアを含む新しい配列イテレーターオブジェクトを返します。

試してみましょう
--------

構文
--

```js
entries()
```

### 引数

なし。

### 返値

新しい反復可能イテレーターオブジェクトです。

解説
--

疎配列で使用された場合、 `entries()` メソッドは空のスロットを `undefined` の値が設定されているかのように反復処理します。

`entries()` メソッドは汎用的です。このメソッドは `this` の値に `length` プロパティと整数のキーを持ったプロパティがあることだけを求めます。

例
-

### インデックスと要素の反復処理

```js
const a = ["a", "b", "c"];

for (const [index, element] of a.entries()) {
  console.log(index, element);
}

// 0 'a'
// 1 'b'
// 2 'c'
```

### for...of ループの使用

```js
const array = ["a", "b", "c"];
const arrayEntries = array.entries();

for (const element of arrayEntries) {
  console.log(element);
}

// [0, 'a']
// [1, 'b']
// [2, 'c']
```

### 疎配列を反復処理

`entries()` は空のスロットを `undefined` であるかのように処理します。

```js
for (const element of [, "a"].entries()) {
  console.log(element);
}
// [0, undefined]
// [1, 'a']
```

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

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

```js
const arrayLike = {
  length: 3,
  0: "a",
  1: "b",
  2: "c",
  3: "d", // length が 3 なので entries() からは無視される
};
for (const entry of Array.prototype.entries.call(arrayLike)) {
  console.log(entry);
}
// [ 0, 'a' ]
// [ 1, 'b' ]
// [ 2, 'c' ]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.prototype.entries |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Array.prototype.entries` のポリフィル (`core-js`)
* インデックス付きコレクションガイド
* `Array`
* `Array.prototype.keys()`
* `Array.prototype.values()`
* `Array.prototype[@@iterator]()`
* `TypedArray.prototype.entries()`
* 反復処理プロトコル


Array.prototype.toSorted() - JavaScript

Array.prototype.toSorted()
==========================

**`toSorted()`** は `Array` インスタンスのメソッドで、 `sort()` メソッドに対応するコピーメソッドです。これは、要素を昇順にソートした新しい配列を返します。

構文
--

```js
toSorted()
toSorted(compareFn)
```

### 引数

`compareFn` 省略可

ソート順を定義する関数を指定します。省略した場合は、配列の要素を文字列に変換し、 Unicode コードポイントの値に従って並べ替えます。

`a`

比較する最初の要素です。

`b`

比較する 2 番目の要素です。

### 返値

要素を昇順にソートした新しい配列です。

解説
--

`compareFn` 引数の情報については `sort()` を参照してください。

疎配列が使用された場合、 `toSorted()` メソッドは空のスロットを `undefined` という値があるものとして反復処理します。

`toSorted()` メソッドは汎用です。 `this` の値が `length` プロパティを持っており、整数のキーのプロパティがあることのみを期待します。

例
-

### 配列のソート

```js
const months = ["Mar", "Jan", "Feb", "Dec"];
const sortedMonths = months.toSorted();
console.log(sortedMonths); // ['Dec', 'Feb', 'Jan', 'Mar']
console.log(months); // ['Mar', 'Jan', 'Feb', 'Dec']

const values = [1, 10, 21, 2];
const sortedValues = values.toSorted((a, b) => a - b);
console.log(sortedValues); // [1, 2, 10, 21]
console.log(values); // [1, 10, 21, 2]
```

他の利用例は、 `sort()` を参照してください。

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

空のスロットは値が `undefined` であるかのようにソートされます。これらは常に配列の末尾にソートされ、 `compareFn` は呼び出されません。

```js
console.log(["a", "c", , "b"].toSorted()); // ['a', 'b', 'c', undefined]
console.log([, undefined, "a", "b"].toSorted()); // ["a", "b", undefined, undefined]
```

### 配列以外のオブジェクトに対する toSorted() の呼び出し

`toSorted()` メソッドは `this` の `length` プロパティを読み取ります。そして、`length - 1` から `0` までの整数のキーを持つ各プロパティを降順に訪れ、現在のプロパティの値を配列の末尾に追加して返します。

```js
const arrayLike = {
  length: 3,
  unrelated: "foo",
  0: 5,
  2: 4,
  3: 3, // length が 3 なので toSorted() からは無視される
};
console.log(Array.prototype.toSorted.call(arrayLike));
// [4, 5, undefined]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.prototype.tosorted |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Array.prototype.toSorted` のポリフィル (`core-js`)
* インデックス付きコレクションのガイド
* `Array.prototype.sort()`
* `Array.prototype.toReversed()`
* `Array.prototype.toSpliced()`
* `Array.prototype.with()`
* `TypedArray.prototype.toSorted()`


Array.prototype.keys() - JavaScript

Array.prototype.keys()
======================

**`keys()`** は `Array` インスタンスのメソッドで、配列内の各インデックスのキーを含む、新しい配列イテレーターオブジェクトを返します。

試してみましょう
--------

構文
--

```js
keys()
```

### 引数

なし。

### 返値

新しい反復可能なイテレーターオブジェクトです。

解説
--

疎配列で使用した場合、 `keys()` メソッドは空のスロットを `undefined` という値があるかのように反復処理します。

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

例
-

### 疎配列に対する keys() の呼び出し

配列に実際に存在するキーだけを処理する `Object.keys()` とは異なり、 `keys()` イテレーターは見つからないプロパティを表す穴を無視しません。

```js
const arr = ["a", , "c"];
const sparseKeys = Object.keys(arr);
const denseKeys = [...arr.keys()];
console.log(sparseKeys); // ['0', '2']
console.log(denseKeys); // [0, 1, 2]
```

### 配列以外のオブジェクトに対する keys() の呼び出し

`keys()`メソッドは `this` の `length` プロパティを読み込み、 0 から `length - 1` までのすべての整数インデックスを返します。実際にはインデックスアクセスは行われません。

```js
const arrayLike = {
  length: 3,
};
for (const entry of Array.prototype.keys.call(arrayLike)) {
  console.log(entry);
}
// 0
// 1
// 2
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.prototype.keys |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Array.prototype.keys` のポリフィル (`core-js`)
* インデックス付きコレクションのガイド
* `Array`
* `Array.prototype.entries()`
* `Array.prototype.values()`
* `Array.prototype[@@iterator]()`
* `TypedArray.prototype.keys()`
* Iteration protocols


Array.prototype.shift() - JavaScript

Array.prototype.shift()
=======================

**`shift()`** は `Array` インスタンスのメソッドで、配列から**最初**の要素を取り除き、その要素を返します。このメソッドは配列の長さを変えます。

試してみましょう
--------

構文
--

```js
shift()
```

### 引数

なし。

### 返値

配列から取り除かれた要素を返します。配列が空の場合は、`undefined` を返します。

解説
--

`shift()` メソッドは 0 番目の位置の要素を取り除き、続く位置の値を小さい方向にずらします。
 そして、削除された値を返します。`length` プロパティが 0 の場合、`undefined` を返します。

`pop()` メソッドは `shift()` と似た動作をしますが、こちらは配列の末尾の要素に適用されます。

`shift()` メソッドは変更メソッドです。長さと `this` の内容を変更します。 `this` の値を変化させず、最初の要素を取り除いた新しい配列を返したい場合は、代わりに `arr.slice(1)` を使用することができます。

`shift()` メソッドは汎用的です。これは `this` 値に `length` プロパティと整数キーのプロパティがあることだけを期待します。文字列も配列風ですが、文字列は不変であるため、このメソッドを適用するのは適切ではありません。

例
-

### 配列から要素を除去

以下のコードは `myFish` 配列を、その最初の要素を取り除く前後で表示します。また、取り除いた要素も表示します。

```js
const myFish = ["angel", "clown", "mandarin", "surgeon"];

console.log("myFish 処理前:", myFish);
// myFish 処理前: ['angel', 'clown', 'mandarin', 'surgeon']

const shifted = myFish.shift();

console.log("myFish 処理後:", myFish);
// myFish 処理後: ['clown', 'mandarin', 'surgeon']

console.log("取り除いた要素:", shifted);
// 取り除いた要素: angel
```

### shift() メソッドの while ループ内での使用

shift() メソッドは時に、 while 文の条件内において用いられます。以下のコードでは、要素がすべて無くなるまで、反復処理のたびにその配列内の次の要素を取り除きます。

```js
const names = ["Andrew", "Tyrone", "Paul", "Maria", "Gayatri"];

while (typeof (i = names.shift()) !== "undefined") {
  console.log(i);
}
// Andrew, Tyrone, Paul, Maria, Gayatri
```

### 配列以外のオブジェクトに対する shift() の呼び出し

`shift()` メソッドは `this` の `length` プロパティを読み込みます。正規化された長さが 0 の場合、`length` は再び `0` に設定されます（以前は負の値または `undefined` であった可能性があります）。そうでない場合は、 `0` のプロパティを返し、残りのプロパティは左に 1 つシフトされます。 `length` プロパティは 1 つデクリメントされます。

```js
const arrayLike = {
  length: 3,
  unrelated: "foo",
  2: 4,
};
console.log(Array.prototype.shift.call(arrayLike));
// undefined。空のスロットであるため
console.log(arrayLike);
// { '1': 4, length: 2, unrelated: 'foo' }

const plainObj = {};
// length プロパティがないため、 length は 0
Array.prototype.shift.call(plainObj);
console.log(plainObj);
// { length: 0 }
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.prototype.shift |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* インデックス付きコレクションのガイド
* `Array`
* `Array.prototype.push()`
* `Array.prototype.pop()`
* `Array.prototype.unshift()`
* `Array.prototype.concat()`
* `Array.prototype.splice()`


Array.prototype.push() - JavaScript

Array.prototype.push()
======================

**`push()`** は `Array` インスタンスのメソッドで、配列の末尾に指定された要素を追加します。また返値として配列の新しい長さを返します。

試してみましょう
--------

構文
--

```js
push()
push(element1)
push(element1, element2)
push(element1, element2, /\* …, \*/ elementN)
```

### 引数

`element1`, …, `elementN`

配列の末尾に追加する要素。

### 返値

メソッドが呼び出されたオブジェクトの新しい `length` プロパティ。

解説
--

`push()` メソッドは配列の末尾に要素を追加します。

`Array.prototype.unshift()` は `push()` と同様の動作ですが、配列の先頭に適用されます。

`push()` メソッドは変更メソッドです。これは、 `this` の長さとコンテンツを変更します。 `this` の値はそのままで、最後に要素を追加した新しい配列を返したい場合は、代わりに `arr.concat([element0, element1, /* ... ,*/ elementN])` を使用することができます。要素が余分な配列に包まれていることに注意してください。そうでなければ、要素が配列そのものである場合、 `concat()` の動作により、単一の要素として挿入されるのではなく、分散されてしまうでしょう。

`pop()` メソッドは汎用的です。これは `this` 値に `length` プロパティと整数キーのプロパティがあることだけを期待します。文字列も配列風ですが、文字列は不変であるため、このメソッドを適用するのは適切ではありません。

例
-

### 配列に要素を追加する

以下のコードは 2 つの要素を持つ配列 `sports` を生成し、それに 2 つの要素を追加します。コードの実行後、変数 `total` には 4 が入ります。

```js
const sports = ["soccer", "baseball"];
const total = sports.push("football", "swimming");

console.log(sports); // ['soccer', 'baseball', 'football', 'swimming']
console.log(total); // 4
```

### ２つの配列をマージする

この例ではスプレッド構文を使用して、二番目の配列から最初の配列へすべての要素を挿入します。

```js
const vegetables = ["parsnip", "potato"];
const moreVegs = ["celery", "beetroot"];

// 1 つ目の配列に 2 つ目の配列をマージさせます
vegetables.push(...moreVegs);

console.log(vegetables); // ['parsnip', 'potato', 'celery', 'beetroot']
```

2 つの配列の結合は、 `concat()` メソッドでも行うことができます。

### 配列以外のオブジェクトに対する push() の呼び出し

`push()` メソッドは `this` の `length` プロパティを読み込みます。そして、 `length` から始まる `this` の各インデックスを `push()` に渡された引数で設定します。最後に、`length` に直前の長さにプッシュされた要素数を加えた値を設定します。

```js
const arrayLike = {
  length: 3,
  unrelated: "foo",
  2: 4,
};
Array.prototype.push.call(arrayLike, 1, 2);
console.log(arrayLike);
// { '2': 4, '3': 1, '4': 2, length: 5, unrelated: 'foo' }

const plainObj = {};
// length プロパティがないので、長さは 0
Array.prototype.push.call(plainObj, 1, 2);
console.log(plainObj);
// { '0': 1, '1': 2, length: 2 }
```

### オブジェクトを配列のように使用する

前述したように、`push` は内部的には汎用的なので、その利点を活かすことができます。この例が示しているように、オブジェクト上で `Array.prototype.push` は正しく動作します。

オブジェクトの集合を保存するために、配列を生成していないことに注意してください。代わりに、集合をオブジェクト自体に保存して、配列を扱っているかのように見せかけるために `Array.prototype.push` 上で `call` を使用しています。そして、JavaScript は実行コンテキストの確立を許可しているおかげで、これは動作します。

```js
const obj = {
  length: 0,

  addElem(elem) {
    // obj.length は、要素が追加されるたびに
    // 自動的に増加する。
    [].push.call(this, elem);
  },
};

// 例示のために空のオブジェクトを追加する。
obj.addElem({});
obj.addElem({});
console.log(obj.length); // 2
```

`obj` は配列ではありませんが、本当の配列を扱っているかのように `push` メソッドは `obj` の `length` プロパティを増加させできていることに注意してください。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.prototype.push |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* このメソッドの修正を含んだ `Array.prototype.push` のポリフィル (`core-js`)
* インデックス付きコレクションのガイド
* `Array.prototype.pop()`
* `Array.prototype.shift()`
* `Array.prototype.unshift()`
* `Array.prototype.concat()`
* `Array.prototype.splice()`


Array.prototype.reduce() - JavaScript

Array.prototype.reduce()
========================

**`reduce()`** は `Array` インターフェイスのメソッドで、配列のそれぞれの要素に対して、ユーザーが提供した「縮小」コールバック関数を呼び出します。その際、直前の要素における計算結果の返値を渡します。配列のすべての要素に対して縮小関数を実行した結果が単一の値が最終結果になります。

 コールバックの初回実行時には「直前の計算の返値」は存在しません。
 初期値が与えらえた場合は、代わりに使用されることがあります。
 そうでない場合は、配列の要素 0 が初期値として使用され、次の要素（0 の位置ではなく 1 の位置）から反復処理が開始されます。

`reduce()` で一番わかりやすいのは、配列のすべての要素の和を返す場合でしょう。

試してみましょう
--------

縮小関数は配列を要素ごとに走査し、それぞれの段階で、前の段階の結果に現在の配列の値を加えていきます (この結果は、それ以前のすべての段階を合算したものです)。

構文
--

```js
reduce(callbackFn)
reduce(callbackFn, initialValue)
```

### 引数

`callbackFn`

配列の各要素に対して実行される関数です。その返値は、次に `callbackFn` を呼び出す際の `accumulator` 引数の値になります。最後の呼び出しでは、返値は `reduce()` の返値となります。この関数は以下の引数で呼び出されます。

`accumulator`

前回の `callbackFn` の呼び出し結果の値です。初回の呼び出しでは `initialValue` が指定されていた場合はその値、そうでない場合は `array[0]` の値です。

`currentValue`

現在の要素の値です。初回の呼び出しでは `initialValue` が指定された場合は `array[0]` の値であり、そうでない場合は `array[1]` の値です。

`currentIndex`

`currentValue` の位置です。初回の呼び出しでは、 `initialValue` が指定された場合は `0`、そうでない場合は `1` です。

`array`

`reduce()` が呼び出された配列です。

`initialValue` 省略可

 コールバックが最初に呼び出された時に `accumulator` が初期化される値です。
 `initialValue` が指定された場合、`callbackFn` は配列の最初の値を `currentValue` として実行を開始します。
 もし `initialValue` が指定されなかった場合、`accumulator` は配列の最初の値に初期化され、`callbackFn` は配列の 2 つ目の値を `currentValue` として実行を開始します。この場合、配列が空であれば（`accumulator`として返す最初の値がなければ）エラーが発生します。

### 返値

配列全体にわたって「縮小」コールバック関数を実行した結果の値です。

### 例外

`TypeError`

配列に要素がなく、かつ `initialValue` が提供されなかった場合に発生します。

解説
--

`reduce()` メソッドは反復処理メソッドです。「縮小」コールバック関数を配列に含まれる各要素に対して昇順に一度ずつ呼び出し、その結果を単一の値に積算します。毎回、 `callbackFn` の返値は次回の `callbackFn` の呼び出しで `accumulator` として渡されます。最終的な `accumulator` の値（配列の最終反復処理において `callbackFn` から返される値）が `reduce()` の返値となります。

`callbackFn` は値が割り当てられている配列インデックスに対してのみ呼び出されます。疎配列の空のスロットに対しては呼び出されません。

他の反復処理メソッドとは異なり、 `reduce()` は `thisArg` 引数を受け入れません。 `callbackFn` は常に `undefined` を `this` として呼び出され、 `callbackFn` が厳格モードでない場合は `globalThis` に置き換えられます。

`reduce()` は関数型プログラミングの中心的な概念です。ここでは、どの値も変異させることができないので、配列のすべての値を積算するには、反復処理のたびに新しい積算値を返さなければなりません。この約束事は JavaScript の `reduce()` にも当てはまります。スプレッド構文や他の可能な限りコピーする方法を使用して、既存のものを変更せずに、アキュームレーターとして新しい配列やオブジェクトを作成すべきなのです。もし、アキュームレーターをコピーする代わりに変化させることにした場合、コールバックで変更したオブジェクトを返すことを忘れないでください、さもなければ、次の反復処理で undefined を受け取ることになります。

`reduce()` メソッドは呼び出し元の配列を変更しませんが、 `callbackFn` に指定された関数は変更することがあります。ただし、配列の長さは `callbackFn` を最初に呼び出す前に保存されることに注意してください。したがって、

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

**警告:** 前項で説明したような、参照中の配列の同時進行での変更は（特殊な場合を除いて）普通は避けるべきです。多くの場合、理解しにくいコードになります。

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

### 稀な場合

配列が（位置に関わらず） 1 つの要素しか持たず、 `initialValue` が指定されなかった場合、または `initialValue` が指定されていても配列が空だった場合、 `callbackFn` は*実行されずに*要素が返却されます。

`initialValue` が提供され、配列が空でない場合、 reduce メソッドは常に 0 の位置からコールバック関数を呼び出し始めます。

`initialValue` が提供されなかった場合、 reduce メソッドは、次の例に示すように、長さが 1 より大きい配列、長さが 1 の配列、長さが 0 の配列に対して異なる動作をします。

```js
const getMax = (a, b) => Math.max(a, b);

// コールバックは 0 の位置から配列内の全要素に対して呼び出される
[1, 100].reduce(getMax, 50); // 100
[50].reduce(getMax, 10); // 50

// コールバックは 1 の位置に対して 1 度だけ呼び出される
[1, 100].reduce(getMax); // 100

// コールバックは呼び出されない
[50].reduce(getMax); // 50
[].reduce(getMax, 1); // 1

[].reduce(getMax); // TypeError
```

例
-

### 初期値がない場合の reduce() の動作

下記のコードは、初期値がない場合に配列に `reduce()` を呼び出したときに何が起こるかを示します。

```js
const array = [15, 16, 17, 18, 19];

function reducer(accumulator, currentValue, index) {
  const returns = accumulator + currentValue;
  console.log(
    `accumulator: ${accumulator}, currentValue: ${currentValue}, index: ${index}, returns: ${returns}`,
  );
  return returns;
}

array.reduce(reducer);
```

コールバック関数は 4 回呼び出され、各回の引数の内容は以下のようになります。

|  | `accumulator` | `currentValue` | `index` | 返値 |
| --- | --- | --- | --- | --- |
| 最初の呼び出し | `15` | `16` | `1` | `31` |
| 2 番目の呼び出し | `31` | `17` | `2` | `48` |
| 3 番目の呼び出し | `48` | `18` | `3` | `66` |
| 4 番目の呼び出し | `66` | `19` | `4` | `85` |

`array` の要素は処理中に変化しません。常に `[15, 16, 17, 18, 19]` です。 `reduce()` の返値は、コールバック呼び出しの最後の返値である (`85`) となるでしょう。

### 初期値がある場合の reduce() の動作

ここでは、同じアルゴリズムで同じ配列を減らしますが、 `reduce()` の 2 番目の引数として `10` という `initialValue` を渡します。

```js
[15, 16, 17, 18, 19].reduce(
  (accumulator, currentValue) => accumulator + currentValue,
  10,
);
```

コールバックは 5 回呼び出され、それぞれの呼び出しにおける引数と返値は次のようになります。

|  | `accumulator` | `currentValue` | `index` | 返値 |
| --- | --- | --- | --- | --- |
| 最初の呼び出し | `10` | `15` | `0` | `25` |
| 2 番目の呼び出し | `25` | `16` | `1` | `41` |
| 3 番目の呼び出し | `41` | `17` | `2` | `58` |
| 4 番目の呼び出し | `58` | `18` | `3` | `76` |
| 5 番目の呼び出し | `76` | `19` | `4` | `95` |

この場合の `reduce()` の返値は `95` となります。

### オブジェクト配列の値の合計値

オブジェクトの配列に含まれた値の合計値を出すには、すべての項目を関数内で取得できるようにするために `initialValue` を指定する**必要があります**。

```js
const objects = [{ x: 1 }, { x: 2 }, { x: 3 }];
const sum = objects.reduce(
  (accumulator, currentValue) => accumulator + currentValue.x,
  0,
);

console.log(sum); // logs 6
```

### 関数を直列にパイプ接続

`pipe` 関数は一連の関数を受け取り、新しい関数を返します。新しい関数が引数で呼び出されると、一連の関数が順番に呼び出され、それぞれが前回関数の返値を受け取ります。

```js
const pipe =
  (...functions) =>
  (initialValue) =>
    functions.reduce((acc, fn) => fn(acc), initialValue);

// 合成に使用する素材
const double = (x) => 2 \* x;
const triple = (x) => 3 \* x;
const quadruple = (x) => 4 \* x;

// 特定の値の乗算のための合成関数
const multiply6 = pipe(double, triple);
const multiply9 = pipe(triple, triple);
const multiply16 = pipe(quadruple, quadruple);
const multiply24 = pipe(double, triple, quadruple);

// 使用方法
multiply6(6); // 36
multiply9(9); // 81
multiply16(16); // 256
multiply24(10); // 240
```

### プロミスを直列に実行

プロミスシーケンスは、非同期で行われることを除けば、基本的に前回の節で示された関数のパイプ接続です。

```js
// パイプと比較すると、 fn(acc) は acc.then(fn) に変更され、
// initialValue はプロミスであることが保証されます。
const asyncPipe =
  (...functions) =>
  (initialValue) =>
    functions.reduce((acc, fn) => acc.then(fn), Promise.resolve(initialValue));

// 合成に使用する構成要素
const p1 = async (a) => a \* 5;
const p2 = async (a) => a \* 2;
// 構成された関数は、最終的にすべてプロミスで包まれるため、
// プロミス以外を返すこともできます。
const f3 = (a) => a \* 3;
const p4 = async (a) => a \* 4;

asyncPipe(p1, p2, f3, p4)(10).then(console.log); // 1200
```

`asyncPipe` は `async`/`await` を使用して実装することもでき、 `pipe` との類似性をよりよく示しています。

```js
const asyncPipe =
  (...functions) =>
  (initialValue) =>
    functions.reduce(async (acc, fn) => fn(await acc), initialValue);
```

### reduce() を疎配列で使用

`reduce()` は疎配列の欠落している要素をスキップしますが、値が `undefined` の場合はスキップしません。

```js
console.log([1, 2, , 4].reduce((a, b) => a + b)); // 7
console.log([1, 2, undefined, 4].reduce((a, b) => a + b)); // NaN
```

### 配列以外のオブジェクトに対する reduce() の呼び出し

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

```js
const arrayLike = {
  length: 3,
  0: 2,
  1: 3,
  2: 4,
  3: 99, // length が 3 であるため reduce() からは無視される
};
console.log(Array.prototype.reduce.call(arrayLike, (x, y) => x + y));
// 9
```

### reduce() を使用すべきでない場合

`reduce()` のような多目的の高次関数は強力ですが、特に経験の浅い JavaScript の開発者にとっては理解しにくい場合があります。他の配列メソッドを使用した方がコードが明快になる場合、開発者は `reduce()` を使用する他の利点と読み取り可能性のトレードオフを比較検討する必要があります。

`reduce()` は常に `for...of` ループと同等ですが、上位スコープの変数を変更する代わりに、各反復処理で新しい値を返すことに注意してください。

```js
const val = array.reduce((acc, cur) => update(acc, cur), initialValue);

// これは、次のものと同等です
let val = initialValue;
for (const cur of array) {
  val = update(val, cur);
}
```

前述のように、人々が `reduce()` を使用したいと思う理由は、データを不変とする関数型プログラミングの手法を模倣するためです。したがって、アキュムレーターの不変性を支持する開発者は、次のように反復処理ごとにアキュムレーター全体をコピーする傾向があります。

```js
const names = ["Alice", "Bob", "Tiff", "Bruce", "Alice"];
const countedNames = names.reduce((allNames, name) => {
  const currCount = Object.hasOwn(allNames, name) ? allNames[name] : 0;
  return {
    ...allNames,
    [name]: currCount + 1,
  };
}, {});
```

このコードは非効率的です。というのも、各イテレーターは `allNames` オブジェクト全体をコピーする必要があり、これは固有の名前がいくつあるかによってサイズが大きくなってしまうからです。このコードは最悪の場合、 `N` が `names` の長さだとすると `O(N^2)` のパフォーマンスになります。

各反復処理で `allNames` オブジェクトを変更したほうがよりよいでしょう。しかし、 `allNames` がいずれにせよ変更されるのであれば、 `reduce()` を単純な `for` ループに変換した方がより明確です。

```js
const names = ["Alice", "Bob", "Tiff", "Bruce", "Alice"];
const countedNames = names.reduce((allNames, name) => {
  const currCount = allNames[name] ?? 0;
  allNames[name] = currCount + 1;
  // allNames を返さないと、次の反復処理で undefined を受け取る
  return allNames;
}, Object.create(null));
```

```js
const names = ["Alice", "Bob", "Tiff", "Bruce", "Alice"];
const countedNames = Object.create(null);
for (const name of names) {
  const currCount = countedNames[name] ?? 0;
  countedNames[name] = currCount + 1;
}
```

したがって、アキュムレーターが配列やオブジェクトで、反復処理ごとに配列やオブジェクトをコピーしている場合、誤ってコードに 2 次的な複雑さを導入してしまい、大きなデータですぐにパフォーマンスが低下してしまう可能性があります。

`reduce()` の受け入れられる用途のいくつかは上で指定されたものです（特に、配列の合計、プロミスの順序付け、関数のパイプ処理）。他にも `reduce()` よりも優れた代替手段が存在する場合があります。

* 配列の平坦化。代わりに `flat()` を使用してください。

```js
const flattened = array.reduce((acc, cur) => acc.concat(cur), []);
```

```js
const flattened = array.flat();
```

* プロパティによるオブジェクトのグループ化。代わりに `Object.groupBy()` を使用してください。

```js
const groups = array.reduce((acc, obj) => {
  const key = obj.name;
  const curGroup = acc[key] ?? [];
  return { ...acc, [key]: [...curGroup, obj] };
}, {});
```

```js
const groups = Object.groupBy(array, (obj) => obj.name);
```

* オブジェクトの配列に格納されている配列の連結。代わりに `flatMap()` を使用してください。

```js
const friends = [
  { name: "Anna", books: ["Bible", "Harry Potter"] },
  { name: "Bob", books: ["War and peace", "Romeo and Juliet"] },
  { name: "Alice", books: ["The Lord of the Rings", "The Shining"] },
];
const allBooks = friends.reduce((acc, cur) => [...acc, ...cur.books], []);
```

```js
const allBooks = friends.flatMap((person) => person.books);
```

* 配列内の重複項目の除去。代わりに `Set` と `Array.from()` を使用してください。

```js
const uniqArray = array.reduce(
  (acc, cur) => (acc.includes(cur) ? acc : [...acc, cur]),
  [],
);
```

```js
const uniqArray = Array.from(new Set(array));
```

* 配列の要素の削除や追加。代わりに `flatMap()` を使用してください。

```js
// 数値の配列を受け取り、完全二乗を平方根に分割します。
const roots = array.reduce((acc, cur) => {
  if (cur < 0) return acc;
  const root = Math.sqrt(cur);
  if (Number.isInteger(root)) return [...acc, root, root];
  return [...acc, cur];
}, []);
```

```js
const roots = array.flatMap((val) => {
  if (val < 0) return [];
  const root = Math.sqrt(val);
  if (Number.isInteger(root)) return [root, root];
  return [val];
});
```

配列から要素を取り除くだけなら `filter()` も使用できます。
* 要素の検索、または要素が条件を満たすかどうかのテスト。代わりに `find()` と `findIndex()` または `some()` と `every()` を使用してください。これらのメソッドには、配列全体を反復処理することなく、結果が確定したらすぐに返すという好ましいこともあります。

```js
const allEven = array.reduce((acc, cur) => acc && cur % 2 === 0, true);
```

```js
const allEven = array.every((val) => val % 2 === 0);
```

`reduce()` が最良の選択である場合は、ドキュメント化と変数名の意味づけをすることで、可読性の欠点を軽減する手助けになります。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.prototype.reduce |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Array.prototype.reduce` のポリフィル (`core-js`)
* インデックス付きコレクションのガイド
* `Array`
* `Array.prototype.map()`
* `Array.prototype.flat()`
* `Array.prototype.flatMap()`
* `Array.prototype.reduceRight()`
* `TypedArray.prototype.reduce()`
* `Object.groupBy()`
* `Map.groupBy()`


Array.prototype.every() - JavaScript

Array.prototype.every()
=======================

**`every()`** は `Array` インスタンスのメソッドは、列内のすべての要素が指定された関数で実装されたテストに合格するかどうかをテストします。これは論理値を返します。

試してみましょう
--------

構文
--

```js
every(callbackFn)
every(callbackFn, thisArg)
```

### 引数

`callbackFn`

配列のそれぞれの要素に対して実行する関数です。要素がテストに合格した場合は真値を返し、そうでなければ偽値を返す必要があります。この関数は以下の引数で呼び出されます。

`element`

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

`index`

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

`array`

`every()` が実行されている配列です。

`thisArg` 省略可

`callbackFn` を実行するときに `this` として使用される値です。反復処理メソッドを参照してください。

### 返値

`callbackFn` 関数がいずれかの要素で偽値を返した場合は、すぐに `false` を返します。それ以外は `true` です。

解説
--

`every()` メソッドは反復処理メソッドです。配列のそれぞれの要素に対して、指定された `callbackFn` 関数が偽値を返すまで一度ずつ呼び出します。 そのような要素が見つかった場合、 `every()` は直ちに `false` を返し、配列の反復処理を中止します。そうでない場合、 `callbackFn` がすべての要素に対して真値を返すと、 `every()` は `true` を返します。

`every` は数学における「∀ （すべての / for all）」記号と同様のふるまいをします。特に、空の配列に対しては `true` を返します。（空集合のすべての要素が与えられた任意の条件を満たすことは空虚に真です。）

`callbackFn` は値が代入されている配列の要素に対してのみ呼び出されます。疎配列の空のスロットに対しては呼び出されません。

`every()` は呼び出された配列を変更しませんが、 `callbackFn` として指定された関数は変更することができます。ただし、配列の長さは `callbackFn` を最初に呼び出す前に保存されることに注意してください。したがって、

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

**警告:** 上記のように進行中の配列に対して変更を行うと、理解しにくいコードになることが多いので、（特別な場合を除いて）避けるのが一般的です。

`every()` メソッドは汎用的です。このメソッドは `this` の値に `length` プロパティと整数のキーを持ったプロパティがあることだけを求めます。

例
-

### すべての配列要素の大きさをテストする

次の例は、配列内のすべての要素が 10 以上であるかどうかテストします。

```js
function isBigEnough(element, index, array) {
  return element >= 10;
}
[12, 5, 8, 130, 44].every(isBigEnough); // false
[12, 54, 18, 130, 44].every(isBigEnough); // true
```

### ある配列が別の配列の部分集合であるかどうかを調べる

以下の例では、ある配列のすべての要素が別の配列に存在するかどうかをテストしています。

```js
const isSubset = (array1, array2) =>
  array2.every((element) => array1.includes(element));

console.log(isSubset([1, 2, 3, 4, 5, 6, 7], [5, 7, 6])); // true
console.log(isSubset([1, 2, 3, 4, 5, 6, 7], [5, 8, 7])); // false
```

### 疎配列に対する every() の使用

`every()` は空のスロットに対して関数を実行しません。

```js
console.log([1, , 3].every((x) => x !== undefined)); // true
console.log([2, , 2].every((x) => x === 2)); // true
```

### 初期配列への影響（変更、追加、削除）

次の例は、配列が変更されたときに `every` メソッドの動作をテストするものです。

```js
// ---------------
// アイテムの変更
// ---------------
let arr = [1, 2, 3, 4];
arr.every((elem, index, arr) => {
  arr[index + 1]--;
  console.log(`[${arr}][${index}] -> ${elem}`);
  return elem < 2;
});

// ループは 3 回反復処理されるが、
// 何も変更しなければ 2 回実行される
//
// 1st iteration: [1,1,3,4][0] -> 1
// 2nd iteration: [1,1,2,4][1] -> 1
// 3rd iteration: [1,1,2,3][2] -> 2

// ---------------
// アイテムの追加
// ---------------
arr = [1, 2, 3];
arr.every((elem, index, arr) => {
  arr.push("new");
  console.log(`[${arr}][${index}] -> ${elem}`);
  return elem < 4;
});

// 新しい項目を追加しても、ループは 3 回反復処理する
//
// 1st iteration: [1, 2, 3, new][0] -> 1
// 2nd iteration: [1, 2, 3, new, new][1] -> 2
// 3rd iteration: [1, 2, 3, new, new, new][2] -> 3

// ---------------
// アイテムの削除
// ---------------
arr = [1, 2, 3, 4];
arr.every((elem, index, arr) => {
  arr.pop();
  console.log(`[${arr}][${index}] -> ${elem}`);
  return elem < 4;
});

// 残りのアイテムは `pop()` して取り除かれるため、ループは 2 回だけ反復処理される
//
// 1st iteration: [1,2,3][0] -> 1
// 2nd iteration: [1,2][1] -> 2
```

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

`every()` メソッドは `this` の `length` プロパティを読み込み、すべてアクセスするか `callbackFn` が `false` を返すまで `length` より小さい非負の整数キーを持つ各プロパティにアクセスします。

```js
const arrayLike = {
  length: 3,
  0: "a",
  1: "b",
  2: "c",
  3: 345, // length が 3 なので every() からは無視される
};
console.log(
  Array.prototype.every.call(arrayLike, (x) => typeof x === "string"),
); // true
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-array.prototype.every |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

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