recursal/MDN huggingface dataset:
String.prototype.sup()
======================

**已弃用:** 不再推荐使用该特性。虽然一些浏览器仍然支持它，但也许已从相关的 web 标准中移除，也许正准备移除或出于兼容性而保留。请尽量不要使用该特性，并更新现有的代码；参见本页面底部的兼容性表格以指导你作出决定。请注意，该特性随时可能无法正常工作。

`String` 值的 **`sup()`** 方法创建一个 `<sup>` 元素字符串，其中嵌入了调用的字符串（`<sup>str</sup>`）中，这会导致该字符串显示为上标。

**备注：** 所有 HTML 包装器方法 均已弃用，仅出于兼容性目的而进行标准化。请改用 DOM API，例如 `document.createElement()`。

语法
--


```js
sup()
```

### 参数

无。

### 返回值

以 `<sup>` 开始标记开头的字符串，然后是文本 `str`，最后是 `</sup>` 结束标记。

示例
--

### 使用 sub() 和 sup() 方法

下面的示例使用了 `sub()` 和 `sup()` 方法来格式化字符串：


```js
const superText = "上标";
const subText = "下标";

console.log(`这就是${superText.sup()}的样子。`);
// "这就是<sup>上标</sup>的样子。"

console.log(`这就是${subText.sub()}的样子。`);
// "这就是<sub>下标</sub>的样子。"
```

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.sup` 的 Polyfill
* `String.prototype.sub()`
String.prototype.toWellFormed()
===============================

`String` 的 **`toWellFormed()`** 方法返回一个字符串，其中该字符串的所有单独代理项都被替换为 Unicode 替换字符 U+FFFD。

语法
--


```js
toWellFormed()
```

### 返回值

新的字符串是原字符串的一个拷贝，其中所有的单独代理项被替换为 Unicode 替换字符 U+FFFD。如果 `str` 是格式正确的，仍然会返回一个新字符串（本质上是 `str` 的一个拷贝）。

描述
--

JavaScript 中的字符串是 UTF-16 编码的。UTF-16 编码中有*代理对*的概念，这一概念在 UTF-16 字符、Unicode 码位和字素簇部分有详细介绍。

`toWellFormed()` 迭代字符串的码元，并将任何单独代理项替换为 Unicode 替换字符 U+FFFD `�`。这确保了返回的字符串格式正确并可用于期望正确格式字符串的函数，比如 `encodeURI`。由于引擎能够直接访问字符串的内部表示，与自定义实现相比 `toWellFormed()` 更高效。

当在某些上下文中使用格式不正确的字符串时，例如 `TextEncoder`，它们会自动转换为使用相同替换字符的格式正确的字符串。当单独代理项被呈现时，它们也会呈现为替换字符（一个带有问号的钻石形状）。

示例
--

### 使用 toWellFormed()


```js
const strings = [
  // 单独的前导代理
  "ab\uD800",
  "ab\uD800c",
  // 单独的后尾代理
  "\uDFFFab",
  "c\uDFFFab",
  // 格式正确
  "abc",
  "ab\uD83D\uDE04c",
];

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

### 避免 encodeURI() 错误

如果传递的字符串格式不正确， `encodeURI` 会抛出错误。可以先通过使用 `toWellFormed()` 将字符串转换为格式正确的字符串来避免这种情况。


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

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

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.toWellFormed` 的 polyfill
* `String.prototype.isWellFormed()`
* `String.prototype.normalize()`
String.raw()
============

**`String.raw()`** 静态方法是模板字符串的标签函数。它的作用类似于 Python 中的 `r` 前缀或 C# 中用于字符串字面量的 `@` 前缀。它用于获取模板字符串的原始字符串形式——即，替换表达式（例如 `${foo}`）会被替换处理，但转义序列（例如 `\n`）不会被处理。

尝试一下
----

语法
--


```js
String.raw(strings, ...substitutions)

