recursal/MDN huggingface dataset:
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`

一个数值

描述
--

`asin` 方法接受 -1 到 1 之间的数值作为参数，返回一个介于 


-

π
2

-\frac{\pi}{2}

 到 


π
2

\frac{\pi}{2}

 弧度的数值。如果接受的参数值超出范围，则返回 `NaN`。

由于 `asin` 是 `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.imul()
===========

该函数将两个参数分别转换为 32 位整数，相乘后返回 32 位结果，类似 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 会将浮点数转换为整数，相乘后会将整数重新转换为浮点数，这两步转换的开销是比较大的。imul 存在的原因是在 AsmJS(目前为止唯一一种环境) 下它是快速的。AsmJS 使 JIST-optimizers 更容易实现 JavaScript 内部的整数。现代浏览器中，唯一能体现出 imul 性能优越的场景是两个 Number 内部以整数的形式相乘 (仅在 AsmJS 下可行)。

示例
--


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

规范
--

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

浏览器兼容性
------

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

参见
--

* `core-js` 中 `Math.imul` 的 Polyfill
* 维基百科上的 Emscripten 词条
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`

一个数值

描述
--

`atan` 返回一个 


-

π
2

-\frac{\pi}{2}

 到 


π
2

\frac{\pi}{2}

 弧度之间的数值。

由于 `atan` 是 `Math` 的静态方法，所以应该像这样使用：`Math.atan()`，而不是作为你创建的 `Math` 实例的方法。

示例
--

### 示例：使用 `Math.atan`


```js
Math.atan(1); // 0.7853981633974483
Math.atan(0); // 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.random()
=============

**`Math.random()`** 函数返回一个浮点数，伪随机数在范围从**0 到**小于**1**，也就是说，从 0（包括 0）往上，但是不包括 1（排除 1），然后你可以缩放到所需的范围。实现将初始种子选择到随机数生成算法;它不能被用户选择或重置。尝试一下
----

**备注：** `Math.random()` *不能*提供像密码一样安全的随机数字。不要使用它们来处理有关安全的事情。使用 Web Crypto API 来代替，和更精确的`window.crypto.getRandomValues()` 方法。

语法
--
```

Math.random()
```

### 返回值

一个浮点型伪随机数字，在`0`（包括 0）和`1`（不包括）之间。

示例
--

请注意，由于 JavaScript 中的数字是 IEEE 754 浮点数字，具有最近舍入（round-to-nearest-even）的行为，因此以下函数的范围 (不包括`Math.random()` 本身) 并不准确。如果选择了非常大的边界 (2^53 或更高), 在极罕见的情况下会计算通常 - 排除（usually-excluded）的上界。（注：round-to-nearest-even 采用最近舍入的去偶数舍入的方式，对.5 的舍入上，采用取偶数的方式）

### 得到一个大于等于 0，小于 1 之间的随机数


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

### 得到一个两数之间的随机数

这个例子返回了一个在指定值之间的随机数。这个值不小于 `min`（有可能等于），并且小于（不等于）`max`。


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

### 得到一个两数之间的随机整数

这个例子返回了一个在指定值之间的随机整数。这个值不小于 `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; //不含最大值，含最小值
}
```


**备注：** 也许很容易想到用 `Math.round()` 来实现，但是这会导致你的随机数处于一个不均匀的分布，这可能不符合你的需求。

### 得到一个两数之间的随机整数，包括两个数在内

上一个例子提到的函数 `getRandomInt()` 结果范围包含了最小值，但不含最大值。如果你的随机结果需要同时包含最小值和最大值，怎么办呢？`getRandomIntInclusive()` 函数可以实现。


```js
function getRandomIntInclusive(min, max) {
  min = Math.ceil(min);
  max = Math.floor(max);
  return Math.floor(Math.random() \* (max - min + 1)) + min; //含最大值，含最小值
}
```

规范
--

| 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.log10()
============

概述
--

**`Math.log10()`** 函数返回一个数字以 10 为底的对数。

语法
--
```

Math.log10(x)
```

