Math.atan() - JavaScript

Math.atan()
===========

**`Math.atan()`** 関数は、引数として与えた数値のアークタンジェントをラジアン単位で返します。

Math.atan
(
x
)

=
arctan
(
x
)
=
 the unique

y
∊

[

-

π
2

;

π
2

]

such that

tan
(
y
)
=
x

\mathtt{\operatorname{Math.atan}(x)} = \arctan(x) = \text{ the unique } ; y \in \left[-\frac{\pi}{2}; \frac{\pi}{2}\right] , \text{such that} ; \tan(y) = x

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

構文
--
```

Math.atan(x)
```

### 引数

`x`

数値です。

### 返値

与えられた数値のアークタンジェント (ラジアン単位) です。

解説
--

`Math.atan()` メソッドは

-

π
2

-\frac{\pi}{2}

 から

π
2

\frac{\pi}{2}

 までのラジアンの数値を返します。

`atan()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.atan()` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.atan() の使用

```js
Math.atan(1); // 0.7853981633974483
Math.atan(0); // 0
Math.atan(-0); // -0

Math.atan(Infinity); // 1.5707963267948966
Math.atan(-Infinity); // -1.5707963267948966

// The angle that the line [(0,0);(x,y)] forms with the x-axis in a Cartesian coordinate system
Math.atan(y / x);
```

様式上の理由から **±**`Infinity` の使用を避けたいと思うことがあるかもしれません。その場合、 `Math.atan2()` を第二引数を `0` としてを使うとよりよいかもしれません。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.atan |

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

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

関連情報
----

* `Math.acos()`
* `Math.asin()`
* `Math.atan2()`
* `Math.cos()`
* `Math.sin()`
* `Math.tan()`


Math.cos() - JavaScript

Math.cos()
==========

**`Math.cos()`** は静的関数で、指定された角度の余弦 (コサイン) を返します。ここで角度はラジアンで指定します。この値は

length

adjacent

length

hypotenuse

 です。

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

構文
--
```

Math.cos(x)
```

### 引数

`x`

余弦を返すラジアンの角度。

### 返値

与えられた数値の余弦 (コサイン) です。

解説
--

`Math.cos()` メソッドはラジアンで指定された角度の余弦 (コサイン) を表す -1 から 1 までの範囲の数値を表します。

`cos()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.cos()` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.cos() の使用

```js
Math.cos(0); // 1
Math.cos(1); // 0.5403023058681398

Math.cos(Math.PI); // -1
Math.cos(2 \* Math.PI); // 1
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.cos |

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

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

関連情報
----

* `Math.acos()`
* `Math.asin()`
* `Math.atan()`
* `Math.atan2()`
* `Math.sin()`
* `Math.tan()`


Math.imul() - JavaScript

Math.imul()
===========

**`Math.imul()`** 関数は、2 つの引数で C 言語風の 32 ビット乗算を行った結果を返します。

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

構文
--
```

var product = Math.imul(a, b);
```

### 引数

`a`

第一の数値。

`b`

第二の数値。

### 返値

与えられた引数で C 言語風の 32 ビット乗算を行った結果です。

解説
--

`Math.imul()` で C 言語と同様のの意味を持った 32 ビット乗算を行うことができます。この機能は Emscripten などのプロジェクトに有効です。

`imul()` は `Math` の静的メソッドなので、常に `Math.imul()` として使用し、自分で `Math` オブジェクトを生成してそのメソッドとして使用しないでください。 (`Math` にはコンストラクターがありません)。

通常の JavaScript の浮動小数点数を imul で使用すると、性能が低下します。これは、乗算のために浮動小数点から整数に変換し、乗算された整数を浮動小数点に変換するというコストのかかる作業があるからです。 imul が存在する理由は、 (今のところ) たった 1 つの状況では imul の方が高速だからです。それは AsmJS です。 AsmJS は JIST オプティマイザーが JavaScript で内部整数をより簡単に実装できるようにします。内部的に整数として格納されている 2 つの数値を imul で乗算すること (これは AsmJS でのみ可能です) は、 Math.imul が現在のブラウザーで性能を発揮する可能性がある唯一の潜在的な状況です。

例
-

### Math.imul() の使用

```js
Math.imul(2, 4); // 8
Math.imul(-1, 8); // -8
Math.imul(-2, -2); // 4
Math.imul(0xffffffff, 5); // -5
Math.imul(0xfffffffe, 5); // -10
```

ポリフィル
-----

これは次の関数でエミュレートすることができます。

```js
if (!Math.imul)
  Math.imul = function (a, b) {
    var aHi = (a >>> 16) & 0xffff;
    var aLo = a & 0xffff;
    var bHi = (b >>> 16) & 0xffff;
    var bLo = b & 0xffff;
    // the shift by 0 fixes the sign on the high part
    // the final |0 converts the unsigned value into a signed value
    return (aLo \* bLo + (((aHi \* bLo + aLo \* bHi) << 16) >>> 0)) | 0;
  };
```

しかし、このポリフィルが使われるであろうブラウザーは、 JavaScript の内部整数型で最適化されておらず、すべての数値に浮動小数点を使用している可能性が高いため、次の関数の方が性能が高くなります。

```js
if (!Math.imul)
  Math.imul = function (opA, opB) {
    opB |= 0; // ensure that opB is an integer. opA will automatically be coerced.
    // floating points give us 53 bits of precision to work with plus 1 sign bit
    // automatically handled for our convienence:
    // 1. 0x003fffff /\*opA & 0x000fffff\*/ \* 0x7fffffff /\*opB\*/ = 0x1fffff7fc00001
    // 0x1fffff7fc00001 < Number.MAX\_SAFE\_INTEGER /\*0x1fffffffffffff\*/
    var result = (opA & 0x003fffff) \* opB;
    // 2. We can remove an integer coersion from the statement above because:
    // 0x1fffff7fc00001 + 0xffc00000 = 0x1fffffff800001
    // 0x1fffffff800001 < Number.MAX\_SAFE\_INTEGER /\*0x1fffffffffffff\*/
    if (opA & 0xffc00000 /\*!== 0\*/) result += ((opA & 0xffc00000) \* opB) | 0;
    return result | 0;
  };
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.imul |

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

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

関連情報
----

* Emscripten


Math.random() - JavaScript

Math.random()
=============

**`Math.random()`** 関数は、 0 以上 1 未満 (0 は含むが、 1 は含まない) の範囲で浮動小数点の擬似乱数を返します。その範囲ではほぼ均一な分布で、ユーザーは範囲の拡大をすることができます。実装側で乱数生成アルゴリズムの初期シードを選択します。ユーザーが初期シードを選択、またはリセットすることは出来ません。

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

**メモ:** `Math.random()` の提供する乱数は、暗号に使用可能な安全性を備えて*いません*。セキュリティに関連する目的では使用しないでください。代わりに Web Crypto API (より具体的には `window.crypto.getRandomValues()` メソッド) を使用してください。

構文
--
```

Math.random()
```

### 返値

`0` (含む) から 1 (含まない) までの擬似乱数である浮動小数点数です。

例
-

JavaScript における数値は、IEEE 754 浮動小数点での round-to-nearest-even を行うため、以下の関数の値域が ( `Math.random()` 自体の値域が正しくても) 厳密ではないことに注意してください。非常に大きい境界値 (253 以上) のうち*極めて*稀な数値で、通常なら返されないはずの上限値が出力されてしまうことがあり得ます。

### 0 以上 1 未満の乱数を得る

```js
function getRandom() {
  return Math.random();
}
```

### 2 つの値の間の乱数を得る

この例は指定した値の間の乱数を返します。返値は `min` 以上、 `max` 未満です。

```js
function getRandomArbitrary(min, max) {
  return Math.random() \* (max - min) + min;
}
```

### 2 つの値の間のランダムな整数を得る

この例は指定した値の間のランダムな整数を返します。返値は `min` 以上 (`min` が整数でない場合、 `min` より大きい次の整数以上)、 `max` 未満です。

```js
function getRandomInt(min, max) {
  min = Math.ceil(min);
  max = Math.floor(max);
  return Math.floor(Math.random() \* (max - min) + min); //The maximum is exclusive and the minimum is inclusive
}
```

**メモ:** `Math.round()` を使う方が魅力的かもしれませんが、その場合は乱数が不均一な分布に従うことになるので、ユーザーのニーズに合わないかもしれません。

### 包括的に 2 つの値の間のランダムな整数を得る

上記の `getRandomInt()` 関数が返す乱数の範囲は `min` を含みますが、`max` は除外されます。 `min` も `max` も範囲に含まれた乱数を生成したいなら、以下の `getRandomIntInclusive()` 関数を使うといいでしょう。

```js
function getRandomIntInclusive(min, max) {
  min = Math.ceil(min);
  max = Math.floor(max);
  return Math.floor(Math.random() \* (max - min + 1) + min); //The maximum is inclusive and the minimum is inclusive
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.random |

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

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

関連情報
----

* `window.crypto.getRandomValues()`


Math.asin() - JavaScript

Math.asin()
===========

**`Math.asin()`** 関数は、引数として与えた数値の逆正弦 (アークサイン) をラジアン単位で返します。

∀
x
∊
[

-
1

;
1
]
,

Math.asin
(
x
)

=
arcsin
(
x
)
=
 the unique

y
∊

[

-

π
2

;

π
2

]

such that

sin
(
y
)
=
x

\forall x \in [{-1};1],;\mathtt{\operatorname{Math.asin}(x)} = \arcsin(x) = \text{ the unique } ; y \in \left[-\frac{\pi}{2}; \frac{\pi}{2}\right] , \text{such that} ; \sin(y) = x

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

構文
--
```

Math.asin(x)
```

### 引数

`x`

数値です。

### 返値

与えられた数値が **-1** から **1** までの場合、その逆正弦 (アークサイン) をラジアン単位で返します。さもなければ、 `NaN` を返します。

解説
--

`Math.asin()` メソッドは、 `-1` から `1` までの *x* に対して、

-

π
2

-\frac{\pi}{2}

 から

π
2

\frac{\pi}{2}

 までのラジアンの数値を返します。 *x* の値がこの範囲を越えている場合、このメソッドは `NaN` を返します。

`asin()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.asin()` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.asin() の使用

```js
Math.asin(-2); // NaN
Math.asin(-1); // -1.5707963267948966 (-pi/2)
Math.asin(0); // 0
Math.asin(0.5); // 0.5235987755982989
Math.asin(1); // 1.5707963267948966 (pi/2)
Math.asin(2); // NaN
```

値が -1 未満か 1 より大きい数値の場合、`Math.asin()` は `NaN` を返します。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.asin |

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

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

関連情報
----

* `Math.acos()`
* `Math.atan()`
* `Math.atan2()`
* `Math.cos()`
* `Math.sin()`
* `Math.tan()`


Math.abs() - JavaScript

Math.abs()
==========

**`Math.abs()`** 関数は、数値の絶対値を返します。

Math.abs
(
x
)

=

|
x
|

=

{

x

if

x
>
0

0

if

x
=
0

-
x

if

x
<
0

{\mathtt{\operatorname{Math.abs}(z)}} = {|z|} = \begin{cases} x & \text{if} \quad x \geq 0 \ x & \text{if} \quad x < 0 \end{cases}

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

構文
--
```

Math.abs(x)
```

### 引数

`x`

数値です。

### 返値

与えられた数値の絶対値。

解説
--

`abs()` は `Math` オブジェクトの静的メソッドなので、 `Math` オブジェクトを生成してメソッドとして使用するのではなく、常に `Math.abs()` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.abs() の動作

空のオブジェクト、複数のメンバーを持つ配列、数値でない文字列、 `undefined`、 空の変数を渡すと、 `NaN` を返します。 `null` を渡すと空文字列を返し、空の配列は 0 を返します。

```js
Math.abs("-1"); // 1
Math.abs(-2); // 2
Math.abs(null); // 0
Math.abs(""); // 0
Math.abs([]); // 0
Math.abs([2]); // 2
Math.abs([1, 2]); // NaN
Math.abs({}); // NaN
Math.abs("string"); // NaN
Math.abs(); // NaN
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.abs |

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

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

関連情報
----

* `Math.ceil()`
* `Math.floor()`
* `Math.round()`
* `Math.sign()`
* `Math.trunc()`


Math.acos() - JavaScript

Math.acos()
===========

**`Math.acos()`** 関数は、引数として与えた数値の逆余弦 (アークコサイン) をラジアン単位で返します。

∀
x
∊
[

-
1

;
1
]
,

Math.acos
(
x
)

=
arccos
(
x
)
=
 the unique

y
∊
[
0
;
π
]

such that

cos
(
y
)
=
x

\forall x \in [{-1};1],;\mathtt{\operatorname{Math.acos}(x)} = \arccos(x) = \text{ the unique } ; y \in [0; \pi] , \text{such that} ; \cos(y) = x

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

構文
--
```

Math.acos(x)
```

### 引数

`x`

コサインを表す数値で、 `x` は `-1` と `1` の間です。

### 返値

与えられた数値が `-1` から `1` までの場合、その逆余弦 (アークコサイン) をラジアン単位で返します。それ以外の場合は `NaN` を返します。

解説
--

`Math.acos()` メソッドは、-1 から 1 までの `x` に対して、0 から π までのラジアンの数値を返します。`x` の値がこの範囲を越えている場合、このメソッドは `NaN` を返します。

`acos()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.acos()` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.acos() の使用

```js
Math.acos(-2); // NaN
Math.acos(-1); // 3.141592653589793
Math.acos(0); // 1.5707963267948966
Math.acos(0.5); // 1.0471975511965979
Math.acos(1); // 0
Math.acos(2); // NaN
```

値が -1 未満か 1 より大きい数値の場合、`Math.acos()` は `NaN` を返します。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.acos |

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

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

関連情報
----

* `Math.asin()`
* `Math.atan()`
* `Math.atan2()`
* `Math.cos()`
* `Math.sin()`
* `Math.tan()`


Math.fround() - JavaScript

Math.fround()
=============

**`Math.fround()`** 関数は、ある `Number` を表す最も近い32ビット単精度浮動小数点数を返します。

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

構文
--
```

var singleFloat = Math.fround(doubleFloat);
```

### 引数

`doubleFloat`

`Number`。この引数が異なる方であった場合は、数値に変換されるか、変換できなければ `NaN` になります。

### 返値

与えられた値を表す最も近い 32 ビット単精度浮動小数点数です。

解説
--

JavaScript は内部的に 64 ビットの倍精度浮動小数点数を使用しており、非常に高い精度を提供しています。しかし、例えば `Float32Array` から値を読み込む場合など 32 ビットの浮動小数点数を扱うことがあるかもしれません。これは混乱を招く可能性があります。 64 ビットの浮動小数点数と 32 ビットの浮動小数点数が等しいかどうかをチェックすると、一見同じように見える数値であっても失敗することがあります。

これを解決するには、 `Math.fround()` を使用して、 64 ビット浮動小数点数を 32 ビットの浮動小数点数にキャストすることができます。内部的には、 JavaScript は数値を 64 ビットの浮動小数点数として扱い続けますが、仮数の 23 番目のビットに「偶数への丸め」を実行し、それに続く仮数ビットをすべて 0 に設定します。数値が 32 ビットの浮動小数点数の範囲外の場合は、 `Infinity` または `-Infinity` が返されます。

`fround()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.fround()` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.fround() の使用

1.5 という数値は二進数で正確に表すことができ、32 ビットと 64 ビットとで同じになります。