String.raw`templateString`
```

### 参数

`strings`

格式正确的模板字符串数组对象，例如 `{ raw: ['foo', 'bar', 'baz'] }`，应该是一个具有 `raw` 属性的对象，其值是一个类数组的字符串对象。

`...substitutions`

包含的替换表达式对应的值。

`templateString`

一个模板字符串，可以包含替换表达式（`${...}`）。

### 返回值

给定模板字符串的原始字符串。

### 异常

`TypeError`

如果第一个参数没有 `raw` 属性，或者 `raw` 属性的值为 `undefined` 或 `null`，则会抛出异常。

描述
--

在大多数情况下，`String.raw()` 与模板字符串一起使用。上面提到的第一种语法很少使用，因为 JavaScript 引擎会自动为你调用它并传入适当的参数（就像其他标记函数一样）。

`String.raw()` 是唯一一个内置的模板字符串标签函数，因为它太常用了。不过它并没有什么特殊能力，你自己也可以实现一个和它功能一模一样的标签函数。

**警告：** 不应直接将 `String.raw` 作为“标识”标签。请参见构建标识标签以了解如何实现此操作。

如果使用没有 `length` 属性或 `length` 为非正数的 `raw` 属性的对象调用 `String.raw()` 方法，它将返回一个空字符串 `""`。如果 `substitutions.length < strings.raw.length - 1`（即没有足够的替换项来填充占位符——这在一个格式正确的标记模板字面量中是不可能发生的），则其余的占位符将被填充为空字符串。

示例
--

### 使用 String.raw()


```js
String.raw`Hi\n${2 + 3}!`;
// 'Hi\\n5!'，'Hi' 后面的字符不是换行符，'\' 和 'n' 是两个不同的字符。

String.raw`Hi\u000A!`;
// 'Hi\\u000A!'，同上，这里得到的会是 \、u、0、0、0、A，6 个字符。
// 任何类型的转义形式都会失效，保留原样输出。
// 你可以通过检查 string 的 .length 属性来确认这一点。

const name = "Bob";
String.raw`Hi\n${name}!`;
// 'Hi\\nBob!'，内插表达式还可以正常替换。

String.raw`Hi \${name}!`;
// 'Hi \\${name}!'，美元符号被转义；这里没有插值。
```

### 构建标识标签

许多工具会对由特定名称标记的字面量进行特殊处理。


```js
// 一些格式化工具将会将这个字面量的内容格式化为 HTML
const doc = html`<!DOCTYPE html>
<html lang="en-US">
 <head>
 <title>Hello</title>
 </head>
 <body>
 <h1>Hello world!</h1>
 </body>
</html>
`;
```


一个天真的实现 `html` 标签的方式可能是：


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


实际上，这对于上面的情况是有效的。然而，因为 `String.raw` 方法将连接*原始*的字符串字面量而不是“处理过”的字符串字面量，所以转义序列将不会被处理。


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


对于“真实的标识”标签而言，这可能并不是你想要的，因为这种情况下标签纯粹用于标记化，不会改变字面量的值。在这种情况下，你可以创建一个自定义标签，并将“处理过”的字面量数组传递给 `String.raw`，假装它们是原始字符串。


```js
const html = (strings, ...values) => String.raw({ raw: strings }, ...values);
// 一些格式化工具将会将这个字面量的内容格式化为 HTML
const doc = html`<canvas>\n</canvas>`;
// "<canvas>\n</canvas>"; "\n" 变成了换行符
```


请注意，第一个参数是一个带有 `raw` 属性的对象，其值是一个类数组对象（具有 `length` 属性和整数索引），表示模板字面量中分隔的字符串。其余的参数是替换项。由于 `raw` 值可以是任何类数组对象，它甚至可以是一个字符串！例如，`'test'` 被视为 `['t', 'e', 's', 't']`。以下代码与 ``t${0}e${1}s${2}t`` 等效：


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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.raw` 的 polyfill
* 模版字符串
* `String`
* 词法文法
String.prototype.toLocaleUpperCase()
====================================