### 参数

`x`

任意数字。

描述
--

如果传入的参数小于 0，则返回 NaN.

示例
--


```js
Math.log10(10); // 1
Math.log10(100); // 2
Math.log10("100"); // 2
Math.log10(1); // 0
Math.log10(0); // -Infinity
Math.log10(-2); // NaN
Math.log10("foo"); // NaN
```

规范
--

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

浏览器兼容性
------

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

参见
--

* `core-js` 中 `Math.log10` 的 polyfill
* `Math.exp()`
* `Math.log()`
* `Math.log1p()`
* `Math.log2()`
* `Math.pow()`
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{ 唯一的} ; y \geq 0 ; \text{使得} ; \cosh(y) = x

尝试一下
----

语法
--


```js
Math.acosh(x)
```

### 参数

`x`

一个数字。

### 返回值

返回给定数的反双曲余弦值，如果该数小于 **1** 则返回 `NaN`。

描述
--

因为 `acosh()` 是 `Math` 的静态方法，所以你应该通过 `Math.acosh()` 调用，而不是作为你创建的 `Math` 对象的方法（`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.cosh()
===========

**`Math.cosh()`** 函数返回数值的双曲余弦函数，可用 constant e 表示：


Math.cosh(x)

=

e
x

+

e

-
x

2

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

语法
--
```

Math.cosh(x)
```

### 参数

`x`

数值。

描述
--

由于 `cosh()` 是 Math 的静态函数，只需通过 `Math.cosh()` 调用，而不用通过创建 Math 对象来调用。

示例
--

### 使用 `Math.cosh()`


```js
Math.cosh(0); // 1
Math.cosh(1); // 1.5430806348152437
Math.cosh(-1); // 1.5430806348152437
```

规范
--

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

浏览器兼容性
------

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

参见
--

* `core-js` 中 `Math.cosh` 的 polyfill
* `Math.acosh()`
* `Math.asinh()`
* `Math.atanh()`
* `Math.sinh()`
* `Math.tanh()`
Math.max()
==========

**`Math.max()`** 函数返回作为输入参数的最大数字，如果没有参数，则返回 -`Infinity`。

尝试一下
----

语法
--


```js
Math.max()
Math.max(value0)
Math.max(value0, value1)
Math.max(value0, value1, /\* … ,\*/ valueN)
```

### 参数

`value1`, `value2`, … , `valueN`

0 个或多个数字，将在其中选择，并返回最大的值。

### 返回值

给定数值中最大的数。如果任一参数不能转换为数值，则返回 `NaN`。如果没有提供参数，返回 -`Infinity`。

描述
--

因为 `max()` 是 `Math` 的静态方法，所以你应始终使用 `Math.max()`，而不是作为你创建的 `Math` 对象的方法（`Math` 不是构造函数）。

`Math.max.length` 是 2，这从某种程度上表明了它旨在处理至少两个参数。

示例
--

### 使用 Math.max()


```js
Math.max(10, 20); // 20
Math.max(-10, -20); // -10
Math.max(-10, 20); // 20
```

### 获取数组的最大元素

`Array.prototype.reduce()` 可以用来查找最大值元素，通过比较每个值：


```js
const arr = [1, 2, 3];
const max = arr.reduce((a, b) => Math.max(a, b), -Infinity);
```


下面的方法使用 `Function.prototype.apply()` 来获取数组的最大值。`getMaxOfArray([1, 2, 3])` 相当于 `Math.max(1, 2, 3)`，但是你可以使用 `getMaxOfArray()` 作用于任意长度的数组上。这应该只用于元素相对较少的数组。


```js
function getMaxOfArray(numArray) {
  return Math.max.apply(null, numArray);
}
```


展开语法是编写 `apply` 解决方案的一种更简短的方法，可以最大限度地利用数组：


```js
const arr = [1, 2, 3];
const max = Math.max(...arr);
```


但是，如果数组有太多的元素，展开语法（`...`）和 `apply` 都将失败或返回错误的结果，因为它们试图将数组元素作为函数形参传递。参见使用 apply 和内置函数了解更多细节。`reduce` 解决方案不存在这个问题。

规范
--

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

浏览器兼容性
------

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

参见
--

* `Math.min()`
Math.min()
==========

**`Math.min()`** 函数返回作为输入参数的数字中最小的一个，如果没有参数，则返回 `Infinity`。

尝试一下
----

语法
--


```js
Math.min()
Math.min(value0)
Math.min(value0, value1)
Math.min(value0, value1, /\* … ,\*/ valueN)
```

### 参数

`value1`, …, `valueN`

0 个或多个数字，将在其中选择，并返回最小值。

### 返回值

给定数值中最小的数。如果任一参数不能转换为数值，则返回 `NaN`。如果没有提供参数，返回 `Infinity`。

描述
--

因为 `min()` 是 `Math` 的静态方法，所以你应始终使用 `Math.min()`，而不是作为你创建的 `Math` 对象的方法（`Math` 不是构造函数）。

`Math.min.length` 是 2，这从某种程度上表明了它旨在处理至少两个参数。

示例
--

### 使用 Math.min()

下例找出 `x` 和 `y` 的最小值，并把它赋值给 `z`：


```js
const x = 10;
const y = -20;
const z = Math.min(x, y); // -20
```

### 使用 Math.min() 裁剪值

`Math.min()` 经常用于裁剪一个值，以便使其总是小于或等于某个边界值。例如：


```js
let x = f(foo);

