AsyncFunction() コンストラクター - JavaScript

AsyncFunction() コンストラクター
========================

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

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

* Learn more
* See full compatibility
* Report feedback
**`AsyncFunction()`** コンストラクターは `AsyncFunction` オブジェクトを生成します。

なお、`AsyncFunction` はグローバルオブジェクトではないことに注意してください。これは以下のようなコードで取得することができます。

```js
const AsyncFunction = async function () {}.constructor;
```

`AsyncFunction()` コンストラクターは直接使用することを意図されておらず、 `Function()` の説明で述べた注意事項はすべて `AsyncFunction()` に適用されます。

構文
--

```js
new AsyncFunction(functionBody)
new AsyncFunction(arg0, functionBody)
new AsyncFunction(arg0, arg1, functionBody)
new AsyncFunction(arg0, arg1, /\* … ,\*/ argN, functionBody)

AsyncFunction(functionBody)
AsyncFunction(arg0, functionBody)
AsyncFunction(arg0, arg1, functionBody)
AsyncFunction(arg0, arg1, /\* … ,\*/ argN, functionBody)
```

**メモ:** `AsyncFunction()` は `new` があってもなくても呼び出すことができます。どちらも新しい `AsyncFunction` インスタンスを生成します。

### 引数

`Function()` を参照してください。

例
-

### AsyncFunction() コンストラクターから非同期関数を生成

```js
function resolveAfter2Seconds(x) {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve(x);
    }, 2000);
  });
}

const AsyncFunction = async function () {}.constructor;

const fn = new AsyncFunction(
  "a",
  "b",
  "return await resolveAfter2Seconds(a) + await resolveAfter2Seconds(b);",
);

fn(10, 20).then((v) => {
  console.log(v); // prints 30 after 4 seconds
});
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-async-function-constructor |

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

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

関連情報
----

* `async function` 宣言
* `async function` 式
* `Function()` コンストラクター


Error.prototype.lineNumber - JavaScript

Error.prototype.lineNumber
==========================

**非標準:** この機能は標準ではなく、標準化の予定もありません。公開されているウェブサイトには使用しないでください。ユーザーによっては使用できないことがあります。実装ごとに大きな差があることもあり、将来は振る舞いが変わるかもしれません。

**`lineNumber`** プロパティは、このエラーを起こしたファイル内の行番号が入ります。

例
-

### lineNumber の使用

```js
var e = new Error("Could not parse input");
throw e;
console.log(e.lineNumber); // 2
```

### error イベントを使用した他の例

```js
window.addEventListener("error", function (e) {
  console.log(e.lineNumber); // 5
});
var e = new Error("入力を解釈できません");
throw e;
```

これは標準の機能ではなく、幅広く対応されていません。下記のブラウザーの互換性の表をご覧ください。

仕様書
---

仕様の一部ではありません。

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

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

関連情報
----

* `Error.prototype.stack`
* `Error.prototype.columnNumber`
* `Error.prototype.fileName`


Error.prototype.message - JavaScript

Error.prototype.message
=======================

**`message`** プロパティは、人間が読めるエラーの説明です。

解説
--

このプロパティは、利用可能または設定されている場合、エラーの簡潔な説明を含みます。SpiderMonkey は、例外の `message` プロパティを広範囲に渡って使用します。`name` プロパティは `message` プロパティとの組み合わせで、Error の文字列表現を生成するために `Error.prototype.toString()` メソッドにより使用されます。

既定で `message` プロパティは空文字列ですが、この振る舞いは、 `Error` コンストラクターの第一引数としてメッセージを指定することにより、インスタンスを上書きできます。

例
-

### 独自のエラーを発生させる

```js
var e = new Error("Could not parse input");
// e.message は 'Could not parse input'
throw e;
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-error.prototype.message |

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

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

関連情報
----

* `Error.prototype.name`
* `Error.prototype.toString()`


Error.prototype.columnNumber - JavaScript

Error.prototype.columnNumber
============================

**非標準:** この機能は標準ではなく、標準化の予定もありません。公開されているウェブサイトには使用しないでください。ユーザーによっては使用できないことがあります。実装ごとに大きな差があることもあり、将来は振る舞いが変わるかもしれません。

**`columnNumber`** プロパティは、このエラーを起こしたファイルの行内の列番号が入ります。

例
-

### columnNumber の使用

```js
var e = new Error("Could not parse input");
throw e;
console.log(e.columnNumber); // 0
```

仕様書
---

仕様の一部ではありません。

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

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

関連情報
----

* `Error.prototype.stack`
* `Error.prototype.lineNumber`
* `Error.prototype.fileName`


Error.prototype.fileName - JavaScript

Error.prototype.fileName
========================

**非標準:** この機能は標準ではなく、標準化の予定もありません。公開されているウェブサイトには使用しないでください。ユーザーによっては使用できないことがあります。実装ごとに大きな差があることもあり、将来は振る舞いが変わるかもしれません。

**`fileName`** プロパティは、このエラーを起こしたファイルへのパスを含みます。

解説
--

この標準外のプロパティは、このエラーを起こしたファイルへのパスが入ります。デバッガーのコンテキストから呼び出された場合、例えば Firefox 開発ツールでは、"debugger eval code" が返されます。

例
-

### fileName の使用

```js
var e = new Error("Could not parse input");
throw e;
// e.fileName could look like "file:///C:/example.html"
```

仕様書
---

仕様の一部ではありません。

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

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

関連情報
----

* `Error.prototype.stack`
* `Error.prototype.columnNumber`
* `Error.prototype.fileName`


Error.prototype.name - JavaScript

Error.prototype.name
====================

**`name`** プロパティは、エラーの種類の名称を表します。初期値は "Error" です。

解説
--

既定で `Error` インスタンスには "Error" という名称が与えられます。 `name` プロパティは `message` プロパティに加えて、 Error の文字列表現を生成するため、`Error.prototype.toString()` メソッドにより使用されます。

例
-

### 独自のエラーを発生させる

```js
var e = new Error("Malformed input"); // e.name は 'Error'

e.name = "ParseError";
throw e;
// e.toString() would return 'ParseError: Malformed input'
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-error.prototype.name |

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

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

関連情報
----

* `Error.prototype.message`
* `Error.prototype.toString()`


Error.prototype.stack - JavaScript

Error.prototype.stack
=====================

**非標準:** この機能は標準ではなく、標準化の予定もありません。公開されているウェブサイトには使用しないでください。ユーザーによっては使用できないことがあります。実装ごとに大きな差があることもあり、将来は振る舞いが変わるかもしれません。

**`stack`** は `Error` オブジェクトの標準外のプロパティで、呼び出された関数のトレース、つまり、その呼び出し順、呼び出したファイルの行番号、呼び出した関数の引数を提供します。スタック文字列は、最後の呼び出しから最初の呼び出しへ進み、元のグローバルスコープの呼び出しまで遡ります。

解説
--

各ステップは改行で区切られ、行の先頭は関数名（グローバルスコープからの呼び出しでない場合）、次に `@` 記号、ファイルの場所（エラーが投げられている時に関数がエラーコンストラクターである場合を除く）、コロン記号、ファイルの場所がある場合は行番号の順に続きます。（ただし、`Error` オブジェクトも、投げられたエラーから取り戻すため `fileName` および `lineNumber`、`columnNumber` プロパティを所有することに注意してください。これはエラーのみであり、そのトレースではありません。）

これは Firefox だけで使用される書式であることに注意してください。スタックトレースに標準の書式はありません。しかし、Safari 6 以降と Opera 12 以前ではとてもよく似た書式を使用します。一方で、V8 JavaScript エンジンを搭載したブラウザー（Chrome、Opera 15 以降、Android Browser など）や IE 10 以降のブラウザーは異なる書式を使用します。

**スタック上の引数の値**: Firefox 14 以前 (Firefox バグ 744842) で、関数名は、文字列に変換され括弧で囲まれた引数の値に続き、`@` 記号の直前に置かれます。オブジェクト (または配列等) は変換された形式 `"[object Object]"` で現れるため、これが実際のオブジェクトに戻され評価されることはありません。スカラー値を受け取ります (それにも関わらず、少なくとも Firefox 14 では可能です。`arguments.callee.caller.arguments` を使用し、`arguments.callee.caller.name` により、簡単に関数名を取り戻すことが可能です)。`"undefined"` は、`"(void 0)"` として記録されます。ただし、`"@"`、`"("`, `")"` (または、これらがファイル名に含まれる場合) を伴う文字列引数が渡された場合、行がそのコンポーネント部分で分かれてしまうため、これらに安易に頼ることができません。従って、Firefox 14 以降では、これが少なからず問題になります。

ブラウザによって値を設定するタイミングが異なります。例えば Firefox は、これを `Error` オブジェクトが作成された時に設定し、PhantomJS は、`Error` が投げられた時にのみ設定します。アーカイブされた MSDN のドキュメントによれば、PhantomJS の実装とも一致するようです。

例
-

### stack プロパティの使用

次の HTML マークアップは、`stack` プロパティの使用を実演します。

```html
<!doctype html>
<meta charset="UTF-8" />
<title>Stack Trace Example</title>
<body>
  <script>
 function trace() {
 try {
 throw new Error("myError");
 } catch (e) {
 alert(e.stack);
 }
 }
 function b() {
 trace();
 }
 function a() {
 b(3, 4, "\n\n", undefined, {});
 }
 a("first call, firstarg");
 </script>
</body>
```

上記のマークアップは、Windows ファイルシステム上の `C:\example.html` に保存されているものと仮定します。これは、次のテキストを含む警告メッセージを生成します:

Firefox 30 以降では、列番号が含まれます。
```

trace@file:///C:/example.html:9:17
b@file:///C:/example.html:16:13
a@file:///C:/example.html:19:13
@file:///C:/example.html:21:9
```

Firefox 14 から Firefox 29 まで:
```

trace@file:///C:/example.html:9
b@file:///C:/example.html:16
a@file:///C:/example.html:19
@file:///C:/example.html:21
```

Firefox 13 以前は、代わりに次のテキストが生成されます。
```

Error("myError")@:0
trace()@file:///C:/example.html:9
b(3,4,"\n\n",(void 0),[object Object])@file:///C:/example.html:16
a("first call, firstarg")@file:///C:/example.html:19
@file:///C:/example.html:21
```

### eval によるコードのスタック

Firefox 30 以降、`Function()` および `eval()` 呼び出し内のコードのエラースタックは、各呼び出しに、行番号と列番号についての詳細情報を含むスタックを生成するようになりました。関数呼び出しは、`"> Function"` で示され、eval 呼び出しは、`"> eval"` で示されます。

```js
try {
  new Function("throw new Error()")();
} catch (e) {
  console.log(e.stack);
}

// anonymous@file:///C:/example.html line 7 > Function:1:1
// @file:///C:/example.html:7:6

try {
  eval("eval('FAIL')");
} catch (x) {
  console.log(x.stack);
}

// @file:///C:/example.html line 7 > eval line 1 > eval:1:1
// @file:///C:/example.html line 7 > eval:1:1
// @file:///C:/example.html:7:6
```

`//# sourceURL` ディレクティブを使用して eval ソースに名前を付けることもできます。 デバッガー ドキュメント内の eval ソースのデバッグ と ブログ記事 も参照してください。

仕様書
---

仕様の一部ではありません。

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

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

関連情報
----

* 外部プロジェクト: TraceKit および javascript-stacktrace
* Overview of the V8 JavaScript stack trace API


Error.prototype.toString() - JavaScript

Error.prototype.toString()
==========================

**`toString()`** メソッドは、指定した `Error` オブジェクトを表す文字列を返します。

構文
--
```

e.toString()
```

### 返値

指定した `Error` オブジェクトを表す文字列です。

解説
--

`Error` オブジェクトは、すべてのオブジェクトに継承される `Object.prototype.toString()` メソッドを上書きします。その意味は、次のようなものです (`Object` と `String` は元の値を持つと仮定します)。

```js
Error.prototype.toString = function () {
  "use strict";

  var obj = Object(this);
  if (obj !== this) {
    throw new TypeError();
  }

  var name = this.name;
  name = name === undefined ? "Error" : String(name);

  var msg = this.message;
  msg = msg === undefined ? "" : String(msg);

  if (name === "") {
    return msg;
  }
  if (msg === "") {
    return name;
  }

  return name + ": " + msg;
};
```

例
-

### toString() の使用

```js
var e = new Error("fatal error");
console.log(e.toString()); // 'Error: fatal error'

e.name = undefined;
console.log(e.toString()); // 'Error: fatal error'

e.name = "";
console.log(e.toString()); // 'fatal error'

e.message = undefined;
console.log(e.toString()); // ''

e.name = "hello";
console.log(e.toString()); // 'hello'
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-error.prototype.tostring |

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

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

関連情報
----

* `Error.prototype.toSource()`


Error() コンストラクター - JavaScript

Error() コンストラクター
================

**`Error`** コンストラクターは、エラーオブジェクトを生成します。

構文
--
```

new Error([message[, fileName[, lineNumber]]])
```

### 引数

`message`省略可

人間が読めるエラーの説明。

`fileName` 省略可
Non-standard

生成された `Error` オブジェクト上の `fileName` プロパティに設定される値。既定では、`Error()` コンストラクターを呼び出したコードを含むファイルの名前です。

`lineNumber` 省略可
Non-standard

生成された `Error` オブジェクト上の `lineNumber` プロパティに設定される値。既定では、`Error()` コンストラクターの呼び出しを含む行番号。

例
-

### 関数呼び出しか new による構築か

`Error` が関数のように使用された場合 — `new` がなかった場合、 `Error` オブジェクトを返します。したがって、 `Error` を呼び出すだけで `Error` オブジェクトを `new` キーワードから構築した場合と同じものを出力します。

```js
// これは...
const x = Error("関数呼び出しによって生成されました。");

// ...これと同じ機能です。
const y = new Error('"new" キーワードによって生成されました。');
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-error-constructor |

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

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

関連情報
----

* `throw`
* `try...catch`


URIError() コンストラクター - JavaScript