`String` 的 **`toLocaleUpperCase()`** 方法会根据特定区域设置的大小写映射规则，将字符串转换为大写形式并返回。

尝试一下
----

语法
--


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

### 参数

`locales` 可选

一个带有 BCP 47 语言标签的字符串，或者是这种字符串的数组。指示要根据特定区域设置的大小写映射规则进行转换的区域设置。有关 `locales` 参数的一般形式和解释，请参阅 `Intl` 主页上的参数描述。

与使用 `locales` 参数的其他方法不同，`toLocaleUpperCase()` 不允许进行区域设置匹配。因此，在检查 `locales` 参数的有效性之后，`toLocaleUpperCase()` 始终使用列表中的第一个区域设置（如果列表为空，则使用默认区域设置），即使该区域设置在实现中不受支持。

### 返回值

一个新的字符串，表示调用字符串根据特定区域设置的大小写映射规则转换得到的大写形式。

描述
--

`toLocaleUpperCase()` 方法返回根据特定区域设置的大小写映射规则将字符串转换为小写形式的值。`toLocaleUpperCase()` 不会影响字符串本身的值。在大多数情况下，这将产生与 `toUpperCase()` 相同的结果，但对于某些区域设置（例如土耳其语），它们的大小写映射与 Unicode 的默认映射不同，可能会得到不同的结果。

 还要注意，转换不一定是一对一的字符映射，因为某些字符在转换为小写形式时可能会产生两个（甚至更多）字符。因此，结果字符串的长度可能与输入长度不同。这也意味着转换是不稳定的，因此下面的例子可能返回 `false`：
 `x.toLocaleLowerCase() === x.toLocaleUpperCase().toLocaleLowerCase()`

示例
--

### 使用 toLocaleUpperCase()


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

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

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

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

规范
--

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

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

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

参见
--

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

`String` 的 **`trim()`** 方法会从字符串的两端移除空白字符，并返回一个新的字符串，而不会修改原始字符串。

要返回一个仅从一端修剪空白字符的新字符串，请使用 `trimStart()` 或 `trimEnd()`。

尝试一下
----

语法
--


```js
trim()
```

### 返回值

一个新的字符串，表示从 `str` 的开头和结尾去除空白字符后的结果。空白字符定义为空白符加上行终止符。

如果 `str` 的开头和结尾都没有空白字符，仍然会返回一个新的字符串（实际上是 `str` 的副本）。

示例
--

### 使用 trim()

下面的示例从 `str` 的两端去除空白字符：


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

规范
--

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

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

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

参见
--

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

`String` 的 **`startsWith()`** 方法用来判断当前字符串是否以另外一个给定的子字符串开头，并根据判断结果返回 `true` 或 `false`。

尝试一下
----

语法
--


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

### 参数

`searchString`

要在该字符串开头搜索的子串。不能是正则表达式。所有不是正则表达式的值都会被强制转换为字符串，因此省略它或传递 `undefined` 将导致 `startsWith()` 搜索字符串 `"undefined"`，这应该不是你想要的结果。

`position` 可选

`searchString` 期望被找到的起始位置（即 `searchString` 的第一个字符的索引）。默认为 `0`。

### 返回值

如果给定的字符在字符串的开头被找到（包括当 `searchString` 是空字符串时），则返回 **`true`**；否则返回 **`false`**。

### 异常

`TypeError`

如果 `searchString` 是正则表达式，则抛出该异常。

描述
--

这个方法能够让你确定一个字符串是否以另一个字符串开头。这个方法区分大小写。

示例
--