if (x > boundary) {
  x = boundary;
}
```


可以写成：


```js
const x = Math.min(f(foo), boundary);
```


`Math.max()` 可以以类似的方式用于在另一端裁剪一个值。

规范
--

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

浏览器兼容性
------

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

参见
--

* `Math.max()`
Math.sqrt()
===========

**`Math.sqrt()`** 函数返回一个数的平方根，即：



∀
x
≥
0
,

M
a
t
h
.
s
q
r
t
(
x
)

=

x

=
the unique

y
≥
0

such that

y
2

=
x

\forall x \geq 0, \mathtt{Math.sqrt(x)} = \sqrt{x} = \text{the unique} ; y \geq 0 ; \text{such that} ; y^2 = x

尝试一下
----

语法
--
```

Math.sqrt(x)
```

### 参数

`x`

一个数值

描述
--

如果参数 `number` 为负值，则 `sqrt` 返回`NaN`。

由于 `sqrt` 是 `Math` 的静态方法，所以应该像这样使用：`Math.sqrt()`，而不是作为你创建的 `Math` 实例的方法。

示例
--

### 使用 `Math.sqrt`
```

Math.sqrt(9); // 3
Math.sqrt(2); // 1.414213562373095

Math.sqrt(1);  // 1
Math.sqrt(0);  // 0
Math.sqrt(-1); // NaN
Math.sqrt(-0); // -0
```

规范
--

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

浏览器兼容性
------

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

参见
--

* `Math.cbrt()`
* `Math.exp()`
* `Math.log()`
* `Math.pow()`
Atomics.isLockFree()
====================

**`Atomics.isLockFree()`** 静态方法用于判断 `Atomics` 在将具有给定字节大小的元素应用于类型化数组时是否会使用锁或原子硬件操作。如果给定的大小不是整数类型化数组类型的 BYTES\_PER\_ELEMENT 属性之一，则返回 `false`。

尝试一下
----

语法
--


```js
Atomics.isLockFree(size)
```

### 参数

`size`

要检查的大小（以字节为单位）。

### 返回值

`true` 或 `false`，指示操作字节是否不涉及锁。

示例
--

### 使用 isLockFree()


```js
Atomics.isLockFree(1); // true
Atomics.isLockFree(2); // true
Atomics.isLockFree(3); // false
Atomics.isLockFree(4); // true
Atomics.isLockFree(5); // false
Atomics.isLockFree(6); // false
Atomics.isLockFree(7); // false
Atomics.isLockFree(8); // true
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.islockfree |

浏览器兼容性
------

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