URIError() コンストラクター
===================

**`URIError`** コンストラクターは、グローバルの URI 操作関数が間違った方法で使用された場合のエラーを生成します。

構文
--
```

new URIError([message[, fileName[, lineNumber]]])
```

### 引数

`message` 省略可

人間が読むためのエラーの説明です。

`fileName` 省略可

例外が発生したコードを含むファイルの名前です。

`lineNumber` 省略可

例外が発生したコードの行番号です。

例
-

### URIError の捕捉

```js
try {
  decodeURIComponent("%");
} catch (e) {
  console.log(e instanceof URIError); // true
  console.log(e.message); // "malformed URI sequence"
  console.log(e.name); // "URIError"
  console.log(e.fileName); // "Scratchpad/1"
  console.log(e.lineNumber); // 2
  console.log(e.columnNumber); // 2
  console.log(e.stack); // "@Scratchpad/2:2:3\n"
}
```

### URIError の生成

```js
try {
  throw new URIError("Hello", "someFile.js", 10);
} catch (e) {
  console.log(e instanceof URIError); // true
  console.log(e.message); // "Hello"
  console.log(e.name); // "URIError"
  console.log(e.fileName); // "someFile.js"
  console.log(e.lineNumber); // 10
  console.log(e.columnNumber); // 0
  console.log(e.stack); // "@Scratchpad/2:2:9\n"
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-nativeerror-constructors |

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

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

関連情報
----

* `Error`
* `decodeURI()`
* `decodeURIComponent()`
* `encodeURI()`
* `encodeURIComponent()`


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

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

**`[@@iterator]()`** は `Iterator` インスタンスのメソッドで、反復可能プロトコルを実行し、組み込みイテレーターが反復可能オブジェクトを期待する大部分の構文、例えばスプレッド構文や `for...of` ループなどで利用できるようにします。これは `this` の値、すなわちイテレーターオブジェクト自身を返します。

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

構文
--

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

### 返値

`this` の値、すなわちイテレーターオブジェクト自身です。

例
-

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

このメソッドを直接呼び出す必要はめったにないことに注意してください。`iterator` メソッドの存在により、組み込みのイテレーターはすべて[反復可能] (/ja/docs/Web/JavaScript/Reference/Iteration\_protocols#反復可能プロトコル)となり、`for...of` ループのような反復処理構文はループオーバーするために自動的にこのメソッドを呼び出してイテレーターを取得します。

```js
const arrIterator = [1, 2, 3].values();
for (const value of arrIterator) {
  console.log(value);
}
// ログ: 1, 2, 3
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-%iteratorprototype%-@@iterator |

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

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

関連情報
----

* `for...of`


AsyncGenerator.prototype.return() - JavaScript

AsyncGenerator.prototype.return()
=================================

**`return()`** は `AsyncGenerator` インスタンスのメソッドで、あたかも `return` 文がジェネレーター本体の中の停止中の位置に挿入されたかのように動作し、ジェネレーターを終了して、`try...finally` ブロックと組み合わせた際に、ジェネレーターが任意のクリーンアップタスクを実行できるようにします。

構文
--

```js
asyncGeneratorObject.return(value)
```

### 引数

`value`

返す値です。

### 返値

`Promise` で、2 つのプロパティを持つ `Object` に解決します。

`done`

論理値です。

* `true`: ジェネレーター関数の制御フローが最後に達した場合。
* `false`: ジェネレーター関数の制御フローが最後に達しておらず、さらに値を生成できる場合。これは `return` が `try...finally` で捉えられ、さらに `finally` ブロックの中に `yield` 式がある場合のみ起こりえます。

`value`

引数として指定された値、または `yield` 式が `try...finally` でラップされている場合、 `finally` ブロックから得られる/返す値を返します。

解説
--

`return()` メソッドは、呼び出されると、ジェネレーター本体の現在の停止位置に `return value;` 文が挿入されたように見ることができます（ここで `value` は `return()` メソッドを渡す値です）。したがって、典型的なフローでは、 `return(value)` を呼び出すと、 `{ done: true, value: value }` が 返されます。しかし、`yield` 式が `try...finally` ブロックでラップされている場合、制御フローは関数本体を抜けず、代わりに `finally` ブロックに進みます。この場合、`finally` ブロックの中にさらに `yield` 式があれば、返す値は異なり、`done` は `false` になる可能性もあります。

例
-

### return() の使用

次の例は、単純な非同期ジェネレーターと `return` メソッドを示しています。

```js
// An async task. Pretend it's doing something more useful
// in practice.
function delayedValue(time, value) {
  return new Promise((resolve, reject) => {
    setTimeout(() => resolve(value), time);
  });
}

async function\* createAsyncGenerator() {
  yield delayedValue(500, 1);
  yield delayedValue(500, 2);
  yield delayedValue(500, 3);
}

const asyncGen = createAsyncGenerator();
asyncGen.next().then((res) => console.log(res)); // { value: 1, done: false }
asyncGen.return("foo").then((res) => console.log(res)); // { value: "foo", done: true }
asyncGen.next().then((res) => console.log(res)); // { value: undefined, done: true }
```

### ジェネレーターが完了した時に return() を一度使用

引数 `value` が `return()` メソッドに渡されない場合、プロミスは next() メソッドを呼び出したかのように解決します。この例では、ジェネレーターは完全に終了しているので、返される値は `undefined` となります。

ジェネレーターが "completed" 状態になった後でも `return()` は呼び出すことができますが、ジェネレーターはこの状態のままとなります。

```js
async function\* createAsyncGenerator() {
  yield await Promise.resolve(1);
  yield await Promise.resolve(2);
  yield await Promise.resolve(3);
}
const asyncGen = createAsyncGenerator();
asyncGen.next().then((res) => console.log(res)); // { value: 1, done: false }
asyncGen.next().then((res) => console.log(res)); // { value: 2, done: false }
asyncGen.next().then((res) => console.log(res)); // { value: 3, done: false }
// value is returned undefined, as no value is passed and generator is 'done'
asyncGen.return().then((res) => console.log(res)); // { value: undefined, done: true }
// we can still return a value once the generator is complete
asyncGen.return(1).then((res) => console.log(res)); // { value: 1, done: true }
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-asyncgenerator-prototype-return |

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

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

関連情報
----

* `async function*`
* イテレーターとジェネレーター


AsyncGenerator.prototype.next() - JavaScript

AsyncGenerator.prototype.next()
===============================

**`next()`** メソッドは、シーケンス内の次の値を返します。

構文
--

```js
asyncGeneratorObject.next()
asyncGeneratorObject.next(value)
```

### 引数

`value` 省略可

ジェネレーターの内部状態を変更するために使用するオプションの値。`next()` メソッドに渡された値は、`yield` で受け取ります。

### 返値

`Promise` で、2 つのプロパティを持つ `Object` に解決します。

`done`

論理値です。

* `true`: ジェネレーターが制御フローの終端を過ぎている場合。この場合、`value` はジェネレーターの返値を指定します（値が undefined である可能性があります）。
* `false`: ジェネレーターがもっと多くの値を生成することができる場合。

`value`

ジェネレーターによってもたらされる、または返される任意の JavaScript 値。

例
-

### next() の使用

次の例は、単純なジェネレーターと `next` メソッドが返すオブジェクトを示しています。

```js
// 非同期タスクです。実際にはもっと有益なことを使用していることを
// 想定してください。
function delayedValue(time, value) {
  return new Promise((resolve, reject) => {
    setTimeout(() => resolve(value), time);
  });
}

async function\* createAsyncGenerator() {
  yield delayedValue(500, 1);
  yield delayedValue(500, 2);
  yield delayedValue(500, 3);
}

const asyncGen = createAsyncGenerator();
asyncGen.next().then((res) => console.log(res)); // { value: 1, done: false }
asyncGen.next().then((res) => console.log(res)); // { value: 2, done: false }
asyncGen.next().then((res) => console.log(res)); // { value: 3, done: false }
asyncGen.next().then((res) => console.log(res)); // { value: undefined, done: true }
```

### ジェネレーターに値を送信

この例では、`next` が値付きで呼び出されます。

**メモ:** 最初の呼び出しは、ジェネレーターが最初は何も出力しなかったため、何もログ出力しません。

```js
// 非同期タスクです。実際にはもっと有益なことを使用していることを
// 想定してください。
function sleep(time) {
  return new Promise((resolve, reject) => {
    setTimeout(resolve, time);
  });
}

async function\* createAsyncGenerator() {
  while (true) {
    await sleep(500);
    const value = yield;
    console.log(value);
  }
}

async function main() {
  const asyncGen = createAsyncGenerator();
  // No log at this step: the first value sent through `next` is lost
  console.log(await asyncGen.next(1)); // { value: undefined, done: false }
  // Logs 2: the value sent through `next`
  console.log(await asyncGen.next(2)); // { value: undefined, done: false }
}

main();
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-asyncgenerator-prototype-next |

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

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

関連情報
----

* `async function*`
* イテレーターとジェネレーター


AsyncGenerator.prototype.throw() - JavaScript

AsyncGenerator.prototype.throw()
================================

**`throw()`** は `AsyncGenerator` インスタンスのメソッドで、あたかも `throw` 文がジェネレーター本体の中の停止中の位置に挿入されたかのように動作し、エラー状態をジェネレーターに通知して、エラーを処理するか、クリーンアップを実行してそれ自身を閉じることができます。

構文
--

```js
asyncGeneratorObject.throw(exception)
```

### 引数

`exception`

発生される例外。デバッグの用途では、`instanceof` `Error` にすると便利です。

### 返値

発生したエラーを捕捉できない場合は、渡された例外で拒否する `Promise` を返します。

例外が `try...catch` で捉えられ、再開してジェネレーターが次の値を生成すると、次の 2 つのプロパティを持つ `Object` で解決する `Promise` を返します。

`done`

論理値です。

* `true`: このジェネレーター関数の制御フローが最後まで達した場合。
* `false`: このジェネレーターが次の値を生成することができる場合。

`value`

次の `yield` 式で生成される値。

例
-

### throw() の使用

次の例では、単純なジェネレーターと、`throw` メソッドを使用して発生したエラーについて示します。エラーは、通常通り `try...catch` ブロックで捕らえることができます。