### 使用 startsWith()


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

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.startsWith` 的 polyfill
* `String.prototype.endsWith()`
* `String.prototype.includes()`
* `String.prototype.indexOf()`
* `String.prototype.lastIndexOf()`
String.prototype.charCodeAt()
=============================

`String` 的 **`charCodeAt()`** 方法返回一个整数，表示给定索引处的 UTF-16 码元，其值介于 `0` 和 `65535` 之间。

`charCodeAt()` 方法总是将字符串当作 UTF-16 码元序列进行索引，因此它可能返回单独代理项（lone surrogate）。如果要获取给定索引处的完整 Unicode 码位，请使用 `String.prototype.codePointAt()` 方法。

尝试一下
----

语法
--


```js
charCodeAt(index)
```

### 参数

`index`

要返回的字符的索引，从零开始。将被转换为整数——`undefined` 被转换为 0。

### 返回值

一个整数，介于 `0` 和 `65535` 之间，表示指定 `index` 处字符的 UTF-16 码元值。如果 `index` 超出了 `0` 到 `str.length - 1` 的范围，则 `charCodeAt()` 返回 `NaN`。

描述
--

字符串中的字符从左到右进行索引。第一个字符的索引为 `0`，而在名为 `str` 的字符串中，最后一个字符的索引为 `str.length - 1`。

Unicode 码位的范围是 `0` 到 `1114111`（`0x10FFFF`）。`charCodeAt()` 方法始终返回一个小于 `65536` 的值，因为更高的码位由*一对* 16 位代理伪字符（surrogate pseudo-character）来表示。因此，为了获取值大于 `65535` 的完整字符，不仅需要检索 `charCodeAt(i)`，而且还要使用 `charCodeAt(i + 1)`（就像操作具有两个字符的字符串一样），或者使用 `codePointAt(i)` 方法。有关 Unicode 的信息，请参见 UTF-16 字符、Unicode 码位和字素簇。

示例
--

### 使用 charCodeAt()

以下示例返回 `65`，即 A 的 Unicode 值。


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


`charCodeAt()` 可能会返回单独代理项，它们不是有效的 Unicode 字符。


```js
const str = "𠮷𠮾";
console.log(str.charCodeAt(0)); // 55362 或 d842，不是有效的 Unicode 字符
console.log(str.charCodeAt(1)); // 57271 或 dfb7，不是有效的 Unicode 字符
```


要获取给定索引处的完整 Unicode 码位，请使用 `String.prototype.codePointAt()` 方法。


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


**备注：** 避免使用 `charCodeAt()` 来重新实现 `codePointAt()`。从 UTF-16 代理到 Unicode 码位的转换相当复杂，而且 `codePointAt()` 可能更加高效，因为它直接使用字符串的内部表示形式。如果需要，可以安装一个 `codePointAt()` 的 polyfill。

以下是将一对 UTF-16 码元转换为 Unicode 码位的可能算法，改编自 Unicode 常问问题：


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

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

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

规范
--

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

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

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

参见
--

* `String.fromCharCode()`
* `String.prototype.charAt()`
* `String.fromCodePoint()`
* `String.prototype.codePointAt()`
String.prototype[@@iterator]()
==============================

`String` 类型的 **`[@@iterator]()`** 方法实现了可迭代协议，并允许字符串与大多数期望传入可迭代对象的语法一起使用，例如展开语法和 `for...of` 循环。它返回一个字符串迭代器对象，它按 Unicode 码位迭代字符串值并以字符串的形式返回。

尝试一下
----

语法
--


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

### 返回值

一个新的可迭代迭代器对象，它以字符串值中的 Unicode 码位生成单独的字符串。

描述
--

按 Unicode 码位迭代字符串。这意味着会将字素簇拆分，但代理对将被保留。


```js
// "Backhand Index Pointing Right: Dark Skin Tone"
[..."👉🏿"]; // ['👉', '🏿']
// splits into the basic "Backhand Index Pointing Right" emoji and
// the "Dark skin tone" emoji

// "Family: Man, Boy"
[..."👨‍👦"]; // [ '👨', '‍', '👦' ]
// splits into the "Man" and "Boy" emoji, joined by a ZWJ
```

示例
--

### 使用 for...of 循环进行迭代

请注意，你很少需要直接调用该方法。`@@iterator` 方法的存在使得字符串可迭代，而像 `for...of` 循环这样的迭代语法会自动调用该方法以获取迭代器进行循环。


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

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

### 手动迭代

你仍然可以手动调用返回的迭代器对象的 `next()` 方法，以实现对迭代过程最大程度的控制。


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

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

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype[@@iterator]` 的 polyfill
* 迭代协议
String.prototype.valueOf()
==========================