参见
--

* `Atomics`
Atomics.load()
==============

**`Atomics.load()`** 静态方法返回数组中指定位置的值。

尝试一下
----

语法
--


```js
Atomics.load(typedArray, index)
```

### 参数

`typedArray`

一个整数类型数组。`Int8Array`、`Uint8Array`、`Int16Array`、`Uint16Array`、`Int32Array`、`Uint32Array`、`BigInt64Array` 或 `BigUint64Array` (en-US) 之一。

`index`

`typedArray` 中的要加载的位置。

### 返回值

给定位置的值（`typedArray[index]`）。

### 异常

`TypeError`

如果 `typedArray` 不是允许的整数类型数组之一，则抛出该异常。

`RangeError`

如果 `index` 超出 `typedArray` 的范围，则抛出该异常。

示例
--

### 使用 load()


```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);

Atomics.add(ta, 0, 12);
Atomics.load(ta, 0); // 12
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.load |

浏览器兼容性
------

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

参阅
--

* `Atomics`
* `Atomics.store()`
Atomics.add()
=============

**`Atomics.add()`** 静态方法会将给定的值加到数组里的指定位置上，并返回该位置的旧值。此原子操作保证在修改后的值写回之前不会发生其他写操作。

尝试一下
----

语法
--


```js
Atomics.add(typedArray, index, value)
```

### 参数

`typedArray`

一个整数类型数组。`Int8Array`、`Uint8Array`、`Int16Array`、`Uint16Array`、`Int32Array`、`Uint32Array`、`BigInt64Array` 或 `BigUint64Array` (en-US) 之一。

`index`

`typedArray` 中的要加上 `value` 的位置。

`value`

要增加的数字。

### 返回值

给定位置的旧值（`typedArray[index]`）。

### 异常

`TypeError`

如果 `typedArray` 不是允许的整数类型数组之一，则抛出该异常。

`RangeError`

如果 `index` 超出 `typedArray` 的范围，则抛出该异常。

示例
--

### 使用 add()


```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);

Atomics.add(ta, 0, 12); // 返回 0，即旧的值
Atomics.load(ta, 0); // 12
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.add |

浏览器兼容性
------

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

参见
--

* `Atomics`
* `Atomics.sub()`
Atomics.waitAsync()
===================

**`Atomics.waitAsync()`** 静态方法异步等待共享内存的特定位置并返回一个 `Promise`。

与 `Atomics.wait()` 不同，`waitAsync` 是非阻塞的且可用于主线程。

**备注：** 此操作仅适用于基于 `SharedArrayBuffer` 的 `Int32Array` 或 `BigInt64Array` 视图。

语法
--


```js
Atomics.waitAsync(typedArray, index, value)
Atomics.waitAsync(typedArray, index, value, timeout)
```

### 参数

`typedArray`

基于 `SharedArrayBuffer` 的 `Int32Array` 或 `BigInt64Array`。

`index`

`typedArray` 中要等待的位置。

`value`

要测试的期望值。

`timeout` 可选

等待时间，以毫秒为单位。`NaN`（以及会被转换为 `NaN` 的值，例如 `undefined`）会被转换为 `Infinity`。负值会被转换为 `0`。

### 返回值

一个 `Object`，包含以下属性：

`async`

一个布尔值，指示 `value` 属性是否为 `Promise`。

`value`

如果 `async` 是 `false`，它将是一个内容为 `"not-equal"` 或 `"timed-out"` 的字符串（仅当 `timeout` 参数为 `0` 时）。如果 `async` 是 `true`，它将会是一个 `Promise`，其兑现值为一个内容为 `"ok"` 或 `"timed-out"` 的字符串。这个 promise 永远不会被拒绝。

### 异常

`TypeError`

如果 `typedArray` 不是一个基于 `SharedArrayBuffer` 的 `Int32Array` 或 `BigInt64Array`，则抛出该异常。

`RangeError`

如果 `index` 超出 `typedArray` 的范围，则抛出该异常。

示例
--