```js
Math.fround(1.5); // 1.5
Math.fround(1.5) === 1.5; // true
```

しかし、 1.337 という数値は二進数では正確に表すことができず、32 ビットと 64 ビットとで異なります。

```js
Math.fround(1.337); // 1.3370000123977661
Math.fround(1.337) === 1.337; // false
```

2
150

2^150

 は 32 ビット浮動小数点では大きすぎるため、 `Infinity` が返されます。

```js
2 \*\* 150; // 1.42724769270596e+45
Math.fround(2 \*\* 150); // Infinity
```

引数が数値に変換できない場合、または非数 (`NaN`) であった場合、 `Math.fround()` は `NaN` を返します。

```js
Math.fround("abc"); // NaN
Math.fround(NaN); // NaN
```

ポリフィル
-----

これは `Float32Array` に対応している場合、次の関数でエミュレートできます。

```js
Math.fround =
  Math.fround ||
  (function (array) {
    return function (x) {
      return (array[0] = x), array[0];
    };
  })(new Float32Array(1));
```

古いブラウザーに対応するには、より遅いですが、次のものも利用できます。

```js
if (!Math.fround)
  Math.fround = function (arg) {
    arg = Number(arg);
    // Return early for ±0 and NaN.
    if (!arg) return arg;
    var sign = arg < 0 ? -1 : 1;
    if (sign < 0) arg = -arg;
    // Compute the exponent (8 bits, signed).
    var exp = Math.floor(Math.log(arg) / Math.LN2);
    var powexp = Math.pow(2, Math.max(-126, Math.min(exp, 127)));
    // Handle subnormals: leading digit is zero if exponent bits are all zero.
    var leading = exp < -127 ? 0 : 1;
    // Compute 23 bits of mantissa, inverted to round toward zero.
    var mantissa = Math.round((leading - arg / powexp) \* 0x800000);
    if (mantissa <= -0x800000) return sign \* Infinity;
    return sign \* powexp \* (leading - mantissa / 0x800000);
  };
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.fround |

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

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

関連情報
----

* `Math.round()`


Math.log10() - JavaScript

Math.log10()
============

**`Math.log10()`** 静的メソッドは、数値の 10 を底とした対数を返します。すなわち次の値です。

∀
x
>
0
,

𝙼𝚊𝚝𝚑.𝚕𝚘𝚐𝟷𝟶
(
𝚡
)

=

log
10

(
x
)
=
the unique
y
 such that

10
y

=
x

\forall x > 0,;\mathtt{\operatorname{Math.log10}(x)} = \log\_{10}(x) = \text{the unique } y \text{ such that } 10^y = x

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

構文
--

```js
Math.log10(x)
```

### 引数

`x`

0 以上の数値です。

### 返値

`x` の 10 を底とした対数です。 `x < 0` であった場合、 `NaN` を返します。

解説
--

`log10()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.log10()` として使用するようにしてください（`Math` はコンストラクターではありません）。

この関数は `Math.log(x) / Math.log(10)` と同等です。 `log10(e)` には定数 `Math.LOG10E` を使用してください (これは 1 / `Math.LN10` です。)

例
-

### Math.log10() の使用

```js
Math.log10(-2); // NaN
Math.log10(-0); // -Infinity
Math.log10(0); // -Infinity
Math.log10(1); // 0
Math.log10(2); // 0.3010299956639812
Math.log10(100000); // 5
Math.log10(Infinity); // Infinity
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.log10 |

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

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

関連情報
----

* `Math.log10` のポリフィル (`core-js`)
* `Math.exp()`
* `Math.log()`
* `Math.log1p()`
* `Math.log2()`
* `Math.pow()`


Math.acosh() - JavaScript

Math.acosh()
============

**`Math.acosh()`** 関数は、数値の双曲線余弦 (ハイパーボリックアークコサイン) を返します。

∀
x
≥
1
,

Math.acosh
(
x
)

=
arcosh
(
x
)
=
 the unique

y
≥
0

such that

cosh
(
y
)
=
x

\forall x \geq 1, \mathtt{\operatorname{Math.acosh}(x)} = \operatorname{arcosh}(x) = \text{ the unique } ; y \geq 0 ; \text{such that} ; \cosh(y) = x

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

構文
--
```

Math.acosh(x)
```

### 引数

`x`

数値。

### 返値

与えられた数値の双曲線余弦 (ハイパーボリックアークコサイン) です。数値が **1** 未満であれば、 `NaN` になります。

解説
--

`acosh()` は `Math` の静的メソッドであるため、作成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.acosh()` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.acosh() の使用

```js
Math.acosh(-1); // NaN
Math.acosh(0); // NaN
Math.acosh(0.5); // NaN
Math.acosh(1); // 0
Math.acosh(2); // 1.3169578969248166
```

1 未満の値に対しては、 `Math.acosh()` は `NaN` を返します。

ポリフィル
-----

x
≥
1

x \geq 1

に対して、

arcosh
(
x
)
=
ln

(

x
+

x
2

-
1

)

\operatorname {arcosh} (x) = \ln \left(x + \sqrt{x^{2} - 1} \right)

 になり、次の関数でエミュレートできます。

```js
Math.acosh =
  Math.acosh ||
  function (x) {
    return Math.log(x + Math.sqrt(x \* x - 1));
  };
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.acosh |

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

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

関連情報
----

* `Math.asinh()`
* `Math.atanh()`
* `Math.cosh()`
* `Math.sinh()`
* `Math.tanh()`


Math.sin() - JavaScript

Math.sin()
==========

**`Math.sin()`** 関数は、引数として与えた数の正弦 (サイン) を返します。

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

構文
--
```

Math.sin(x)
```

### 引数

`x`

数値 (ラジアンで指定)。

### 返値

指定された数値の正弦 (サイン) です。

解説
--

`Math.sin()` メソッドはラジアンで指定された角度の正弦 (サイン) を表す -1 から 1 までの範囲の数値を表します。

`sin()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.sin()` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.sin() の使用

```js
Math.sin(0); // 0
Math.sin(1); // 0.8414709848078965

Math.sin(Math.PI / 2); // 1
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.sin |

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

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

関連情報
----

* `Math.acos()`
* `Math.asin()`
* `Math.atan()`
* `Math.atan2()`
* `Math.cos()`
* `Math.tan()`


Math.log() - JavaScript

Math.log()
==========

**`Math.log()`** 関数は、 (`e` を底とした) 数値の自然対数を返します。

∀
x
>
0
,

Math.log
(
x
)

=
ln
(
x
)
=
the unique

y

such that

e
y

=
x

\forall x > 0, \mathtt{\operatorname{Math.log}(x)} = \ln(x) = \text{the unique} ; y ; \text{such that} ; e^y = x

JavaScript の **`Math.log()`** 関数は、数学の *ln(x)* と同等です。

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

構文
--
```

Math.log(x)
```

### 引数

`x`

数値です。

### 返値

(`e` を底とした) 与えられた数値の自然対数です。数値が負の数であった場合、 `NaN` が返されます。

解説
--

`x` の値が 0 であった場合、返値は常に `-Infinity` です。

`x` の値が 0 未満であった場合、返値は常に `NaN` です。

`log()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.log()` として使用するようにしてください (`Math` はコンストラクターではありません)。

2 または 10 の自然対数が必要な場合は、定数の `Math.LN2` または `Math.LN10` を使用してください。 2 や 10 を底とした対数が必要な場合は、 `Math.log2()` または `Math.log10()` を使用してください。他の数を底とした対数が必要な場合は、下記の例にあるように Math.log(x) / Math.log(otherBase) を使用してください。事前に 1 / Math.log(otherBase) を計算しておいた方がいいかもしれません。

例
-

### Math.log() の使用

```js
Math.log(-1); // NaN, out of range
Math.log(0); // -Infinity
Math.log(1); // 0
Math.log(10); // 2.302585092994046
```

### 様々な底による Math.log() の使用

以下の関数は、 `x` を底とした `y` の対数を返します (すなわち

log
x

y

\log\_x y

)。

```js
function getBaseLog(x, y) {
  return Math.log(y) / Math.log(x);
}
```

`getBaseLog(10, 1000)` を実行すると、実際の答えが 3 であるのに対し、浮動小数点の丸め処理により近似値の `2.9999999999999996` を返します。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.log |

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

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

関連情報
----

* `Math.exp()`
* `Math.log1p()`
* `Math.log10()`
* `Math.log2()`
* `Math.pow()`


Math.SQRT1_2 - JavaScript

Math.SQRT1\_2
=============

**`Math.SQRT2`** プロパティは、 1/2 の平方根、約 0.707 を表します。

Math.SQRT1\_2

=

1
2

=

1

2

≈
0.707

\mathtt{\mi{Math.SQRT1\_2}} = \sqrt{\frac{1}{2}} = \frac{1}{\sqrt{2}} \approx 0.707

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

| `Math.SQRT1_2` のプロパティ属性 |
| --- |
| 書込可能 | 不可 |
| 列挙可能 | 不可 |
| 設定可能 | 不可 |

解説
--

`SQRT1_2` は `Math` オブジェクトの静的プロパティなので、 `Math` オブジェクトを生成してプロパティとして使用するのではなく、常に `Math.SQRT1_2` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.SQRT1\_2 の使用

以下の関数は 1 を 2 の平方根で割った値を返します。

```js
function getRoot1\_2() {
  return Math.SQRT1\_2;
}

getRoot1\_2(); // 0.7071067811865476
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.sqrt1\_2 |

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

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

関連情報
----

* `Math.pow()`
* `Math.sqrt()`


Math.cbrt() - JavaScript

Math.cbrt()
===========

**`Math.cbrt()`** 関数は、引数として与えた数の立方根を返します。すなわち、

M
a
t
h
.
c
b
r
t
(
x
)

=

x
3

=
the unique

y

such that

y
3

=
x

\mathtt{Math.cbrt(x)} = \sqrt[3]{x} = \text{the unique} ; y ; \text{such that} ; y^3 = x

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

構文
--
```

Math.cbrt(x)
```

### 引数

*x*

数値。

### 返値

与えられた数値の立方根です。

解説
--

`cbrt()` は `Math` の静的なメソッドであるため、自ら生成した `Math` オブジェクトのメソッドとしてではなく、常に、 `Math.cbrt()` として使用してください (`Math` はコンストラクターではありません)。

ポリフィル
-----

すべての

x
≥
0

x \geq 0

 に対して、

x
3

=

x

1
/
3

\sqrt[3]{x} = x^{1/3}

 が存在し、次の関数でエミュレートできます:

```js
if (!Math.cbrt) {
  Math.cbrt = (function (pow) {
    return function cbrt(x) {
      // ensure negative numbers remain negative:
      return x < 0 ? -pow(-x, 1 / 3) : pow(x, 1 / 3);
    };
  })(Math.pow); // localize Math.pow to increase efficiency
}
```

例
-

### Math.cbrt() の使用

```js
Math.cbrt(NaN); // NaN
Math.cbrt(-1); // -1
Math.cbrt(-0); // -0
Math.cbrt(-Infinity); // -Infinity
Math.cbrt(0); // 0
Math.cbrt(1); // 1
Math.cbrt(Infinity); // Infinity
Math.cbrt(null); // 0
Math.cbrt(2); // 1.2599210498948732
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.cbrt |

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

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

関連情報
----

* `Math.pow()`
* `Math.sqrt()`


Math.pow() - JavaScript

Math.pow()
==========

**`Math.pow()`** 関数は `base` を `exponent` 乗した値、つまり、`baseexponent` の値を返します。

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

構文
--
```

Math.pow(base, exponent)
```

### 引数

`base`

底となる数です。

`exponent`

`base` を累乗する指数です。

### 返値

指定された低を指定された指数だけ累乗したものを表す数値です。

解説
--

**`Math.pow()`** 関数は `base` の `exponent` 乗、すなわち `baseexponent` を返します。 `base` と `exponent` は 10 進数の数値です。

`pow()` は `Math` の静的メソッドなので、常に `Math.pow()` として使用し、自分で `Math` オブジェクトを生成してそのメソッドとして使用しないでください。 (`Math` にはコンストラクターがありません)。

例
-

### Math.pow() の使用

```js
// 単純
Math.pow(7, 2); // 49
Math.pow(7, 3); // 343
Math.pow(2, 10); // 1024
// 小数のべき乗
Math.pow(4, 0.5); // 2 (4 の平方根)
Math.pow(8, 1 / 3); // 2 (8 の立方根)
Math.pow(2, 0.5); // 1.4142135623730951 (2 の平方根)
Math.pow(2, 1 / 3); // 1.2599210498948732 (2 の立方根)
// 負の数のべき乗
Math.pow(7, -2); // 0.02040816326530612 (1/49)
Math.pow(8, -1 / 3); // 0.5
// 負の数の底
Math.pow(-7, 2); // 49 (2乗は正の数)
Math.pow(-7, 3); // -343 (3乗は負の数)
Math.pow(-7, 0.5); // NaN (負の数には実数の平方根がない)
// due to "even" and "odd" roots laying close to each other,
// and limits in the floating number precision,
// negative bases with fractional exponents always return NaN
Math.pow(-7, 1 / 3); // NaN
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.pow |

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

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

関連情報
----

* `Math.cbrt()`
* `Math.exp()`
* `Math.log()`
* `Math.sqrt()`
* べき乗演算子


Math.E - JavaScript

Math.E
======

**`Math.E`** プロパティはオイラー定数である、自然対数の底 (e)、約 2.718 を表します。

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

値
-

𝙼𝚊𝚝𝚑.𝙴
=
e
≈
2.718

\mathtt{\mi{Math.E}} = e \approx 2.718

| `Math.E` のプロパティ属性 |
| --- |
| 書込可能 | 不可 |
| 列挙可能 | 不可 |
| 設定可能 | 不可 |

解説
--

`E` は `Math` オブジェクトの静的プロパティなので、`Math` オブジェクトを生成してプロパティとして使用するのではなく、常に `Math.E` として使用するようにしてください（`Math` はコンストラクターではありません）。

例
-

### Math.E の使用

以下の関数は、e を返します。

```js
function getNapier() {
  return Math.E;
}

getNapier(); // 2.718281828459045
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.e |

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

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

関連情報
----

* `Math.exp()`
* `Math.log()`
* `Math.log1p()`


Math.LOG10E - JavaScript

Math.LOG10E
===========

**`Math.LOG10E`** は静的データプロパティで、 10 を底とした e の対数、約 0.434 を表します。

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

値
-

𝙼𝚊𝚝𝚑.𝙻𝙾𝙶𝟷𝟶𝙴
=

log
10

(
e
)
≈
0.434

\mathtt{\mi{Math.LOG10E}} = \log\_{10}(\mathrm{e}) \approx 0.434

| `Math.LOG10E` のプロパティ属性 |
| --- |
| 書込可能 | 不可 |
| 列挙可能 | 不可 |
| 設定可能 | 不可 |

解説
--

`LOG10E` は `Math` オブジェクトの静的プロパティなので、自分で作成した `Math` オブジェクトのプロパティとして使用するのではなく、常に `Math.LOG10E` として使用するようにしてください（`Math` はコンストラクターではありません）。

例
-

### Math.LOG10E の使用

以下の関数は、10 を底とした e の対数を返します。

```js
function getLog10e() {
  return Math.LOG10E;
}

getLog10e(); // 0.4342944819032518
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.log10e |

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

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

関連情報
----