**`valueOf()`** 方法返回 `String` 对象的字符串值。

尝试一下
----

语法
--


```js
valueOf()
```

### 返回值

一个字符串，表示给定 `String` 对象的原始值。

描述
--

`String` 的 `valueOf()` 方法以字符串数据类型返回 `String` 对象的原始值。此值等价于 `String.prototype.toString()`。

此方法通常由 JavaScript 在内部调用，而不是在代码中显式调用。

示例
--

### 使用 `valueOf()`


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

规范
--

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

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

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

参见
--

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

`String` 的 **`toUpperCase()`** 方法将该字符串转换为大写形式。

尝试一下
----

语法
--


```js
toUpperCase()
```

### 返回值

一个新的字符串，表示转换为大写的调用字符串。

描述
--

`toUpperCase()` 方法返回将字符串转换为大写形式后的值。由于 JavaScript 中的字符串是不可变的，因此此方法不会影响字符串本身的值。

示例
--

### 基本用法


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

### 将非字符串类型的 `this` （上下文）转为字符串

此方法会将任何非字符串类型的值转为字符串，当你将其上下文 `this` 值设置为非字符串类型


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

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

// 输出 'ABCDEF TRUE'。
console.log(a, b);
```

规范
--

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

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

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

参见
--

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

`String` 值的 **`isWellFormed()`** 方法返回一个表示该字符串是否包含单独代理项的布尔值。

语法
--


```js
isWellFormed()
```

### 返回值

如果字符串不包含单独代理项，返回 `true`，否则返回 `false`。

描述
--

JavaScript 中的字符串是 UTF-16 编码的。UTF-16 编码中有*代理对*的概念，这一概念在 UTF-16 字符、Unicode 码位和字素簇部分有详细介绍。

`isWellFormed()` 让你能够测试一个字符串是否是格式正确的（即不包含单独代理项）。由于引擎能够直接访问字符串的内部表示，与自定义实现相比 `isWellFormed()` 更高效。如果你需要将字符串转换为格式正确的字符串，可以使用 `toWellFormed()` 方法。`isWellFormed()` 让你可以对格式正确和格式错误的字符串进行不同的处理，比如抛出一个错误或将其标记为无效。

示例
--

### 使用 isWellFormed()


```js
const strings = [
  // 单独的前导代理
  "ab\uD800",
  "ab\uD800c",
  // 单独的后尾代理
  "\uDFFFab",
  "c\uDFFFab",
  // 格式正确
  "abc",
  "ab\uD83D\uDE04c",
];