### 使用 waitAsync()

给定一个共享的 `Int32Array`。


```js
const sab = new SharedArrayBuffer(1024);
const int32 = new Int32Array(sab);
```


令一个读取线程休眠并在位置 0 处等待，预期该位置的值为 0。`result.value` 将是一个 promise。


```js
const result = Atomics.waitAsync(int32, 0, 0, 1000);
// { async: true, value: Promise {<pending>} }
```


在该读取线程或另一个线程中，对内存位置 0 调用以令该 promise 解决为 `"ok"`。


```js
Atomics.notify(int32, 0);
// { async: true, value: Promise {<fulfilled>: 'ok'} }
```


如果它没有解决为 `"ok"`，则共享内存该位置的值不符合预期（`value` 将是 `"not-equal"` 而不是一个 promise）或已经超时（该 promise 将解决为 `"time-out"`）。

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.waitasync |

浏览器兼容性
------

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

参见
--

* `Atomics`
* `Atomics.wait()`
* `Atomics.notify()`
Atomics.exchange()
==================

**`Atomics.exchange()`** 静态方法会将给定的值替换数组上指定位置的值，并返回该位置的旧值。此原子操作保证在修改后的值写回之前不会发生其他写操作。

尝试一下
----

语法
--


```js
Atomics.exchange(typedArray, index, value)
```

### 参数

`typedArray`

一个整数类型数组。`Int8Array`、`Uint8Array`、`Int16Array`、`Uint16Array`、`Int32Array`、`Uint32Array`、`BigInt64Array` 或 `BigUint64Array` (en-US) 之一。

`index`

`typedArray` 中的要替换为 `value` 的位置。

`value`

要替换的数字。

### 返回值

给定位置的旧值（`typedArray[index]`）。

### 异常

`TypeError`

如果 `typedArray` 不是允许的整数类型数组之一，则抛出该异常。

`RangeError`

如果 `index` 超出 `typedArray` 的范围，则抛出该异常。

示例
--

### 使用 exchange()


```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);

Atomics.exchange(ta, 0, 12); // 返回 0，即旧的值
Atomics.load(ta, 0); // 12
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.exchange |

浏览器兼容性
------

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

参见
--

* `Atomics`
* `Atomics.compareExchange()`
Atomics.notify()
================

**`Atomics.notify()`** 静态方法唤醒一些在等待队列中休眠的代理。

**备注：** 此操作仅适用于基于 `SharedArrayBuffer` 的 `Int32Array` 或 `BigInt64Array` 视图。对于非共享的 `ArrayBuffer` 对象，其将返回 `0`。

语法
--


```js
Atomics.notify(typedArray, index, count)
```

### 参数

`typedArray`

基于 `SharedArrayBuffer` 的 `Int32Array` 或 `BigInt64Array`。

`index`

`typedArray` 中要唤醒的位置。

`count` 可选

要唤醒的休眠代理的数量。默认为 `Infinity`。

### 返回值

* 返回唤醒的代理数量。
* 如果在非共享的 `ArrayBuffer` 上调用则返回 `0`。
### 异常

`TypeError`

如果 `typedArray` 不是一个基于 `SharedArrayBuffer` 的 `Int32Array` 或 `BigInt64Array`，则抛出该异常。

`RangeError`

如果 `index` 超出 `typedArray` 的范围，则抛出该异常。

示例
--

### 使用 notify()

给定一个共享的 `Int32Array`：


```js
const sab = new SharedArrayBuffer(1024);
const int32 = new Int32Array(sab);
```


令一个读取线程休眠并在位置 0 处等待，预期该位置的值为 0。只要条件一直为真，则将不会继续运行。然而，一旦写入线程存储了一个新的值，它将被读取线程唤醒并返回新的值（123）。


```js
Atomics.wait(int32, 0, 0);
console.log(int32[0]); // 123
```


写入线程存储一个新的值并在写入后唤醒等待的线程：


```js
console.log(int32[0]); // 0;
Atomics.store(int32, 0, 123);
Atomics.notify(int32, 0, 1);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.notify |