* `Math.exp()`
* `Math.log()`
* `Math.log10()`


Math.round() - JavaScript

Math.round()
============

**`Math.round()`** 関数は、引数として与えた数を四捨五入して、もっとも近似の整数を返します。

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

構文
--
```

Math.round(x)
```

### 引数

`x`

数値

### 返値

与えられた値をもっとも近似の整数に四捨五入した値。

解説
--

引数の小数部分が 0.5 以上の場合、その引数は、次に大きい整数に切り上げられます。引数の小数部分が 0.5 未満の場合、その引数は、次に小さい整数に切り下げられます。小数部分が 0.5 である場合は、正の無限大の方向で次の整数に丸められます。**これは多くの言語の `round()` 関数と異なることに注意してください。この場合はたいてい、*0 から遠ざかる*次の整数に丸められます** (小数部分が 0.5 である負の値を四捨五入する場合に、結果が変わります)。

`round()` は `Math` オブジェクトの静的なメソッドなので、自ら生成した `Math` オブジェクトのメソッドとしてではなく、常に、`Math.round()` として使用するようにしてください (`Math` のコンストラクターはありません)。

例
-

### round の使用

```js
Math.round(20.49); // 20
Math.round(20.5); // 21
Math.round(42); // 42
Math.round(-20.5); // -20
Math.round(-20.51); // -21
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.round |

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

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

関連情報
----

* `Number.toPrecision()`
* `Number.toFixed()`
* `Math.abs()`
* `Math.ceil()`
* `Math.floor()`
* `Math.sign()`
* `Math.trunc()`


Math.tan() - JavaScript

Math.tan()
==========

**`Math.tan()`** 関数は、数値のタンジェントを返します。

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

構文
--
```