for (const str of strings) {
  console.log(str.isWellFormed());
}
// 输出：
// false
// false
// false
// false
// true
// true
```

### 避免 encodeURI() 错误

如果传递的字符串格式不正确， `encodeURI` 会抛出错误。可以通过使用 `isWellFormed()` 在将字符串传递给 `encodeURI()` 之前测试字符串来避免这种情况。


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

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

if (illFormed.isWellFormed()) {
  console.log(encodeURI(illFormed));
} else {
  console.warn("Ill-formed strings encountered."); // Ill-formed strings encountered.
}
```

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.isWellFormed` 的 polyfill
* `String.prototype.toWellFormed()`
* `String.prototype.normalize()`
String.prototype.codePointAt()
==============================

`String` 的 **`codePointAt()`** 方法返回一个非负整数，该整数是从给定索引开始的字符的 Unicode 码位值。请注意，索引仍然基于 UTF-16 码元，而不是 Unicode 码位。

尝试一下
----

语法
--


```js
codePointAt(index)
```

### 参数

`index`

需要返回的字符的（从零开始的）索引。会被转换为整数——`undefined` 会转换为 0。

### 返回值

一个非负整数，表示给定 `index` 处字符的码位值。

* 如果 `index` 超出了 `0` – `str.length - 1` 的范围，`codePointAt()` 返回 `undefined`。
* 如果 `index` 处的元素是一个 UTF-16 前导代理（leading surrogate），则返回代理*对*的码位。
* 如果 `index` 处的元素是一个 UTF-16 后尾代理（trailing surrogate），则*只*返回后尾代理的码元。
描述
--

字符串中的字符从左到右进行索引。第一个字符的索引为 `0`，而字符串 `str` 中最后一个字符的索引为 `str.length - 1`。

Unicode 码位范围从 `0` 到 `1114111`（`0x10FFFF`）。在 UTF-16 中，每个字符串索引是一个取值范围为 `0` – `65535` 的码元。较高的码位由一个由*一对* 16 位代理伪字符表示。因此，`codePointAt()` 返回的码位可能跨越两个字符串索引。有关 Unicode 的信息，请参阅 UTF-16 字符、Unicode 码位和字素簇。

示例
--

### 使用 codePointAt()


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

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

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

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

### 在循环中使用 codePointAt()

因为使用字符串索引进行循环会导致同一码位被访问两次（一次是前导代理，一次是后尾代理），而第二次调用 `codePointAt()` 时*只*返回后尾代理项，所以最好避免使用索引进行循环。


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

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


相反，可以使用 `for...of` 语句或字符串展开语法，这两种方法都会调用字符串的 `@@iterator`，从而按照码位进行迭代。然后，可以使用 `codePointAt(0)` 获取每个元素的码位值。


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

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.codePointAt` 的 polyfill
* `String.fromCodePoint()`
* `String.fromCharCode()`
* `String.prototype.charCodeAt()`
* `String.prototype.charAt()`
String.prototype.concat()
=========================

**`concat()`** 方法将字符串参数连接到调用的字符串，并返回一个新的字符串。

尝试一下
----

语法
--


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

### 参数

`strN`

要连接到 `str` 的一个或多个字符串。

### 返回值

一个包含所提供的多个字符串文本组合的新字符串。

描述
--

`concat()` 函数将字符串参数连接到调用的字符串并返回一个新字符串。对原字符串或返回的字符串所做的更改不会影响另一个字符串。

如果参数不是字符串类型，它们在连接之前将会被转换成字符串。

`concat()` 方法与加号/字符串连接运算符（`+`，`+=`）非常相似，不同之处在于 `concat()` 直接将其参数强制转换为字符串进行连接，而加号运算符首先将其操作数强制转换为原始值，然后再进行连接。有关更多信息，请参阅 `+` 运算符的参考页面。

示例
--

### 使用 concat()

下面的示例将多个字符串组合为一个新字符串。