浏览器兼容性
------

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

参见
--

* `Atomics`
* `Atomics.wait()`
* `Atomics.waitAsync()`
Atomics.compareExchange()
=========================

如果给定的预期值等于旧值，**`Atomics.exchange()`** 静态方法会用给定的值替换数组上指定位置的值，并返回该位置的旧值，无论其是否等于预期的值。此原子操作保证在修改后的值写回之前不会发生其他写操作。

尝试一下
----

语法
--


```js
Atomics.compareExchange(typedArray, index, expectedValue, replacementValue)
```

### 参数

`typedArray`

一个整数类型数组。`Int8Array`、`Uint8Array`、`Int16Array`、`Uint16Array`、`Int32Array`、`Uint32Array`、`BigInt64Array` 或 `BigUint64Array` (en-US) 之一。

`index`

`typedArray` 中的要替换为 `replacementValue` 的位置。

`expectedValue`

用于检查相等性的值。

`replacementValue`

要替换的值。

### 返回值

给定位置的旧值（`typedArray[index]`）。

### 异常

`TypeError`

如果 `typedArray` 不是允许的整数类型数组之一，则抛出该异常。

`RangeError`

如果 `index` 超出 `typedArray` 的范围，则抛出该异常。

示例
--

### 使用 compareExchange()


```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);
ta[0] = 7;

Atomics.compareExchange(ta, 0, 7, 12); // 返回 7，即旧的值
Atomics.load(ta, 0); // 12
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.compareexchange |

浏览器兼容性
------

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

参见
--

* `Atomics`
* `Atomics.exchange()`
Atomics.and()
=============

**`Atomics.and()`** 静态方法会将给定的值与数组指定位置上的值进行按位与运算，并返回该位置的旧值。此原子操作保证在修改后的值写回之前不会发生其他写操作。

尝试一下
----

语法
--


```js
Atomics.and(typedArray, index, value)
```

### 参数

`typedArray`

一个整数类型数组。`Int8Array`、`Uint8Array`、`Int16Array`、`Uint16Array`、`Int32Array`、`Uint32Array`、`BigInt64Array` 或 `BigUint64Array` (en-US) 之一。

`index`

`typedArray` 中要进行按位与运算的位置。

`value`

要进行按位与运算的值。

### 返回值

给定位置的旧值（`typedArray[index]`）。

### 异常

`TypeError`

如果 `typedArray` 不是允许的整数类型数组之一，则抛出该异常。

`RangeError`

如果 `index` 超出 `typedArray` 的范围，则抛出该异常。

描述
--

当且仅当 `a` 和 `b` 都为 1 时，按位与运算结果为 1。与运算的真值表如下：

| `a` | `b` | `a & b` |
| --- | --- | --- |
| 0 | 0 | 0 |
| 0 | 1 | 0 |
| 1 | 0 | 0 |
| 1 | 1 | 1 |

例如，`5 & 1` 按位与运算的结果是 `0001`，也就是十进制的 1。
```

5  0101
1  0001
   ----

1  0001
```

示例
--

### 使用 and()


```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);
ta[0] = 5;

Atomics.and(ta, 0, 1); // 返回 5，即旧的值
Atomics.load(ta, 0); // 1
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.and |

浏览器兼容性
------

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

参见
--

* `Atomics`
* `Atomics.or()`
* `Atomics.xor()`
Atomics.store()
===============

**`Atomics.store()`** 静态方法将给定的值存储在数组中的指定位置，并返回该值。

尝试一下
----

语法
--


```js
Atomics.store(typedArray, index, value)
```

### 参数

`typedArray`

一个整数类型数组。`Int8Array`、`Uint8Array`、`Int16Array`、`Uint16Array`、`Int32Array`、`Uint32Array`、`BigInt64Array` 或 `BigUint64Array` (en-US) 之一。

`index`

`typedArray` 中的要存储 `value` 的位置。

`value`

要存储的数字。

### 返回值

已存储的值。

### 异常

`TypeError`