```js
// 非同期タスクです。実際にはもっと有益なことを使用していることを
// 想定してください。
function sleep(time) {
  return new Promise((resolve, reject) => {
    setTimeout(resolve, time);
  });
}

async function\* createAsyncGenerator() {
  while (true) {
    try {
      await sleep(500);
      yield 42;
    } catch (e) {
      console.error(e);
    }
  }
}

const asyncGen = createAsyncGenerator();
asyncGen.next(1).then((res) => console.log(res)); // { value: 42, done: false }
asyncGen
  .throw(new Error("Something went wrong")) // Error: Something went wrong
  .then((res) => console.log(res)); // { value: 42, done: false }
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-asyncgenerator-prototype-throw |

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

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

関連情報
----

* `async function*`
* イテレーターとジェネレーター


AggregateError() コンストラクター - JavaScript

AggregateError() コンストラクター
=========================

**`AggregateError()`** コンストラクターは、単一のエラーにラップする必要があるいくつかのエラーに対してエラーを作成します。

構文
--

```js
new AggregateError(errors);
new AggregateError(errors, message);
```

### 引数

`errors`

エラーの反復可能オブジェクトであり、実際には `Error` インスタンスではない場合があります。

`message`省略可

オプションで、統合エラーの人間可読な説明です。

例
-

### `AggregateError` の作成

```js
try {
  throw new AggregateError([new Error("some error")], "Hello");
} catch (e) {
  console.log(e instanceof AggregateError); // true
  console.log(e.message); // "Hello"
  console.log(e.name); // "AggregateError"
  console.log(e.errors); // [ Error: "some error" ]
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-aggregate-error-constructor |

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

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

関連情報
----

* `AggregateError` のポリフィルが `core-js` で利用できます
* `Promise.any`


String.prototype.localeCompare() - JavaScript

String.prototype.localeCompare()
================================

**`localeCompare()`** メソッドは、参照文字列がソート順で指定された文字列の前か後か、または同じかを示す数値を返します。`Intl.Collator` API に対応している実装では、このメソッドは単に `Intl.Collator` を呼び出します。

大量の文字列を比較する場合、例えば巨大な配列を並べ替えしている時は、`Intl.Collator` オブジェクトを生成してそれが提供する `compare()` メソッドを使用したほうがいいでしょう。

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

構文
--

```js
localeCompare(compareString)
localeCompare(compareString, locales)
localeCompare(compareString, locales, options)
```

### 引数

`locales` と `options` 引数は、この関数の動作をカスタマイズし、アプリケーションが書式化の習慣で使用する言語を指定することができます。

`Intl.Collator` API に対応している実装では、これらの引数はちょうど `Intl.Collator()` コンストラクターの引数に対応します。`Intl.Collator` の対応のない実装では、両方の引数を無視し、比較を行うと完全に実装依存の値を返します。一貫性があることだけが必要です。

`compareString`

この文字列と比較される文字列です。すべての値は文字列に変換されますので、省略したり `undefined` を渡したりすると、`localeCompare()` は `"undefined"` という文字列と比較を行います。これはおそらく望むところではないでしょう。

`locales` 省略可

BCP 47 言語タグの文字列、またはそのような文字列の配列です。`Intl.Collator()` コンストラクターの `locales` 引数に対応します。

`Intl.Collator` の対応がない実装では、この引数は無視され、普通はホストのロケールが使用されます。

`options` 省略可

出力形式を調整するオブジェクトです。`Intl.Collator()` コンストラクターの `options` 引数に対応します。

`Intl.Collator` の対応がない実装では、この引数は無視されます。

`Intl.Collator()` コンストラクター の記事に、`locales` および `options` 引数の詳細と使い方が書かれています。

### 返値

`referenceStr` が `compareString` より前に出現するものである場合は**負**の数です。 `referenceStr` が `compareString` より後に出現するものである場合は**正**の数です。等しい場合は `0` です。

`Intl.Collator` の実装では、これは `new Intl.Collator(locales, options).compare(referenceStr, compareString)` と等価です。

解説
--

`referenceStr` が `compareString` より前に来るか、後に来るか、あるいは等しいかを示す整数を返します。

* `referenceStr` が `compareString` より前に出現するものである場合は負の数
* `referenceStr` が `compareString` より後に出現するものである場合は正の数
* 等しい場合は `0`

**警告:** 返値が正確な `-1` または `1` であると思わないでください。

結果の負の整数と正の整数は、ブラウザー間（およびブラウザーのバージョン間）で異なります。これは W3C の仕様が負の値か正の値かとだけ指定しているためです。ブラウザーによっては `-2` や `2` を、あるいは他の負の値、正の値を返却するかもしれません。

例
-

### localeCompare() の使用

```js
// 文字 "a" は "c" は負の数になります
"a".localeCompare("c"); // -2 や -1 （あるいはまた別の負の数）

// 単語 "check" はアルファベット順に "against" より後ろなので正の数になります
"check".localeCompare("against"); // 2 や 1 （あるいはまた別の正の数）

// "a" と"a" は等しいので自然数 0 になります
"a".localeCompare("a"); // 0
```

### 配列の並べ替え

`localeCompare()` で、大文字小文字の違いを無視した配列の並べ替えができます。

```js
const items = ["réservé", "Premier", "Cliché", "communiqué", "café", "Adieu"];
items.sort((a, b) => a.localeCompare(b, "fr", { ignorePunctuation: true }));
// ['Adieu', 'café', 'Cliché', 'communiqué', 'Premier', 'réservé']
```

### 拡張引数をブラウザーが対応しているか調べる

`locales` と `options` の引数は、まだすべてのブラウザーで対応しているわけではありません。

実装がこれらに対応しているか調べるには、引数 `"i"`（不正な言語タグが除外される要件）を使用して、例外 `RangeError` を調べてください。

```js
function localeCompareSupportsLocales() {
  try {
    "foo".localeCompare("bar", "i");
  } catch (e) {
    return e.name === "RangeError";
  }
  return false;
}
```

### locales の使用

`localeCompare()` によって得られる結果は言語間で異なります。アプリケーションのユーザーインターフェイスで使用される言語の整列順を得るには、 `locales` 引数を使用してその言語（そしてできればいくつかの代替言語）を指定していることを確かめて下さい。

```js
console.log("ä".localeCompare("z", "de")); // 負の数: ドイツ語で ä は a に分類される
console.log("ä".localeCompare("z", "sv")); // 正の数: スウェーデン語では ä は z の後になる
```

### options の使用

`localeCompare()` によって得られる結果は、`options` 引数を使用することによってカスタマイズできます。:

```js
// ドイツ語では ä の base letter は a
console.log("ä".localeCompare("a", "de", { sensitivity: "base" })); // 0

// スウェーデン語では ä と a は base letter が異なる
console.log("ä".localeCompare("a", "sv", { sensitivity: "base" })); // 正の値
```

### 数値の並べ替え

```js
// 既定では "2" > "10"
console.log("2".localeCompare("10")); // 1

// options を使用した数値
console.log("2".localeCompare("10", undefined, { numeric: true })); // -1

// ロケールタグを使用した数値
console.log("2".localeCompare("10", "en-u-kn-true")); // -1
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.localecompare |
| ECMAScript Internationalization API Specification # sup-String.prototype.localeCompare |

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

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

関連情報
----

* `Intl.Collator`


String.prototype.fontsize() - JavaScript

String.prototype.fontsize()
===========================

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

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

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

構文
--

```js
fontsize(size)
```

### 引数

`size`

1 ～ 7 の整数、または 1 ～ 7 の符号付き整数を表す文字列です。

### 返値

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

解説
--

`fontsize()` メソッド自体は、単純に文字列の部品を検証や正規化せずに接続するだけです。しかし、妥当な `<font>` 要素を作成するには、大きさを整数で指定した場合は、 `str` のフォントの大きさを 7 つの定義済みの大きさで設定します。 `size` を "-2" または "+3" のような文字列で指定すると、 `str` のフォントの大きさを既定値からの相対的な大きさで設定します。

例
-

### fontsize() の使用

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

```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</font>
```

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

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

仕様書
---

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

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

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

関連情報
----

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


String.prototype.toString() - JavaScript

String.prototype.toString()
===========================

**`toString()`** メソッドは指定されたオブジェクトを表す文字列を返します。

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

構文
--

```js
toString()
```

### 返値

呼び出したオブジェクトを表す文字列です。

詳細
--

その `String` オブジェクトは、`Object` の `toString` メソッドを上書きします。つまり、`Object.prototype.toString()` を継承しません。`String` オブジェクトの `toString` メソッドは、そのオブジェクトを表す文字列を返します（`String.prototype.valueOf()` と同等です）。

`toString()` メソッドは `this` 値が `String` プリミティブまたはラッパーオブジェクトであることを要求します。他の `this` の値に対しては、文字列値に変換しようとせずに `TypeError` を発生します。

`String` には `[@@toPrimitive]()` メソッドがないため、JavaScript は `toString()` メソッドを、文字列が求められるコンテキスト、例えばテンプレートリテラルで `String` オブジェクトが使用されると、自動的に呼び出します。しかし、文字列プリミティブ値は文字列に変換するために `toString()` を呼び出しません。既に文字列なので、変換が実施されないからです。

```js
String.prototype.toString = () => "Overridden";
console.log(`${"foo"}`); // "foo"
console.log(`${new String("foo")}`); // "Overridden"
```

例
-

### toString() メソッドを使う

以下の例は、`String` オブジェクトを表す文字列の値を表示します。

```js
const x = new String("Hello world");

console.log(x.toString()); // "Hello world"
```

仕様書
---

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

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

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

関連情報
----

* `String.prototype.valueOf()`


String.prototype.repeat() - JavaScript

String.prototype.repeat()
=========================

**`repeat()`** メソッドは、呼び出し元の文字列を指定した数だけコピーして結合した新しい文字列を構築して返します。

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

構文
--

```js
repeat(count)
```

### 引数

`count`

`0` から`正の無限大`までの間の整数で、文字列を繰り返す数を示します。

### 返値

与えられた文字列の指定した回数分のコピーを含む新しい文字列です。

### 例外

`RangeError`

`count` が負の数であるか、 `count` が文字列の最大長を超えた場合に発生します。

例
-

### repeat() の使用

```js
"abc".repeat(-1); // RangeError
"abc".repeat(0); // ''
"abc".repeat(1); // 'abc'
"abc".repeat(2); // 'abcabc'
"abc".repeat(3.5); // 'abcabcabc' （小数は丸められ、整数の結果が返されます）
"abc".repeat(1 / 0); // RangeError

({ toString: () => "abc", repeat: String.prototype.repeat }).repeat(2);
// 'abcabc' （repeat() は汎用メソッドです）
```

仕様書
---

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

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

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

関連情報
----

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


String.prototype.italics() - JavaScript

String.prototype.italics()
==========================

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

**`italics()`** メソッドは、文字列を `<i>` 要素に埋め込んだ文字列 (`<i>str</i>`) を生成し、文字列がイタリック体で表示されるようにします。

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

構文
--

```js
italics()
```

### 返値

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

解説
--

`italics()` メソッドは、文字列を `<i>` 要素の中に、 "`<i>str</i>`" のように埋め込みます。

例
-

### italics() の使用

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

```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.italics |

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

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

関連情報
----

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


String.prototype.padEnd() - JavaScript

String.prototype.padEnd()
=========================

**`padEnd()`** メソッドは、結果の文字列が指定した長さになるように、現在の文字列を他の文字列で（必要に応じて繰り返して）延長します。延長は、現在の文字列の末尾から適用されます。

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

構文
--

```js
padEnd(targetLength)
padEnd(targetLength, padString)
```

### 引数

`targetLength`

現在の文字列の延長後に返される文字列の長さです。この値が現在の文字列の長さよりも短い場合、現在の文字列が返されます。

`padString` 省略可

現在の文字列を延長するための文字列です。この文字列が `targetLength` に収まらないほど長い場合は、左書きの言語では最も左の部分が、右書きの言語では最も右の部分が使用され、残りは切り捨てられます。この引数の既定値は、 " " (`U+0020`) です。

### 返値

`String` で、 `targetLength` で指定された長さにするために、 `padString` を現在の `str` の末尾に適用したものです。

例
-

### padEnd の使用

```js
"abc".padEnd(10); // "abc "
"abc".padEnd(10, "foo"); // "abcfoofoof"
"abc".padEnd(6, "123456"); // "abc123"
"abc".padEnd(1); // "abc"
```

仕様書
---

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

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

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

関連情報
----

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


String() コンストラクター - JavaScript

String() コンストラクター
=================

**`String`** コンストラクターは新しい `String` オブジェクトを生成します。関数として呼び出された場合は、文字列型のプリミティブ値を返します。

構文
--

```js
new String(thing)
String(thing)
```

**メモ:** `String()` は `new` があってもなくても呼び出せますが、効果は異なります。返値を参照してください。

### 引数

`thing`

文字列に変換するもの。

### 返値

`String` がコンストラクターとして（`new` 付きで）呼び出された場合、`String` オブジェクトを生成します。これはプリミティブでは**ありません**。

`String` が関数として呼び出された場合、引数を文字列プリミティブに変換します。シンボル値は例外を発生させず、`"Symbol(description)"` の形に変換され、この `description` はそのシンボルの description となります。

**警告:** `String` をコンストラクターとして使用する場面はほとんど見つからないでしょう。

例
-

### String コンストラクターと String 関数

String 関数と String コンストラクターは異なる結果を生み出します。

```js
const a = new String("Hello world"); // a === "Hello world" is false
const b = String("Hello world"); // b === "Hello world" is true
a instanceof String; // is true
b instanceof String; // is false
typeof a; // "object"
typeof b; // "string"
```

ここでは、この関数は約束通り (プリミティブ型の) 文字列を生成します。しかし、コンストラクターは String 型 (オブジェクトのラッパー) のインスタンスを生成しますので、 String コンストラクターを使用するのは稀だといえます。

### String() を用いてシンボルを文字列化

`String()` はシンボルを文字列に例外を発生させることなく変換することができる唯一の方法です。とても明示的だからです。

```js
const sym = Symbol("example");
`${sym}`; // TypeError: Cannot convert a Symbol value to a string
"" + sym; // TypeError: Cannot convert a Symbol value to a string
"".concat(sym); // TypeError: Cannot convert a Symbol value to a string
```

```js
const sym = Symbol("example");
String(sym); // "Symbol(example)"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-string-constructor |

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

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

関連情報
----

* JavaScript ガイドのテキスト処理


String.prototype.link() - JavaScript

String.prototype.link()
=======================

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

**`link()`** メソッドは、文字列を `<a>` 要素に埋め込み (`<a href="...">str</a>`)、他の URL へのハイパーテイストリンクとして使用される文字列を生成します。

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

構文
--

```js
link(url)
```

### 引数

`url`

`<a>` 要素の `href` 属性を指定する任意の文字列です。これは妥当な（相対または絶対）URL で、すべての `&` の文字を `&` でエスケープしたものです。

### 返値

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

例
-

### link() の使用

以下の例は、"MDN" という語を、Mozilla Developer Network へのハイパーテキストリンクとして表示します。

```js
const hotText = "MDN";
const url = "https://developer.mozilla.org/";

console.log(`クリックで ${hotText.link(url)} へ戻ります。`);
// クリックで <a href="https://developer.mozilla.org/">MDN</a> へ戻ります。
```

仕様書
---

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

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

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

関連情報
----

* `String.prototype.link` のポリフィル (`core-js`)
* `String.prototype.anchor()`
* `document.links`


String.raw() - JavaScript

String.raw()
============

**`String.raw()`** 静的メソッドは、テンプレートリテラルのためのタグ関数です。この関数は Python の文字列リテラルの `r` 接頭辞や C# の文字列リテラルの `@` 接頭辞に似ています。この関数は、テンプレートリテラルの生の文字列形式を取得するために使用されます。つまり、置換（`${foo}` など）は行われますが、エスケープ（`\n` など）は実行されません。

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

構文
--

```js
String.raw(strings)
String.raw(strings, sub1)
String.raw(strings, sub1, sub2)
String.raw(strings, sub1, sub2, /\* …, \*/ subN)

String.raw`templateString`
```

### 引数

`strings`

整形式のテンプレートリテラル配列オブジェクト、たとえば `{ raw: ['foo', 'bar', 'baz'] }` などです。文字列の配列風オブジェクトを値として持つ `raw` プロパティを持っているオブジェクトであるべきです。

`sub1`, …, `subN`

置換される値が入ります。

`templateString`

テンプレートリテラルです。オプションでで置換文字列 (`${...}`) を含みます。

### 返値

指定されたテンプレートリテラルの生の文字列形式です。

### 例外

`TypeError`

第 1 引数に `raw` プロパティが含まれていなかったり、`raw` プロパティが `undefined` または `null` 出会ったりした場合に発生します。

解説
--

ほとんどの場合、`String.raw()` はテンプレートリテラルとともに使用されます。前述の最初の構文は、滅多に使用されません。JavaScript エンジンが（他のタグ関数のように）適切な引数で呼び出すからです。

`String.raw()` はテンプレートリテラルの唯一の組み込みタグ関数です。既定のテンプレート関数のように動作し、連結を行います。通常の JavaScript コードで再実装することができます。

**警告:** `String.raw` を直接「識別」タグとして使用しないでください。この実装方法については識別タグの構築を参照してください。

`String.raw()` が `raw` プロパティに `length` プロパティがないか、正でない `length` を持つオブジェクトで呼び出された場合、空の文字列 `""` を返します。もし `substitutions.length < strings.raw.length - 1` （つまり、プレースホルダーを埋めるだけの置換がない - 整形式タグ付きテンプレートリテラルでは起こりえない）場合、残りのプレースホルダーは空の文字列で埋められます。

例
-

### String.raw() の使用

```js
String.raw`Hi\n${2 + 3}!`;
// 'Hi\\n5!' です。'Hi' の次の文字は
// 改行文字ではなく、
// '\' および 'n' は 2 つの文字です。

String.raw`Hi\u000A!`;
// 'Hi\\u000A!' です。同様で、今回は
// \, u, 0, 0, 0, A, の 6 文字です。
// すべての種類のエスケープ文字は無効で、バックスラッシュが
// 出力文字列中に存在します。
// 文字列の .length プロパティを調べると確認できます。

const name = "Bob";
String.raw`Hi\n${name}!`;
// 'Hi\\nBob!' です。置き換えが処理されます。

String.raw`Hi \${name}!`;
// 'Hi \\${name}!' です。ドル記号がエスケープされます。補間は行われません。
```

### 識別タグの構築

多くのツールは、特定の名前でタグ付けされたリテラルを特別扱いします。

```js
// フォーマッターによっては、このリテラルのコンテンツを HTML として書式化する
const doc = html`<!DOCTYPE html>
<html lang="en-US">
 <head>
 <title>Hello</title>
 </head>
 <body>
 <h1>Hello world!</h1>
 </body>
</html>
`;
```

`html` タグを素朴に実装するためには、次のようにします。

```js
const html = String.raw;
```

これは、実際は、上記のように動作します。しかし、`String.raw` は "cooked" 文字列ではなく、生の文字列リテラルを連結するので、エスケープシーケンスは処理されません。

```js
const doc = html`<canvas>\n</canvas>`;
// "<canvas>\\n</canvas>"
```

タグが純粋にマークアップのためのもので、リテラルの値を変更しないような「純粋な識別タグ」では、これは望むものではないかもしれません。 この場合、カスタムタグを作成し、"cooked"（つまり、エスケープシーケンスが処理されたｓ）リテラル配列を `String.raw` に渡して、生の文字列であるかのように見せかけることができます。

```js
const html = (strings, ...values) => String.raw({ raw: strings }, ...values);
// フォーマッターによっては、このリテラルのコンテンツを HTML として書式化する
const doc = html`<canvas>\n</canvas>`;
// "<canvas>\n</canvas>"; "\n" が改行文字になる
```

最初の引数は `raw` プロパティを持つオブジェクトで、その値はテンプレートリテラルの区切られた文字列を表す配列風オブジェクト（`length` プロパティと整数のインデックスを持つ）であることに注意してください。残りの引数は置き換え用です。`raw` の値は配列風オブジェクトであれば何でも良いので、文字列であっても構いません。例えば、 `'test'` は `['t', 'e', 's', 't']` として扱われます。以下は ``t${0}e${1}s${2}t`` と等価です。

```js
String.raw({ raw: "test" }, 0, 1, 2); // 't0e1s2t'
```

仕様書
---

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

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

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

関連情報
----

* `String.raw` のポリフィル (`core-js`)
* テンプレートリテラル
* `String`
* 字句文法


String.prototype.slice() - JavaScript

String.prototype.slice()
========================

**`slice()`** メソッドは、元の文字列を変更せず、文字列の一部分を取り出し、それを新しい文字列として返します。

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

構文
--

```js
slice(indexStart)
slice(indexStart, indexEnd)
```

### 引数

`indexStart`

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

`indexEnd` 省略可

返却する部分文字列から除外する最初の文字の位置です。

### 返値

文字列の取り出された部分を含んだ新しい文字列です。

解説
--

`slice()` は 1 つの文字列からテキストを取り出し、新しい文字列を返します。一方の文字列におけるテキストへの変更は、他の文字列に影響を与えません。

`slice()` は `indexEnd` を含まずにテキストを取り出します。例えば `str.slice(1, 4)` は、 2 番目から 4 番目までの文字（`1`, `2`, `3` の位置の文字）を取り出します。

* `indexStart >= str.length` の場合、空文字列が返されます。
* `indexStart < 0` の場合、位置は文字列の末尾から数えられます。もっと正式に言えば、この場合、部分文字列は `max(indexStart + str.length, 0)` から始まります。
* `indexStart` が省略されたり、 undefined であったり、（`Number(indexStart)` を使用して）数値に変換できなかったりした場合は、 `0` として扱われます。
* `indexEnd` が省略されたり、 undefined であったり、（`Number(indexEnd)` を使用して）数値に変換できなかったり、 `indexEnd >= str.length` であったりした場合は、 `slice()` は文字列の末尾まで抽出します。
* `indexEnd < 0` であった場合、その位置は文字列の末尾から数えられます。もっと正式に言えば、この場合、部分文字列は `max(indexEnd + str.length, 0)` で終わります。
* 負の値を正規化した後で `indexEnd <= indexStart` であった場合（すなわち、 `indexEnd` が `indexStart` よりも前の文字を表していた場合）は、空文字列が返されます。
例
-

### slice() を使って新しい文字列を作る

以下の例では、新しい文字列を生成するために `slice()` を使っています。

```js
const str1 = "The morning is upon us."; // The length of str1 is 23.
const str2 = str1.slice(1, 8);
const str3 = str1.slice(4, -2);
const str4 = str1.slice(12);
const str5 = str1.slice(30);
console.log(str2); // he morn
console.log(str3); // morning is upon u
console.log(str4); // is upon us.
console.log(str5); // ""
```

### 負の位置で slice() を使う

下記の例では負の位置で `slice()` を使っています。

```js
const str = "The morning is upon us.";
str.slice(-3); // 'us.'
str.slice(-3, -1); // 'us'
str.slice(0, -1); // 'The morning is upon us'
str.slice(4, -1); // 'morning is upon us'
```

この例では、文字列の末尾から前方に `11` 番目を開始位置とし、先頭から後方に `16` 番目を終了位置とします。

```js
console.log(str.slice(-11, 16)); // "is u"
```

こちらは先頭から後方に `11` 番目を開始位置とし、末尾から前方に `7` 番目を終了位置とします。

```js
console.log(str.slice(11, -7)); // " is u"
```

これらの引数は、末尾から前方に `5` 番目を開始位置とし、末尾から前方に `1` 番目を終了位置とします。

```js
console.log(str.slice(-5, -1)); // "n us"
```

仕様書
---

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

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

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

関連情報
----

* `String.prototype.substr()`
* `String.prototype.substring()`
* `Array.prototype.slice()`


String.prototype.at() - JavaScript

String.prototype.at()
=====================

**`at()`** メソッドは整数値を受け取り、指定したオフセットに位置する 1 つの UTF-16 コード単位からなる新しい文字列を返します。このメソッドでは、正と負の整数を扱うことができます。負の整数の場合は、文字列の最後の文字から前へ数えます。

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

構文
--

```js
at(index)
```

### 引数

`index`

返す文字列のインデックス（位置）。負のインデックスを渡した場合、文字列の末尾からの相対位置指定に対応しています。つまり、負の数を使用した場合、文字列の末尾から数えて返す文字を見つけます。

### 返値

指定した位置にある単一の UTF-16 コード単位からなる文字列を返します。指定された位置が見つからない場合は `undefined` を返します。

例
-

### 文字列の最後の文字を返す

次の例は、指定した文字列の中で最後に見つかった文字を返す関数です。

```js
// 指定された文字列の最後の文字を返す関数
function returnLast(arr) {
  return arr.at(-1);
}

let invoiceRef = "myinvoice01";

console.log(returnLast(invoiceRef)); // '1'

invoiceRef = "myinvoice02";

console.log(returnLast(invoiceRef)); // '2'
```

### メソッドの比較

ここでは、`String` の最後から 2 番目の文字を選択する複数の方法を比較します。以下に示すどの方法も有効ですが、`at()` メソッドの簡潔さと読みやすさが際立っています。

```js
const myString = "Every green bus drives fast.";

// length プロパティと charAt() メソッドの使用
const lengthWay = myString.charAt(myString.length - 2);
console.log(lengthWay); // 't'

// slice() メソッドの使用
const sliceWay = myString.slice(-2, -1);
console.log(sliceWay); // 't'

// at() メソッドの使用
const atWay = myString.at(-2);
console.log(atWay); // 't'
```

仕様書
---

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

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

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

関連情報
----

* `String.prototype.at` のポリフィル (`core-js`)
* at() メソッドのポリフィル.
* `String.prototype.indexOf()`
* `String.prototype.lastIndexOf()`
* `String.prototype.charCodeAt()`
* `String.prototype.codePointAt()`
* `String.prototype.split()`


String: length - JavaScript

String: length
==============

**`length`** データプロパティは、`String` オブジェクトの文字列長を UTF-16 コード単位の数で表します。

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

値
-

非負の整数です。

| `String: length` のプロパティ属性 |
| --- |
| 書込可能 | 不可 |
| 列挙可能 | 不可 |
| 設定可能 | 不可 |

解説
--

このプロパティは、文字列内のコード単位の数を返します。JavaScript では UTF-16 エンコーディングを使用しており、すべての Unicode 文字が 1 つまたは 2 つのコード単位にエンコードされるため、`length` で返される値は文字列の実際の Unicode 文字数に一致しない可能性があります。よく使われるラテン、キリル、有名な漢字などはこのような問題にはなりませんが、絵文字、数学記号、難しい漢字などのような特定の文字体系では、`length` で返される値が文字列の実際の文字数と一致しなくなる可能性があるので、コード単位数と文字数の違いを考慮する必要があるかもしれません。

言語の仕様書では、文字列の最大長が 253 - 1 要素と制定されており、これは正確に表せる整数の上限となっています。しかし、この長さの文字列は 16,384TiB のストレージを必要とし、これは一般的な機器のメモリーに収まらないため、実装上はもっと低い閾値を設けている傾向があり、文字列の長さを便宜上 32 ビット整数に収めています。

* V8 （Chrome と node で使用）では、最大長は 229 - 24 (~1GiB) です。32 ビットの場合、最大長は 228 - 16 (~512MiB) です。
* Firefox では、最大長は 230 - 2 (~2GiB) です。Firefox 65 以前では、最大長は 228 - 1 (~512MiB) でした。
* Safari では、最大長は 231 - 1 (~4GiB) です。

空文字列の場合、`length` は 0 になります。

静的プロパティの `String.length` は文字列の長さとは関係なく、 `String` 関数のアリティ（簡単に言えば、それが持つ形式的な引数の数）であり、1 です。

`length` は文字数ではなくコード単位で数えるため、文字数を取得したい場合は、まず文字列をイテレーターで分割し、文字ごとに反復処理をっしてください。

```js
function getCharacterLength(str) {
  // ここで使用する文字列イテレーターは、単なるコード単位ではなく、
  // 文字を反復処理します。
  return [...str].length;
}

console.log(getCharacterLength("A\uD87E\uDC04Z")); // 3
```

例
-

### 基本的な使い方

```js
const x = "Mozilla";
const empty = "";

console.log(`${x} は ${x.length} コード単位の長さです`);
/\* "Mozilla は 7 コード単位の長さです" \*/

console.log(`空文字列の長さは ${empty.length} です`);
/\* "空文字の長さは 0 です" \*/
```

### 文字列の length は文字数と等しいとは限らない

```js
const emoji = "😄";
console.log(emoji.length); // 2
console.log([...emoji].length); // 1
const adlam = "𞤲𞥋𞤣𞤫";
console.log(adlam.length); // 8
console.log([...adlam].length); // 4
const formula = "∀𝑥∈ℝ,𝑥²≥0";
console.log(formula.length); // 11
console.log([...formula].length); // 9
```

### length への代入

文字列はプリミティブであるため、文字列の `length` プロパティに値を代入しても目に見える効果はなく、厳格モードでは例外が発生します。

```js
const myString = "bluebells";

myString.length = 4;
console.log(myString); // "bluebells"
console.log(myString.length); // 9
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-properties-of-string-instances-length |

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

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

関連情報
----

* JavaScript `String.length` and Internationalizing Web Applications


String.prototype.trimStart() - JavaScript

String.prototype.trimStart()
============================

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

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

構文
--

```js
trimStart()

trimLeft()
```

### 返値

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

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

### 別名

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

```js
String.prototype.trimLeft.name === "trimStart";
```

例
-

### trimStart() の使用

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

```js
let str = " foo ";

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

str = str.trimStart();
console.log(str.length); // 5
console.log(str); // 'foo '
```

仕様書
---

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

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

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

関連情報
----

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


String.prototype.big() - JavaScript

String.prototype.big()
======================

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

**`big()`** は `String` 値のメソッドで、ｋの文字列を `<big>` 要素の中に埋め込み (`<big>str</big>`)、この文字列が大きなフォントで表示されるようにします。

**警告:** HTML ラッパーメソッドはすべて非推奨となっており、互換性目的のみで標準化されています。`<big>` 要素自体は HTML 仕様書から削除されており、今後使用するべきではありません。代わりにウェブ開発者は CSS プロパティを使用してください。

構文
--

```js
big()
```

### 引数

なし。

### 返値

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

例
-

### big() の使用

下記のコードは HTML 文字列を作成し、文書内の本体を文字列で置き換えています。

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

document.body.innerHTML = contentString.big();
```

これで次の HTML が作成されます。

```html
<big>Hello, world</big>
```

**警告:** `big` は有効な要素ではなくなっているので、このマークアップは無効です。

`big()` を使用して直接 HTML テキストを作成する代わりに、 CSS を使用してフォントを操作しましょう。例えば、 `element.style` 属性を通して `font-size` を操作することができます。

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

仕様書
---

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

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

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

関連情報
----

* `String.prototype.big` のポリフィル (`core-js`)
* HTML ラッパーメソッド
* `<big>`


String.prototype.sup() - JavaScript

String.prototype.sup()
======================

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

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

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

構文
--

```js
sup()
```

### 返値

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

例
-

### 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.sup |

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

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

関連情報
----

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


String.prototype.bold() - JavaScript

String.prototype.bold()
=======================

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

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

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

構文
--

```js
bold()
```

### 返値

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

例
-

### bold() の使用

次の例では、非推奨の文字列メソッドを使用して文字列の書式を変更しています。

```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.bold |

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

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

関連情報
----

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


String.prototype.includes() - JavaScript

String.prototype.includes()
===========================

**`includes()`** メソッドは、1 つの文字列を別の文字列の中に見出すことができるかどうかを判断し、必要に応じて `true` か `false` を返します。

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

構文
--

```js
includes(searchString)
includes(searchString, position)
```

引数
--

`searchString`

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

`position` 省略可

文字列内で `searchString` を検索し始める位置です。（既定値は `0` です。）

### 返値

検索文字列が指定された文字列の中で見つかった場合、`searchString` が空文字列の場合は **`true`**。そうでなければ **`false`** です。

### 例外

`TypeError`

`searchString` が正規表現であった場合に発生します。

解説
--

このメソッドで、ある文字列が別な文字列の中に含まれているかどうかを判断することができます。

### 大文字小文字の区別

`includes()` メソッドは大文字と小文字が区別します。例えば、次のコードでは `false` を返します。

```js
"Blue Whale".includes("blue"); // false を返す
```

元の文字列と検索文字列の両方をすべて小文字に変換することで、この制約を回避することができます。

```js
"Blue Whale".toLowerCase().includes("blue"); // true を返す
```

例
-

### includes() の使用

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

console.log(str.includes("To be")); // true
console.log(str.includes("question")); // true
console.log(str.includes("nonexistent")); // false
console.log(str.includes("To be", 1)); // false
console.log(str.includes("TO BE")); // false
console.log(str.includes("")); // true
```

仕様書
---

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

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

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

関連情報
----

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


String.prototype.search() - JavaScript

String.prototype.search()
=========================

**`search()`** メソッドは、正規表現とこの `String` オブジェクトが一致するかどうかを調べます。

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

構文
--

```js
search(regexp)
```

### 引数

`regexp`

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

`regexp` が `RegExp` オブジェクトでなく、`Symbol.search` メソッドもなかった場合は、`RegExp` オブジェクトに `new RegExp(regexp)` を使用して暗黙的に変換されます。

### 返値

与えられた文字列と正規表現の間で最初に一致した箇所のインデックスを返します。一致しなかった場合は `-1` を返します。

解説
--

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

`regexp` の `g` フラグは `search()` の結果には影響がなく、検索は常に正規表現の `lastIndex` が 0 であるかのように行われます。`search()` の動作についての詳しい情報は、`RegExp.prototype[@@search]()` を参照してください。

パターンが見つかるかどうかを知りたい場合、かつ、文字列内のインデックスを知りたい場合は、`search()` を使用してください。

* パターンが存在するかどうかを知りたいだけであれば、`RegExp.prototype.test()` メソッドを使用してください。これは論理値を返します。
* 一致したテキストの内容が必要な場合は、`match()` または `RegExp.prototype.exec()` を使用してください。
例
-

### search() の使用

次の例は、2 つの異なる正規表現オブジェクトで文字列を検索し、成功した検索（正の値）と失敗した検索 (`-1`) を表示します。

```js
const str = "hey JudE";
const re = /[A-Z]/;
const reDot = /[.]/;
console.log(str.search(re)); // 最初の大文字 "J" のインデックスである 4 を返します
console.log(str.search(reDot)); // ドット記号 '.' が見つからないので -1 を返します
```

仕様書
---

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

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

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

関連情報
----

* `String.prototype.search` のポリフィル (`core-js`) （`Symbol.search` のようなの現代の修正や挙動つき）
* JavaScript の正規表現の使用
* `String.prototype.match()`
* `RegExp.prototype.exec()`
* `RegExp.prototype[@@search]()`


String.prototype.split() - JavaScript

String.prototype.split()
========================

**`split()`** メソッドは、パターンを受け取り、`String` をパターン検索によって部分文字列の順序付きリストに分割し、これらの部分文字列を配列に入れ、その配列を返します。

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

構文
--

```js
split(separator)
split(separator, limit)
```

### 引数

`separator`

各分割がどこで行われるかを表すパターンです。`undefined`、文字列、または `Symbol.split` メソッドを持つオブジェクトを指定することができます。典型的な例は正規表現です。`separator` を省略したり `undefined` を渡したりすると、`split()` は呼び出し元の文字列を 1 つの要素とする配列を返します。`undefined` でない値、または `@@split` メソッドを持つオブジェクトはすべて文字列に変換されます。

`limit` 省略可

配列に含める部分文字列の数の制限を指定する非負の整数。指定した場合は、指定した `separator` が出現するたびに文字列を分割しますが、`limit` 個の項目が配列に格納された時点で分割を終了します。残った文字列は配列に格納されません。

* 制限数に達する以前に文字列の末尾に達した場合は、配列の要素が `limit` よりも少なくなることがあります。
* `limit` が `0` の場合は、`[]` が返されます。

### 返値

文字列の `Array` で、指定された文字列で `separator` が現れるたびに分割されたものです。

解説
--

`separator` が空でない文字列の場合、対象の文字列は `separator` に一致するすべての文字列で分割され、その結果には `separator` は含まれません。例えば、タブ区切り値 (TSV) を含む文字列は、`myString.split("\t")` のようにタブ文字を区切り文字として渡すことで解析できます。`separator` が複数の文字を含む場合、分割するためにはその文字列をすべて見つける必要があります。`separator` が文字列の先頭（または末尾）にある場合でも分割の効果は変わりません。その結果、返値の配列の最初 (または最後) の位置には空文字列（つまり長さ 0）が含まれます。`separator` が `str` 内に存在しない場合、返値の配列には文字列全体からなる要素が 1 つ含まれます。

`separator` が空文字列 (`""`) の場合、`str` は UTF-16 の「文字」の配列に変換され、両端が空文字列になることはありません。

**メモ:** したがって、`"".split("")` は `separator` として文字列を渡されたときに空文字列の配列を生成する唯一の方法です。

**警告:** 区切り文字として空文字列 (`""`) が用いられた場合、文字列はユーザが認識する文字（書記素クラスタ）や Unicode 文字（コードポイント）ではなく、UTF-16 コード単位で分割されます。 これはサロゲートペアを破壊します。StackOverflow の "How do you get a string to a character array in JavaScript?" を参照してください。

`separator` が空文字列に一致する正規表現である場合、一致する文字列が UTF-16 コード単位で分割されるか、Unicode コード点で分割されるかは、正規表現が Unicode-aware かどうかに依存します。

```js
"😄😄".split(/(?:)/); // [ "\ud83d", "\ude04", "\ud83d", "\ude04" ]
"😄😄".split(/(?:)/u); // [ "😄", "😄" ]
```

もし `separator` がキャプチャグループを持つ正規表現であれば、`separator` が一致するたびに、キャプチャされたグループ（`undefined` の結果を含む）が出力配列に分割されます。 この動作は正規表現の `Symbol.split` メソッドで指定します。

区切り文字 `separator` が `Symbol.split` メソッドを持つオブジェクトの場合、そのメソッドは対象の文字列と `limit` を引数として呼び出され、`this` にはそのオブジェクトが設定されます。 その返値が `split` の返値になります。

それ以外の値は、セパレーターとして使われる前に文字列に変換されます。

例
-

### split() の使用

文字列が空の場合、 `split()` は空の配列ではなく、1 つの空文字列を含む配列を返します。文字列と区切り文字列が共に空文字列の場合、空の配列が返ります。

```js
const emptyString = "";

// 文字列は空で、セパレーターは空ではない
console.log(emptyString.split("a"));
// [""]

// 文字列とセパレーターがともに空文字列
console.log(emptyString.split(emptyString));
// []
```

次の例では、文字列を `separator` を用いて文字列の配列に分割する関数を定義します。 文字列を分割した後、この関数は元の文字列（分割前）、用いている区切り文字、配列の要素数、個々の配列要素を示すメッセージをログ出力します。

```js
function splitString(stringToSplit, separator) {
  const arrayOfStrings = stringToSplit.split(separator);

  console.log("元の文字列: ", stringToSplit);
  console.log("区切り文字列: ", separator);
  console.log(
    "配列の要素数は",
    arrayOfStrings.length,
    "件: ",
    arrayOfStrings.join(" / "),
  );
}

const tempestString = "Oh brave new world that has such people in it.";
const monthString = "Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec";

const space = " ";
const comma = ",";

splitString(tempestString, space);
splitString(tempestString);
splitString(monthString, comma);
```

この例は次のような出力結果を生成します。
```

元の文字列: "Oh brave new world that has such people in it."
区切り: " "
配列は 10 要素: Oh / brave / new / world / that / has / such / people / in / it.

元の文字列: "Oh brave new world that has such people in it."
区切り: "undefined"
配列は 1 要素: Oh brave new world that has such people in it.

元の文字列: "Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
区切り: ","
配列は 12 要素: Jan / Feb / Mar / Apr / May / Jun / Jul / Aug / Sep / Oct / Nov / Dec
```

### 文字列からの空白の削除

以下の例では、`split()` は、0 回以上の空白とそれに続くセミコロン、それにさらに続く 0 回以上の空白を探し、それらが見つかったとき、文字列から空白を削除します。`nameList` は、`split()` の結果として返された配列です。

```js
const names = "Harry Trump ;Fred Barney; Helen Rigby ; Bill Abel ;Chris Hand ";

console.log(names);

const re = /\s\*(?:;|$)\s\*/;
const nameList = names.split(re);

console.log(nameList);
```

これは 2 つの行を出力します。1 行目は元の文字列を出力し、2 行目は `split` メソッドの実行結果の配列を出力します。
```

Harry Trump ;Fred Barney; Helen Rigby ; Bill Abel ;Chris Hand
[ "Harry Trump", "Fred Barney", "Helen Rigby", "Bill Abel", "Chris Hand", "" ]
```

### 限られた数の分割結果を返す

以下の例では、`split()` は 文字列中の 0 回以上の空白を探し、見つかった最初の 3 つの分割結果を返します。

```js
const myString = "Hello World. How are you doing?";
const splits = myString.split(" ", 3);

console.log(splits); // [ "Hello", "World.", "How" ]
```

### `RegExp` を使った分割でセパレーターの一部を結果に含める

もし `separator` が括弧 `( )` を含む正規表現であれば、一致した結果が配列に含められます。

```js
const myString = "Hello 1 word. Sentence number 2.";
const splits = myString.split(/(\d)/);

console.log(splits);
// [ "Hello ", "1", " word. Sentence number ", "2", "." ]
```

**メモ:** `\d` は数字 0 から 9 までの文字クラスに一致します。

### 独自のスプリッターの使用

`Symbol.split` メソッドを持つオブジェクトは、独自の動作を持つスプリッターとして使用することができます。

次の例は、増加する数値からなる内部状態を使用して文字列を分割します。

```js
const splitByNumber = {
  [Symbol.split](str) {
    let num = 1;
    let pos = 0;
    const result = [];
    while (pos < str.length) {
      const matchPos = str.indexOf(num, pos);
      if (matchPos === -1) {
        result.push(str.substring(pos));
        break;
      }
      result.push(str.substring(pos, matchPos));
      pos = matchPos + String(num).length;
      num++;
    }
    return result;
  },
};

const myString = "a1bc2c5d3e4f";
console.log(myString.split(splitByNumber)); // [ "a", "bc", "c5d", "e", "f" ]
```

次の例では、内部状態を使用して特定の動作を強制し、「有効な」結果が確実に保持されるようにしています。

```js
const DELIMITER = ";";

// Split the commands, but remove any invalid or unnecessary values.
const splitCommands = {
  [Symbol.split](str, lim) {
    const results = [];
    const state = {
      on: false,
      brightness: {
        current: 2,
        min: 1,
        max: 3,
      },
    };
    let pos = 0;
    let matchPos = str.indexOf(DELIMITER, pos);

    while (matchPos !== -1) {
      const subString = str.slice(pos, matchPos).trim();

      switch (subString) {
        case "light on":
          // If the `on` state is already true, do nothing.
          if (!state.on) {
            state.on = true;
            results.push(subString);
          }
          break;

        case "light off":
          // If the `on` state is already false, do nothing.
          if (state.on) {
            state.on = false;
            results.push(subString);
          }
          break;

        case "brightness up":
          // Enforce a brightness maximum.
          if (state.brightness.current < state.brightness.max) {
            state.brightness.current += 1;
            results.push(subString);
          }
          break;

        case "brightness down":
          // Enforce a brightness minimum.
          if (state.brightness.current > state.brightness.min) {
            state.brightness.current -= 1;
            results.push(subString);
          }
          break;
      }

      if (results.length === lim) {
        break;
      }

      pos = matchPos + DELIMITER.length;
      matchPos = str.indexOf(DELIMITER, pos);
    }

    // If we broke early due to reaching the split `lim`, don't add the remaining commands.
    if (results.length < lim) {
      results.push(str.slice(pos).trim());
    }

    return results;
  },
};

const commands =
  "light on; brightness up; brightness up; brightness up; light on; brightness down; brightness down; light off";
console.log(commands.split(splitCommands, 3)); // ["light on", "brightness up", "brightness down"]
```

仕様書
---

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

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

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

関連情報
----

* `String.prototype.split` のポリフィル (`core-js`)（`Symbol.split` のような現代の動作の修正と実装に対応）
* `String.prototype.charAt()`
* `String.prototype.indexOf()`
* `String.prototype.lastIndexOf()`
* `Array.prototype.join()`
* JavaScript での正規表現の使用


String.fromCodePoint() - JavaScript

String.fromCodePoint()
======================

**`String.fromCodePoint()`** 静的メソッドは指定されたコードポイントの並びを使って生成された文字列を返します。

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

構文
--

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

### 引数

`numN`

`0` 以上 `0x10FFFF` 以下の整数で、Unicode コードポイントを表します。

### 返値

指定されたコードポイントの並びを使って生成された文字列です。

### 例外

`RangeError`

`numN` を数値に変換した後で整数でなかった場合、`0` よりも小さかった場合、`0x10FFFF` よりも大きかった場合に発生します。

解説
--

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

Unicode のコードポイントは `0` から `1114111` (`0x10FFFF`) までの範囲です。`charAt()` は常に `65536` より小さい値を返しますが、これは上位のコードポイントは 16 ビットのサロゲート擬似文字のペアによって表されているからです。従って、`fromCodePoint()` は（UTF-16 コード単位である） `length` が渡された引数の数よりも大きくなる文字列を返す可能性があります。Unicode に関する情報はUTF-16 文字、Unicode コードポイント、書記素クラスターを参照してください。

例
-

### fromCodePoint() の使用

有効な入力:

```js
String.fromCodePoint(42); // "\*"
String.fromCodePoint(65, 90); // "AZ"
String.fromCodePoint(0x404); // "\u0404" === "Є"
String.fromCodePoint(0x2f804); // "\uD87E\uDC04"
String.fromCodePoint(194564); // "\uD87E\uDC04"
String.fromCodePoint(0x1d306, 0x61, 0x1d307); // "\uD834\uDF06a\uD834\uDF07"
```

無効な入力:

```js
String.fromCodePoint("\_"); // RangeError
String.fromCodePoint(Infinity); // RangeError
String.fromCodePoint(-1); // RangeError
String.fromCodePoint(3.14); // RangeError
String.fromCodePoint(3e-2); // RangeError
String.fromCodePoint(NaN); // RangeError
```

### fromCharCode() との比較

`String.fromCharCode()` では補助文字（すなわち `0x010000` – `0x10FFFF`）のコードポイントを指定することで返すことができません。補助文字を返すためには、 UTF-16 のサロゲートペアでが必要です。

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

一方、 `String.fromCodePoint()` はコードポイント（UTF-32 のコード単位に相当）を指定することで、 4 バイトの補助文字や、一般的な 2 バイトの BMP 文字を返すことができます。

```js
String.fromCodePoint(0x1f303); // または 10 進数で 127747
```

仕様書
---

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

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

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

関連情報
----

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


String.prototype.fixed() - JavaScript

String.prototype.fixed()
========================

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

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

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

構文
--

```js
fixed()
```

### 返値

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

例
-

### fixed() の使用

下記の例は、 `fixed` メソッドを使用して文字列の表示方法を変更します。

```js
const worldString = "世界のみなさん、こんにちは！";
console.log(worldString.fixed()); // "<tt>世界のみなさん、こんにちは！</tt>"
```

仕様書
---

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

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

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

関連情報
----

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


String.prototype.replace() - JavaScript

String.prototype.replace()
==========================

**`replace()`** メソッドは、`pattern` に一致する文字列の一部またはすべてを `replacement` で置き換えた新しい文字列を返します。`pattern` には文字列または正規表現 (`RegExp`) を指定することができ、 `replacement` には文字列または一致するごとに呼び出される関数を指定することができます。`pattern` が文字列の場合、最初に一致した箇所のみを置き換えます。元の文字列は変更されません。

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

構文
--

```js
replace(pattern, replacement)
```

### 引数

`pattern`

文字列または `Symbol.replace` メソッドを持つオブジェクトを置くことができます。典型的な例は正規表現です。`Symbol.replace` メソッドを持たない値は文字列に変換されます。

`replacement`

文字列または関数です。

* 文字列の場合、`pattern` に一致する部分文字列を置き換えます。数々の特別な置換パターンに対応しています。下記の「置換文字列としての文字列の指定」の節を参照してください。
* 関数の場合、一致するごとに呼び出され、その返値が置き換えるテキストとして使用されます。この関数に渡される引数は下記の「置換文字列としての関数の指定」で述べられています。

### 返値

パターンの 1 つ、いくつか、またはすべての一致を指定した置換で置き換えた新しい文字列です。

解説
--

このメソッドは、それを呼び出した文字列を変化させません。返値として新しい文字列を返します。

文字列パターンは一度だけ置換されます。 グローバルな検索と置換を行うには、正規表現を `g` フラグで使用するか、代わりに `replaceAll()` を使用してください。

`pattern` が `Symbol.replace` メソッドを持つオブジェクト（`RegExp` オブジェクトを含む）である場合、そのメソッドはターゲット文字列と `replacement` を引数として呼び出されます。その返値は `replace()` の返値となります。この場合、`replace()` の動作は完全に `@@replace` メソッドによってエンコードされます。例えば、以下の説明で「グループをキャプチャする」と書かれているものは、実際には `RegExp.prototype[@@replace]` によって提供される機能です。

`pattern` が空文字列の場合、文字列の始めには置換後の文字列が置かれます。

```js
"xxx".replace("", "\_"); // "\_xxx"
```

`g` フラグを持つ正規表現は、 `replace()` が複数回置換する唯一のケースです。正規表現プロパティ（特に sticky フラグ）と `replace()` の相互作用については、`RegExp.prototype[@@replace]()` を参照してください。

### 置換文字列としての文字列の指定

置換文字列には以下の特殊な置換パターンを入れることができます。

| パターン | 導入 |
| --- | --- |
| `$$` | `"$"` を挿入します。 |
| `$&` | 一致した部分文字列を挿入します。 |
| `$`` | 一致した部分文字列の直前の文字列の部分を挿入します。 |
| `$'` | 一致した部分文字列の直後の文字列の部分を挿入します。 |
| `$n` | `n` 番目（1 基点）にキャプチャされた文字列を挿入します。`n` は 100 未満の正の整数です。 |
| `$<Name>` | `Name` はグループ名で、指定された名前のキャプチャグループを挿入します。 |

`$n` と `$<Name>` は `pattern` 引数が `RegExp` オブジェクトである場合にのみ利用できます。`pattern` が文字列であった場合、または対応するキャプチャグループが正規表現に存在しなかった場合、パターンはリテラルとして置き換えられます。グループが存在しているものの、一致しなかった場合（論理和の一部であった場合など）は、空文字列に置き換えられます。

```js
"foo".replace(/(f)/, "$2");
// "$2oo" となる。正規表現に 2 番目のグループがないため。

"foo".replace("f", "$1");
// "$1oo" となる。パターンが文字列であり、グループを持たないため。

"foo".replace(/(f)|(g)/, "$2");
// "oo" となる。2 番目のグループが存在するものの、一致するものがないため。
```

### 置換文字列としての関数の指定

第 2 引数として関数を指定することができます。この場合、関数は照合が行われた後に実行されます。関数呼び出しの結果（返値）が、置換文字列として使われます

**メモ:** 上記の特殊な置き換えパターンは、置き換え関数から返される文字列には適用されません。

関数の形式は次の通りです。

```js
function replacer(match, p1, p2, /\* …, \*/ pN, offset, string, groups) {
  return replacement;
}
```

関数に与えられる引数は次の通りです。

`match`

一致した部分文字列（上記の `$&` に対応）です。

`p1, p2, …, pN`

キャプチャグループ（名前付きキャプチャグループを含む）で見つかった `n` 番目の文字列で、`replace()` の第一引数が `RegExp` オブジェクトだった場合に提供されるものです。（上記の `$1`, `$2`, などに対応します。）例えば `pattern` が `/(\a+)(\b+)/` であった場合、`p1` は `\a+` に対する一致、`p2` は `\b+` に対する一致となります。そのグループが論理和の一部である場合（`"abc".replace(/(a)|(b)/, replacer)` など）、一致しない選択肢は `undefined` なります。

`offset`

一致した部分文字列の、分析中の文字列全体の中でのオフセットです。例えば、文字列全体が `'abcd'` で、一致した部分文字列が `'bc'` ならば、この引数は 1 となります。

`string`

分析中の文字列全体です。

`groups`

名前付きキャプチャグループに対応しているブラウザーのバージョンでは、使用されるグループ名をキーとし、一致した部分を値とするオブジェクトになります（一致しない場合は `undefined`）。

（引数の正確な個数は、第一引数が `RegExp` オブジェクトかどうか、そうならばさらに括弧でキャプチャされるサブ一致がいくつ指定されているかによります。）

以下の例は `newString` に `'abc - 12345 - #$*%'` をセットします。

```js
function replacer(match, p1, p2, p3, offset, string) {
  // p1 is non-digits, p2 digits, and p3 non-alphanumerics
  return [p1, p2, p3].join(" - ");
}
const newString = "abc12345#$\*%".replace(/([^\d]\*)(\d\*)([^\w]\*)/, replacer);
console.log(newString); // abc - 12345 - #$\*%
```

この関数は、最初の引数の正規表現がグローバルである場合、それぞれ完全に一致するものが置き換えられるごとに複数回呼び出されます。

例
-

### replace() で正規表現を利用する

以下の例では、 `replace()` メソッドで正規表現を利用しています。

```js
const str = "Twas the night before Xmas...";
const newstr = str.replace(/xmas/i, "Christmas");
console.log(newstr); // Twas the night before Christmas...
```

これは `'Twas the night before Christmas...'` と出力します。

**メモ:** 正規表現についてのその他の例はこのガイドを参照してください。

### 大文字小文字を区別しないフラグとグローバルフラグの使用

グローバルな置換は、正規表現でのみ行うことができます。次の例では、正規表現にグローバルフラグと大文字小文字の区別をしないフラグが含まれているため、 `replace()` は文字列中の `'apples'` の各出現箇所を `'oranges'` に置き換えることができます。

```js
const re = /apples/gi;
const str = "Apples are round, and apples are juicy.";
const newstr = str.replace(re, "oranges");
console.log(newstr); // oranges are round, and oranges are juicy.
```

この出力は 'oranges are round, and oranges are juicy' となります。

### 文字列内の単語の交換

次のスクリプトでは、文字列内の単語を交換します。テキストを置き換えるために、このスクリプトはキャプチャリンググループと置換パターン `$1` および `$2` を使用しています。

```js
const re = /(\w+)\s(\w+)/;
const str = "Maria Cruz";
const newstr = str.replace(re, "$2, $1");
console.log(newstr); // Cruz, Maria
```

この出力は `'Cruz, Maria'` となります。

### 一致した文字を修正するインライン関数の使用

次の例では、文字列内に出現する大文字のすべては小文字に変換され、ハイフンが一致した位置の直前に挿入されます。ここで重要なことは、追加の操作は、一致したアイテムが置換されて戻される前に必要とされるということです。

置換する関数は一致した断片をその関数の引数として適用します。そして、その引数を大文字小文字変形し、返値の直前にハイフンを連結します。

```js
function styleHyphenFormat(propertyName) {
  function upperToHyphenLower(match, offset, string) {
    return (offset > 0 ? "-" : "") + match.toLowerCase();
  }
  return propertyName.replace(/[A-Z]/g, upperToHyphenLower);
}
```

`styleHyphenFormat('borderTop')`を入力すると `'border-top'` を返します。

最終的な置換が行われる前に、一致の*結果*をさらに変換したいので、関数を使用する必要があります。これにより、`toLowerCase()` メソッドの前に一致の評価が行われます。関数を使わず一致を使ってこれを行おうとした場合、 `toLowerCase()` は何の効果もないでしょう。

```js
// 動作しない
const newString = propertyName.replace(/[A-Z]/g, "-" + "$&".toLowerCase());
```

これは、 `'$&'.toLowerCase()` は、まずその文字がパターンとして使用される前に（`'$&'` という結果である）文字列リテラルとして評価されるだろうからです。

### 華氏温度を同等の摂氏温度と置き換える

以下の例は、ある華氏温度をそれと同等の摂氏温度と置き換えます。その華氏温度は `"F"` で終わる数でなければなりません。この関数は `"C"` で終わる摂氏を返します。例えば、入力される数が `"212F"` である場合、その関数は `"100C"` を返します。入力される数が `"0F"` であった場合、その関数は `"-17.77777777777778C"` を返します。

その正規表現 `test` は、任意の数が `F` で終わっているかチェックします。華氏温度の数は、関数の 第二引数 `p1` を通して、その関数にアクセスできます。その関数は文字列内で渡された華氏温度をベースとした摂氏の数を `f2c()` にセットします。それから、`f2c()` は、摂氏の数を返します。この関数は Perl の `s///e` フラグと似ています。

```js
function f2c(x) {
  function convert(str, p1, offset, s) {
    return `${((p1 - 32) \* 5) / 9}C`;
  }
  const s = String(x);
  const test = /(-?\d+(?:\.\d\*)?)F\b/g;
  return s.replace(test, convert);
}
```

### 汎用リプレイサーの作成

一致する文字列にオフセットのデータを追加するリプレイサーを作成したいとします。 リプレイサー関数はすでに `offset` 引数を受け取っているので、正規表現が静的に分かっていれば簡単です。

```js
"abcd".replace(/(bc)/, (match, p1, offset) => `${match} (${offset}) `);
// "abc (1) d"
```

しかし、このリプレイサーを任意の正規表現パターンで動作させたい場合、一般化するのは難しいでしょう。 このリプレイサーは可変的です。引数の数は存在するキャプチャグループの数に依存します。残余引数を使用することができますが、`offset` や `string` なども配列に収集してしまいます。`groups` が正規表現の同一性によって渡されたり渡されなかったりするため、`offset` に対応する引数を知る処理を一般化することは難しいでしょう。

```js
function addOffset(match, ...args) {
  const offset = args.at(-2);
  return `${match} (${offset}) `;
}

console.log("abcd".replace(/(bc)/, addOffset)); // "abc (1) d"
console.log("abcd".replace(/(?<group>bc)/, addOffset)); // "abc (abcd) d"
```

この例では `args.at(-2)` が `offset` ではなく `string` になってしまうため、上記の `addOffset` の例は正規表現に名前付きグループが格納されている場合にはうまく動作しません。

代わりに、`groups` はオブジェクトですが、`string` は文字列なので、型に基づいて最後のいくつかの引数を抽出する必要があります。

```js
function addOffset(match, ...args) {
  const hasNamedGroups = typeof args.at(-1) === "object";
  const offset = hasNamedGroups ? args.at(-3) : args.at(-2);
  return `${match} (${offset}) `;
}

console.log("abcd".replace(/(bc)/, addOffset)); // "abc (1) d"
console.log("abcd".replace(/(?<group>bc)/, addOffset)); // "abc (1) d"
```

仕様書
---

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

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

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

関連情報
----

* `String.prototype.replace` のポリフィル (`core-js`) （`Symbol.replace` への対応など、現代の修正や実装に対応したもの）
* `String.prototype.replaceAll()`
* `String.prototype.match()`
* `RegExp.prototype.exec()`
* `RegExp.prototype.test()`
* `Symbol.replace`
* `RegExp.prototype[@@replace]()`


String.prototype.replaceAll() - JavaScript

String.prototype.replaceAll()
=============================

**`replaceAll()`** メソッドは、`pattern` に一致したすべての文字列を `replacement` で置き換えた新しい文字列を返します。`pattern` は文字列または `RegExp` を指定することができ、`replacement` は文字列または各一致に対して呼び出される関数を指定することができます。元の文字列は変更されません。

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

構文
--

```js
replaceAll(pattern, replacement)
```

### 引数

`pattern`

文字列または `Symbol.replace` メソッドを持つオブジェクトを置くことができます。典型的な例は正規表現です。`Symbol.replace` メソッドを持たない値は文字列に変換されます。

`regexp` が正規表現である場合、グローバルフラグ (`g`) が設定されます。そうでなければ `TypeError` が発生します。

`replacement`

文字列または関数を指定することができます。この置換は `String.prototype.replace()` と意味的に同じです。

### 返値

パターンに一致したすべての文字列を置換文字列で置き換えた新しい文字列です。

### 例外

`TypeError`

`pattern` が正規表現である場合で、グローバルフラグ (`g`) が設定されていない場合（`flags` プロパティに `"g"` が含まれていない場合）。

解説
--

このメソッドは呼び出された文字列値を変更しません。新しい文字列を返します。

`replace()` とは異なり、このメソッドは最初に一致した文字列だけでなく、出現した文字列を置き換えます。これは文字列が静的に既知でない場合に特に有用です。特殊文字をエスケープせずに `RegExp()` コンストラクターを呼び出すと、意図せずに意味づけが変わってしまう可能性があるからです。

```js
function unsafeRedactName(text, name) {
  return text.replace(new RegExp(name, "g"), "[REDACTED]");
}
function safeRedactName(text, name) {
  return text.replaceAll(name, "[REDACTED]");
}

const report =
  "A hacker called ha.\*er used special characters in their name to breach the system.";

console.log(unsafeRedactName(report, "ha.\*er")); // "A [REDACTED]s in their name to breach the system."
console.log(safeRedactName(report, "ha.\*er")); // "A hacker called [REDACTED] used special characters in their name to breach the system."
```

`pattern` が `Symbol.replace` メソッドを持つオブジェクト（`RegExp` オブジェクトを含む）である場合、そのメソッドは対象の文字列と `replacement` を引数として呼び出されます。その返値は `replaceAll()` の返値となります。この場合、`replaceAll()` の動作は完全に `@@replace` メソッドによってエンコードされるので、 `replace()` と同じ結果になります（正規表現がグローバルであるかどうかの余分な入力検証を除けば）。
 `pattern` が空文字列の場合、`split()` の動作と同様に、UTF-16 のコード単位ごとに置換文字列が挿入されます。

```js
"xxx".replaceAll("", "\_"); // "\_x\_x\_x\_"
```

正規表現プロパティ（特に sticky フラグ）と `replaceAll()` との相互作用については、`RegExp.prototype[@@replace]()` を参照してください。

例
-

### replaceAll() の使用

```js
"aabbcc".replaceAll("b", ".");
// 'aa..cc'
```

### グローバルではない正規表現

正規表現フラグを使用する場合は、グローバルである必要があります。これは動作しません。

```js
"aabbcc".replaceAll(/b/, ".");
// TypeError: replaceAll must be called with a global RegExp
```

これは動作します。

```js
"aabbcc".replaceAll(/b/g, ".");
("aa..cc");
```

仕様書
---

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

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

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

関連情報
----

* `String.prototype.replaceAll` のポリフィル (`core-js`)
* `String.prototype.replace()`
* `String.prototype.match()`
* `RegExp.prototype.exec()`
* `RegExp.prototype.test()`


String.prototype.valueOf() - JavaScript

String.prototype.valueOf()
==========================

**`valueOf()`** メソッドは、`String` オブジェクトのプリミティブ値を返します。

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

構文
--

```js
valueOf()
```

### 返値

与えられた `String` オブジェクトのプリミティブ値を表す文字列です。

詳細
--

`String` オブジェクトの `valueOf()` メソッドは、`String` オブジェクトの文字列型としてのプリミティブ値を返します。この値は、`String.prototype.toString()` の返値と等価です。

このメソッドは通常、JavaScript によって内部的に呼ばれ、コード中で明示的に呼ばれることはありません。

例
-

### `valueOf()` メソッドの使用

```js
const x = new String("Hello world");
console.log(x.valueOf()); // 'Hello world'
```

仕様書
---

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

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

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

関連情報
----

* `String.prototype.toString()`
* `Object.prototype.valueOf()`


String.prototype.matchAll() - JavaScript

String.prototype.matchAll()
===========================

**`matchAll()`** は正規表現に一致するすべての文字列を、キャプチャグループを含み、イテレーターで返すメソッドです。

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

構文
--

```js
matchAll(regexp)
```

### 引数

`regexp`

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

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

`regexp` が正規表現である場合、グローバルフラグ (`g`) が設定されます。そうでなければ `TypeError` が発生します。

### 返値

一致したものの反復可能なイテレーターオブジェクト（再起動不可能なもの）です。それぞれの一致する配列は `RegExp.prototype.exec()` の返値と同じ形です。

### 例外

`TypeError`

`regexp` が正規表現である場合で、グローバルフラグ (`g`) が設定されていない場合（`flags` プロパティに `"g"` が含まれていない場合）。

解説
--

`String.prototype.matchAll` の実装自体は、正規表現がグローバルであるという余分な入力検証を除けば）非常にシンプルで、引数の文字列を最初の引数として `Symbol.matchAll` メソッドを呼び出すだけです。実際の実装は `RegExp.prototype[@@matchAll]()` から来ています。

例
-

### Regexp.prototype.exec() と matchAll()

`matchAll()` が JavaScript に追加される前は、 regexp.exec（および `/g` フラグ付きの正規表現）をループの中で呼び出すことですべての一致結果を取得することができました。

```js
const regexp = /foo[a-z]\*/g;
const str = "table football, foosball";
let match;

while ((match = regexp.exec(str)) !== null) {
  console.log(
    `Found ${match[0]} start=${match.index} end=${regexp.lastIndex}.`,
  );
}
// Found football start=6 end=14.
// Found foosball start=16 end=24.
```

`matchAll()` が使えるようになったことで、 `while` によるループと、`g` 付きの `exec` を避けることができます。代わりにイテレーターが取得できるので、`for...of`、配列スプレッド、`Array.from()` 構造と効率よく組み合わせることができます。

```js
const regexp = /foo[a-z]\*/g;
const str = "table football, foosball";
const matches = str.matchAll(regexp);

for (const match of matches) {
  console.log(
    `Found ${match[0]} start=${match.index} end=${
 match.index + match[0].length
 }.`,
  );
}
// Found football start=6 end=14.
// Found foosball start=16 end=24.

// 一致したイテレーターは for...of の反復処理の後で利用不可になる
// 新しいイテレーターを作成するために matchAll を再度呼び出す
Array.from(str.matchAll(regexp), (m) => m[0]);
// [ "football", "foosball" ]
```

`matchAll` は、グローバル (`g`) フラグがない場合は例外が発生します。

```js
const regexp = /[a-c]/;
const str = "abc";
str.matchAll(regexp);
// TypeError
```

`matchAll` では内部的に `regexp` の複製を作成します。そのため `regexp.exec()` とは違って文字列をスキャンした際に `lastIndex` が変わることはありません。

```js
const regexp = /[a-c]/g;
regexp.lastIndex = 1;
const str = "abc";
Array.from(str.matchAll(regexp), (m) => `${regexp.lastIndex} ${m[0]}`);
// [ "1 b", "1 c" ]
```

しかし、これは `regexp.exec()` をループ内で使うのとは異なり、正規表現を進めたり戻したりするために `lastIndex` を変更することができないことを意味します。

### キャプチャリンググループへのより良いアクセス（String.prototype.match() との比較）

`matchAll` はキャプチャグループへのよりよいアクセスを実現します。

`match()` では、グローバル `g` フラグを使用するとキャプチャグループが無視されてしまいます。

```js
const regexp = /t(e)(st(\d?))/g;
const str = "test1test2";

str.match(regexp); // ['test1', 'test2']
```

`matchAll` を使えば簡単にキャプチャグループにアクセスできます。

```js
const array = [...str.matchAll(regexp)];

array[0];
// ['test1', 'e', 'st1', '1', index: 0, input: 'test1test2', length: 4]
array[1];
// ['test2', 'e', 'st2', '2', index: 5, input: 'test1test2', length: 4]
```

### matchAll() を RegExp ではない @@matchAll を実装しているオブジェクトで使用

オブジェクトに `Symbol.matchAll` メソッドがあれば、それをカスタムマッチャーとして使うことができます。`Symbol.matchAll` の返値は `matchAll()` の返値となる。

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

str.matchAll({
  [Symbol.matchAll](str) {
    return [["Yes, it's interesting."]];
  },
}); // [["Yes, it's interesting."]] を返す
```

仕様書
---

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

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

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

関連情報
----

* `String.prototype.matchAll` のポリフィル (`core-js`)
* `String.prototype.match()`
* JavaScript での正規表現の使用
* キャプチャグループ
* `RegExp`
* `RegExp.prototype.exec()`
* `RegExp.prototype.test()`
* `RegExp.prototype[@@matchAll]()`


String.prototype.endsWith() - JavaScript

String.prototype.endsWith()
===========================

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

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

構文
--

```js
endsWith(searchString)
endsWith(searchString, endPosition)
```

### 引数

`searchString`

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

`endPosition` 省略可

`searchString` が見つかると期待される末尾の位置（`searchString` の最後の文字 +1 のインデックス）です。既定値は `str.length` です。

### 返値

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

### 例外

`TypeError`

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

解説
--

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

例
-

### endsWith() の使用

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

console.log(str.endsWith("question.")); // true
console.log(str.endsWith("to be")); // false
console.log(str.endsWith("to be", 19)); // true
```

仕様書
---

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

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

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

関連情報
----

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


String.prototype.anchor() - JavaScript

String.prototype.anchor()
=========================

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

**`anchor()`** メソッドは、`<a>` 要素に name を付けたものに文字列を埋め込んだ文字列 (`<a name="...">str</a>`) を生成します。

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

HTML 仕様書では `<a>` 要素に `name` 属性を設定することを許容しなくなりましたので、このメソッドが生成するものは妥当なマークアップになりません。

構文
--

```js
anchor(name)
```

### 引数

`name`

`name` 値を表す文字列で、 `<a name="...">` 開始タグに入れられます。

### 返値

`<a name="name">` 開始タグで始まり（`name` の中の二重引用符は `"` で置き換え）、`str` のテキストが続き、 `</a>` 終了タグで終わる文字列です。

例
-

### anchor() の使用

```js
const myString = "Table of Contents";

document.body.innerHTML = myString.anchor("contents\_anchor");
```

以下の HTML が生成されます。

```html
<a name="contents\_anchor">Table of Contents</a>
```

仕様書
---

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

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

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

関連情報
----

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


String.prototype.substring() - JavaScript

String.prototype.substring()
============================

**`substring()`** メソッドは `string` の一部、開始インデックスから終了インデックスの手前まで、または終了インデックスが指定されなかった場合は文字列の最後までを返します。

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

構文
--

```js
substring(indexStart)
substring(indexStart, indexEnd)
```

### 引数

`indexStart`

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

`indexEnd` 省略可

返される部分文字列から除外される、最初の文字の位置です。

### 返値

与えられた文字列から抽出された区間を含む新しい文字列です。

解説
--

`substring()` は `indexStart` から `indexEnd` の直前までの文字を取り出します。特に、

* `indexEnd` が省略された場合、`substring()` は文字列の最後までの文字を取り出します。
* `indexStart` が `indexEnd` と等しい場合、 `substring()` は空の文字列を返します。
* `indexStart` が `indexEnd` より大きかった場合、 `substring()` は 2 つの引数が交換されたものとして実行されます。下記の例をご覧ください。

引数が `0` 未満、または `stringName.length` を超えた場合、それはそれぞれ `0` と `stringName.length` として扱われます。

いずれかの引数が `NaN` の場合、それは `0` として扱われます。

例
-

### substring() の使用

以下の例では `substring()` を使用して、 `'Mozilla'` という文字列から文字を取り出して表示します。

```js
const anyString = "Mozilla";

console.log(anyString.substring(0, 1)); // 'M'
console.log(anyString.substring(1, 0)); // 'M'

console.log(anyString.substring(0, 6)); // 'Mozill'

console.log(anyString.substring(4)); // 'lla'
console.log(anyString.substring(4, 7)); // 'lla'
console.log(anyString.substring(7, 4)); // 'lla'

console.log(anyString.substring(0, 7)); // 'Mozilla'
console.log(anyString.substring(0, 10)); // 'Mozilla'
```

### substring() と length プロパティの使用

次の例では `substring()` メソッドと `length` プロパティを使用して、特定の文字列の最後の文字を抜き出しています。この方法では、上記の例と同じようあなたが最初と最後の位置を知っている必要がないこと考えると、覚えやすいかもしれません。

```js
const text = "Mozilla";

// 文字列の最後の 4 文字を取る
console.log(text.substring(text.length - 4)); // "illa" と表示

// 文字列の最後の 5 文字を取る
console.log(text.substring(text.length - 5)); // "zilla" と表示
```

### substring() と substr() の違い

`substring()` メソッドと `substr()` メソッドとの間には微妙な違いがあるので、混乱しないように注意してください。

* `substr()` の 2 つの引数は `start` および `length` であるのに対し、`substring()` の場合は `start` および `end` です。
* `substr()` の `start` インデックスは負の数の場合に文字列の末尾から逆に進むのに対し、`substring()` は `0` に丸められます。
* `substr()` で負の長さを指定すると 0 と見なされますが、`substring()` で `end` が `start` よりも小さい場合は 2 つのインデックスが交換されます。

さらに、 `substr()` は ECMAScript の古い機能とみなされており、将来のバージョンでは削除される可能性があるため、できれば使用しないのが最良です。

```js
const text = "Mozilla";
console.log(text.substring(2, 5)); // "zil"
console.log(text.substr(2, 3)); // "zil"
```

### substring() と slice() の違い

`substring()` メソッドと `slice()` メソッドはほぼ同じですが、特に負の数の引数の扱いについて、いくつかの微妙な違いがあります。

`substring()` メソッドは `indexStart` が `indexEnd` よりも大きい場合に 2 つの引数を交換するので、文字列が返されます。`slice()` メソッドはこの場合には空文字列を返します。

```js
const text = "Mozilla";
console.log(text.substring(5, 2)); // "zil"
console.log(text.slice(5, 2)); // ""
```

どちらかまたは両方の引数が負の数または `NaN` であった場合、 `substring()` メソッドはこれらを `0` として扱います。

```js
console.log(text.substring(-5, 2)); // "Mo"
console.log(text.substring(-5, -2)); // ""
```

`slice()` も `NaN` の引数を `0` として扱いますが、負の数を指定した場合は、文字列の末尾からの文字数で位置を探します。

```js
console.log(text.slice(-5, 2)); // ""
console.log(text.slice(-5, -2)); // "zil"
```

負の数を使用した例は `slice()` のページをご覧ください。

### 文字列内の部分文字列の置き換え

次の例は、文字列内の部分文字列を置き換えます。これは単独の文字と部分文字列の両方を置き換えます。例の最後にある関数呼び出しは、`Brave New World` という文字列を `Brave New Web` に置き換えます。

```js
// fullS という文字列内で oldS を newS に置き換えます。
function replaceString(oldS, newS, fullS) {
  for (let i = 0; i < fullS.length; ++i) {
    if (fullS.substring(i, i + oldS.length) === oldS) {
      fullS =
        fullS.substring(0, i) +
        newS +
        fullS.substring(i + oldS.length, fullS.length);
    }
  }
  return fullS;
}

replaceString("World", "Web", "Brave New World");
```

なお、これは `oldS` が `newS` の部分文字列である場合に無限ループに陥ります。 — 例えば、 '`World`' を '`OtherWorld`' で置き換える場合などです。

置き換えるのにより良い方法は以下の通りです。

```js
function replaceString(oldS, newS, fullS) {
  return fullS.split(oldS).join(newS);
}
```

上述のコードは、 substring の操作の例を提供します。部分文字列を置き換える必要があるとき、多くの場合 `String.prototype.replace()` を使用します。

仕様書
---

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

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

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

関連情報
----

* `String.prototype.substr()`
* `String.prototype.slice()`


String.prototype.lastIndexOf() - JavaScript

String.prototype.lastIndexOf()
==============================

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

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

構文
--

```js
lastIndexOf(searchString)
lastIndexOf(searchString, position)
```

### 引数

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

`searchString` が最後に出現した位置です。見つからなかった場合は、 `-1` になります。

解説
--

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

```js
"canal".lastIndexOf("a"); // 3 を返す
"canal".lastIndexOf("a", 2); // 1 を返す
"canal".lastIndexOf("a", 0); // -1 を返す
"canal".lastIndexOf("x"); // -1 を返す
"canal".lastIndexOf("c", -5); // 0 を返す
"canal".lastIndexOf("c", 0); // 0 を返す
"canal".lastIndexOf(""); // 5 を返す
"canal".lastIndexOf("", 2); // 2 を返す
```

### 大文字小文字の区別

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

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

例
-

### indexOf() と lastIndexOf() の使用

以下の例は、 `indexOf()` と `lastIndexOf()` を使用して文字列 `"Brave, Brave New World"` の中の値の位置を示します。

```js
const anyString = "Brave, Brave New World";

console.log(anyString.indexOf("Brave")); // 0
console.log(anyString.lastIndexOf("Brave")); // 7
```

仕様書
---

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

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

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

関連情報
----

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


String.prototype.toLowerCase() - JavaScript

String.prototype.toLowerCase()
==============================

**`toLowerCase()`** メソッドは、呼び出す文字列の値を小文字に変換して返します。

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

構文
--

```js
toLowerCase()
```

### 返値

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

解説
--

`toLowerCase()` メソッドは、小文字に変換された文字列の値を返します。`toLowerCase()` メソッドは、文字列 `str` 自身の値には影響を与えません。

例
-

### `toLowerCase()` メソッドの使用

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

仕様書
---

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

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

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

関連情報
----

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


String.prototype.toLocaleLowerCase() - JavaScript

String.prototype.toLocaleLowerCase()
====================================

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

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

構文
--

```js
toLocaleLowerCase()
toLocaleLowerCase(locales)
```

### 引数

`locales` 省略可

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

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

### 返値

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

解説
--

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

例
-

### toLocaleLowerCase() の使用

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

"\u0130".toLocaleLowerCase("tr") === "i"; // true
"\u0130".toLocaleLowerCase("en-US") === "i"; // false

const locales = ["tr", "TR", "tr-TR", "tr-u-co-search", "tr-x-turkish"];
"\u0130".toLocaleLowerCase(locales) === "i"; // true
```

仕様書
---

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

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

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

関連情報
----

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


String.prototype.normalize() - JavaScript

String.prototype.normalize()
============================

**`normalize()`** メソッドは、文字列の Unicode 正規化形式を返します。

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

構文
--

```js
normalize()
normalize(form)
```

### 引数

`form` 省略可

Unicode 正規化形式を示す `"NFC"`, `"NFD"`, `"NFKC"`, `"NFKD"` のうちの一つです。省略されたり `undefined` であったりした場合は `"NFC"` が使われます。

これらの値には以下の意味があります。

`"NFC"`

正規化形式 C。正準等価性によって分解され、再度合成される。

`"NFD"`

正規化形式 D。正準等価性によって分解される。

`"NFKC"`

正規化形式 KC。互換等価性によって分解され、正準等価性によって再度合成される。

`"NFKD"`

正規化形式 KD。互換等価性によって分解される。

### 返値

与えられた文字列の Unicode 正規化形式を含む文字列です。

### 発生する例外

`RangeError`

`form` が上記で指定された値のいずれでもない場合は `RangeError` が発生します。

解説
--

Unicode は個々の文字に対して、「コードポイント」と呼ばれる固有の値を割り当てています。例えば、 `"A"` のコードポイントは U+0041 が割り当てられています。しかし、複数のコードポイントや、コードポイントの一連の並びが、同一の抽象文字を表すことがあります。 — 例えば、`"ñ"` の文字は以下のいずれかで表すことができます。

* 単一のコードポイント U+00F1
* `"n"` のコードポイント (U+006E) に続いて組み合わせチルダのコードポイント (U+0303)

```js
const string1 = "\u00F1";
const string2 = "\u006E\u0303";

console.log(string1); // ñ
console.log(string2); // ñ
```

しかし、コードポイントが異なるため、文字列の比較ではこれらが同じものとして扱われません。また、それぞれのコードポイントの数が異なるため、長さすら異なります。

```js
const string1 = "\u00F1"; // ñ
const string2 = "\u006E\u0303"; // ñ

console.log(string1 === string2); // false
console.log(string1.length); // 1
console.log(string2.length); // 2
```

`normalize()` メソッドは、同じ文字を表すコードポイントのすべての並びを共通の正規化された形式に文字列を変換することで、この問題を解決するのに役立ちます。正規化の方法は主に 2 つがあり、1 つは**正準等価性**に、もう 1 つは**互換等価性**に基づきます。

### 正準等価性による正規化

Unicode では、2 つのコードポイントの並びが同じ抽象文字を表していれば、正準等価性があるとされ、常に同じ外見表示と動作をするべきです（例えば、並べ替えで常に同じものとして扱うべきです）。

`normalize()` を `"NFD"` または `"NFC"` の引数で使用することで、すべてが正準等価な文字列となる文字列の形を生成することができます。以下の例では、文字 `"ñ"` の二つの表現を正規化しています。

```js
let string1 = "\u00F1"; // ñ
let string2 = "\u006E\u0303"; // ñ

string1 = string1.normalize("NFD");
string2 = string2.normalize("NFD");

console.log(string1 === string2); // true
console.log(string1.length); // 2
console.log(string2.length); // 2
```

#### 合成形と分解形

`"NFD"` で正規化された形の長さが `2` であることに注意してください。`"NFD"` は**分解**正規形を生成するからであり、これは単一のコードポイントを複数のコードポイントの組み合わせに分解します。 `"ñ"` の分解正規形は `"\u006E\u0303"` です。

`"NFC"` を指定すると**合成**正規形を取得することができ、これは複数のコードポイントを可能な限り単一のコードポイントで置き換えます。 `"ñ"` の合成正規形は `"\u00F1"` です。

```js
let string1 = "\u00F1"; // ñ
let string2 = "\u006E\u0303"; // ñ

string1 = string1.normalize("NFC");
string2 = string2.normalize("NFC");

console.log(string1 === string2); // true
console.log(string1.length); // 1
console.log(string2.length); // 1
console.log(string2.codePointAt(0).toString(16)); // f1
```

### 互換正規形

Unicode では、2 つのコードポイントの並びが、同じ抽象文字を表す場合に互換性があり、場合によっては同じ文字として扱われるべきですが、すべてのアプリケーションでそうするべきとは限らないことがあります。

すべての正準等価な並びは互換といえますが、逆はそうとはいえません。

例を挙げます。

* コードポイント U+FB00 は合字 `"ﬀ"` を表します。これは 2 つの連続したコードポイント U+0066 (`"ff"`) と互換性があります。
* コードポイント U+24B9 は、記号 `"Ⓓ"` を表します。
 これは U+0044 のコードポイント (`"D"`) と互換性があります。

場面によっては（並べ替えなど）同じものとしてみなされるべきであり、その他の場合は（外見など）同じとするべきではないので、これらは厳密には等しくありません。

`normalize()` を `"NFKD"` または `"NFKC"` を引数にして使用することで、互換等価な文字列が同じになる形の文字列を生成することができます。

```js
let string1 = "\uFB00";
let string2 = "\u0066\u0066";

console.log(string1); // ﬀ
console.log(string2); // ff
console.log(string1 === string2); // false
console.log(string1.length); // 1
console.log(string2.length); // 2

string1 = string1.normalize("NFKD");
string2 = string2.normalize("NFKD");

console.log(string1); // ff <- 外見が変わった
console.log(string2); // ff
console.log(string1 === string2); // true
console.log(string1.length); // 2
console.log(string2.length); // 2
```

互換等価な正規化を適用する際には、正規化された形式がすべてのアプリケーションに適しているとは限らないので、文字列で何をしようとしているのかを考慮することが重要です。上の例では、ユーザーが `"f"` を検索すれば文字列を見つけることができるので、正規化は検索に適しています。しかし、視覚的な表現が異なるため、表示には適切ではないかもしれません。

正準等価な正規化のように、分解形または合成形の互換等価形式は、それぞれ `"NFKD"` または `"NFKC"` を渡すことで問い合わせることができます。

例
-

### normalize() の使用

```js
// 最初の文字列

// U+1E9B: LATIN SMALL LETTER LONG S WITH DOT ABOVE
// U+0323: COMBINING DOT BELOW
const str = "\u1E9B\u0323";

// 正準合成形 (NFC)

// U+1E9B: LATIN SMALL LETTER LONG S WITH DOT ABOVE
// U+0323: COMBINING DOT BELOW
str.normalize("NFC"); // '\u1E9B\u0323'
str.normalize(); // same as above

// 正準分解形 (NFD)

// U+017F: LATIN SMALL LETTER LONG S
// U+0323: COMBINING DOT BELOW
// U+0307: COMBINING DOT ABOVE
str.normalize("NFD"); // '\u017F\u0323\u0307'

// 互換合成形 (NFKC)

// U+1E69: LATIN SMALL LETTER S WITH DOT BELOW AND DOT ABOVE
str.normalize("NFKC"); // '\u1E69'

// 互換分解形 (NFKD)

// U+0073: LATIN SMALL LETTER S
// U+0323: COMBINING DOT BELOW
// U+0307: COMBINING DOT ABOVE
str.normalize("NFKD"); // '\u0073\u0323\u0307'
```

仕様書
---

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

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

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

関連情報
----

* Unicode Standard Annex #15, Unicode Normalization Forms
* Unicode の等価性


String.prototype.padStart() - JavaScript

String.prototype.padStart()
===========================

**`padStart()`** メソッドは、結果の文字列が指定した長さになるように、現在の文字列を他の文字列で（必要に応じて繰り返して）延長します。延長は、現在の文字列の先頭から適用されます。

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

構文
--

```js
padStart(targetLength)
padStart(targetLength, padString)
```

### 引数

`targetLength`

現在の文字列の延長後に返される文字列の長さです。この値が現在の文字列の長さよりも短い場合、文字列がそのまま返されます。

`padString` 省略可

 現在の文字列を延長するための文字列です。 `padString` が `targetLength` より長い場合は、右からその長さ分が切り捨てられます。
 この引数の既定値は、Unicode の「空白」文字 (U+0020) です。

### 返値

現在の文字列の先頭に `padString` が適用された、指定された `targetLength` の長さの `String` です。

例
-

### 基本的な例

```js
"abc".padStart(10); // " abc"
"abc".padStart(10, "foo"); // "foofoofabc"
"abc".padStart(6, "123465"); // "123abc"
"abc".padStart(8, "0"); // "00000abc"
"abc".padStart(1); // "abc"
```

### 数値を固定長文字列へ変換

```js
// JavaScript version of: (unsigned)
// printf "%0\*d" width num
function leftFillNum(num, targetLength) {
  return num.toString().padStart(targetLength, "0");
}

const num = 123;
console.log(leftFillNum(num, 5)); // "00123"
```

仕様書
---

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

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

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

関連情報
----

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