```js
const hello = "Hello, ";
console.log(hello.concat("Kevin", ". Have a nice day."));
// Hello, Kevin. Have a nice day.

const greetList = ["Hello", " ", "Venkat", "!"];
"".concat(...greetList); // "Hello Venkat!"

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

规范
--

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

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

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

参见
--

* `Array.prototype.concat()`
* 加法运算符
String.prototype.substr()
=========================

**已弃用:** 不再推荐使用该特性。虽然一些浏览器仍然支持它，但也许已从相关的 web 标准中移除，也许正准备移除或出于兼容性而保留。请尽量不要使用该特性，并更新现有的代码；参见本页面底部的兼容性表格以指导你作出决定。请注意，该特性随时可能无法正常工作。

`String` 值的 **`substr()`** 方法返回该字符串的一部分，从指定的索引开始，然后扩展到给定数量的字符。

**备注：** `substr()` 不属于 ECMAScript 主要规范——它在附件 B: Web 浏览器的附加 ECMAScript 功能中定义，这是非浏览器运行时的可选标准。因此，建议人们使用标准的 `String.prototype.substring()` 和 `String.prototype.slice()` 方法，以便使他们的代码能够更好地、最大程度地跨平台。`String.prototype.substring()` 页面对这三种方法进行了一些比较。

尝试一下
----

语法
--


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

### 参数

`start`

返回子字符串中要包含的第一个字符的索引。

`length` 可选

要提取的字符数。

### 返回值

一个包含给定字符串指定部分的新字符串。

描述
--

字符串的 `substr()` 方法从字符串中提取 `length` 字符，从 `start` 索引开始计数。

* 如果 `start >= str.length`，则返回空字符串。
* 如果 `start < 0`，则索引从字符串末尾开始计数。更准确地说，在这种情况下，子字符串从 `max(start + str.length, 0)` 开始。
* 如果省略 `start` 或其值为 `undefined`，则将其视为 `0`。
* 如果省略 `length` 或其值为 `undefined`，或者如果 `start + length >= str.length`，则 `substr()` 会提取字符到字符串末尾。
* 如果 `length < 0`，则返回空字符串。
* 对于 `start` 和 `length`，`NaN` 被视为 `0`。

尽管我们建议你避免使用 `substr()`，但是没有简单的方法可以将遗留代码中的 `substr()` 迁移到 `slice()` 或 `substring()`，而无需为 `substr()` 编写一个 polyfill。例如，当 `str = "01234", a = 1, l = -2` 时，`str.substr(a, l)`、`str.slice(a, a + l)` 和 `str.substring(a, a + l)` 都有不同的结果——`substr()` 返回空字符串，`slice()` 返回 `"123"`，而 `substring()` 返回 `"0"`。实际的重构路径取决于对 `a` 和 `l` 范围的了解。

示例
--

### 使用 substr()


```js
const aString = "Mozilla";

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.substr` 的 Polyfill
* `String.prototype.slice()`
* `String.prototype.substring()`
TypedArray.prototype.find()
===========================

如果某个元素满足所提供的测试函数，**`find()`** 方法返回类型化数组中的**值**，否则返回 `undefined`。*TypedArray* 是这里的类型化数组类型之一。

同时请参见 `findIndex()` 方法，它返回了类型化数组中所发现元素的**下标**，而不是它的值。

语法
--


```js
find(callbackFn)
find(callbackFn, thisArg)
```

### 参数

`callback`

用于在类型化数组中的每个元素上执行的函数，接受三个参数：

`element`

要处理的类型化数组的当前元素。

`index`

要处理的当前元素在类型化数组中的下标

`array`

`find` 在其上调用的类型化数组


`thisArg`

可选，执行`callback`时的`this`值。

### 返回值

如果元素通过了测试，则为该元素，否则为`undefined`。

描述
--

`find` 方法对类型化数组中的每个元素执行一次 `callback` 函数，直到它找到一个使 `callback` 返回 *true*的元素。如果发现了一个这样的元素，`find` 方法将会立即返回该元素的值。否则，`find` 方法会返回`undefined`。`callback` 只会对那些已经被赋值的索引调用。不会对那些被删除或从来没被赋值的索引调用。

`callback` 以三个参数调用：元素的值，元素索引，以及要遍历的数组对象。

如果将`thisArg`参数提供给`find`，它会在调用时传递给`callback`，作为它的 `this`值。如果没有提供，会使用`undefined`。

`find` 不修改在其上调用的类型化数组。

由 `find`处理的元素范围在`callback`调用之前就确定了。在 `find`调用之后添加到数组的元素不会由 `callback`访问。如果类型化数组的现有元素被改变，或被删除，它们传给`callback`的值是`find` 访问它们时候的值。已删除的元素不会被访问。

示例
--

### 在类型化数组中寻找质数

下面的示例在类型化数组中寻找质数（如果没有质数则返回 `undefined`）。


```js
function isPrime(element, index, array) {
  var start = 2;
  while (start <= Math.sqrt(element)) {
    if (element % start++ < 1) {
      return false;
    }
  }
  return element > 1;
}

var uint8 = new Uint8Array([4, 5, 8, 12]);
console.log(uint8.find(isPrime)); // 5
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-%typedarray%.prototype.find |

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

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

另见
--

* `TypedArray.prototype.findIndex()`
* `TypedArray.prototype.every()`