Math.tan(x)
```

### 引数

`x`

数値です。

### 返値

与えられた数値のタンジェントです。

解説
--

`Math.tan()` メソッドは、ある角度のタンジェントを表す数値を返します。

`tan()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.tan()` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.tan() の使用

```js
Math.tan(1); // 1.5574077246549023
```

`Math.tan()` 関数はラジアンを受け付けますが、角度で使用したほうが簡単な場合が多いので、次の関数は角度の値を受け付け、それをラジアンに変換してタンジェントを返します。

```js
function getTanDeg(deg) {
  var rad = (deg \* Math.PI) / 180;
  return Math.tan(rad);
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.tan |

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

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

関連情報
----

* `Math.acos()`
* `Math.asin()`
* `Math.atan()`
* `Math.atan2()`
* `Math.cos()`
* `Math.sin()`


Math.LN10 - JavaScript

Math.LN10
=========

**`Math.LN10`** プロパティは 10 の自然対数、およそ 2.302 を表します。

Math.LN10

=
ln
(
10
)
≈
2.302

\mathtt{\mi{Math.LN10}} = \ln(10) \approx 2.302

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

| `Math.LN10` のプロパティ属性 |
| --- |
| 書込可能 | 不可 |
| 列挙可能 | 不可 |
| 設定可能 | 不可 |

解説
--

`LN10` は `Math` オブジェクトの静的プロパティなので、 `Math` オブジェクトを生成してプロパティとして使用するのではなく、常に `Math.LN10` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.LN10 の使用

以下の関数は、10 の自然対数を返します。

```js
function getNatLog10() {
  return Math.LN10;
}

getNatLog10(); // 2.302585092994046
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.ln10 |

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

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

関連情報
----

* `Math.exp()`
* `Math.log()`
* `Math.log10()`


Math.SQRT2 - JavaScript

Math.SQRT2
==========

**`Math.SQRT2`** プロパティは、 2 の平方根、約 1.414 を表します。

Math.SQRT2

=

2

≈
1.414

\mathtt{\mi{Math.SQRT2}} = \sqrt{2} \approx 1.414

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

| `Math.SQRT2` のプロパティ属性 |
| --- |
| 書込可能 | 不可 |
| 列挙可能 | 不可 |
| 設定可能 | 不可 |

解説
--

`SQRT2` は `Math` オブジェクトの静的プロパティなので、 `Math` オブジェクトを生成してプロパティとして使用するのではなく、常に `Math.SQRT2` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.SQRT2 の使用

以下の関数は 2 の平方根を返します。

```js
function getRoot2() {
  return Math.SQRT2;
}

getRoot2(); // 1.4142135623730951
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.sqrt2 |

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

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

関連情報
----

* `Math.pow()`
* `Math.sqrt()`


Math.hypot() - JavaScript

Math.hypot()
============

**`Math.hypot()`** 関数は、各引数の二乗の合計値の平方根を返します。

Math.hypot
(

v
1

,

v
2

,
…
,

v
n

)

=

∑

i
=
1

n

v
i
2

=

v
1
2

+

v
2
2

+
…
+

v
n
2

\mathtt{\operatorname{Math.hypot}(v

*1, v\_2, \dots, v\_n)} = \sqrt{\sum*{i=1}^n v\_i^2} = \sqrt{v\_1^2 + v\_2^2 + \dots + v\_n^2}

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

構文
--
```

Math.hypot([value1[, value2[, ...]]])
```

### 引数

`value1, value2, ...`

数値です。

### 返値

与えられた各引数の二乗の合計値の平方根を返します。1 つ上の引数が数値に変換できなかった場合は、 `NaN` が返されます。

解説
--

直角三角形の斜辺や、複素数の大きさを計算するには `Math.sqrt(v1*v1 + v2*v2)` という公式を用い、ここで v1 と v2 は三角形の辺の長さであったり、複素数の実数と複素数部分であったりします。二次元またはそれ以上の次元における対応する距離は、 `Math.sqrt(v1*v1 + v2*v2 + v3*v3 + v4*v4)` のように平方根の下にさらに多くの平方を足すことで計算できます。

この関数はこの計算をより簡単に、より高速に行います。 `Math.hypot(v1, v2)` または `Math.hypot(v1, v2, v3, v4, ...)` を呼び出すだけです。

`Math.hypot` はまた、数値が非常に大きい場合のオーバーフロー/アンダーフローの問題を回避します。 JS で表現できる最大の数は `Number.MAX_VALUE` で、これは約 10308 です。数字の大きさが約 10154 よりも大きい場合、その 2 乗を取ると無限大になります。例えば、 `Math.sqrt(1e200*1e200 + 1e200*1e200) = Infinity`. 代わりに `hypot()` を使うと、 `Math.hypot(1e200, 1e200) = 1.4142...e+200` となり、より良い答えが得られます。これは非常に小さな数の場合にも当てはまります。 `Math.sqrt(1e-200*1e-200 + 1e-200*1e-200) = 0` ですが、 `Math.hypot(1e-200, 1e-200) = 1.4142...e-200` となります。

`hypot()` は `Math` の静的メソッドなので、常に `Math.hypot()` として使用し、自分で `Math` オブジェクトを生成してそのメソッドとして使用しないでください。 (`Math` にはコンストラクターがありません)。

引数が与えられなかった場合、結果は +0 になります。引数のいずれかが ±Infinity であった場合、結果は Infinity になります。引数のいずれかが NaN であった場合は (他に ±Infinity の引数がない限り)、結果は NaN になります。数値に変換できない引数があった場合は、結果は `NaN` になります。

引数が 1 つの場合、 `Math.hypot()` は `Math.abs()` と同等です。

例
-

### Math.hypot() の使用

```js
Math.hypot(3, 4); // 5
Math.hypot(3, 4, 5); // 7.0710678118654755
Math.hypot(); // 0
Math.hypot(NaN); // NaN
Math.hypot(NaN, Infinity); // Infinity
Math.hypot(3, 4, "foo"); // NaN, since +'foo' => NaN
Math.hypot(3, 4, "5"); // 7.0710678118654755, +'5' => 5
Math.hypot(-3); // 3, the same as Math.abs(-3)
```

ポリフィル
-----

オーバーフロー/アンダーフローの問題を処理しないナイーブなアプローチです。

```js
if (!Math.hypot)
  Math.hypot = function () {
    var y = 0,
      i = arguments.length,
      containsInfinity = false;
    while (i--) {
      var arg = arguments[i];
      if (arg === Infinity || arg === -Infinity) containsInfinity = true;
      y += arg \* arg;
    }
    return containsInfinity ? Infinity : Math.sqrt(y);
  };
```

アンダーフローやオーバーフローを回避するポリフィルです。

```js
if (!Math.hypot)
  Math.hypot = function () {
    var max = 0;
    var s = 0;
    var containsInfinity = false;
    for (var i = 0; i < arguments.length; ++i) {
      var arg = Math.abs(Number(arguments[i]));
      if (arg === Infinity) containsInfinity = true;
      if (arg > max) {
        s \*= (max / arg) \* (max / arg);
        max = arg;
      }
      s += arg === 0 && max === 0 ? 0 : (arg / max) \* (arg / max);
    }
    return containsInfinity
      ? Infinity
      : max === 1 / 0
        ? 1 / 0
        : max \* Math.sqrt(s);
  };
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.hypot |

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

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

関連情報
----

* `Math.abs()`
* `Math.pow()`
* `Math.sqrt()`


Math.log1p() - JavaScript

Math.log1p()
============

**`Math.log1p()`** 関数は、 1 + 数値の (`e` を底とする) 自然対数を返します。

∀
x
>
-
1
,

Math.log1p
(
x
)

=
ln
(
1
+
x
)

\forall x > -1, \mathtt{\operatorname{Math.log1p}(x)} = \ln(1 + x)

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

構文
--
```

Math.log1p(x)
```

### 引数

`x`

数値です。

### 返値

1 + 与えられた数値の (`e` を底とした) 自然対数です。数値が **-1** よりも小さかった場合は `NaN` が返されます。

解説
--

`x` の値が非常に小さかった場合、 1 を加えると有効精度が減少します。 JS で使用する倍精度浮動小数点型の精度は 15 桁です。 1 + 1e-15 = 1.000000000000001 ですが、 1 + 1e-16 = 1.000000000000000 となり、 15 桁を超えた桁は四捨五入されるため、正確に 1.0 となります。

log(1 + x) を計算すると、 x が小さければ、 x にとても近い答えになるはずです (これが「自然」対数と呼ばれる所以です)。 Math.log(1 + 1.1111111111e-15) を計算すると、 1.1111111111e-15 に近い答えが得られるはずです。しかし、 1.00000000000000111022 の対数を取ることになります (四捨五入は二進数なので、時に醜い結果になることがあります) ので、答えは 1.11022...e-15 となり、正しい数字は 3 桁だけです。もし、代わりに Math.log1p(1.1111111111e-15) を計算した場合は、もっとずっと正確な答えである 1.1111111110999995e-15 が得られ、 15 桁の正しい数字が得られます (この場合は実際には 16 桁です)。

`x` の値が -1 未満であった場合、返値は常に `NaN` です。

`log1p()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.log1p()` として使用するようにしてください (`Math` はコンストラクターではありません)。

ポリフィル
-----

これは次の関数でエミュレートできます。

```js
Math.log1p =
  Math.log1p ||
  function (x) {
    x = Number(x);
    if (x < -1 || x !== x) return NaN;
    if (x === 0 || x === Infinity) return x;

    var nearX = x + 1 - 1;

    return nearX === 0 ? x : x \* (Math.log(x + 1) / nearX);
  };
```

例
-

### Math.log1p() の使用

```js
Math.log1p(1); // 0.6931471805599453
Math.log1p(0); // 0
Math.log1p(-1); // -Infinity
Math.log1p(-2); // NaN
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.log1p |

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

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

関連情報
----

* `Math.exp()`
* `Math.log()`
* `Math.expm1()`
* `Math.log10()`
* `Math.log2()`
* `Math.pow()`


Math.exp() - JavaScript

Math.exp()
==========

**`Math.exp()`** 関数は `ex` (`x` は引数、 `e` はオイラー数 (ネイピア定数とも)、自然対数の底) を返します。

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

構文
--
```

Math.exp(x)
```

### 引数

`x`

数値です。

### 返値

`ex` (`e` はオイラー数、 `x` は引数) を表す数値です。

解説
--

`exp()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.exp()` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.exp() の使用

```js
Math.exp(-1); // 0.36787944117144233
Math.exp(0); // 1
Math.exp(1); // 2.718281828459045
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.exp |

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

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

関連情報
----

* `Math.E`
* `Math.expm1()`
* `Math.log()`
* `Math.log10()`
* `Math.log1p()`
* `Math.log2()`
* `Math.pow()`


Math.asinh() - JavaScript

Math.asinh()
============

**`Math.asinh()`** 関数は、数値の双曲線逆正弦 (ハイパーボリックアークサイン) を返します。

Math.asinh
(
x
)

=
arsinh
(
x
)
=
 the unique

y

such that

sinh
(
y
)
=
x

\mathtt{\operatorname{Math.asinh}(x)} = \operatorname{arsinh}(x) = \text{ the unique } ; y ; \text{such that} ; \sinh(y) = x

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

構文
--
```

Math.asinh(x)
```

### 引数

`x`

数値

### 返値

与えられた数値の双曲線逆正弦 (ハイパーボリックアークサイン) です。

解説
--

`asinh()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.asinh()` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.asinh() の使用

```js
Math.asinh(1); // 0.881373587019543
Math.asinh(0); // 0
```

ポリフィル
-----

`Math.asinh` は、次の関数でエミュレートできます。

```js
if (!Math.asinh)
  Math.asinh = function (x) {
    var absX = Math.abs(x),
      w;
    if (absX < 3.725290298461914e-9)
      // |x| < 2^-28
      return x;
    if (absX > 268435456)
      // |x| > 2^28
      w = Math.log(absX) + Math.LN2;
    else if (absX > 2)
      // 2^28 >= |x| > 2
      w = Math.log(2 \* absX + 1 / (Math.sqrt(x \* x + 1) + absX));
    else
      var t = x \* x,
        w = Math.log1p(absX + t / (1 + Math.sqrt(1 + t)));

    return x > 0 ? w : -w;
  };
```

`Math.log1p` にもポリフィルを適用する必要があるかもしれません。詳しくは Math.log1p を参照してください。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.asinh |

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

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

関連情報
----

* `Math.acosh()`
* `Math.atanh()`
* `Math.cosh()`
* `Math.sinh()`
* `Math.tanh()`


Math.PI - JavaScript

Math.PI
=======

**`Math.PI`** プロパティは、円周と直径の比率、およそ 3.14159 を表します。

Math.PI

=
π
≈
3.14159

\mathtt{\mi{Math.PI}} = \pi \approx 3.14159

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

| `Math.PI` のプロパティ属性 |
| --- |
| 書込可能 | 不可 |
| 列挙可能 | 不可 |
| 設定可能 | 不可 |

解説
--

`PI` は `Math` オブジェクトの静的プロパティなので、 `Math` オブジェクトを生成してプロパティとして使用するのではなく、常に `Math.PI` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.PI の使用

次の関数は `Math.PI` を使用して、指定された半径を持つ円の円周を計算します。

```js
function calculateCircumference(radius) {
  return Math.PI \* (radius + radius);
}

calculateCircumference(1); // 6.283185307179586
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.pi |

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

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

関連情報
----

* `Math`


Math.expm1() - JavaScript

Math.expm1()
============

**`Math.expm1()`** 関数は `ex - 1` (`x` は引数、 e は自然対数の底) を返します。

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

構文
--
```

Math.expm1(x)
```

### 引数

`x`

数値です。

### 返値

`ex - 1` (`e` はオイラー数、 `x` は引数) を表す数値です。

解説
--

`expm1()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.expm1()` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.expm1() の使用

```js
Math.expm1(-1); // -0.6321205588285577
Math.expm1(0); // 0
Math.expm1(1); // 1.718281828459045
```

ポリフィル
-----

これは `Math.exp()` 関数の助けを借りてエミュレートすることができます。

```js
Math.expm1 =
  Math.expm1 ||
  function (x) {
    return Math.exp(x) - 1;
  };
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.expm1 |

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

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

関連情報
----

* `Math.E`
* `Math.exp()`
* `Math.log()`
* `Math.log10()`
* `Math.log1p()`
* `Math.log2()`
* `Math.pow()`


Math.atanh() - JavaScript

Math.atanh()
============

**`Math.atanh()`** 関数は、数値の双曲線逆正接 (ハイパーボリックアークタンジェント) を返します。

∀
x
∊

(

-
1
,
1

)

,

Math.atanh
(
x
)

=
arctanh
(
x
)
=
 the unique

y

such that

tanh
(
y
)
=
x

\forall x \in \left( -1, 1 \right), \mathtt{\operatorname{Math.atanh}(x)} = \operatorname{arctanh}(x) = \text{ the unique } ; y ; \text{such that} ; \tanh(y) = x

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

構文
--
```

Math.atanh(x)
```

### 引数

`x`

数値。

### 返値

与えられた数値の双曲線逆正接 (ハイパーボリックアークタンジェント) です。

解説
--

`atanh()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.atanh()` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.atanh() の使用

```js
Math.atanh(-2); // NaN
Math.atanh(-1); // -Infinity
Math.atanh(0); // 0
Math.atanh(0.5); // 0.5493061443340548
Math.atanh(1); // Infinity
Math.atanh(2); // NaN
```

１よりも大きな値もしくは -1 よりも小さな値に対しては、 `NaN` が返されます。

ポリフィル
-----

|
x
|

<
1

\left|x\right| < 1

に対して、

artanh
(
x
)
=

1
2

ln

(

1
+
x

1
-
x

)

\operatorname {artanh} (x) = \frac{1}{2}\ln \left( \frac{1 + x}{1 - x} \right)

 になり、次の関数でエミュレートできます。

```js
Math.atanh =
  Math.atanh ||
  function (x) {
    return Math.log((1 + x) / (1 - x)) / 2;
  };
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.atanh |

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

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

関連情報
----

* `Math.acosh()`
* `Math.asinh()`
* `Math.cosh()`
* `Math.sinh()`
* `Math.tanh()`


Math.sign() - JavaScript

Math.sign()
===========

**`Math.sign()`** 関数は、引数として渡された数値の符号が**正**か**負**かを表す +/- 1 を返します。 `Math.sign()` に渡された数が 0 であれば、 +/- 0 を返します。なお、数値が正である場合、明示的な (+) は返され**ません**。

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

構文
--
```

Math.sign(x)
```

### 引数

`x`

数値です。引数が `number` ではない場合は、暗黙に変換されます。

### 返値

与えられた引数の符号を表す数値です。

* 引数が正の値の場合は、 `1` を返します。
* 引数が負の値の場合は、 `-1` を返します。
* 引数が正のゼロの場合は、 `0` を返します。
* 引数が負のゼロの場合は、 `-0` を返します。
* それ以外は `NaN` を返します。
解説
--

`sign()` は `Math` の静的メソッドなので、常に `Math.sign()` として使用し、自分で `Math` オブジェクトを生成してそのメソッドとして使用しないでください。 (`Math` にはコンストラクターがありません)。

ポリフィル
-----

```js
if (!Math.sign) {
  Math.sign = function (x) {
    // If x is NaN, the result is NaN.
    // If x is -0, the result is -0.
    // If x is +0, the result is +0.
    // If x is negative and not -0, the result is -1.
    // If x is positive and not +0, the result is +1.
    return (x > 0) - (x < 0) || +x;
    // A more aesthetic pseudo-representation:
    //
    // ( (x > 0) ? 1 : 0 ) // if x is positive, then positive one
    // + // else (because you can't be both - and +)
    // ( (x < 0) ? -1 : 0 ) // if x is negative, then negative one
    // || // if x is 0, -0, or NaN, or not a number,
    // +x // then the result will be x, (or) if x is
    // // not a number, then x converts to number
  };
}
```

上記のポリフィルでは `(x > 0)` と `(x < 0)` の数値を互いに減算することで、真偽値から数値型へ強制的に型変換されるため、追加の型強制は必要ありません。

例
-

### Math.sign() の使用

```js
Math.sign(3); // 1
Math.sign(-3); // -1
Math.sign("-3"); // -1
Math.sign(0); // 0
Math.sign(-0); // -0
Math.sign(NaN); // NaN
Math.sign("foo"); // NaN
Math.sign(); // NaN
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.sign |

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

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

関連情報
----

* `Math.abs()`
* `Math.ceil()`
* `Math.floor()`
* `Math.round()`
* `Math.trunc()`


Math.sinh() - JavaScript

Math.sinh()
===========

**`Math.sinh()`** 関数は、引数として与えた数の双曲線正弦 (ハイパーボリックサイン) を返します。これは定数 e を使用して次のように表すことができます。

Math.sinh(x)

=

e
x

-

e

-
x

2

\mathtt{\operatorname{Math.sinh(x)}} = \frac{e^x - e^{-x}}{2}

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

構文
--
```

Math.sinh(x)
```

### 引数

`x`

数値。

### 返値

指定された数値の双曲線正弦 (ハイパーボリックサイン) です。

解説
--

`sinh()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.sinh()` として使用するようにしてください (`Math` はコンストラクターではありません)。

ポリフィル
-----

これは `Math.exp()` 関数を使用して次のようにエミュレートできます。

```js
Math.sinh =
  Math.sinh ||
  function (x) {
    return (Math.exp(x) - Math.exp(-x)) / 2;
  };
```

または `Math.exp()` 関数を一度だけ呼び出すようにすると、次のようになります。

```js
Math.sinh =
  Math.sinh ||
  function (x) {
    var y = Math.exp(x);
    return (y - 1 / y) / 2;
  };
```

例
-

### Using Math.sinh() の使用

```js
Math.sinh(0); // 0
Math.sinh(1); // 1.1752011936438014
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.sinh |

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

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

関連情報
----

* `Math.acosh()`
* `Math.asinh()`
* `Math.atanh()`
* `Math.cosh()`
* `Math.tanh()`


Math.clz32() - JavaScript

Math.clz32()
============

**`Math.clz32()`** 関数は、引数として与えられた数値の 32 ビットバイナリ表現での先頭の 0 の個数を返します。

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

構文
--
```

Math.clz32(x)
```

### 引数

`x`

数値。

### 返値

与えられた数値の 32 ビットバイナリ表現での先頭の 0 の個数。

解説
--

"`clz32`" は **CountLeadingZeroes32** の省略形です。

`x` が数値でない場合、まず数値に変換され、32 ビット符号なし整数値に変換されます。

変換された 32 ビット符号なし整数値が `0` の場合、すべてのビットが `0` であるため、`32` を返します。

この関数は Emscripten のような JS にコンパイルするシステムに対して特に役に立ちます。

### 先頭の 1 を数える

現在のところ、 "Count Leading Ones" を表す `Math.clon` はありません ("clo" ではなく "clon" と名付けられています、なぜなら "clo" と "clz" は特に英語を話さない人にとっては似すぎているからです)。しかし、 `clon` 関数は、数値のビットを逆数にして、その結果を `Math.clz32` に渡すことで簡単に作ることができます。 1 の逆数は 0 であり、その逆も同様です。このように、ビットを逆数にすると、測定された 0 の量が (`Math.clz32` からの) 逆数になり、 `Math.clz32` はゼロの数を数えるのではなく、1 の数を数えるようになります。

以下の 32 ビットワード値を想定してみます。

```js
var a = 32776; // 00000000000000001000000000001000 (16 leading zeros)
Math.clz32(a); // 16

var b = ~32776; // 11111111111111110111111111110111 (32776 inversed, 0 leading zeros)
Math.clz32(b); // 0 (this is equal to how many leading one's there are in a)
```

この論理を使用すると、 `clon` 関数は次のように作成することができます。

```js
var clz = Math.clz32;
function clon(integer) {
  return clz(~integer);
}
```

さらに、この技術を拡張して、以下に示すようなジャンプレスの「Count Trailing Zeros」と「Count Trailing Ones」関数を作成することができます。以下の `ctrz` 関数は、すべての上位ビットを最も低いビットで埋め、そのビットを否定して上位のセットビットをすべて消去するので、clz が使用できます。

```js
var clz = Math.clz32;
function ctrz(integer) {
  // count trailing zeros
  // 1. fill in all the higher bits after the first one
  integer |= integer << 16;
  integer |= integer << 8;
  integer |= integer << 4;
  integer |= integer << 2;
  integer |= integer << 1;
  // 2. Now, inversing the bits reveals the lowest bits
  return (32 - clz(~integer)) | 0; // `|0` ensures integer coercion
}
function ctron(integer) {
  // count trailing ones
  // No shift-filling-in-with-ones operator is available in
  // JavaScript, so the below code is the fastest
  return ctrz(~integer);
  /\* Alternate implementation for demonstrational purposes:
 // 1. erase all the higher bits after the first zero
 integer &= (integer << 16) | 0xffff;
 integer &= (integer << 8 ) | 0x00ff;
 integer &= (integer << 4 ) | 0x000f;
 integer &= (integer << 2 ) | 0x0003;
 integer &= (integer << 1 ) | 0x0001;
 // 2. Now, inversing the bits reveals the lowest zeros
 return 32 - clon(~integer) |0;
 \*/
}
```

これらのヘルパー関数を ASM.JS モジュールに入れます。そして、そうすれば、真のパフォーマンスの傑作ができあがります。このような状況は、まさに ASM.JS のために設計されたものです。

```js
var countTrailsMethods = (function (stdlib, foreign, heap) {
  "use asm";
  var clz = stdlib.Math.clz32;
  function ctrz(integer) {
    // count trailing zeros
    integer = integer | 0; // coerce to an integer
    // 1. fill in all the higher bits after the first one
    // ASMjs for some reason does not allow ^=,&=, or |=
    integer = integer | (integer << 16);
    integer = integer | (integer << 8);
    integer = integer | (integer << 4);
    integer = integer | (integer << 2);
    integer = integer | (integer << 1);
    // 2. Now, inversing the bits reveals the lowest bits
    return (32 - clz(~integer)) | 0;
  }
  function ctron(integer) {
    // count trailing ones
    integer = integer | 0; // coerce to an integer
    return ctrz(~integer) | 0;
  }
  // unfourtunately, ASM.JS demands slow crummy objects:
  return { a: ctrz, b: ctron };
})(window, null, null);
var ctrz = countTrailsMethods.a;
var ctron = countTrailsMethods.b;
```

例
-

### Math.clz32() の使用

```js
Math.clz32(1); // 31
Math.clz32(1000); // 22
Math.clz32(); // 32

var stuff = [
  NaN,
  Infinity,
  -Infinity,
  0,
  -0,
  false,
  null,
  undefined,
  "foo",
  {},
  [],
];
stuff.every((n) => Math.clz32(n) == 32); // true

Math.clz32(true); // 31
Math.clz32(3.5); // 30
```

ポリフィル
-----

以下のポリフィルが最も効果的です。

```js
if (!Math.clz32)
  Math.clz32 = (function (log, LN2) {
    return function (x) {
      // Let n be ToUint32(x).
      // Let p be the number of leading zero bits in
      // the 32-bit binary representation of n.
      // Return p.
      var asUint = x >>> 0;
      if (asUint === 0) {
        return 32;
      }
      return (31 - ((log(asUint) / LN2) | 0)) | 0; // the "| 0" acts like math.floor
    };
  })(Math.log, Math.LN2);
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.clz32 |

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

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

関連情報
----

* `Math`
* `Math.imul`


Math.log2() - JavaScript

Math.log2()
===========

**`Math.log2()`** 関数は、数値の 2 を底とした対数を返します。

∀
x
>
0
,

Math.log2
(
x
)

=

log
2

(
x
)
=
the unique

y

such that

2
y

=
x

\forall x > 0, \mathtt{\operatorname{Math.log2}(x)} = \log\_2(x) = \text{the unique} ; y ; \text{such that} ; 2^y = x

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

構文
--
```

Math.log2(x)
```

### 引数

`x`

数値です。

### 返値

与えられた数値の 2 を底とした対数です。数値が負の数であった場合、 `NaN` が返されます。

解説
--

`x` の値が 0 未満であった場合、返値は常に `NaN` です。

`log2()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.log2()` として使用するようにしてください (`Math` はコンストラクターではありません)。

この関数は Math.log(x) / Math.log(2) と同等です。 log2(e) には定数 `Math.LOG2E` を使用してください (これは 1 / `Math.LN2` です。)

ポリフィル
-----

このポリフィルは `Math.log2` 関数をエミュレートします。なお、これは入力値によっては不正確な値を返すので (1 << 29 など)、ビットマスクで使用するときは `Math.round()` で囲んでください。

```js
if (!Math.log2)
  Math.log2 = function (x) {
    return Math.log(x) \* Math.LOG2E;
  };
```

例
-

### Math.log2() の使用

```js
Math.log2(3); // 1.584962500721156
Math.log2(2); // 1
Math.log2(1); // 0
Math.log2(0); // -Infinity
Math.log2(-2); // NaN
Math.log2(1024); // 10
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.log2 |

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

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

関連情報
----

* `Math.exp()`
* `Math.log()`
* `Math.log10()`
* `Math.log1p()`
* `Math.pow()`


Math.atan2() - JavaScript

Math.atan2()
============

**`Math.atan2()`** 関数は、`Math.atan2(y, x)` に対して点 (0, 0) から点 (x, y) までの半直線と、正の x 軸の間の平面上での角度 (ラジアン単位) を返します。

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

構文
--
```

Math.atan2(y, x)
```

### 引数

`y`

点の y 座標です。

`x`

点の x 座標です。

### 返値

点 (0, 0) から点

(x,y)

 までの半直線と、正の x 軸の間の (

[
-
π
,
π
]

[-\pi, \pi]

 内の) ラジアン単位の角度です。

解説
--

`Math.atan2()` メソッドは、`(x, y)` 座標のシータ角を表す -π から π までの数値を返します。これは、ラジアン単位で表された、正の X 軸と点 `(x, y)` の間の反時計回りの角度です。このメソッドへ渡す引数は、初めに y 座標、次に x 座標であることに注意してください。

![A simple diagram showing the angle returned by atan2(y, x)](/ja/docs/Web/JavaScript/Reference/Global_Objects/Math/atan2/atan2.png)

`Math.atan2()` は、`x` と `y` が別々に渡され、 `Math.atan()` は 2 つの引数の比率が渡されます。

`atan2()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.atan2()` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.atan2() の使用

```js
Math.atan2(90, 15); // 1.4056476493802699
Math.atan2(15, 90); // 0.16514867741462683

Math.atan2(±0, -0);               // ±PI.
Math.atan2(±0, +0);               // ±0.
Math.atan2(±0, -x);               // ±PI for x > 0.
Math.atan2(±0, x);                // ±0 for x > 0.
Math.atan2(-y, ±0);               // -PI/2 for y > 0.
Math.atan2(y, ±0);                // PI/2 for y > 0.
Math.atan2(±y, -Infinity);        // ±PI for finite y > 0.
Math.atan2(±y, +Infinity);        // ±0 for finite y > 0.
Math.atan2(±Infinity, x);         // ±PI/2 for finite x.
Math.atan2(±Infinity, -Infinity); // ±3\*PI/4.
Math.atan2(±Infinity, +Infinity); // ±PI/4.
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.atan2 |

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

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

関連情報
----

* `Math.acos()`
* `Math.asin()`
* `Math.atan()`
* `Math.cos()`
* `Math.sin()`
* `Math.tan()`


Math.trunc() - JavaScript

Math.trunc()
============

**`Math.trunc()`** 関数は、引数として与えた数の小数部の桁を取り除くことによって整数部を返します。

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

構文
--

```js
Math.trunc(x)
```

### 引数

`x`

数値。

### 返値

`x` の整数部です。

解説
--

他の 3 つの `Math` メソッド、`Math.floor()`、`Math.ceil()`、`Math.round()` とは異なり、 `Math.trunc()` の動作は非常にシンプルで分かりやすいです。引数が正の数または負の数であるかに関わらず、ただ小数点とそれ以降にある数字を*切り捨て*ます。

`trunc()` は `Math` オブジェクトの静的なメソッドなので、自ら生成した `Math` オブジェクトのメソッドとしてではなく、常に、`Math.trunc()` として使用してください (`Math` オブジェクトにはコンストラクタがありません)。

例
-

### Math.trunc() の使用

```js
Math.trunc(-Infinity); // -Infinity
Math.trunc("-1.123"); // -1
Math.trunc(-0.123); // -0
Math.trunc(-0); // -0
Math.trunc(0); // 0
Math.trunc(0.123); // 0
Math.trunc(13.37); // 13
Math.trunc(42.84); // 42
Math.trunc(Infinity); // Infinity
```

### ビット単位の no-op を使った数値の切り捨て

**警告:** 無視できないエッジケースがあるため、これは `Math.trunc()` のポリフィルにはなりません。

ビット演算はオペランドを 32 ビット整数に変換します。一般的なテクニックは以下の通りです。

```js
const original = 3.14;
const truncated1 = ~~original; // 二重否定
const truncated2 = original & -1; // Bitwise AND with -1
const truncated3 = original | 0; // Bitwise OR with 0
const truncated4 = original ^ 0; // Bitwise XOR with 0
const truncated5 = original >> 0; // Bitwise shifting by 0
```

これは本質的に `toInt32` であり、 `Math.trunc` とは異なることに注意してください。値が -231 - 1 < `value` < 231 (-2147483649 < `value` < 2147483648) を満たさない場合、変換がオーバーフローしてしまいます。

```js
const a = ~~2147483648; // -2147483648
const b = ~~-2147483649; // 2147483647
const c = ~~4294967296; // 0
```

`Math.trunc()` の代用として `~~` を使うのは、入力の範囲が 32 ビット整数の範囲に収まっていると確信できる場合だけにしてください。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.trunc |

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

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

関連情報
----

* `Math.trunc` のポリフィル (`core-js`)
* `Math.abs()`
* `Math.ceil()`
* `Math.floor()`
* `Math.round()`
* `Math.sign()`


Math.ceil() - JavaScript

Math.ceil()
===========

**`Math.ceil()`** 関数は、引数として与えた数以上の最小の整数を返します。

**注:** `Math.ceil(`null`)` は整数の 0 を返し、 `NaN` エラーは返しません。

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

構文
--
```

Math.ceil(x)
```

### 引数

`x`

数値。

### 返値

引数として与えた数以上の最小の整数を返します。

解説
--

`ceil()` は `Math` オブジェクトの静的メソッドなので、 `Math` オブジェクトを生成してメソッドとして使用するのではなく、常に `Math.ceil()` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.ceil() の使用

以下の例は、`Math.ceil()` を使用した例です。

```js
Math.ceil(0.95); // 1
Math.ceil(4); // 4
Math.ceil(7.004); // 8
Math.ceil(-0.95); // -0
Math.ceil(-4); // -4
Math.ceil(-7.004); // -7
```

### 10 進補正 (Decimal adjustment)

```js
// Closure
(function () {
  /\*\*
 \* Decimal adjustment of a number.
 \*
 \* @param {String} type The type of adjustment.
 \* @param {Number} value The number.
 \* @param {Integer} exp The exponent (the 10 logarithm of the adjustment base).
 \* @returns {Number} The adjusted value.
 \*/
  function decimalAdjust(type, value, exp) {
    // If the exp is undefined or zero...
    if (typeof exp === "undefined" || +exp === 0) {
      return Math[type](value);
    }
    value = +value;
    exp = +exp;
    // If the value is not a number or the exp is not an integer...
    if (isNaN(value) || !(typeof exp === "number" && exp % 1 === 0)) {
      return NaN;
    }
    // Shift
    value = value.toString().split("e");
    value = Math[type](+(value[0] + "e" + (value[1] ? +value[1] - exp : -exp)));
    // Shift back
    value = value.toString().split("e");
    return +(value[0] + "e" + (value[1] ? +value[1] + exp : exp));
  }

  // Decimal round
  if (!Math.round10) {
    Math.round10 = function (value, exp) {
      return decimalAdjust("round", value, exp);
    };
  }
  // Decimal floor
  if (!Math.floor10) {
    Math.floor10 = function (value, exp) {
      return decimalAdjust("floor", value, exp);
    };
  }
  // Decimal ceil
  if (!Math.ceil10) {
    Math.ceil10 = function (value, exp) {
      return decimalAdjust("ceil", value, exp);
    };
  }
})();

// Round
Math.round10(55.55, -1); // 55.6
Math.round10(55.549, -1); // 55.5
Math.round10(55, 1); // 60
Math.round10(54.9, 1); // 50
Math.round10(-55.55, -1); // -55.5
Math.round10(-55.551, -1); // -55.6
Math.round10(-55, 1); // -50
Math.round10(-55.1, 1); // -60
// Floor
Math.floor10(55.59, -1); // 55.5
Math.floor10(59, 1); // 50
Math.floor10(-55.51, -1); // -55.6
Math.floor10(-51, 1); // -60
// Ceil
Math.ceil10(55.51, -1); // 55.6
Math.ceil10(51, 1); // 60
Math.ceil10(-55.59, -1); // -55.5
Math.ceil10(-59, 1); // -50
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.ceil |

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

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

関連情報
----

* `Math.abs()`
* `Math.floor()`
* `Math.round()`
* `Math.sign()`
* `Math.trunc()`


Math.floor() - JavaScript

Math.floor()
============

**`Math.floor()`** 関数は与えられた数値以下の最大の整数を返します。

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

構文
--
```

Math.floor(x)
```

### 引数

`x`

数値です。

### 返値

指定された数値以下の最大の整数を表す数値です。

解説
--

`floor()` は `Math` オブジェクトの静的なメソッドなので、自ら生成した `Math` オブジェクトのメソッドとしてではなく、常に、`Math.floor()` として使用するようにしてください (`Math` のコンストラクターはありません)。

**メモ:** `Math.floor(null)` は `NaN` ではなく 0 を返します。

例
-

### Math.floor() の使用

```js
Math.floor(45.95); // 45
Math.floor(45.05); // 45
Math.floor(4); // 4
Math.floor(-45.05); // -46
Math.floor(-45.95); // -46
```

### 十進数の丸め

```js
/\*\*
 \* Decimal adjustment of a number.
 \*
 \* @param {String} type The type of adjustment.
 \* @param {Number} value The number.
 \* @param {Integer} exp The exponent (the 10 logarithm of the adjustment base).
 \* @returns {Number} The adjusted value.
 \*/
function decimalAdjust(type, value, exp) {
  // If the exp is undefined or zero...
  if (typeof exp === "undefined" || +exp === 0) {
    return Math[type](value);
  }
  value = +value;
  exp = +exp;
  // If the value is not a number or the exp is not an integer...
  if (isNaN(value) || !(typeof exp === "number" && exp % 1 === 0)) {
    return NaN;
  }
  // Shift
  value = value.toString().split("e");
  value = Math[type](+(value[0] + "e" + (value[1] ? +value[1] - exp : -exp)));
  // Shift back
  value = value.toString().split("e");
  return +(value[0] + "e" + (value[1] ? +value[1] + exp : exp));
}

// Decimal round
const round10 = (value, exp) => decimalAdjust("round", value, exp);
// Decimal floor
const floor10 = (value, exp) => decimalAdjust("floor", value, exp);
// Decimal ceil
const ceil10 = (value, exp) => decimalAdjust("ceil", value, exp);

// Round
round10(55.55, -1); // 55.6
round10(55.549, -1); // 55.5
round10(55, 1); // 60
round10(54.9, 1); // 50
round10(-55.55, -1); // -55.5
round10(-55.551, -1); // -55.6
round10(-55, 1); // -50
round10(-55.1, 1); // -60
// Floor
floor10(55.59, -1); // 55.5
floor10(59, 1); // 50
floor10(-55.51, -1); // -55.6
floor10(-51, 1); // -60
// Ceil
ceil10(55.51, -1); // 55.6
ceil10(51, 1); // 60
ceil10(-55.59, -1); // -55.5
ceil10(-59, 1); // -50
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.floor |

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

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

関連情報
----

* `Math.abs()`
* `Math.ceil()`
* `Math.round()`
* `Math.sign()`
* `Math.trunc()`


Math.tanh() - JavaScript

Math.tanh()
===========

**`Math.tanh()`** 関数は、引数として与えた数のハイパーボリックタンジェントを返します。すなわち

tanh
x
=

sinh
x

cosh
x

=

e
x

-

e

-
x

e
x

+

e

-
x

=

e

2
x

-
1

e

2
x

+
1

\tanh x = \frac{\sinh x}{\cosh x} = \frac {e^x - e^{-x}} {e^x + e^{-x}} = \frac{e^{2x} - 1}{e^{2x}+1}

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

構文
--
```

Math.tanh(x)
```

### 引数

`x`

数値。

### 返値

指定された数値のハイパーボリックタンジェントです。

解説
--

`tanh()` は `Math` の静的メソッドであるため、生成した `Math` オブジェクトのメソッドとしてではなく、常に `Math.tanh()` として使用するようにしてください (`Math` はコンストラクターではありません)。

ポリフィル
-----

`Math.exp()` 関数の助けを借りて、エミュレートできます。:

```js
Math.tanh =
  Math.tanh ||
  function (x) {
    var a = Math.exp(+x),
      b = Math.exp(-x);
    return a == Infinity ? 1 : b == Infinity ? -1 : (a - b) / (a + b);
  };
```

例
-

### Math.tanh() の使用

```js
Math.tanh(0); // 0
Math.tanh(Infinity); // 1
Math.tanh(1); // 0.7615941559557649
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.tanh |

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

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

関連情報
----

* `Math.acosh()`
* `Math.asinh()`
* `Math.atanh()`
* `Math.cosh()`
* `Math.sinh()`


Math.LN2 - JavaScript

Math.LN2
========

**`Math.LN2`** プロパティは 2 の自然対数、およそ 0.693 を表します。

Math.LN2

=
ln
(
2
)
≈
0.693

\mathtt{\mi{Math.LN2}} = \ln(2) \approx 0.693

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

| `Math.LN2` のプロパティ属性 |
| --- |
| 書込可能 | 不可 |
| 列挙可能 | 不可 |
| 設定可能 | 不可 |

解説
--

`LN2` は `Math` オブジェクトの静的プロパティなので、 `Math` オブジェクトを生成してプロパティとして使用するのではなく、常に `Math.LN2` として使用するようにしてください (`Math` はコンストラクターではありません)。

例
-

### Math.LN2 の使用

以下の関数は、2 の自然対数を返します。

```js
function getNatLog2() {
  return Math.LN2;
}

getNatLog2(); // 0.6931471805599453
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-math.ln2 |

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

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

関連情報
----

* `Math.exp()`
* `Math.log()`
* `Math.log2()`


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

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

**`FinalizationRegistry`** コンストラクターは、指定されたコールバックを使用する `FinalizationRegistry` オブジェクトを生成します。

構文
--
```

new FinalizationRegistry([callback]);
```

### 引数

`callback` 省略可

レジストリが使用するコールバック関数です。指定された場合、関数である必要があります。

例
-

### 新しいレジストリの生成

コールバックを渡してレジストリを生成します。

```js
const registry = new FinalizationRegistry((heldValue) => {
  // ....
});
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-finalization-registry-constructor |

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

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

関連情報
----

* `FinalizationRegistry`


FinalizationRegistry.prototype.unregister() - JavaScript

FinalizationRegistry.prototype.unregister()
===========================================

`unregister` は対象のオブジェクトを `FinalizationRegistry` インスタンスから登録解除します。

構文
--
```

registry.unregister(unregisterToken);
```

### 引数

`unregisterToken`

対象オブジェクトを登録したときに `register` メソッドで使用したトークンです。

### 返値

`undefined` です。

注
-

対象オブジェクトの回収が完了すると、レジストリに登録された状態ではなくなります。クリーンアップコールバックですべてに `unregister` を行う必要はありません。クリーンアップコールバックを受信しておらず、クリーンアップコールバックを受信する必要がなくなった場合にのみ `unregister` を呼び出してください。

例
-

### unregister の使用

この例では、登録解除トークンとして同じオブジェクトを使用して対象のオブジェクトを登録し、その後、 `unregister` を介して対象のオブジェクトの登録を解除します。

```js
class Thingy {
  #cleanup = (label) => {
    // ^^^^^−−−−− held value
    console.error(
      `The \`release\` method was never called for the object with the label "${label}"`,
    );
  };
  #registry = new FinalizationRegistry(this.#cleanup);

  /\*\*
 \* Constructs a `Thingy` instance. Be sure to call `release` when you're done with it.
 \*
 \* @param label A label for the `Thingy`.
 \*/
  constructor(label) {
    // vvvvv−−−−− held value
    this.#registry.register(this, label, this);
    // target −−−−−^^^^ ^^^^−−−−− unregister token
  }

  /\*\*
 \* Releases resources held by this `Thingy` instance.
 \*/
  release() {
    this.#registry.unregister(this);
    // ^^^^−−−−− unregister token
  }
}
```

この例では、登録解除トークンとして別のオブジェクトを使用して対象のオブジェクトを登録しています。

```js
 {
    // ^^^^−−−−− held value
        console.error(
            `The \`release\` method was never called for the \`Thingy\` for the file "${file.name}"`
        );
    };
    #registry = new FinalizationRegistry(this.#cleanup);

    /\*\*
 \* Constructs a `Thingy` instance for the given file. Be sure to call `release` when you're done with it.
 \*
 \* @param filename The name of the file.
 \*/
    constructor(filename) {
        this.#file = File.open(filename);
        // vvvvv−−−−− held value
        this.#registry.register(this, label, this.#file);
        // target −−−−−^^^^ ^^^^^^^^^^−−−−− unregister token
    }

    /\*\*
 \* Releases resources held by this `Thingy` instance.
 \*/
    release() {
        if (this.#file) {
            this.#registry.unregister(this.#file);
            // ^^^^^^^^^^−−−−− unregister token
            File.close(this.#file);
            this.#file = null;
        }
    }
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-finalization-registry.prototype.unregister |

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

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

関連情報
----

* `FinalizationRegistry`


FinalizationRegistry.prototype.register() - JavaScript

FinalizationRegistry.prototype.register()
=========================================

`register()` メソッドはオブジェクトを `FinalizationRegistry` インスタンスへ登録し、オブジェクトがガベージコレクションで回収された場合、レジストリのコールバックが呼び出されるようになります。

構文
--
```

registry.register(target, heldValue, [unregisterToken]);
```

### 引数

`target`

登録する対象オブジェクトです。

`heldValue`

このオブジェクトのためにファイナライザーへ渡す値です。これは `target` オブジェクトにすることはできません。

`unregisterToken` 省略可

のちに対象オブジェクトを登録解除するために `unregister` メソッドと共に使用するトークンです。提供された場合 (かつ `undefined` ではない場合)、これはオブジェクトである必要があります。提供されなかった場合は、対象を登録解除することはできません。

### 返値

`undefined` です。

注
-

重要な注意点については、 `FinalizationRegistry` ページの可能な限り避けるとクリーンアップコールバックに関する注意事項の部分を参照してください。

例
-

### register の使用

次の例は `target` で参照される対象オブジェクトを保持値 `"some value"` で登録し、対象オブジェクト自身を登録解除トークンとして渡します。

```js
registry.register(target, "some value", target);
```

次の例は `target` で参照される対象オブジェクトを他のオブジェクトを保持値として登録し、登録解除トークンを渡していません (すなわち `target` は登録解除できません)。

```js
registry.register(target, { useful: "info about target" });
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-finalization-registry.prototype.register |

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

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

関連情報
----

* `FinalizationRegistry`


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

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

**`AsyncGeneratorFunction()`** コンストラクターは `AsyncGeneratorFunction` オブジェクトを生成します。

なお、 `AsyncGeneratorFunction` はグローバルオブジェクトではありません。 以下のコードを評価することで得られます。

```js
const AsyncGeneratorFunction = async function\* () {}.constructor;
```

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

構文
--

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

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

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

### 引数

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

例
-

### コンストラクターの使用

次の例では、`AsyncGeneratorFunction` コンストラクターを使用して非同期ジェネレータ関数を作成します。

```js
const AsyncGeneratorFunction = async function\* () {}.constructor;
const createAsyncGenerator = new AsyncGeneratorFunction("a", "yield a \* 2");
const asyncGen = createAsyncGenerator(10);
asyncGen.next().then((res) => console.log(res.value)); // 20
```

仕様書
---

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

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

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

関連情報
----

* `async function*` 宣言
* `async function*` 式
* `Function()` コンストラクター
* イテレーターとジェネレーター
* 関数


WeakSet.prototype.delete() - JavaScript

WeakSet.prototype.delete()
==========================

**`delete()`** メソッドは、`WeakSet` オブジェクトから指定された要素を取り除きます。

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

構文
--
```

ws.delete(value);
```

### 引数

`value`

必須。 `WeakSet` オブジェクトから取り除くオブジェクトです。

### 返値

`WeakSet` オブジェクトの中の要素が正常に削除された場合は `true` を返します。 `value` が `WeakSet` の中で見つからなかったり、 `value` がオブジェクトではなかった場合は `false` を返します。

例
-

### delete() メソッドの使用

```js
var ws = new WeakSet();
var obj = {};

ws.add(window);

ws.delete(obj); // false を返します。削除する obj が見つかりません。
ws.delete(window); // true を返します。正常に削除されます。

ws.has(window); // false を返します。 window はもう WeakSet の中にないからです。
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-weakset.prototype.delete |

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

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

関連情報
----

* `WeakSet`
* `WeakSet.prototype.clear()`


WeakSet.prototype.has() - JavaScript

WeakSet.prototype.has()
=======================

**`has()`** メソッドは、特定の値をもつ要素が `WeakSet` オブジェクト内に存在するかどうかを示す真偽値を返します。

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

構文
--
```

ws.has(value);
```

### 引数

`value`

`WeakSet` オブジェクトに存在するかテストする値です。

### 返値

Boolean

`WeakSet` オブジェクト内に特定の値をもつ要素が存在していたら `true` を返します。さもなければ `false` を返します。

例
-

### has() メソッドの使用

```js
var ws = new WeakSet();
var obj = {};
ws.add(window);

mySet.has(window); // returns true
mySet.has(obj); // returns false
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-weakset.prototype.has |

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

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

関連情報
----

* `WeakSet`
* `WeakSet.prototype.add()`
* `WeakSet.prototype.delete()`


WeakSet.prototype.add() - JavaScript

WeakSet.prototype.add()
=======================

**`add()`** メソッドは、新しい要素を `WeakSet` オブジェクトの最後に追加します。

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

構文
--
```

ws.add(value);
```

### 引数

`value`

必須。 `WeakSet` コレクションに追加する要素の値です。

### 返値

`WeakSet` オブジェクトです。

例
-

### add() の使用

```js
var ws = new WeakSet();

ws.add(window); //window オブジェクトを WeakSet へ追加

ws.has(window); // true

// WeakSet は引数としてオブジェクトのみを取ります。
ws.add(1);
// 結果は "TypeError: Invalid value used in weak set" (Chrome)
// "TypeError: 1 is not a non-null object" (Firefox)
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-weakset.prototype.add |

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

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

関連情報
----

* `WeakSet`
* `WeakSet.prototype.delete()`
* `WeakSet.prototype.has()`


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

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

**`WeakSet`** コンストラクターで、 `WeakSet` オブジェクトを生成し、これに弱い参照で*オブジェクト*をコレクションで保持することができます。

構文
--
```

new WeakSet([iterable]);
```

### 引数

*iterable*

反復可能オブジェクトが渡された場合、すべての要素が新しい `WeakSet` に追加されます。 null は undefined として扱われます。

例
-

### WeakSet オブジェクトの使用

```js
var ws = new WeakSet();
var foo = {};
var bar = {};

ws.add(foo);
ws.add(bar);

ws.has(foo); // true
ws.has(bar); // true

ws.delete(foo); // foo を set から削除
ws.has(foo); // false, foo は削除済み
ws.has(bar); // true, bar は残っている
```

`foo !== bar` であることに注意してください。これらは似たオブジェクトですが、***まったく同じオブジェクト**ではありません*。したがって、両方のオブジェクトが set に追加されます。

仕様書
---

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

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

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

関連情報
----

* `WeakSet`


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

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

**`ReferenceError`** オブジェクトは、存在しない変数が参照されたときのエラーを表します。

構文
--
```

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

### 引数

`message` 省略可

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

`fileName` 省略可

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

`lineNumber` 省略可

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

例
-

### ReferenceError の捕捉

```js
try {
  let a = undefinedVariable;
} catch (e) {
  console.log(e instanceof ReferenceError); // true
  console.log(e.message); // "undefinedVariable is not defined"
  console.log(e.name); // "ReferenceError"
  console.log(e.fileName); // "Scratchpad/1"
  console.log(e.lineNumber); // 2
  console.log(e.columnNumber); // 6
  console.log(e.stack); // "@Scratchpad/2:2:7\n"
}
```

### ReferenceError の生成

```js
try {
  throw new ReferenceError("Hello", "someFile.js", 10);
} catch (e) {
  console.log(e instanceof ReferenceError); // true
  console.log(e.message); // "Hello"
  console.log(e.name); // "ReferenceError"
  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`


Promise.any() - JavaScript

Promise.any()
=============

**`Promise.any()`** は静的メソッドで、入力としてプロミスの反復可能オブジェクトを取り、単一の `Promise` を返します。この返されたプロミスは、入力のプロミスのいずれかが履行されたときに、この最初の履行値で履行されます。入力のプロミスがすべて拒否された場合（空の反復可能オブジェクトが渡された場合を含む）、拒否理由の配列を格納した `AggregateError` で、拒否されます。

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

構文
--

```js
Promise.any(iterable)
```

### 引数

`iterable`

プロミスの反復可能オブジェクト（`Array` など）です。

### 返値

次のような `Promise` です。

* 渡された反復可能オブジェクトが空の場合は、**拒否済み**になります。
* 渡された*反復可能*オブジェクトのいずれかのプロミスが履行された場合、**非同期に履行**されます。履行値は、最初に履行されたプロミスの履行値になります。
* 指定された反復可能オブジェクトにあるすべてのプロミスが拒否された場合、**非同期に拒否**されます。拒否理由は `AggregateError` で、その `errors` プロパティに拒否理由の配列が格納されています。エラーは、完了順に関係なく、通過したプロミスの順番になります。渡された反復可能オブジェクトが空でなく、待機中のプロミスを含んでいない場合、返されたプロミスは（同期的ではなく）非同期に拒否されたままです。
解説
--

`Promise.any()` メソッドはプロミスの並行処理メソッドの 1 つです。このメソッドは、最初に履行されたプロミスを返すのに有益なものです。最初のプロミスが履行された後は短絡的に処理するので、一つを見つけると、他のプロミスが完了するのを待つことはありません。

**メモ:** 日本語の技術文書では、このメソッドが複数のプロミスを並列に処理すると説明されることがありますが、実際には複数のスレッドでプロミスが処理されるわけではないことに注意してください。詳細はプロミスの並行処理を参照してください。

`Promise.all()` が履行された値の *配列* を返すのとは異なり、 1 つの履行値だけを取得します（少なくとも 1 つのプロミスが履行されることを想定しています）。これは、履行されるプロミスが 1 つだけ必要で、どれが履行されるかは気にしない場合、有益なことがあります。もう一つの異なる形に注意してください。このメソッドは、*空の反復可能オブジェクト* を受け取ると拒否します。なぜなら、正直に言うと、反復処理オブジェクトには、履行されるアイテムが格納されていないからです。`Promise.any()` と `Promise.all()` を `Array.prototype.some()` と `Array.prototype.every()` で比較することができます。

また、 `Promise.race()` が最初の *決定された* 値（履行されたか拒否されたか）を返すのとは異なり、このメソッドは最初の *履行された* 値を返します。このメソッドは、最初に履行されたプロミスまでのすべての拒否されたプロミスを無視します。

例
-

### 最初に履行されるもの

`Promise.any()` は、先に拒否されたプロミスがあったとしても、最初に履行されたプロミスで解決されます。これは `Promise.race()` が、最初に決定されたプロミスで解決または拒否されるのとは対照的です。

```js
const pErr = new Promise((resolve, reject) => {
  reject("Always fails");
});

const pSlow = new Promise((resolve, reject) => {
  setTimeout(resolve, 500, "Done eventually");
});

const pFast = new Promise((resolve, reject) => {
  setTimeout(resolve, 100, "Done quick");
});

Promise.any([pErr, pSlow, pFast]).then((value) => {
  console.log(value);
  // pFast が最初に履行される
});
// ログ出力:
// Done quick
```

### AggregateError での拒否

`Promise.any()` は履行されたプロミスがないと `AggregateError` で拒否されます。

```js
const failure = new Promise((resolve, reject) => {
  reject("Always fails");
});

Promise.any([failure]).catch((err) => {
  console.log(err);
});
// AggregateError: No Promise in Promise.any was resolved
```

### 最初に読み込まれた画像の表示

この例では、画像を読み込んで blob を返す関数があります。 `Promise.any()` を使用して二つの画像を読み込み、先に利用可能になった方 (つまり、プロミスが解決された方) を表示します。

```js
async function fetchAndDecode(url, description) {
  const res = await fetch(url);
  if (!res.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  const data = await response.blob();
  return [data, description];
}

const coffee = fetchAndDecode("coffee.jpg", "Coffee");
const tea = fetchAndDecode("tea.jpg", "Tea");

Promise.any([coffee, tea])
  .then(([blob, description]) => {
    const objectURL = URL.createObjectURL(blob);
    const image = document.createElement("img");
    image.src = objectURL;
    image.alt = description;
    document.body.appendChild(image);
  })
  .catch((e) => {
    console.error(e);
  });
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-promise.any |

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

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

関連情報
----

* `Promise.any` のポリフィル (`core-js`)
* `Promise`
* `Promise.all()`
* `Promise.allSettled()`
* `Promise.race()`


Promise.allSettled() - JavaScript

Promise.allSettled()
====================

**`Promise.allSettled()`** は静的メソッドで、入力としてプロミスの反復可能オブジェクトを受け取り、単一の `Promise` を返します。この返されたプロミスは、入力のすべてのプロミスが決定したとき（空の反復可能オブジェクトが渡された場合を含む）に履行され、各プロミスの結果を記述するオブジェクトの配列が返されます。

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

構文
--

```js
Promise.allSettled(iterable)
```

### 引数

`iterable`

プロミスの反復可能オブジェクト（`Array` など）です。

### 返値

次のような `Promise` です。

* *反復可能*オブジェクトが空であった場合は、**履行済み**になります。
* 渡された*反復可能*オブジェクトのすべてのプロミスが（履行または拒否に）決定したとき、**非同期に履行されます**。履行されたプロミスの値はオブジェクトの配列で、それぞれが反復可能なオブジェクトの中の一つのプロミスの結果を記述しています。それぞれの成果オブジェクトには、以下のようなプロパティがあります。

`status`

文字列で、 `"fulfilled"` （履行）または `"rejected"` （拒否）をとり、そのプロミスの最終的な状態を示します。

`value`

`status` が `"fulfilled"` の場合のみ存在します。プロミスが履行された値です。

`reason`

`status` が `"rejected"` の場合のみ存在します。プロミスが拒否された理由です。

渡された反復可能オブジェクトが空でなく、待機中のプロミスを含んでいない場合、返されたプロミスは（同期ではなく）非同期に履行されます。

解説
--

`Promise.allSettled()` メソッドはプロミスの並行処理 メソッドの 1 つです。`Promise.allSettled()` は、通常、正常に完了するために互いに依存しない複数の非同期タスクがある場合、または各プロミスの結果を常に知りたい場合に使用されます。

**メモ:** 日本語の技術文書では、このメソッドが複数のプロミスを並列に処理すると説明されることがありますが、実際には複数のスレッドでプロミスが処理されるわけではないことに注意してください。詳細はプロミスの並行処理を参照してください。

それに対して、 `Promise.all()` が返すプロミスは、タスクが他にも依存している場合や、どれかが拒否されたらすぐに拒否したい場合により適しているかもしれません。

例
-

### Promise.allSettled の使用

```js
Promise.allSettled([
  Promise.resolve(33),
  new Promise((resolve) => setTimeout(() => resolve(66), 0)),
  99,
  Promise.reject(new Error("an error")),
]).then((values) => console.log(values));

// [
// { status: 'fulfilled', value: 33 },
// { status: 'fulfilled', value: 66 },
// { status: 'fulfilled', value: 99 },
// { status: 'rejected', reason: Error: an error }
// ]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-promise.allsettled |

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

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

関連情報
----

* `Promise.allSettled` のポリフィル (`core-js`)
* プロミスの使用
* プロミスを使った行儀のよい非同期のプログラミング
* `Promise`
* `Promise.all()`
* `Promise.any()`
* `Promise.race()`


get Promise[@@species] - JavaScript

get Promise[@@species]
======================

**`Promise[@@species]`** アクセサープロパティは、プロミスのメソッドからの返値を構築するのに使用されるコンストラクターを返します。

**警告:** `@@species` が存在すると、任意のコードの実行が可能になり、セキュリティ上の脆弱性を生み出す可能性があります。また、特定の最適化も非常に難しくなります。エンジンの実装者はこの機能を削除するかどうか調査しています。可能であれば、この機能に頼ることは避けてください。

構文
--

```js
Promise[Symbol.species];
```

### 返値

`get @@species` が呼び出されたコンストラクター (`this`) の値です。この返値は、新しいプロミスを作成するプロミス連鎖メソッドから返値を作成するために使用されます。

解説
--

`@@species` アクセサープロパティは `Promise` オブジェクトの既定のコンストラクターを返します。サブクラスのコンストラクターはこれを上書きしてコンストラクターの割り当てを変更することができます。既定の実装では、基本的に次のようになります。

```js
// 解説のため架空の基礎実装
class Promise {
  static get [Symbol.species]() {
    return this;
  }
}
```

この多相的な実装のため、派生したサブクラスの `@@species` も既定ではコンストラクター自身を返すことになります。

```js
class SubPromise extends Promise {}
SubPromise[Symbol.species] === Promise; // true
```

プロミス連鎖メソッドである `then()`、`catch()`、`finally()` は、新しいプロミスオブジェクトを返します。これらは `this.constructor[@@species]` を介して新しいプロミスを構築するためのコンストラクターを取得します。 `this.constructor` が `undefined` の場合、または `this.constructor[@@species]` が `undefined` または `null` の場合、既定の `Promise()` コンストラクターが使用されます。それ以外の場合は、 `this.constructor[@@species]` から返されるコンストラクターが使用され、新しいプロミスオブジェクトが構築されます。

例
-

### 通常のオブジェクトの species

`Symbol.species` プロパティは、既定では `Promise` のコンストラクター関数を返します。

```js
Promise[Symbol.species]; // [Function: Promise]
```

### 派生オブジェクトの species

`MyPromise` のような独自の `Promise` サブクラスのインスタンスでは、 `MyPromise` コンストラクターが `MyPromise` の species となります。しかし、派生クラスのメソッドで親の `Promise` オブジェクトを返すために、これをオーバーライドしたい場合があるかもしれません。

```js
class MyPromise extends Promise {
  // MyPromise の species を親の Promise コンストラクターで上書きする
  static get [Symbol.species]() {
    return Promise;
  }
}
```

既定では、プロミスメソッドはサブクラスの型を持つプロミスを返します。

```js
class MyPromise extends Promise {
  someValue = 1;
}

console.log(MyPromise.resolve(1).then(() => {}).someValue); // 1
```

`@@species` を上書きすることで、プロミスのメソッドは基底の `Promise` 型を返すことになります。

```js
class MyPromise extends Promise {
  someValue = 1;
  static get [Symbol.species]() {
    return Promise;
  }
}

console.log(MyPromise.resolve(1).then(() => {}).someValue); // undefined
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-get-promise-@@species |

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

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

関連情報
----

* `Promise`
* `Symbol.species`


Promise.prototype.catch() - JavaScript

Promise.prototype.catch()
=========================

**`catch()`** は `Promise` オブジェクトのメソッドで、プロミスが拒否されたときに呼び出される関数をスケジュールします。これは即座に同等の `Promise` オブジェクトを返すので、他のプロミスのメソッドを連鎖 して呼び出すことができます。これは `Promise.prototype.then(undefined, onRejected)` の省略形です。

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

構文
--

```js
catch(onRejected)

catch((reason) => {
  // 拒否ハンドラー
})
```

### 引数

`onRejected`

`Promise` が拒否された時に呼び出される `Function` です。この関数は 1 つの引数、 *拒否された理由* を取ります。

### 返値

新しい `Promise` を返します。この新しいプロミスは、現在のプロミスの状態に関係なく、返すときには常に待機状態です。`onRejected` がエラーを発生させるか、それ自身が拒否されたプロミスを返す場合、最終的に拒否されます。そうでなければ、最終的に履行されます。

解説
--

`catch` メソッドは複合したプロミスの複合のエラー処理に使用されます。これは `Promise` を返すので、姉妹メソッドである `then()` と同様の方法で連鎖が可能です。

もしプロミスが拒否され、呼び出すべき拒否ハンドラーがない場合（ハンドラーは `then()`, `catch()`, `finally()` のいずれかを通して装着されます）、拒否イベントはホストから表面化されます。ブラウザーでは、これは `unhandledrejection` イベントとして発生します。もし、拒否されたプロミスにハンドラーが装着され、その拒否がすでに `unhandledrejection` イベントを発生していた場合、別の `rejectionhandled` イベントが発行されます。

`catch()` は内部的に、呼び出されたオブジェクトに対して `then()` を呼び出し、引数として `undefined` と `onRejected` を渡します。その呼び出された値がそのまま返されます。これは、メソッドをラップすればオブザーバーで監視することができます。

```js
// 元の Promise.prototype.then/catch をログを追加するだけ上書きする。
((Promise) => {
  const originalThen = Promise.prototype.then;
  const originalCatch = Promise.prototype.catch;

  Promise.prototype.then = function (...args) {
    console.log("Called .then on %o with arguments: %o", this, args);
    return originalThen.apply(this, args);
  };
  Promise.prototype.catch = function (...args) {
    console.error("Called .catch on %o with arguments: %o", this, args);
    return originalCatch.apply(this, args);
  };
})(Promise);

// 解決済みのプロミスに対する catch の呼び出し
Promise.resolve().catch(function XXX() {});

// ログ出力:
// Called .catch on Promise{} with arguments: Arguments{1} [0: function XXX()]
// Called .then on Promise{} with arguments: Arguments{2} [0: undefined, 1: function XXX()]
```

つまり、`undefined` を渡しても、返されたプロミスは拒否されるため、最終的にプロミスが拒否されないようにするための関数を渡さなければなりません。

`catch()` は `then()` を呼び出すだけなので、サブクラス化に対応しています。

**メモ:** 下記の例では、`Error` のインスタンスを例外として発生させています。同期 `throw` 文と同様、これは良い習慣と考えられています。さもなければ、捕捉を行う部分は引数が文字列かエラーかを調べる必要があり、スタックトレースのような貴重な情報を失う可能性があります。

例
-

### catch メソッドの使用とチェーン化

```js
const p1 = new Promise((resolve, reject) => {
  resolve("Success");
});

p1.then((value) => {
  console.log(value); // "Success!"
  throw new Error("oh, no!");
})
  .catch((e) => {
    console.error(e.message); // "oh, no!"
  })
  .then(
    () => console.log("after a catch the chain is restored"),
    () => console.log("Not fired due to the catch"),
  );

// 以下は、上記と同様に動作します
p1.then((value) => {
  console.log(value); // "Success!"
  return Promise.reject("oh, no!");
})
  .catch((e) => {
    console.error(e); // "oh, no!"
  })
  .then(
    () => console.log("after a catch the chain is restored"),
    () => console.log("Not fired due to the catch"),
  );
```

### エラーが発生したことを知る

エラーが発生すると、たいていの場合 `catch()` メソッドが呼び出されます。

```js
const p1 = new Promise((resolve, reject) => {
  throw new Error("Uh-oh!");
});

p1.catch((e) => {
  console.error(e); // "Uh-oh!"
});
```

非同期関数内で発生したエラーは、捕捉されないエラーとして扱われます。

```js
const p2 = new Promise((resolve, reject) => {
  setTimeout(() => {
    throw new Error("Uncaught Exception!");
  }, 1000);
});

p2.catch((e) => {
  console.error(e); // これは呼び出されない
});
```

`resolve` が呼び出された後に発生したエラーは無視されます。

```js
const p3 = new Promise((resolve, reject) => {
  resolve();
  throw new Error("Silenced Exception!");
});

p3.catch((e) => {
  console.error(e); // これは呼び出されない
});
```

### プロミスが履行されたときは catch() は呼び出されない

```js
// onReject を呼び出さないプロミスを作る
const p1 = Promise.resolve("calling next");

const p2 = p1.catch((reason) => {
  // これは呼び出されない
  console.error("catch p1!");
  console.error(reason);
});

p2.then(
  (value) => {
    console.log("next promise's onFulfilled");
    console.log(value); // 次を呼び出し
  },
  (reason) => {
    console.log("next promise's onRejected");
    console.log(reason);
  },
);
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-promise.prototype.catch |

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

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

関連情報
----

* `Promise`
* `Promise.prototype.then()`
* `Promise.prototype.finally()`


Promise.prototype.finally() - JavaScript

Promise.prototype.finally()
===========================

**`finally()`** は `Promise` のメソッドで、プロミスが決定したとき（履行されたか拒否されたかのどちらか）に呼び出される関数を準備します。直ちに同等の `Promise` オブジェクトを返すため、プロミスの他のメソッドを連鎖呼び出しすることができます。

これによって、プロミスの `then()` ハンドラーと `catch()` ハンドラーでコードが重複することを避けることができます。

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

構文
--

```js
finally(onFinally)

finally(() => {
  // プロミスの決定（履行または拒否）後に実行されるコード
})
```

### 引数

`onFinally`

`Promise` が決定したら呼び出される関数 (`Function`) です。このハンドラーは引数を取りません。

### 返値

同等の `Promise` を返します。ハンドラーがエラーを発生したり、拒否されたプロミスを返したりした場合、代わりに `finally()` が返すプロミスがその値で拒否されます。そうでなければ、ハンドラーの返す値は元のプロミスの状態に影響しません。

解説
--

プロミスが決定した後、結果に関わらず何らかの処理や後始末を行いたいなら、`finally()` メソッドは役立ちます。

`finally()` メソッドは `then(onFinally, onFinally)` の呼び出しとよく似ていますが、いくつかの点が異なります。

* 関数をインラインで作成する場合、関数を 2 度宣言するか、変数を作成するかのどちらかで、一度に渡すことができます。
* `onFinally` コールバックは一切引数を受け取りません。この用途では、拒否された理由や履行された値などを提供する必要がなく、それらを気にしないときに適しています。
* `finally()` の呼び出しは通常透過的で、元のプロミスの最終的な状態を変更することはありません。ですから例えば、
    + `Promise.resolve(2).then(() => 77, () => {})` が最終的に `77` の値で履行されるプロミスを返すのとは異なり、`Promise.resolve(2).finally(() => 77)` は最終的に `2` の値で履行されるプロミスを返します。
    + 同様に、`Promise.reject(3).then(() => {}, () => 88)` が最終的に `88` の値で履行されるプロミスを返すのとは異なり、`Promise.reject(3).finally(() => 88)` は最終的に `3` の値で拒否されるプロミスを返します。

**メモ:** `finally` コールバックの中で `throw` （あるいは拒否されたプロミスを返すこと）しても、返されたプロミスは拒否されます。例えば、 `Promise.reject(3).finally(() => { throw 99; })` と `Promise.reject(3).finally(() => Promise.reject(99))` はどちらも `99` という理由をつけて、返ってきたプロミスを拒否することになります。

`catch()` と同様に、 `finally()` は内部的に呼び出されたオブジェクトの `then` メソッドを呼び出します。もし `onFinally` が関数でない場合、 `then()` は `onFinally` を両方の引数として呼び出されます。これは `Promise.prototype.then()` にとって、有益なハンドラーが添付されないということを意味します。そうでなければ、`then()` は内部で作成された 2 つの関数で呼び出され、以下のような振る舞いをします。

**警告:** これは説明用のものであり、ポリフィルではありません。

```js
promise.then(
  (value) => Promise.resolve(onFinally()).then(() => value),
  (reason) =>
    Promise.resolve(onFinally()).then(() => {
      throw reason;
    }),
);
```

`finally()` は `then()` を呼び出すので、サブクラス化に対応しています。さらに、上記の `Promise.resolve()` の呼び出しに注目してください。実際には、 `onFinally()` の返値は `Promise.resolve()` と同じアルゴリズムで解決されますが、解決されたプロミスを構築するために使用される実際のコンストラクターはサブクラスとなります。 `finally()` はこのコンストラクターを `promise.constructor[@@species]` で取得します。

例
-

### finally() の使用

```js
let isLoading = true;

fetch(myRequest)
  .then((response) => {
    const contentType = response.headers.get("content-type");
    if (contentType && contentType.includes("application/json")) {
      return response.json();
    }
    throw new TypeError("Oops, we haven't got JSON!");
  })
  .then((json) => {
    /\* さらに JSON を処理します \*/
  })
  .catch((error) => {
    console.error(error); // この行は、 console = {} の場合など、例外が発生する可能性がある
  })
  .finally(() => {
    isLoading = false;
  });
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-promise.prototype.finally |

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

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

関連情報
----

* `Promise.prototype.finally` のポリフィル (`core-js`)
* `Promise`
* `Promise.prototype.then()`
* `Promise.prototype.catch()`


Promise.resolve() - JavaScript

Promise.resolve()
=================

**`Promise.resolve()`** は静的メソッドで、 `Promise` を与えられた値で「解決」させます。値がプロミスの場合は、そのプロミスが返されます。その値が Thenable であれば、`Promise.resolve()` は `then()` メソッドを、準備した 2 つのコールバックと共に呼び出します。それ以外の場合は、その値で履行するプロミスが返されます。

この関数は複数階層のプロミス風オブジェクト (例えば、何かで解決するプロミスで解決するプロミス) を単一の階層に平坦化します。

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

構文
--

```js
Promise.resolve(value)
```

### 引数

`value`

この `Promise` で解決する際の引数。解決するための `Promise` または Thenable にすることもできます。

### 返値

与えられた値で解決された `Promise`、または value がプロミスオブジェクトであった場合、値として渡されたプロミスです。解決されたプロミスは、履行、拒否、待機のいずれかの状態になることができます。例えば、拒否されたプロミスが解決しても、結果は拒否されたプロミスのままです。

解説
--

`Promise.resolve()` はプロミスを *解決* します。これはプロミスを履行したり拒否したりすることとは異なります。用語の定義については、プロミスの説明を参照してください。簡単に言うと、 `Promise.resolve()` は、最終的な状態が他のプロミス、 Thenable オブジェクト、または他の値に依存しているプロミスを返します。

`Promise.resolve()` は汎用で、サブクラス化を対応しています。つまり、`Promise` のサブクラスで呼び出すことができ、その結果はサブクラス型のプロミスになります。これを行うには、サブクラスのコンストラクターは `Promise()` コンストラクターと同じ定義で実装する必要があります。引数として `resolve` と `reject` コールバックで呼び出すことができる単一の `executor` 関数を受け入れることができます。

`Promise.resolve()` は、ネイティブの `Promise` のインスタンスを特別扱いしています。 `value` が `Promise` またはそのサブクラスに属し、 `value.constructor === Promise` の場合、新しい `Promise` インスタンスを作成せずに、`Promise.resolve()` で直接 `value` を返すことができます。そうでない場合、`Promise.resolve()` は基本的に `new Promise((resolve) => resolve(value))` の一括指定となります。

解決ロジックの大部分は，実際には `Promise()` コンストラクターに渡されるリゾルバー関数で実装されます。概要をまとめると、次のようになります。

* Thenable でない値が渡された場合，返されたプロミスはその値ですでに履行されたものとなります。
 Thenable が渡された場合、`then` メソッドを呼び出され、引数としてリゾルバー関数のペアを渡すことで、返されるプロミスはその Thenable の状態を採用することになります。（しかし、ネイティブのプロミスはラッパーを作成せずに直接 `Promise.resolve()` を通すので、ネイティブのプロミスでは `then` メソッドは呼ばれません）。リゾルバー関数が別の Thenable オブジェクトを受け取ると、それは再び解決されるので、最終的なプロミスの履行値は決して Thenable になることはないでしょう。
例
-

### 静的な Promise.resolve メソッドの使用

```js
Promise.resolve("Success").then(
  (value) => {
    console.log(value); // "Success"
  },
  (reason) => {
    // 呼び出されない
  },
);
```

### 配列で解決

```js
const p = Promise.resolve([1, 2, 3]);
p.then((v) => {
  console.log(v[0]); // 1
});
```

### 別の Promise で解決

`Promise.resolve()` は、既存の `Promise` インスタンスを再利用します。ネイティブのプロミスを解決する場合は、ラッパーを作成せずに同じプロミスインスタンスを返します。

```js
const original = Promise.resolve(33);
const cast = Promise.resolve(original);
cast.then((value) => {
  console.log(`value: ${value}`);
});
console.log(`original === cast ? ${original === cast}`);

// ログ（順番通り）:
// original === cast ? true
// value: 33
```

ログの順番が反転するのは、 `then` ハンドラーが非同期に呼び出されるために発生します。詳しくは `then()` のリファレンスを参照してください。

### Thenable で解決してエラーを発生させる

```js
// Thenable オブジェクトを解決
const p1 = Promise.resolve({
  then(onFulfill, onReject) {
    onFulfill("fulfilled!");
  },
});
console.log(p1 instanceof Promise); // true、オブジェクトが Promise にキャストされた

p1.then(
  (v) => {
    console.log(v); // "fulfilled!"
  },
  (e) => {
    // 呼び出されない
  },
);

// Thenable throws before callback
// Promise rejects
const thenable = {
  then(onFulfilled) {
    throw new TypeError("Throwing");
    onFulfilled("Resolving");
  },
};

const p2 = Promise.resolve(thenable);
p2.then(
  (v) => {
    // 呼び出されない
  },
  (e) => {
    console.error(e); // TypeError: Throwing
  },
);

// Thenable はコールバックの後で Promise が解決した場合に
// 例外を発生させます。
const thenable = {
  then(onFulfilled) {
    onFulfilled("Resolving");
    throw new TypeError("Throwing");
  },
};

const p3 = Promise.resolve(thenable);
p3.then(
  (v) => {
    console.log(v); // "Resolving"
  },
  (e) => {
    // not called
  },
);
```

入れ子になった Thenable は、単一のプロミスに「深く平坦化」されます。

```js
const thenable = {
  then(onFulfilled, onRejected) {
    onFulfilled({
      // The thenable is fulfilled with another thenable
      then(onFulfilled, onRejected) {
        onFulfilled(42);
      },
    });
  },
};

Promise.resolve(thenable).then((v) => {
  console.log(v); // 42
});
```

**警告:** 自分自身に解決する thenable に対して `Promise.resolve()` を呼び出さないでください。これは無限にネストしたプロミスを平坦化しようとするため、無限の再帰を引き起こします。

```js
const thenable = {
  then(onFulfilled, onRejected) {
    onFulfilled(thenable);
  },
};

Promise.resolve(thenable); // 無z限の再帰を引き起こす
```

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

`Promise.resolve()` は汎用的なメソッドです。これは `Promise()` コンストラクタと同じ定義を実装した任意のコンストラクターで呼び出すことができます。例えば、`resolve` として `console.log` を渡すコンストラクターで呼び出すことができます。

```js
class NotPromise {
  constructor(executor) {
    // "resolve" と "reject" 関数はネイティブのプロミスと同じような振る舞いはしませんが、
    // Promise.resolve() は同じようにそれらを呼び出します。
    executor(
      (value) => console.log("Resolved", value),
      (reason) => console.log("Rejected", reason),
    );
  }
}

Promise.resolve.call(NotPromise, "foo"); // Logs "Resolved foo"
```

入れ子になった Thenable を平坦化する機能は `Promise()` コンストラクターのリゾルバー関数で実装されています。そのため、他のコンストラクターで呼び出すと、そのコンストラクターがリゾルバーをどのように実装しているかによって入れ子の Thenable が平坦化されない場合があります。

```js
const thenable = {
  then(onFulfilled, onRejected) {
    onFulfilled({
      // Thenable は他の Thenable に履行されます
      then(onFulfilled, onRejected) {
        onFulfilled(42);
      },
    });
  },
};

Promise.resolve.call(NotPromise, thenable); // "Resolved { then: [Function: then] }" と出力
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-promise.resolve |

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

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

関連情報
----

* `Promise`


Promise.prototype.then() - JavaScript

Promise.prototype.then()
========================

**`then()`** は `Promise` オブジェクトのメソッドであり、最大 2 つの引数として、 `Promise` が成功した場合と失敗した場合のコールバック関数を取ります。これは直ちに同等の `Promise` オブジェクトを返し、プロミスの他のメソッドを連鎖呼び出し

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

構文
--

```js
then(onFulfilled)
then(onFulfilled, onRejected)

then(
  (value) => { /\* 履行ハンドラー \*/ },
  (reason) => { /\* 拒否ハンドラー \*/ },
)
```

### 引数

`onFulfilled` 省略可

`Promise` が成功したときに非同期に呼び出される関数 (`Function`) です。この関数は 1 つの引数、 *履行値* を取ります。これが関数ではない場合は、内部的に、履行された値を送るための *識別* 関数 (`(x) => x`) に置き換えられます。

`onRejected` 省略可

`Promise` が拒否されたときに非同期に呼び出される関数 (`Function`) です。この関数は 1 つの引数、 *拒否理由* を取ります。これが関数ではない場合は、内部的に引数として受け取ったエラーを投げる *スロワー* 関数 (`(x) => { throw x; }`) に置き換えられます。

### 返値

新しい `Promise` をすぐに返します。この新しいプロミスは、現在のプロミスの状態に関係なく、返すときには常に待機状態です。

`onFulfilled` と `onRejected` ハンドラーのいずれかが実行され、現在のプロミスの履行されたか拒否されたかが処理されます。この呼び出しは、現在のプロミスが既に決定されている場合でも、常に非同期で行われます。返されたプロミス（`p` と呼ぶ）の振る舞いは、ハンドラーの実行結果に依存し、一連の特定のルールに従います。もしハンドラー関数が、

* 値を返した場合、 `p` は返値をその値として履行されます。
* 何も返さなかった場合、 `p` は `undefined` の値で履行されます。
* エラーを投げた場合、 `p` はその値としてエラーを投げて拒否されます。
* すでに履行されたプロミスを返した場合、 `p` は、そのプロミスの値をその値として履行されます。
* すでに拒否されたプロミスを返した場合、 `p` は、そのプロミスの値をその値として拒否されます。
* 他の待機状態のプロミスオブジェクトを返した場合、 `then` から返されたプロミスの履行/拒否は、ハンドラーによって返されたプロミスの履行/拒否結果に依存します。また、 `then` から返されたプロミスの解決値は、ハンドラーによって返されたプロミスの解決値と同じになります。
解説
--

`then()` メソッドは、プロミスの最終的な完了（履行されるか拒否されるか）のためにコールバック関数をスケジュールします。これはプロミスの基本メソッドです。Thenable プロトコルはすべてのプロミス型オブジェクトが `then()` メソッドを公開することを想定しており、`catch()` と `finally()` メソッドは、どちらもオブジェクトの `then()` メソッドを呼び出すことで動作するようになっています。

`onRejected` ハンドラーの詳細については、 `catch()` のリファレンスを参照してください。

`then()` は、新しいプロミスオブジェクトを返すことです。同じプロミスオブジェクトで `then()` メソッドを 2 回呼び出すと（連鎖するのではなく）、このプロミスオブジェクトは 2 組の決定ハンドラーを保有することになります。同じプロミスオブジェクトに付けられたすべてのハンドラーは、常に追加された順番に呼び出されます。さらに、 `then()` の各呼び出しによって返される 2 つのプロミスは、別個の連鎖を始め、お互いの決定を待つことはありません。

`then()` チェーンに沿って発生する Thenable オブジェクトは常に解決されます。`onFulfilled` ハンドラーは thenable オブジェクトを決して受け取らず、いずれかのハンドラーによって返される thenable は常に次のハンドラーに渡される前に解決されます。これは、新しいプロミスを構築するときに、 `executor` から渡された `resolve` 関数と `reject` 関数が保存され、現在のプロミスが決定したときに、それぞれの関数が履行された値または拒絶の理由とともに呼び出されるからです。解決ロジックは、 `Promise()` コンストラクターから渡されるリゾルバー関数から決まります。

`then()` はサブクラス化に対応しており、`Promise` のサブクラスのインスタンスに対して呼び出すことができ、その結果はサブクラスの型のプロミスになります。返す値の種類は `@@species` プロパティでカスタマイズすることができます。

例
-

### then() メソッドの使用

```js
const p1 = new Promise((resolve, reject) => {
  resolve("Success!");
  // or
  // reject(new Error("Error!"));
});

p1.then(
  (value) => {
    console.log(value); // Success!
  },
  (reason) => {
    console.error(reason); // Error!
  },
);
```

### どちらかの引数に関数以外を指定

```js
Promise.resolve(1).then(2).then(console.log); // 1
Promise.reject(1).then(2, 2).then(console.log, console.log); // 1
```

### 連鎖

`then` メソッドは `Promise` を返すので、メソッド連鎖ができます。

関数が `then` にハンドラーとして渡されると `Promise` を返します。同じ `Promise` がメソッド連鎖の次の `then` に現れます。次のスニペットは、非同期実行をシミュレートする、 `setTimeout` 関数付きのコードです。

```js
Promise.resolve("foo")
  // 1. Receive "foo", concatenate "bar" to it, and resolve that to the next then
  .then(
    (string) =>
      new Promise((resolve, reject) => {
        setTimeout(() => {
          string += "bar";
          resolve(string);
        }, 1);
      }),
  )
  // 2. receive "foobar", register a callback function to work on that string
  // and print it to the console, but not before returning the unworked on
  // string to the next then
  .then((string) => {
    setTimeout(() => {
      string += "baz";
      console.log(string); // foobarbaz
    }, 1);
    return string;
  })
  // 3. print helpful messages about how the code in this section will be run
  // before the string is actually processed by the mocked asynchronous code in the
  // previous then block.
  .then((string) => {
    console.log(
      "Last Then: oops... didn't bother to instantiate and return a promise in the prior then so the sequence may be a bit surprising",
    );

    // Note that `string` will not have the 'baz' bit of it at this point. This
    // is because we mocked that to happen asynchronously with a setTimeout function
    console.log(string); // foobar
  });

// Logs, in order:
// Last Then: oops... didn't bother to instantiate and return a promise in the prior then so the sequence may be a bit surprising
// foobar
// foobarbaz
```

`then()` から返される値は、`Promise.resolve()` と同じ方法で解決されます。つまり、Thenable オブジェクトが対応していて、返値がプロミスでない場合は、暗黙のうちに `Promise` でラップされ、その後解決されます。

```js
const p2 = new Promise((resolve, reject) => {
  resolve(1);
});

p2.then((value) => {
  console.log(value); // 1
  return value + 1;
}).then((value) => {
  console.log(value, " - A synchronous value works"); // 2 - A synchronous value works
});

p2.then((value) => {
  console.log(value); // 1
});
```

`then` の引数として渡した関数が拒否されたプロミスを返した場合や、例外（エラー）が発生した場合は、拒否されたプロミスを返します。

```js
Promise.resolve()
  .then(() => {
    // Makes .then() return a rejected promise
    throw new Error("Oh no!");
  })
  .then(
    () => {
      console.log("Not called.");
    },
    (error) => {
      console.error(`onRejected function called: ${error.message}`);
    },
  );
```

現実的には、`catch()` を使って拒否されたプロミスを捕捉する方が、 `then()` の 2 つの引数の構文を使って処理するよりも現実的です。下記の例を見てください。

```js
Promise.resolve()
  .then(() => {
    // Makes .then() return a rejected promise
    throw new Error("Oh no!");
  })
  .catch((error) => {
    console.error(`onRejected function called: ${error.message}`);
  })
  .then(() => {
    console.log("I am always called even if the prior then's promise rejects");
  });
```

他にもすべての場合において、返されたプロミスは最終的に履行されます。以下の例では、最初の `then()` は、チェーン内の前のプロミスが拒否されたにもかかわらず、履行されたプロミスに包まれた `42` を返します。

```js
Promise.reject()
  .then(
    () => 99,
    () => 42,
  ) // onRejected は履行されたプロミスにラップされた 42 を返す
  .then((solution) => console.log(`Resolved with ${solution}`)); // Fulfilled with 42
```

もし `onFulfilled` がプロミスを返した場合、 `then` の返値はそのプロミスの最終的な状態に基づいて履行される/拒否されることになります。

```js
function resolveLater(resolve, reject) {
  setTimeout(() => {
    resolve(10);
  }, 1000);
}
function rejectLater(resolve, reject) {
  setTimeout(() => {
    reject(new Error("Error"));
  }, 1000);
}

const p1 = Promise.resolve("foo");
const p2 = p1.then(() => {
  // Return promise here, that will be resolved to 10 after 1 second
  return new Promise(resolveLater);
});
p2.then(
  (v) => {
    console.log("resolved", v); // "resolved", 10
  },
  (e) => {
    // not called
    console.error("rejected", e);
  },
);

const p3 = p1.then(() => {
  // Return promise here, that will be rejected with 'Error' after 1 second
  return new Promise(rejectLater);
});
p3.then(
  (v) => {
    // not called
    console.log("resolved", v);
  },
  (e) => {
    console.error("rejected", e); // "rejected", 'Error'
  },
);
```

プロミスベースの API を使用する関数を別の関数の上に実装するために、チェーニングを使用することができます。

```js
function fetchCurrentData() {
  // fetch() API はプロミスを返します。この関数は
  // 同様のAPIを公開していますが、この関数の
  // プロミスの履行された値には、より多くの作業が
  // 施されていることが特徴です。
  return fetch("current-data.json").then((response) => {
    if (response.headers.get("content-type") !== "application/json") {
      throw new TypeError();
    }
    const j = response.json();
    // おそらく j で何かをする

    // fulfillment value given to user of
    // fetchCurrentData().then()
    return j;
  });
}
```

### then() の非同期性

以下は `then` メソッドの非同期性を示す例である。

```js
// 例として解決済みのプロミス 'resolvedProm' を使用すると、
// 関数呼び出し 'resolvedProm.then(...)' は直ちに新しいプロミスを返しますが、
// そのハンドラー '(value) => {...}' は console.log で示されるように非同期に呼ばれることになります。
// 新しいプロミスは 'thenProm' に代入され、
// thenProm はハンドラーが返す値で解決されます。
const resolvedProm = Promise.resolve(33);
console.log(resolvedProm);

const thenProm = resolvedProm.then((value) => {
  console.log(
    `this gets called after the end of the main stack. the value received is: ${value}, the value returned is: ${
 value + 1
 }`,
  );
  return value + 1;
});
console.log(thenProm);

// setTimeout を使用すると、スタックが空になった瞬間まで関数の実行を延期することができる
setTimeout(() => {
  console.log(thenProm);
});

// Logs, in order:
// Promise {[[PromiseStatus]]: "resolved", [[PromiseResult]]: 33}
// Promise {[[PromiseStatus]]: "pending", [[PromiseResult]]: undefined}
// "this gets called after the end of the main stack. the value received is: 33, the value returned is: 34"
// Promise {[[PromiseStatus]]: "resolved", [[PromiseResult]]: 34}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-promise.prototype.then |

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

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

関連情報
----

* `Promise`
* `Promise.prototype.catch()`