如果 `typedArray` 不是允许的整数类型数组之一，则抛出该异常。

`RangeError`

如果 `index` 超出 `typedArray` 的范围，则抛出该异常。

示例
--

### 使用 store()


```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);

Atomics.store(ta, 0, 12); // 12
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.store |

浏览器兼容性
------

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

参见
--

* `Atomics`
* `Atomics.load()`
Atomics.wait()
==============

**`Atomics.wait()`** 静态方法验证共享内存特定位置是否仍然包含给定值，如果是则休眠，直到被唤醒或超时。其返回一个内容为 `"ok"`、`"not-equal"` 或 `"timed-out"` 的字符串。

**备注：** 此操作仅适用于基于 `SharedArrayBuffer` 的 `Int32Array` 或 `BigInt64Array` 视图，并且在主线程中可能不可用。有关此方法的非阻塞异步版本，请参见 `Atomics.waitAsync()`。

语法
--


```js
Atomics.wait(typedArray, index, value)
Atomics.wait(typedArray, index, value, timeout)
```

### 参数

`typedArray`

基于 `SharedArrayBuffer` 的 `Int32Array` 或 `BigInt64Array`。

`index`

`typedArray` 中要等待的位置。

`value`

要测试的期望值。

`timeout` 可选

等待时间，以毫秒为单位。`NaN`（以及会被转换为 `NaN` 的值，例如 `undefined`）会被转换为 `Infinity`。负值会被转换为 `0`。

### 返回值

一个内容为 `"ok"`、`"not-equal"` 或 `"timed-out"` 的字符串。

### 异常

`TypeError`

有下列情况之一，则抛出该异常：

* 如果 `typedArray` 不是一个基于 `SharedArrayBuffer` 的 `Int32Array` 或 `BigInt64Array`。
* 如果当前线程无法被阻塞（例如主线程）。

`RangeError`

如果 `index` 超出 `typedArray` 的范围，则抛出该异常。

示例
--

### 使用 wait()

给定一个共享的 `Int32Array`：


```js
const sab = new SharedArrayBuffer(1024);
const int32 = new Int32Array(sab);
```


令一个读取线程休眠并在位置 0 处等待，预期该位置的值为 0。只要条件一直为真，则将不会继续运行。然而，一旦写入线程存储了一个新的值，它将被读取线程唤醒并返回新的值（123）。


```js
Atomics.wait(int32, 0, 0);
console.log(int32[0]); // 123
```


写入线程存储一个新的值并在写入后唤醒等待的线程：


```js
console.log(int32[0]); // 0;
Atomics.store(int32, 0, 123);
Atomics.notify(int32, 0, 1);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.wait |

浏览器兼容性
------

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

参见
--

* `Atomics`
* `Atomics.waitAsync()`
* `Atomics.notify()`
Atomics.sub()
=============

**`Atomics.sub()`** 静态方法对数组中的指定位置减去给定的值，并返回该位置的旧值。此原子操作保证在修改后的值写回之前不会发生其他写操作。

尝试一下
----

语法
--


```js
Atomics.sub(typedArray, index, value)
```

### 参数

`typedArray`

一个整数类型数组。`Int8Array`、`Uint8Array`、`Int16Array`、`Uint16Array`、`Int32Array`、`Uint32Array`、`BigInt64Array` 或 `BigUint64Array` (en-US) 之一。

`index`

`typedArray` 中的要减去 `value` 的位置。

`value`

要减去的数字。

### 返回值

给定位置的旧值 (`typedArray[index]`)。

### 异常

`TypeError`

如果 `typedArray` 不是允许的整数类型数组之一，则抛出该异常。

`RangeError`

如果 `index` 超出 `typedArray` 的范围，则抛出该异常。

示例
--

### 使用 sub()


```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);
ta[0] = 48;

Atomics.sub(ta, 0, 12); // 返回 48，即旧的值
Atomics.load(ta, 0); // 36
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.sub |

浏览器兼容性
------

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

参见
--

* `Atomics`
* `Atomics.add()`