Error() 构造函数 - JavaScript

Error() 构造函数
============

**`Error()`** 构造函数能够创建一个包含错误信息的对象。

语法
--

```js
new Error()
new Error(message)
new Error(message, options)
new Error(message, fileName)
new Error(message, fileName, lineNumber)
Error()
Error(message)
Error(message, options)
Error(message, fileName)
Error(message, fileName, lineNumber)
```

**备注：** 调用 `Error()` 时，可以使用关键字 `new`，也可以不使用。两种声明方式均能创建一个新的 `Error` 实例。

### 参数

`message` 可选

人类可读的错误信息。

`options` 可选

一个包含以下属性的对象：

`cause` 可选

指示错误的具体原因，反映在 `cause` 属性中。当捕获并重新抛出带有更具体或有用的错误消息的错误时，可以使用此属性传递原始错误。

`fileName` 可选
非标准

引发此错误的文件路径，反映在 `fileName` 属性中。默认为调用 `Error()` 构造函数的代码所在文件的名称。

`lineNumber` 可选
非标准

引发错误的文件中的行号，反映在 `lineNumber` 属性中。默认为包含 `Error()` 构造函数调用的行号。

示例
--

### 函数调用与构造函数

当 `Error` 作为函数使用，即不包含 `new` 关键字时，它将返回一个 Error 对象。因此，直接调用 `Error` 函数将产生与使用 `new` 关键字构造 `Error` 对象相同的输出。

```js
const x = Error("I was created using a function call!");
// 上述代码与以下代码具有相同的功能
const y = new Error('I was constructed via the "new" keyword!');
```

### 使用 cause 重新抛出错误

在捕获错误时，我们可能会使用新的错误信息对错误进行包装，再将其重新抛出。这种场景下，你应当将原始错误也传入新的 `Error` 的构造函数，如下所示：

```js
try {
  frameworkThatCanThrow();
} catch (err) {
  throw new Error("New error message", { cause: err });
}
```

更多示例参考错误 > 区分相似的错误。

### 省略 options 参数

JavaScript 只有在 `options` 参数为对象时才会尝试读取 `options.cause` 属性，这样可以避免与另一种非标准的 `Error(message, fileName, lineNumber)` 函数签名产生歧义，后者要求第二个参数必须是字符串。如果你省略了 `options` 参数，或者将原始值作为 `options` 传入，又或者传递的对象中没有 `cause` 属性，那么创建的 `Error` 对象将不会包含 `cause` 属性。

```js
// 省略 options
const error1 = new Error("Error message");
console.log("cause" in error1); // false

// 传递原始值
const error2 = new Error("Error message", "");
console.log("cause" in error2); // false

// 传递不包含 cause 属性的对象
const error3 = new Error("Error message", { details: "http error" });
console.log("cause" in error3); // false
```

规范
--

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

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

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

参见
--

* `core-js` 提供了支持 `cause` 等最新特性 (modern behavior) 的 `Error` polyfill
* `throw`
* `try...catch`
* Error cause（v8.dev/features）


Error.prototype.lineNumber - JavaScript

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

**非标准:** 该特性是非标准的，请尽量不要在生产环境中使用它！

**`lineNumber`** 属性的值为抛出错误的代码在其源文件中所在的行号。

示例
--

### 使用 `lineNumber`

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

### 监听 `error` 事件的示例

```js
window.addEventListener("error", function (e) {
  console.log(e.lineNumber); // 5
});
var e = new Error("Could not parse input");
throw e;
```

这不是一个标准化的属性，缺乏广泛的支持。参见下面的浏览器兼容性表格。

规范
--

非标准化属性。不属于任何规范。

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

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

相关内容
----

* `Error.prototype.stack`
非标准
* `Error.prototype.columnNumber`
非标准
* `Error.prototype.fileName`
非标准


Error.prototype.fileName - JavaScript

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

**非标准:** 该特性是非标准的，请尽量不要在生产环境中使用它！

**`fileName`** 属性包含引发此错误的文件的路径。

描述
--

此非标准属性包含引发此错误的文件的路径。如果从调试器上下文调用，例如 Firefox Developer Tools，将会返回“debugger eval code”.

示例
--

### 使用 `fileName`

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

规范
--

#### No specification found

No specification data found for `javascript.builtins.Error.fileName`.
Check for problems with this page or contribute a missing `spec_url` to mdn/browser-compat-data. Also make sure the specification is included in w3c/browser-specs.

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

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

参见
--

* `Error.prototype.stack`
非标准
* `Error.prototype.columnNumber`
非标准
* `Error.prototype.lineNumber`
非标准


String.prototype.search() - JavaScript

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

**`search()`** 方法用于在 `String` 对象中执行正则表达式的搜索，寻找匹配项。

尝试一下
----

语法
--

```js
search(regexp)
```

### 参数

`regexp`

一个正则表达式对象，或者具有 `Symbol.search` 方法的任意对象。

如果 `regexp` 不是 `RegExp` 对象，并且不具有 `Symbol.search` 方法，则会使用 `new RegExp(regexp)` 将其隐式转换为 `RegExp`。

### 返回值

如果匹配成功，则返回正则表达式在字符串中首次匹配的索引；否则，返回 `-1`。

描述
--

`String.prototype.search()` 方法的实现非常简单——它只是将该字符串作为调用实参拥有的 `Symbol.search` 方法的第一个参数。实际的实现来自于 `RegExp.prototype[@@search]()`。

`regexp` 的 `g` 标志对 `search()` 方法的结果没有影响，搜索总是以正则表达式的 `lastIndex` 为 0 进行。有关 `search()` 方法行为的更多信息，请参阅 `RegExp.prototype[@@search]()`。

当你想知道字符串中是否存在某个模式，并且*还*想知道它在字符串中的索引时，可以使用 `search()` 方法。

* 如果你只想知道某个模式是否存在，请使用 `RegExp.prototype.test()` 方法，它返回一个布尔值。
* 如果你需要获取匹配文本的内容，请使用 `match()` 或 `RegExp.prototype.exec()`。
示例
--

### 使用 search()

下面的示例中用两个不同的正则表达式对同一个字符串执行搜索匹配，得到一个成功匹配（正数返回值）和一个失败匹配（`-1`）。

```js
const str = "hey JudE";
const re = /[A-Z]/;
const reDot = /[.]/;
console.log(str.search(re)); // 返回 4，这是第一个大写字母“J”的索引
console.log(str.search(reDot)); // 返回 -1，找不到点符号“.”
```

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.search` 的 polyfill，修复并实现了 `Symbol.search` 支持等现代行为
* 在 JavaScript 中使用正则表达式
* `String.prototype.match()`
* `RegExp.prototype.exec()`
* `RegExp.prototype[@@search]()`


String.prototype.fixed() - JavaScript

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

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

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

**备注：** 所有 HTML 包装方法都已被弃用，并且仅为了兼容性而标准化。请使用 DOM API（例如 `document.createElement()`）代替。

语法
--

```js
fixed()
```

### 参数

无。

### 返回值

一个以 `<tt>` 开始标签开头的字符串，接着是文本 `str`，然后是 `</tt>` 结束标签。

示例
--

### 使用 fixed()

以下示例使用 `fixed` 方法来更改字符串的格式：

```js
const worldString = "Hello, world";
console.log(worldString.fixed()); // "<tt>Hello, world</tt>"
```

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.fixed` 的 polyfill
* `String.prototype.bold()`
* `String.prototype.italics()`
* `String.prototype.strike()`


String.prototype.replaceAll() - JavaScript

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

**`replaceAll()`** 方法返回一个新字符串，其中所有匹配 `pattern` 的部分都被替换为 `replacement`。`pattern` 可以是一个字符串或一个 `RegExp`，`replacement` 可以是一个字符串或一个在每次匹配时调用的函数。原始字符串保持不变。

尝试一下
----

语法
--

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

### 参数

`pattern`

可以是一个字符串或一个具有 `Symbol.replace` 方法的对象，典型的例子是正则表达式。任何没有 `Symbol.replace` 方法的值都将被强制转换为字符串。

如果 `pattern` 是一个正则表达式，则必须设置全局（`g`）标志，否则会抛出 `TypeError`。

`replacement`

可以是一个字符串或一个函数。替换字符串的语义与 `String.prototype.replace()` 相同。

### 返回值

返回一个新字符串，其中所有匹配 `pattern` 的部分都被替换为 `replacement`。

### 异常

`TypeError`

如果 `pattern` 是一个正则表达式，并且没有设置全局（`g`）标志（其 `flags` 属性不包含 `"g"`），则会抛出该异常。

描述
--

该方法不会修改调用它的字符串。它返回一个新字符串。

与 `replace()` 不同，该方法将替换所有匹配的字符串，而不仅仅是第一个。如果字符串不是静态已知的，那么这特别有用，因为调用 `RegExp()` 构造函数而不转义特殊字符可能会意外地改变它的语义。

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

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

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

如果 `pattern` 是一个具有 `Symbol.replace` 方法的对象（包括 `RegExp` 对象），则该方法将被调用，并以目标字符串和 `replacement` 作为参数。它的返回值成为 `replaceAll()` 的返回值。在这种情况下，`replaceAll()` 的行为完全取决于 `@@replace` 方法，因此除了额外的输入验证（即正则表达式必须是全局的）之外，它将具有与 `replace()` 相同的结果。

如果 `pattern` 是一个空字符串，则替换内容将插入到每个 UTF-16 码元之间，类似于 `split()` 的行为。

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

有关正则表达式属性（尤其是 sticky 标志）如何与 `replaceAll()` 交互的更多信息，请参阅 `RegExp.prototype[@@replace]()`。

示例
--

### 使用 replaceAll()

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

### 非全局正则表达式抛出错误

使用正则表达式搜索值时，它必须是全局的。下面的代码是不可行的：

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

下面的代码可以正常运行：

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.replaceAll` 的 polyfill
* `String.prototype.replace()`
* `String.prototype.match()`
* `RegExp.prototype.exec()`
* `RegExp.prototype.test()`


String：length - JavaScript

String：length
=============

`String` 类型的 **`length`** 数据属性表示字符串的 UTF-16 码元长度。

尝试一下
----

值
-

一个非负整数。

| `String：length` 的属性特性 |
| --- |
| 可写 | 否 |
| 可枚举 | 否 |
| 可配置 | 否 |

描述
--

该属性返回字符串中的码元数量。JavaScript 使用 UTF-16 编码，其中每个 Unicode 字符可以编码为一个或两个码元，因此 `length` 返回的值可能与字符串中 Unicode 字符的实际数量不匹配。对于拉丁文、西里尔文、众所周知的 CJK 字符等常见脚本，这应该不是问题，但如果你正在处理某些脚本，例如表情符号、数学符号或生僻字，你可能需要考虑码元和字符之间的差异。

语言规范要求字符串的最大长度为 253 - 1 个元素，这是精确整数的上限。但是，具有此长度的字符串需要 16384TiB 的存储空间，这远远超出了任何合理设备的内存限制，因此实现通常会降低这个阈值，从而允许字符串的长度方便地存储在一个 32 位整数中。

* 在 V8 引擎（Chrome 和 Node 使用）中，最大长度为 229 - 24（约为 1GiB）。在 32 位系统上，最大长度为 228 - 16（约为 512MiB）。
* 在 Firefox 中，最大长度为 230 - 2（约为 2GiB）。在 Firefox 65 之前，最大长度为 228 - 1（约为 512MiB）。
* 在 Safari 中，最大长度为 231 - 1（约为 4GiB）。

对于空字符串，`length` 为 0。

静态属性 `String.length` 与字符串的长度无关。它是 `String` 函数的参数数量（简单地说，就是它有多少个形参），也就是 1。

由于 `length` 统计的是码元而不是字符，如果你想得到字符的数量，你可以首先用它的迭代器分割字符串，它按字符进行迭代：

```js
function getCharacterLength(str) {
  // 这里使用的字符串迭代器遍历的是字符，而不仅仅是码元
  return [...str].length;
}

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

示例
--

### 基本用法

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

console.log(`${x} 有 ${x.length} 个码元`);
// Mozilla 有 7 个码元

console.log(`空字符串的 length 为 ${empty.length}`);
// 空字符串的 length 为 0
```

### 长度不等于字符数的字符串

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

### 指定长度

因为字符串是一个基本类型，所以尝试为字符串的 `length` 属性赋值没有可观察到的效果，并且在严格模式下会抛出错误。

```js
const myString = "bluebells";

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

规范
--

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

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

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

参见
--

* JavaScript 的 `String.length` 属性和国际化 Web 应用


String.prototype.split() - JavaScript

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

**`split()`** 方法接受一个模式，通过搜索模式将字符串分割成一个有序的子串列表，将这些子串放入一个数组，并返回该数组。

尝试一下
----

语法
--

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

### 参数

`separator`

描述每个分割应该发生在哪里的模式。可以是 `undefined`，一个字符串，或者一个具有 `Symbol.split` 方法的对象——典型的例子是正则表达式。省略 `separator` 或传递 `undefined` 会导致 `split()` 返回一个只包含所调用字符串数组。所有不是 `undefined` 的值或不具有 `@@split` 方法的对象都被强制转换为字符串。

`limit` 可选

一个非负整数，指定数组中包含的子字符串的数量限制。当提供此参数时，split 方法会在指定 `separator` 每次出现时分割该字符串，但在已经有 `limit` 个元素时停止分割。任何剩余的文本都不会包含在数组中。

* 如果在达到极限之前就达到了字符串的末端，那么数组包含的条目可能少于 `limit`。
* 如果 `limit` 为 `0`，则返回 `[]`。

### 返回值

在给定字符串中出现 `separator` 的每一个点上进行分割而成的字符串数组。

描述
--

如果 `separator` 是一个非空字符串，目标字符串会被所有匹配的 `separator` 分割，结果中不包括 `separator`。例如，一个包含制表符分隔值（TSV）的字符串可以通过传递一个制表符作为分隔符来解析，如 `myString.split("\t")`。如果 `separator` 包含多个字符，必须找到整个字符序列才能分割。如果 `separator` 出现在字符串的开头（或结尾），它仍然具有分割的效果，会导致一个空（即零长度）的字符串出现在返回数组的第一个（或最后一个）位置。如果 `separator` 没有出现在 `str` 中，返回的数组包含一个元素，其中是整个字符串。

如果 `separator` 是一个空字符串（`""`），`str` 被转换为一个由其 UTF-16 字符组成的数组，形成的字符串的两端没有空字符。

**备注：** `"".split("")` 是唯一一种字符串作为 `separator` 参数传入的生成空数组的方法。

**警告：** 当空字符串（`""`）被用作分隔符时，字符串**不是**由*用户感知的字符*（grapheme cluster）或 unicode 字符（码位）分割，而是由 UTF-16 代码单位分割。这破坏了代理对。请参阅 StackOverflow 上的“How do you get a string to a character array in JavaScript?”。

如果 `separator` 是一个匹配空字符串的正则表达式，匹配是由 UTF-16 码元（code unit）还是 Unicode 码位（code point）分割，取决于是否设置了 `u` 标志。

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

如果 `separator` 是包含捕获括号的正则表达式，则每次 `separator` 匹配时，捕获括号的结果（包括任何 `undefined` 的结果）将被拼接到输出数组中。此行为是由正则表达式对象的 `Symbol.split` 方法指定的。

如果 `separator` 是一个具有 `Symbol.split` 方法的对象，该方法被调用，目标字符串和 `limit` 作为参数， `this` 设置为该对象。它的返回值成为 `split` 的返回值。

任何其他值在作为分隔符（separator）使用之前都将被强制转换为字符串。

示例
--

### 使用 split()

当字符串为空并且指定了一个非空的分隔符，`split()` 返回 `[""]`。如果字符串和分隔符都是空字符串，将返回一个空数组。

```js
const emptyString = "";

// 字符串是空的，分隔符是非空的
console.log(emptyString.split("a"));
// [""]

// 字符串和分隔符都是空的
console.log(emptyString.split(emptyString));
// []
```

下面的示例定义了一个函数，使用 `separator` 将一个字符串分割成一个字符串数组。在分割字符串后，该函数记录信息，指出原始字符串（分割前）、使用的分隔符、数组中的元素数，以及各个数组元素。

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

  console.log("原始字符串为：", stringToSplit);
  console.log("分隔符为：", separator);
  console.log(
    "分隔后的数组有",
    arrayOfStrings.length,
    "个元素：",
    arrayOfStrings.join(" / "),
  );
}

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

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

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

上述示例会产生如下输出：
```

原始字符串为："Oh brave new world that has such people in it."
分隔符为：" "
分隔后的数组有 10 个元素：Oh / brave / new / world / that / has / such / people / in / it. /

原始字符串为："Oh brave new world that has such people in it."
分隔符为："undefined"
分隔后的数组有 1 个元素：Oh brave new world that has such people in it. /

原始字符串为："Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
分隔符为：","
分隔后的数组有 12 个元素：Jan / Feb / Mar / Apr / May / Jun / Jul / Aug / Sep / Oct / Nov / Dec /
```

### 移除字符串中的空格

下例中，`split()` 方法会查找“0 或多个空白字符接着分号，再接着 0 或多个空白字符”模式的字符串，找到后，就将空白符和分号从字符串中移除，`nameList` 是 `split` 的返回数组。

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

console.log(names);

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

console.log(nameList);
```

上例输出两行，第一行输出原始字符串，第二行输出结果数组。
```

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

### 限制返回值中分割元素数量

下例中，`split` 查找字符串中的 0 或多个空格，并返回找到的前 3 个分割元素。

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

console.log(splits);
```

上例输出：
```

["Hello", "World.", "How"]
```

### 使用 `RegExp` 来分割使结果中包含分割符

如果 `separator` 包含捕获括号 `( )`，则其匹配结果将会包含在返回的数组中。

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

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

**备注：** `\d` 匹配从 0 到 9 的数字字符类。

### 使用自定义分割器

一个包含 `Symbol.split` 方法的对象可以用作分割器，可以自定义分割行为。

下面的示例使用一个由递增的数字组成的内部状态来分割一个字符串：

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

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

下面的示例使用一个内部状态来强制执行某些行为，并确保产生一个“有效”的结果。

```js
const DELIMITER = ";";

// 分割命令，移除任何不合法或不需要的值
const splitCommands = {
  [Symbol.split](str, lim) {
    const results = [];
    const state = {
      on: false,
      brightness: {
        current: 2,
        min: 1,
        max: 3,
      },
    };
    let pos = 0;
    let matchPos = str.indexOf(DELIMITER, pos);

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

      switch (subString) {
        case "light on":
          // 如果 `on` 状态已经为 true，什么都不做。
          if (!state.on) {
            state.on = true;
            results.push(subString);
          }
          break;

        case "light off":
          // 如果 `on` 状态已经为 false，什么都不做。
          if (state.on) {
            state.on = false;
            results.push(subString);
          }
          break;

        case "brightness up":
          // 亮度有一个最大值检查
          if (state.brightness.current < state.brightness.max) {
            state.brightness.current += 1;
            results.push(subString);
          }
          break;

        case "brightness down":
          // 亮度有一个最小值检查
          if (state.brightness.current > state.brightness.min) {
            state.brightness.current -= 1;
            results.push(subString);
          }
          break;
      }

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

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

    // 如果到达分割极限 `lim`，不要添加剩下的命令
    if (results.length < lim) {
      results.push(str.slice(pos).trim());
    }
    return results;
  },
};

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

规范
--

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

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

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

参见
--

* `cors-js` 中 `String.prototype.split` 的 polyfill 及对 `Symbol.split` 现代行为的支持进行修复和实现
* `String.prototype.charAt()`
* `String.prototype.indexOf()`
* `String.prototype.lastIndexOf()`
* `Array.prototype.join()`
* 在 JavaScript 中使用正则表达式


String.prototype.trimEnd() - JavaScript

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

`String` 的 **`trimEnd()`** 方法会从字符串的结尾移除空白字符，并返回一个新的字符串，而不会修改原始字符串。`trimRight()` 是该方法的别名。

尝试一下
----

语法
--

```js
trimEnd()

trimRight()
```

### 返回值

一个新的字符串，表示从 `str` 的末尾（右侧）去除空白字符后的结果。空白字符定义为空白符加上行终止符。

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

### 别名

在 `trim()` 标准化后，引擎也实现了非标准的 `trimRight` 方法。然而，为了与 `padEnd()` 保持一致，在该方法标准化时，选择了 `trimEnd` 作为其名称。出于 Web 兼容性的考虑，`trimRight` 仍然作为 `trimEnd` 的别名，它们引用的是完全相同的函数对象。在某些引擎中，这意味着：

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

示例
--

### 使用 trimEnd()

下面的示例从 `str` 的末尾去除空白字符，但不会去除开头的空白字符。

```js
let str = " foo ";

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

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.trimEnd` 的 polyfill
* `String.prototype.trim()`
* `String.prototype.trimStart()`


String.prototype.fontsize() - JavaScript

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

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

`String` 值的 **`fontsize()`** 方法会创建一个 `<font>` 元素字符串，其中嵌入了调用字符串（`<font size="...">str</font>`），从而导致该字符串以指定的字体大小显示。

**备注：** 所有的 HTML 包装方法都已经被弃用，并且仅为了兼容性而标准化。对于 `fontsize()` 方法来说，`<font>` 元素本身在 HTML5 中已被移除，不应再使用。Web 开发者应该使用 CSS 属性来代替。

语法
--

```js
fontsize(size)
```

### 参数

`size`

一个介于 1 和 7 之间的整数，或表示介于 1 和 7 之间的有符号整数的字符串。

### 返回值

一个以 `<font size="size">` 开始标签开头的字符串（`size` 中的双引号被替换为 `"`），然后是文本 `str`，最后是 `</font>` 结束标签。

描述
--

`fontsize()` 方法本身只是简单地将字符串部分连接在一起，没有进行任何验证或规范化。然而，为了创建有效的 `<font>` 元素，当你将大小指定为整数时，你将 `str` 的字体大小设置为 7 个定义的大小之一。你还可以将 `size` 指定为字符串，例如 `"-2"` 或 `"+3"`，以相对于默认值 3 调整 `str` 的字体大小。

示例
--

### 使用 fontsize()

以下示例使用字符串方法来改变字符串的大小：

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

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

使用 `element.style` 对象，你可以获取元素的 `style` 属性并进行更通用的操作，例如：

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.fontsize` 的 polyfill
* `String.prototype.big()`
* `String.prototype.small()`


String.prototype.anchor() - JavaScript

String.prototype.anchor()
=========================

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

`String` 值的 **`anchor()`** 方法创建一个带有名称的 `<a>` 元素字符串，其中嵌入了调用的字符串（`<a name="...">str</a>`）。

**备注：** 所有的 HTML 包装方法都已被弃用，并且仅为了兼容性而标准化。请使用 DOM API（比如 `document.createElement()`）代替。

HTML 规范不再允许 `<a>` 元素具有 `name` 属性，因此该方法甚至无法创建有效的标记。

语法
--

```js
anchor(name)
```

### 参数

`name`

一个字符串，表示要生成的 `<a name="...">` 开始标签的 `name` 属性。

### 返回值

一个以 `<a name="name">` 开始标签开头的字符串（`name` 中的双引号被替换为 `"`），然后是文本 `str`，最后是一个 `</a>` 结束标签。

示例
--

### 使用 anchor()

```js
const myString = "内容目录";

document.body.innerHTML = myString.anchor("内容锚点");
```

将会输出下面的 HTML：

```html
<a name="内容锚点">内容目录</a>
```

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.anchor` 的 polyfill
* `String.prototype.link()`


String.prototype.sub() - JavaScript

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

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

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

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

语法
--

```js
sub()
```

### 参数

无。

### 返回值

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

示例
--

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

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

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

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

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

规范
--

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

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

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

参见
--

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


String.prototype.link() - JavaScript

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

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

`String` 值的 **`link()`** 方法创建一个 `<a>` 元素字符串，其中嵌入了调用的字符串（`<a href="...">str</a>`），用作指向另一个 URL 的超文本链接。

**备注：** 所有 HTML 包装方法都已被弃用，并且仅为了兼容性而标准化。请使用 DOM API（例如 `document.createElement()`）代替。

语法
--

```js
link(url)
```

### 参数

`url`

任何能够指定 `<a>` 元素的 `href` 属性的字符串；它应当是有效的 URL（相对或绝对），任何 `&` 字符将会被转义为 `&`。

### 返回值

一个以 `<a href="url">` 开始标签开始（`url` 中的双引号被替换为 `"`），接着是文本 `str`，最后是 `</a>` 结束标签的字符串。

示例
--

### 使用 link()

下面的示例将单词“MDN”显示为一个超文本链接，点击该链接将用户返回到 Mozilla Developer Network。

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

console.log(`点击返回 ${hotText.link(url)}`);
// 点击返回 <a href="https://developer.mozilla.org/">MDN</a>
```

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.link` 的 polyfill
* `String.prototype.anchor()`
* `document.links`


String.prototype.toString() - JavaScript

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

`String` 的 **`toString()`** 方法返回该字符串的值。

尝试一下
----

语法
--

```js
toString()
```

### 返回值

表示指定字符串值的字符串。

描述
--

`String` 对象重写了 `Object` 的 `toString` 方法；它不会继承 `Object.prototype.toString()`。对于 `String` 值，`toString` 方法返回字符串本身（如果它是原始值）或 `String` 对象封装的字符串。它的实现与 `String.prototype.valueOf()` 完全相同。

`toString()` 方法要求其 `this` 值为 `String` 原始值或封装对象。对于其他 `this` 值，它会抛出 `TypeError` 而不尝试将其转换为字符串值。

由于 `String` 没有 `[@@toPrimitive]()` 方法，当一个 `String` *对象*在期望字符串的上下文中使用时（比如在模板字面量中），JavaScript 会自动调用 `toString()` 方法。然而，`String` *原始值*不会使用 `toString()` 方法来进行字符串强制转换——因为它们已经是字符串，所以不会进行转换。

```js
String.prototype.toString = () => "已经被重写了";
console.log(`${"foo"}`); // "foo"
console.log(`${new String("foo")}`); // "已经被重写了"
```

示例
--

### 使用 toString()

以下示例输出一个 `String` 对象的字符串值：

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

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

规范
--

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

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

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

参见
--

* `String.prototype.valueOf()`


String.prototype.repeat() - JavaScript

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

**`repeat()`** 方法构造并返回一个新字符串，其中包含指定数量的所调用的字符串副本，这些副本连接在一起。

尝试一下
----

语法
--

```js
repeat(count)
```

### 参数

`count`

介于 `0` 和 `+Infinity` 之间的整数。表示在新构造的字符串中重复了多少遍原字符串。

### 返回值

包含指定字符串的指定数量副本的新字符串。

### 异常

`RangeError`

如果 `count` 为负值，或者 `count` 超过了字符串的最大长度，将抛出错误。

示例
--

### 使用 repeat()

```js
"abc".repeat(-1); // RangeError
"abc".repeat(0); // ''
"abc".repeat(1); // 'abc'
"abc".repeat(2); // 'abcabc'
"abc".repeat(3.5); // 'abcabcabc'（count 将被转换为整数）
"abc".repeat(1 / 0); // RangeError

({ toString: () => "abc", repeat: String.prototype.repeat }).repeat(2);
// 'abcabc'（repeat() 是一个通用方法）
```

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.repeat` 的 polyfill
* `String.prototype.concat()`


String.prototype.endsWith() - JavaScript

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

**`endsWith()`** 方法用于判断一个字符串是否以指定字符串结尾，如果是则返回 `true`，否则返回 `false`。

尝试一下
----

语法
--

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

### 参数

`searchString`

要搜索的作为结尾的字符串，不能是正则表达式。所有非正则表达式的值都会被强制转换为字符串，因此如果该参数被省略或传入 `undefined`，`endsWith()` 方法会在字符串中搜索 `"undefined"`，这通常不是你想要的。

`endPosition` 可选

预期找到 `searchString` 的末尾位置（即 `searchString` 最后一个字符的索引加 1）。默认为 `str.length`。

### 返回值

如果被检索字符串的末尾出现了指定的字符串（包括 `searchString` 为空字符串的情况），则返回 **`true`**；否则返回 **`false`**。

### 异常

`TypeError`

如果 `searchString` 是一个正则表达式，则会抛出。

描述
--

这个方法可以让你确定一个字符串是否以另一个字符串结尾。该方法区分大小写。

示例
--

### 使用 endsWith()

```js
const str = "生存还是毁灭，这是一个问题。";

console.log(str.endsWith("问题。")); // true
console.log(str.endsWith("毁灭")); // false
console.log(str.endsWith("毁灭", 6)); // true
```

规范
--

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

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

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

参见
--

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


String.prototype.indexOf() - JavaScript

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

`String` 的 **`indexOf()`** 方法在字符串中搜索指定子字符串，并返回其第一次出现的位置索引。它可以接受一个可选的参数指定搜索的起始位置，如果找到了指定的子字符串，则返回的位置索引大于或等于指定的数字。

尝试一下
----

语法
--

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

### 参数

`searchValue`

要搜索的子字符串。所有传入值都会被强制转换为字符串，因此如果该参数被省略或传入 `undefined`，`indexOf()` 方法会在字符串中搜索 `"undefined"`，这通常不是你想要的。

`position` 可选

该方法返回指定子字符串在大于或等于 `position` 位置的第一次出现的索引，默认为 `0`。如果 `position` 大于调用字符串的长度，则该方法根本不搜索调用字符串。如果 `position` 小于零，该方法的行为就像 `position` 为 `0` 时一样。

* `hello world hello'.indexOf('o', -5)` 返回 `4`——因为它使该方法的行为类似于第二个参数为 `0`，并且 `o` 在大于或等于 `0` 位置的第一次出现是在 `4` 位置。
* `'hello world hello'.indexOf('world', 12)` 返回 `-1`——因为，虽然子字符串 `world` 确实出现在索引 `6` 处，但该位置不大于或等于 `12`。
* `'hello world hello'.indexOf('o', 99)` 返回 `-1`——因为 `99` 大于 `hello world hello` 的长度，这会导致方法根本不搜索字符串。

### 返回值

查找的字符串 `searchValue` 的第一次出现的索引，如果没有找到，则返回 `-1`。

#### 搜索空字符串时的返回值

搜索空字符串会产生奇怪的结果。如果没有第二个参数，或者第二个参数的值小于调用字符串的长度，则返回值与第二个参数的值相同：

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

但是，如果第二个参数的值大于或等于字符串的长度，则返回值是字符串的长度：

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

在前一个实例中，该方法的行为就像在第二个参数指定的位置之后发现了一个空字符串。在后一个实例中，该方法的行为就好像在调用字符串的末尾找到了一个空字符串。

描述
--

字符串的索引从零开始：字符串的第一个字符的索引为 `0`，字符串的最后一个字符的索引为字符串长度减 1。

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

`indexOf()` 方法是区分大小写的。例如，下面的表达式将返回 `-1`：

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

### 检测指定字符串是否存在

当检查字符串中是否出现特定的子字符串时，正确的检查方法是测试返回值是否为 `-1`：

```js
"Blue Whale".indexOf("Blue") !== -1; // true；在 'Blue Whale' 中找到 'Blue'
"Blue Whale".indexOf("Bloe") !== -1; // false；'Blue Whale' 中不存在 'Bloe'
```

示例
--

### 使用 indexOf()

下面的例子使用 `indexOf()` 来定位字符串 `"Brave new world"` 中的子字符串。

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

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

### indexOf() 和区分大小写

下例定义了两个字符串变量。

两个变量包含相同的字符串，只是第二个字符串中的某些字符为大写。第一个 `console.log()` 方法输出 `19`。但是由于 `indexOf()` 方法区分大小写，因此不会在 `myCapString` 中发现字符串 `“cheddar"`，所以第二个 `console.log()` 方法会输出 `-1`。

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

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

### 使用 indexOf() 统计一个字符串中某个字母出现的次数

在下例中，使用 `count` 来记录字母 `e` 在字符串 `str` 中出现的次数：

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

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

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

规范
--

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

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

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

参见
--

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


String.prototype.matchAll() - JavaScript

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

**`matchAll()`** 方法返回一个迭代器，该迭代器包含了检索字符串与正则表达式进行匹配的所有结果（包括捕获组）。

尝试一下
----

语法
--

```js
matchAll(regexp)
```

### 参数

`regexp`

一个正则表达式对象，或者是任何具有 `Symbol.matchAll` 方法的对象。

如果 `regexp` 不是一个 `RegExp` 对象，并且没有 `Symbol.matchAll` 方法，它将通过 `new RegExp(regexp, 'g')` 被隐式转换为一个 `RegExp` 对象。

如果 `regexp` 是一个正则表达式，那么它必须设置了全局（`g`）标志，否则会抛出 `TypeError` 异常。

### 返回值

一个匹配结果的可迭代迭代器对象（它不可重新开始）。每个匹配结果都是一个数组，其形状与 `RegExp.prototype.exec()` 的返回值相同。

### 异常

`TypeError`

如果 `regexp` 是一个正则表达式，且没有设置全局（`g`）标志（其 `flags` 属性不包含 `"g"`），则会抛出该异常。

描述
--

`String.prototype.matchAll` 方法本身的实现非常简单，它只是调用了参数的 `Symbol.matchAll` 方法，并将字符串作为第一个参数传递了进去（除了额外的输入验证，即正则表达式必须是全局的）。实际的实现来自 `RegExp.prototype[@@matchAll]()`。

示例
--

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

如果没有 `matchAll()` 方法，仍然可以使用带有 `g` 标志的正则表达式调用 `regexp.exec()` 来在循环中获取所有匹配结果：

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

while ((match = regexp.exec(str)) !== null) {
  console.log(
    `找到 ${match[0]} 起始位置=${match.index} 结束位置=${regexp.lastIndex}。`,
  );
}
// 找到 football 起始位置=6 结束位置=14。
// 找到 foosball 起始位置=16 结束位置=24。
```

如果有 `matchAll()` 方法，则可以避免使用 `while` 循环和带有 `g` 标志的 `exec`。相反，你可以获得一个迭代器，以便使用更方便的 `for...of` 循环、数组展开语法或 `Array.from()` 构造函数：

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

for (const match of matches) {
  console.log(
    `找到 ${match[0]} 起始位置=${match.index} 结束位置=${
 match.index + match[0].length
 }.`,
  );
}
// 找到 football 起始位置=6 结束位置=14.
// 找到 foosball 起始位置=16 结束位置=24.

// 匹配迭代器在 for...of 迭代后用尽
// 再次调用 matchAll 以创建新的迭代器
Array.from(str.matchAll(regexp), (m) => m[0]);
// [ "football", "foosball" ]
```

如果没有 `g` 标志，`matchAll` 会抛出异常。

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

`matchAll` 内部做了一个 `regexp` 的复制，所以不像 `regexp.exec()`，`lastIndex` 在字符串扫描后不会改变。

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

然而，这也意味着，与在循环中使用 `regexp.exec()` 不同，你不能更改 `lastIndex` 来使正则表达式前进或倒退。

### 比 String.prototype.match() 更好的捕获组获取方式

`matchAll()` 方法的另一个重要优点是改进了对于捕获组的获取方式。

当使用全局 `g` 标志调用 `match()` 方法时，捕获组会被忽略：

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

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

使用 `matchAll` 方法，可以轻松获取捕获组：

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

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

### 使用实现了 @@matchAll 的非正则对象调用 matchAll()

如果一个对象有一个 `Symbol.matchAll` 方法，它可以被用作自定义匹配器。`Symbol.matchAll` 的返回值将成为 `matchAll()` 的返回值。

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

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.matchAll` 的 polyfill
* `String.prototype.match()`
* 在 JavaScript 中使用正则表达式
* 捕获组
* `RegExp`
* `RegExp.prototype.exec()`
* `RegExp.prototype.test()`
* `RegExp.prototype[@@matchAll]()`


String.prototype.bold() - JavaScript

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

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

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

**备注：** 所有 HTML 包装方法都已被弃用，并且仅为了兼容性而标准化。请使用 DOM API（例如 `document.createElement()`）代替。

语法
--

```js
bold()
```

### 返回值

一个以 `<b>` 开始标签开头的字符串，接着是文本 `str`，然后是 `</b>` 结束标签。

示例
--

### 使用 bold()

以下示例使用已弃用的字符串方法来更改字符串的格式：

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

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.bold` 的 polyfill
* `String.prototype.blink()`
* `String.prototype.italics()`
* `String.prototype.strike()`


String.prototype.includes() - JavaScript

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

**`includes()`** 方法执行区分大小写的搜索，以确定是否可以在一个字符串中找到另一个字符串，并根据情况返回 `true` 或 `false`。

尝试一下
----

语法
--

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

### 参数

`searchString`

要在 `str` 中搜索的字符串。不能是正则表达式。

`position` 可选

在字符串中开始搜索 `searchString` 的位置。（默认为 `0`。）

`searchString`

一个要在 `str` 中查找的字符串。不能是正则表达式。所有非正则表达式的值都会被强制转换为字符串，因此如果该参数被省略或传入 `undefined`，`includes()` 方法会在字符串中搜索 `"undefined"`，这通常不是你想要的。

`position` 可选

在字符串中开始搜索 `searchString` 的位置。默认值为 `0`。

### 返回值

如果在给定的字符串中找到了要搜索的字符串（包括 `searchString` 为空字符串的情况），则返回 **`true`**，否则返回 **`false`**。

### 异常

`TypeError`

如果 `searchString` 是一个正则表达式，则会抛出。

描述
--

此方法可以帮你判断一个字符串是否包含另外一个字符串。

### 区分大小写

`includes()` 方法是区分大小写的。例如，下面的表达式会返回 `false`：

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

你可以通过将原字符串和搜索字符串全部转换为小写来解决这个约束：

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

示例
--

### 使用 includes()

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

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

规范
--

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

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

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

参见
--

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


String.prototype.trimStart() - JavaScript

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

`String` 的 **`trimStart()`** 方法会从字符串的开头移除空白字符，并返回一个新的字符串，而不会修改原始字符串。`trimLeft()` 是该方法的别名。

尝试一下
----

语法
--

```js
trimStart()

trimLeft()
```

### 返回值

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

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

### 别名

在 `trim()` 标准化后，引擎也实现了非标准的 `trimLeft` 方法。然而，为了与 `padStart()` 保持一致，在该方法标准化时，选择了 `trimStart` 作为其名称。出于 Web 兼容性的考虑，`trimLeft` 仍然作为 `trimStart` 的别名，它们引用的是完全相同的函数对象。在某些引擎中，这意味着：

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

示例
--

### 使用 trimStart()

下面的示例从 `str` 的开头去除空白字符，但不会去除结尾的空白字符。

```js
let str = " foo ";

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

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.trimStart` 的 polyfill
* `String.prototype.trim()`
* `String.prototype.trimEnd()`


String() 构造函数 - JavaScript

String() 构造函数
=============

**`String()`** 构造函数创建 `String` 对象。当作为函数调用时，它返回 String 类型的原始值。

语法
--

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

**备注：** `String()` 被调用时可以带或不带 `new`，但会有不同的效果。请参见返回值。

### 参数

`thing`

任何要转换为字符串的内容。

### 返回值

当 `String` 作为构造函数（使用 `new`）被调用时，它会创建一个 `String` 对象，该对象**不是**原始类型。

当 `String` 作为函数被调用时，它会将参数强制转换为一个字符串原始类型。Symbol 值会被转换成 `"Symbol(description)"`，其中 `description` 是该 Symbol 的 description 属性值，而不会抛出错误。

**警告：** 你应该很少需要使用 `String` 作为构造函数。

示例
--

### String 构造函数和 String 函数

String 函数和 String 构造函数产生不同的结果：

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

在这里，该函数生成了一个字符串（即原始值），如其所述。然而，构造函数生成了一个类型为 `String` 的实例（即一个对象包装器），这就是为什么你很少需要使用 `String` 作为构造函数的原因。

### 使用 String() 将 Symbol 转换为字符串：

`String()` 是唯一一种可以将 Symbol 转换为字符串而不抛出异常的方式，因为它非常明确。

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

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

规范
--

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

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

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

参见
--

* JavaScript 指南中的文本格式化


String.prototype.padEnd() - JavaScript

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

**`padEnd()`** 方法会将当前字符串从末尾开始填充给定的字符串（如果需要会重复填充），直到达到给定的长度。填充是从当前字符串的末尾开始的。

尝试一下
----

语法
--

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

### 参数

`targetLength`

当前 `str` 填充后的长度。如果该值小于或等于 `str.length`，则会直接返回当前 `str`。

`padString` 可选

用于填充当前 `str` 的字符串。如果 `padString` 太长，无法适应 `targetLength`，则会被截断：对于从左到右的语言，左侧的部分将会被保留；对于从右到左的语言，右侧的部分将会被保留。默认值为“ ” (`U+0020`)。

### 返回值

在当前 `str` 末尾填充 `padString` 直到达到给定的 `targetLength` 所形成的 `String`。

示例
--

### 使用 padEnd

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.padEnd` 的 polyfill
* `String.prototype.padStart()`


String.prototype.slice() - JavaScript

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

**`slice()`** 方法提取字符串的一部分，并将其作为新字符串返回，而不修改原始字符串。

尝试一下
----

语法
--

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

### 参数

`indexStart`

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

`indexEnd` 可选

要返回的子字符串中排除的第一个字符的索引。

### 返回值

一个包含提取的字符串片段的新字符串。

描述
--

`slice()` 方法从一个字符串中提取文本并返回一个新的字符串。对它们中的一个的文本进行的更改不会影响另一个字符串。

`slice()` 方法提取直到但不包括 `indexEnd` 的文本。例如，`str.slice(1, 4)` 提取的是第二个字符到第四个字符（字符的索引为 `1`、`2` 和 `3`）。

* 如果 `indexStart >= str.length`，则返回一个空字符串。
* 如果 `indexStart < 0`，则索引从字符串末尾开始计数。更正式地说，在这种情况下，子字符串从 `max(indexStart + str.length, 0)` 开始。
* 如果 `indexStart` 被省略、为 undefined，或无法转换为数字（使用 `Number(indexStart)`），则将其视为 `0`。
* 如果 `indexEnd` 被省略、为 undefined，或无法转换为数字（使用 `Number(indexEnd)`），或者 `indexEnd >= str.length`，则 `slice()` 提取到字符串的末尾。
* 如果 `indexEnd < 0`，则索引从字符串末尾开始计数。更正式地说，在这种情况下，子字符串在 `max(indexEnd + str.length, 0)` 处结束。
* 在标准化负值后，如果 `indexEnd <= indexStart`（即 `indexEnd` 表示位于 `indexStart` 之前的字符），则返回一个空字符串。
示例
--

### 使用 slice() 创建一个新的字符串

以下示例使用 `slice()` 创建了一个新字符串。

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

### 使用负值索引调用 slice()

下面的例子在使用 `slice()` 时传入了负值作为索引。

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

这个例子通过从字符串末尾倒数 `11` 个字符来找到起始索引，并通过从字符串开头正数 `16` 个字符来找到结束索引。

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

在这个例子中，它通过从字符串开头正数 `11` 个字符来找到起始索引，并通过从字符串末尾倒数 `7` 个字符来找到结束索引。

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

这些参数通过从字符串末尾倒数 `5` 个字符来找到起始索引，并通过从字符串末尾倒数 `1` 个字符来找到结束索引。

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

规范
--

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

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

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

参见
--

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


String.fromCharCode() - JavaScript

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

**`String.fromCharCode()`** 静态方法返回由指定的 UTF-16 码元序列创建的字符串。

尝试一下
----

语法
--

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

### 参数

`numN`

一个介于 `0` 和 `65535`（`0xFFFF`）之间的数字，表示一个 UTF-16 码元。大于 `0xFFFF` 的数字会被截断为最后的 16 位。不进行有效性检查。

### 返回值

一个长度为 `N` 的字符串，由 `N` 个指定的 UTF-16 码元组成。

描述
--

因为 `fromCharCode()` 是 `String` 的静态方法，所以始终使用 `String.fromCharCode()` 来调用它，而不是作为你创建的 `String` 值的方法。

Unicode 码位的范围是从 `0` 到 `1114111`（`0x10FFFF`）。`charCodeAt()` 总是返回一个小于 `65536` 的值，因为较高的码位由*一对* 16 位代理伪字符组成。因此，为了生成一个值大于 `65535` 的完整字符，需要提供两个码元（就好像操作一个包含两个字符的字符串）。有关 Unicode 的信息，请参阅 UTF-16 字符、Unicode 码位和字素簇。

由于 `fromCharCode()` 仅适用于 16 位的值（与 `\u` 转义序列相同），因此需要使用代理对来返回补充字符。例如，`String.fromCharCode(0xd83c, 0xdf03)` 和 `"\ud83c\udf03"` 都返回码位 `U+1F303` "Night with Stars"。虽然补充码位值（例如 `0x1f303`）与表示它的两个代理值（例如 `0xd83c` 和 `0xdf03`）之间存在数学关系，但每次使用补充码位时都需要额外的步骤来计算或查找代理对值。出于这个原因，使用 `String.fromCodePoint()` 更方便，它可以根据实际的码位值返回补充字符。例如，`String.fromCodePoint(0x1f303)` 返回码位 `U+1F303` "Night with Stars"。

示例
--

### 使用 fromCharCode()

在 UTF-16 中，BMP 字符使用单个码元：

```js
String.fromCharCode(65, 66, 67); // 返回 "ABC"
String.fromCharCode(0x2014); // 返回 "—"
String.fromCharCode(0x12014); // 也返回 "—"；数字 1 被截断并忽略
String.fromCharCode(8212); // 也返回 "—"；8212 是 0x2014 的十进制表示
```

在 UTF-16 中，补充字符需要两个码元（即一个代理对）：

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

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

规范
--

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

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

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

参见
--

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


String.fromCodePoint() - JavaScript

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

**`String.fromCodePoint()`** 静态方法将根据指定的码位序列返回一个字符串。

尝试一下
----

语法
--

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

### 参数

`numN`

一个介于 `0` 和 `0x10FFFF`（包括两者）之间的整数，表示一个 Unicode 码位。

### 返回值

通过使用指定的码位序列创建的字符串。

### 异常

`RangeError`

如果 `numN` 不是整数、小于 `0` 或者在转换为数字后大于 `0x10FFFF`，则会抛出该异常。

说明
--

`fromCodePoint()` 是 `String` 的静态方法，因此始终使用 `String.fromCodePoint()` 调用它，而不是作为你创建的 `String` 值的方法。

Unicode 码位范围从 `0` 到 `1114111`（`0x10FFFF`）。在 UTF-16 中，每个字符串索引是一个取值范围为 `0` 到 `65535` 的码元。较高的码位由一对 16 位代理伪字符表示。因此，`fromCodePoint()` 可能返回一个字符串，其在 UTF-16 码元中的 `length` 大于传递的参数个数。有关 Unicode 的更多信息，请参阅 UTF-16 字符、Unicode 码位和字素簇。

示例
--

### 使用 fromCodePoint()

有效输入：

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

无效输入：

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

### 与 fromCharCode() 的比较

`String.fromCharCode()` 方法无法通过指定其码位来返回补充字符（即码位 `0x010000` 至 `0x10FFFF`）。相反，它需要使用 UTF-16 代理对来返回补充字符：

```js
String.fromCharCode(0xd83c, 0xdf03); // 码位 U+1F303（夜晚与星星）=== "\uD83C\uDF03"
String.fromCharCode(55356, 57091);
```

另一方面，`String.fromCodePoint()` 可以通过指定其码位（相当于 UTF-32 码元）返回 4 个字节的补充字符，以及更常见的 2 个字节的 BMP 字符：

```js
String.fromCodePoint(0x1f303); // 或十进制数 127747
```

规范
--

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

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

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

参见
--

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


String.prototype.fontcolor() - JavaScript

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

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

`String` 值的 **`fontcolor()`** 方法会创建一个 `<font>` 元素字符串，其中嵌入了调用字符串（`<font color="...">str</font>`），从而导致该字符串以指定的字体颜色显示。

**备注：** 所有的 HTML 包装方法都已经被弃用，并且仅为了兼容性而标准化。对于 `fontcolor()` 方法来说，`<font>` 元素本身在 HTML5 中已被移除，不应再使用。Web 开发者应该使用 CSS 属性来代替。

语法
--

```js
fontcolor(color)
```

### 参数

`color`

该参数可以接受十六进制 RGB 三元组或字符串字面量来表示颜色。颜色名称的字符串字面量可以参考 CSS 颜色参考。

### 返回值

一个以 `<font color="color">` 开头的字符串（`color` 中的双引号被替换为 `"`），然后是文本 `str`，最后以 `</font>` 结束标记。

描述
--

`fontcolor()` 方法本身只是简单地将字符串部分连接在一起，没有进行任何验证或规范化。然而，为了创建有效的 `<font>` 元素，如果你将颜色表示为十六进制 RGB 三元组，你必须使用格式 `rrggbb`。例如，salmon（鲑鱼色）的十六进制 RGB 值为红色 = FA，绿色=80，蓝色=72，因此 salmon 的 RGB 三元组为 `"FA8072"`。

示例
--

### 使用 fontcolor()

下面的示例使用 `fontcolor()` 方法通过生成一个带有 HTML `<font>` 元素的字符串来改变字符串的颜色。

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

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

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

使用 `element.style` 对象，你可以获取元素的 `style` 属性并进行更通用的操作，例如：

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

规范
--

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

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

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

参见
--

* `core-js` 的 `String.prototype.fontcolor` 的 polyfill
* `String.prototype.fontsize()`


String.prototype.toLocaleLowerCase() - JavaScript

String.prototype.toLocaleLowerCase()
====================================

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

尝试一下
----

语法
--

```js
toLocaleLowerCase()
toLocaleLowerCase(locales)
```

### 参数

`locales` 可选

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

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

### 返回值

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

描述
--

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

示例
--

### 使用 toLocaleLowerCase()

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

"\u0130".toLocaleLowerCase("tr") === "i"; // true
"\u0130".toLocaleLowerCase("en-US") === "i"; // false

const locales = ["tr", "TR", "tr-TR", "tr-u-co-search", "tr-x-turkish"];
"\u0130".toLocaleLowerCase(locales) === "i"; // true
```

规范
--

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

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

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

参见
--

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


String.prototype.italics() - JavaScript

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

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

`String` 值的 **`italics()`** 方法会创建一个 `<i>` 元素字符串，其中嵌入了调用的字符串（`<i>str</i>`），从而使该字符串以斜体显示。

**备注：** 所有 HTML 包装方法都已被弃用，并且仅为了兼容性而标准化。请使用 DOM API（例如 `document.createElement()`）代替。

语法
--

```js
italics()
```

### 参数

无。

### 返回值

一个以 `<i>` 开始标签，然后是文本 `str`，最后是 `</i>` 结束标签的字符串。

示例
--

### 使用 italics()

下面的示例使用已弃用的字符串方法来更改字符串的格式：

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

规范
--

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

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

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

参见
--

* `core-js 中` String.prototype.italics `的 polyfill`
* `String.prototype.blink()`
* `String.prototype.bold()`
* `String.prototype.strike()`


String.prototype.charAt() - JavaScript

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

`String` 的 **`charAt()`** 方法返回一个由给定索引处的单个 UTF-16 码元构成的新字符串。

`charAt()` 方法总是将字符串作为 UTF-16 码元序列进行索引，因此它可能会返回孤项代理。要获取给定索引处的完整 Unicode 码位，请使用 `String.prototype.codePointAt()` 和 `String.fromCodePoint()`。

尝试一下
----

语法
--

```js
charAt(index)
```

### 参数

`index`

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

### 返回值

返回一个字符串，该字符串表示指定 `index` 处的字符（恰好是一个 UTF-16 码元）。如果 `index` 超出了 `0` – `str.length - 1` 的范围，`charAt()` 将返回一个空字符串。

描述
--

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

Unicode 码位的范围从 `0` 到 `1114111` (`0x10FFFF`)。`charAt()` 方法总是返回一个其值小于 `65536` 的字符，因为更高的码位是由*一对* 16 位代理伪字符表示的。因此，为了获取值大于 `65535` 的完整字符，需要检索不仅是 `charAt(i)`，还要检索 `charAt(i + 1)`（就像操作一个由两个字符组成的字符串一样），或者使用 `codePointAt(i)` 和 `String.fromCodePoint()` 代替。有关 Unicode 的信息，请参阅 UTF-16 字符、Unicode 码位和字素簇。

`charAt()` 和使用方括号表示法访问指定索引处的字符非常相似。它们的主要区别在于：

* `charAt()` 尝试将 `index` 转换为整数，而方括号表示法不会，直接使用 `index` 作为属性名。
* 如果 `index` 超出范围，`charAt()` 返回一个空字符串，而方括号表示法返回 `undefined`。
示例
--

### 使用 charAt()

下例输出字符串 `"Brave new world"` 不同位置处的字符：

```js
const anyString = "Brave new world";
console.log(`在索引 0 处的字符为 '${anyString.charAt()}'`);
// 没有提供索引，使用 0 作为默认值

console.log(`在索引 0 处的字符为 '${anyString.charAt(0)}'`);
console.log(`在索引 1 处的字符为 '${anyString.charAt(1)}'`);
console.log(`在索引 2 处的字符为 '${anyString.charAt(2)}'`);
console.log(`在索引 3 处的字符为 '${anyString.charAt(3)}'`);
console.log(`在索引 4 处的字符为 '${anyString.charAt(4)}'`);
console.log(`在索引 999 处的字符为 '${anyString.charAt(999)}'`);
```

上面代码的输出为：
```

在索引 0 处的字符为 'B'

在索引 0 处的字符为 'B'
在索引 1 处的字符为 'r'
在索引 2 处的字符为 'a'
在索引 3 处的字符为 'v'
在索引 4 处的字符为 'e'
在索引 999 处的字符为 ''
```

`charAt()` 可能会返回孤项代理，这些代理项不是有效的 Unicode 字符。

```js
const str = "𠮷𠮾";
console.log(str.charAt(0)); // "\ud842"，这不是有效的 Unicode 字符
console.log(str.charAt(1)); // "\udfb7"，这不是有效的 Unicode 字符
```

要获取给定索引处的完整 Unicode 码位，请使用按 Unicode 码位拆分的索引方法，例如 `String.prototype.codePointAt()` 和将字符串展开为 Unicode 码位数组。

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

**备注：** 避免使用 `charAt()` 重新实现上述解决方案。检测孤项代理及其配对很复杂，而内置 API 可能更高效，因为它们直接使用字符串的内部表示形式。如有必要，请安装上述 API 的 polyfill。

规范
--

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

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

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

参见
--

* `String.prototype.indexOf()`
* `String.prototype.lastIndexOf()`
* `String.prototype.charCodeAt()`
* `String.prototype.codePointAt()`
* `String.prototype.split()`
* `String.fromCodePoint()`
* JavaScript 有一个关于 Unicode 的问题——Mathias Bynens


String.prototype.strike() - JavaScript

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

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

`String` 值的 **`strike()`** 方法创建一个 `<strike>` 元素字符串，其中嵌入了调用的字符串（`<strike>str</strike>`），从而使该字符串以删除线的形式显示。

**备注：** 所有 HTML 包装方法都已被弃用，并且仅为了兼容性而标准化。请使用 DOM API（例如 `document.createElement()`）代替。

语法
--

```js
strike()
```

### 参数

无。

### 返回值

一个以 `<strike>` 开始标签开头的字符串，接着是文本 `str`，最后是 `</strike>` 结束标签。

示例
--

### 使用 strike()

下面的示例使用了已弃用的字符串方法来更改字符串的格式：

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

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.strike` 的 polyfill
* `String.prototype.blink()`
* `String.prototype.bold()`
* `String.prototype.italics()`


String.prototype.blink() - JavaScript

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

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

`String` 值的 **`blink()`** 方法创建一个字符串，其在 `<blink>str</blink>` 中嵌入字符串，这使得字符串在旧版浏览器中闪烁。

**备注：** 所有 HTML 包装方法都已被弃用，并且仅为了兼容性而标准化。对于 `blink()` 方法，`<blink>` 元素本身已在现代浏览器中移除，并且闪烁文本违反了多个无障碍标准。请避免以任何方式使用该元素。

语法
--

```js
blink()
```

### 参数

无。

### 返回值

一个以 `<blink>` 开始标签开头的字符串，接着是文本 `str`，然后是 `</blink>` 结束标签。

示例
--

### 使用 blink()

以下示例使用已弃用的字符串方法来更改字符串的格式：

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

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.blink` 的 polyfill
* `String.prototype.bold()`
* `String.prototype.italics()`
* `String.prototype.strike()`


String.prototype.substring() - JavaScript

String.prototype.substring()
============================

`String` 的 **`substring()`** 方法返回该字符串从起始索引到结束索引（不包括）的部分，如果未提供结束索引，则返回到字符串末尾的部分。

尝试一下
----

语法
--

```js
substring(indexStart)
substring(indexStart, indexEnd)
```

### 参数

`indexStart`

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

`indexEnd` 可选

返回子字符串中第一个要排除的字符的索引。

### 返回值

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

描述
--

`substring()` 方法从 `indexStart` 开始提取字符，直到（*但不包括*）`indexEnd`。具体来说：

* 如果省略了 `indexEnd`，则 `substring()` 提取字符直到字符串的末尾。
* 如果 `indexStart` 等于 `indexEnd`，则 `substring()` 返回一个空字符串。
* 如果 `indexStart` 大于 `indexEnd`，则 `substring()` 的效果就像交换了这两个参数一样；请参考下面的示例。

任何小于 `0` 或大于 `str.length` 的参数值都会被视为分别等于 `0` 和 `str.length`。

任何值为 `NaN` 的参数将被视为等于 `0`。

示例
--

### 使用 substring()

下例使用 `substring` 输出字符串 `"Mozilla"` 中的字符：

```js
const anyString = "Mozilla";

console.log(anyString.substring(0, 1)); // 'M'
console.log(anyString.substring(1, 0)); // 'M'

console.log(anyString.substring(0, 6)); // 'Mozill'

console.log(anyString.substring(4)); // 'lla'
console.log(anyString.substring(4, 7)); // 'lla'
console.log(anyString.substring(7, 4)); // 'lla'

console.log(anyString.substring(0, 7)); // 'Mozilla'
console.log(anyString.substring(0, 10)); // 'Mozilla'
```

### 调用 substring() 时使用 length 属性

以下示例使用 `substring()` 方法和 `length` 属性来提取特定字符串的最后字符。这种方法可能更容易记住，因为你不需要像上面的示例那样知道起始和结束索引。

```js
const text = "Mozilla";

// 获取字符串的最后 4 个字符
console.log(text.substring(text.length - 4)); // 打印“illa”

// 获取字符串的最后 5 个字符
console.log(text.substring(text.length - 5)); // 打印“zilla”
```

### substring() 和 substr() 之间的区别

`substring()` 和 `substr()` 方法之间存在细微差别，因此你应该小心不要混淆它们。

* `substr()` 方法的两个参数是 `start` 和 `length`，而 `substring()` 方法的参数是 `start` 和 `end`。
* 如果 `substr()` 的 `start` 索引为负数，它将循环到字符串的末尾，而 `substring()` 会将其限制为 `0`。
* 在 `substr()` 中，如果长度为负数，将被视为零；而在 `substring()` 中，如果 `end` 小于 `start` ，则会交换这两个索引。

此外，`substr()` 被认为是 ECMAScript 中的*遗留特性*，因此如果可能的话最好避免使用它。

```js
const text = "Mozilla";
console.log(text.substring(2, 5)); // "zil"
console.log(text.substr(2, 3)); // "zil"
```

### substring() 和 slice() 之间的区别

`substring()` 和 `slice()` 方法几乎相同，但在处理负数参数时有一些细微差别。

`substring()` 方法在 `indexStart` 大于 `indexEnd` 的情况下会交换它的两个参数，这意味着仍会返回一个字符串。而 `slice()` 方法在这种情况下返回一个空字符串。

```js
const text = "Mozilla";
console.log(text.substring(5, 2)); // "zil"
console.log(text.slice(5, 2)); // ""
```

如果两个参数中的任何一个或两个都是负数或 `NaN`，`substring()` 方法将把它们视为 `0`。

```js
console.log(text.substring(-5, 2)); // "Mo"
console.log(text.substring(-5, -2)); // ""
```

`slice()` 方法也将 `NaN` 参数视为 `0`，但当给定负值时，它会从字符串的末尾开始反向计数以找到索引。

```js
console.log(text.slice(-5, 2)); // ""
console.log(text.slice(-5, -2)); // "zil"
```

请参阅 `slice()` 页面以获取更多关于负数的示例。

### 替换字符串中的子字符串

以下示例替换字符串中的子字符串。它可以替换单个字符和子字符串。示例的最后一个函数调用将字符串 `Brave New World` 更改为 `Brave New Web`。

```js
// 将字符串 fullS 中的 oldS 替换为 newS
function replaceString(oldS, newS, fullS) {
  for (let i = 0; i < fullS.length; ++i) {
    if (fullS.substring(i, i + oldS.length) === oldS) {
      fullS =
        fullS.substring(0, i) +
        newS +
        fullS.substring(i + oldS.length, fullS.length);
    }
  }
  return fullS;
}

replaceString("World", "Web", "Brave New World");
```

请注意，如果 `oldS` 本身是 `newS` 的子字符串，这可能导致无限循环，例如，假如你尝试在此处用 `"OtherWorld"` 替换 `"World"`。

替换字符串的更好方法如下：

```js
function replaceString(oldS, newS, fullS) {
  return fullS.split(oldS).join(newS);
}
```

上面的代码仅作为子字符串操作的示例。如果你需要替换子字符串，大多数情况下你会想要使用 `String.prototype.replace()` 函数。

规范
--

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

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

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

参见
--

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


String.prototype.small() - JavaScript

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

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

`String` 值的 **`small()`** 方法创建一个 `<small>` 元素字符串，其中嵌入了调用的字符串（`<small>str</small>`），从而使该字符串以小号字体显示。

**备注：** 所有 HTML 包装方法都已被弃用，并且仅为了兼容性而标准化。请使用 DOM API（例如 `document.createElement()`）代替。

语法
--

```js
small()
```

### 参数

无。

### 返回值

一个以 `<small>` 开始标签开头的字符串，接着是文本 `str`，最后是 `</small>` 结束标签。

示例
--

### 使用 small()

以下示例使用字符串方法更改字符串的大小：

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

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

使用 `element.style` 对象，你可以获取元素的 `style` 属性并以更通用的方式进行操作，例如：

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.small` 的 polyfill
* `String.prototype.fontsize()`
* `String.prototype.big()`


String.prototype.toLowerCase() - JavaScript

String.prototype.toLowerCase()
==============================

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

尝试一下
----

语法
--

```js
toLowerCase()
```

### 返回值

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

描述
--

`toLowerCase()` 方法返回将字符串转换为小写形式后的值。`toLowerCase()` 不会影响字符串 `str` 本身的值。

示例
--

### 使用 `toLowerCase()`

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

规范
--

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

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

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

参见
--

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


String.prototype.at() - JavaScript

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

**`at()`** 方法接受一个整数值，并返回一个新的 `String`，该字符串由位于指定偏移量处的单个 UTF-16 码元组成。该方法允许正整数和负整数。负整数从字符串中的最后一个字符开始倒数。

尝试一下
----

语法
--

```js
at(index)
```

### 参数

`index`

要返回的字符串字符的索引（位置）。当传递负数时，支持从字符串末端开始的相对索引；也就是说，如果使用负数，返回的字符将从字符串的末端开始倒数。

### 返回值

由位于指定位置的单个 UTF-16 码元组成的 `String`。如果找不到指定的索引，则返回 `undefined` 。

示例
--

### 返回字符串的最后一个字符

以下示例提供了一个函数，该函数返回指定字符串中的最后一个字符。

```js
// 返回给定字符串的最后一个字符的函数
function returnLast(arr) {
  return arr.at(-1);
}

let invoiceRef = "myinvoice01";

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

invoiceRef = "myinvoice02";

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

### 方法对比

下面我们通过比较不同的方法来实现选择 `String` 的倒数第二个字符。尽管以下所有方法都是有效的，但它们凸显了 `at()` 方法的简洁性和可读性。

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

// 使用 length 属性和 charAt() 方法
const lengthWay = myString.charAt(myString.length - 2);
console.log(lengthWay); // 't'

// 使用 slice() 方法
const sliceWay = myString.slice(-2, -1);
console.log(sliceWay); // 't'

// 使用 at() 方法
const atWay = myString.at(-2);
console.log(atWay); // 't'
```

规范
--

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

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

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

参见
--

* `core-js` 中的 `String.prototype.at` 的 polyfill
* at() 方法的 polyfill.
* `String.prototype.indexOf()`
* `String.prototype.lastIndexOf()`
* `String.prototype.charCodeAt()`
* `String.prototype.codePointAt()`
* `String.prototype.split()`


String.prototype.lastIndexOf() - JavaScript

String.prototype.lastIndexOf()
==============================

`String` 的 **`lastIndexOf()`** 方法搜索该字符串并返回指定子字符串最后一次出现的索引。它可以接受一个可选的起始位置参数，并返回指定子字符串在小于或等于指定数字的索引中的最后一次出现的位置。

尝试一下
----

语法
--

```js
lastIndexOf(searchString)
lastIndexOf(searchString, position)
```

### 参数

`searchString`

要搜索的子字符串。所有值都会强制转换为字符串，因此如果该参数被省略或传入 `undefined`，`lastIndexOf()` 方法会在字符串中搜索 `"undefined"`，这通常不是你想要的。

`position` 可选

该方法返回指定子字符串在小于或等于 `position` 的位置中的最后一次出现的索引，默认为 `+Infinity`。如果 `position` 大于调用字符串的长度，则该方法将搜索整个字符串。如果 `position` 小于 `0`，则行为与 `0` 相同，即该方法只在索引 `0` 处查找指定的子字符串。

* `'hello world hello'.lastIndexOf('world', 4)` 返回 `-1`——因为虽然子字符串 `world` 在索引 `6` 处出现，但该位置不小于或等于 `4`。
* `'hello world hello'.lastIndexOf('hello', 99)` 返回 `12`——因为小于或等于 `99` 的位置中，最后一次出现 `hello` 的位置是索引 `12`。
* `'hello world hello'.lastIndexOf('hello', 0)` 和 `'hello world hello'.lastIndexOf('hello', -5)` 都返回 `0`——因为两者都导致该方法只在索引 `0` 处查找 `hello`。

### 返回值

如果找到了 `searchString`，则返回最后一次出现的索引，否则返回 `-1`。

描述
--

字符串的索引从 0 开始：字符串第一个字符的索引为 `0`，字符串最后一个字符的索引为字符串长度减 1。

```js
"canal".lastIndexOf("a"); // 返回 3
"canal".lastIndexOf("a", 2); // 返回 1
"canal".lastIndexOf("a", 0); // 返回 -1
"canal".lastIndexOf("x"); // 返回 -1
"canal".lastIndexOf("c", -5); // 返回 0
"canal".lastIndexOf("c", 0); // 返回 0
"canal".lastIndexOf(""); // 返回 5
"canal".lastIndexOf("", 2); // 返回 2
```

### 区分大小写

`lastIndexOf()` 方法区分大小写。例如，以下表达式返回 `-1`：

```js
"Blue Whale, Killer Whale".lastIndexOf("blue"); // 返回 -1
```

示例
--

### 使用 indexOf() 和 lastIndexOf()

以下示例使用 `indexOf()` 和 `lastIndexOf()` 在字符串 `"Brave, Brave New World"` 中查找值。

```js
const anyString = "Brave, Brave New World";

console.log(anyString.indexOf("Brave")); // 0
console.log(anyString.lastIndexOf("Brave")); // 7
```

规范
--

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

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

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

参见
--

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


String.prototype.padStart() - JavaScript

String.prototype.padStart()
===========================

**`padStart()`** 方法用另一个字符串填充当前字符串（如果需要会重复填充），直到达到给定的长度。填充是从当前字符串的开头开始的。

尝试一下
----

语法
--

```js
padStart(targetLength)
padStart(targetLength, padString)
```

### 参数

`targetLength`

当前 `str` 填充后的长度。如果该值小于或等于 `str.length`，则会直接返回当前 `str`。

`padString` 可选

用于填充当前 `str` 的字符串。如果 `padString` 太长，无法适应 `targetLength`，则会从末尾被截断。默认值为 Unicode“空格”字符（U+0020）。

### 返回值

在开头填充 `padString` 直到达到给定的 `targetLength` 所形成的 `String`。

示例
--

### 简单示例

```js
"abc".padStart(10); // " abc"
"abc".padStart(10, "foo"); // "foofoofabc"
"abc".padStart(6, "123465"); // "123abc"
"abc".padStart(8, "0"); // "00000abc"
"abc".padStart(1); // "abc"
```

### 将数字转换为固定长度的字符串

```js
// JavaScript version of: (unsigned)
// printf "%0\*d" width num
function leftFillNum(num, targetLength) {
  return num.toString().padStart(targetLength, "0");
}

const num = 123;
console.log(leftFillNum(num, 5)); // "00123"
```

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.padStart` 的 polyfill
* `String.prototype.padEnd()`


String.prototype.normalize() - JavaScript

String.prototype.normalize()
============================

`String` 的 **`normalize()`** 方法返回该字符串的 Unicode 标准化形式。

尝试一下
----

语法
--

```js
normalize()
normalize(form)
```

### 参数

`form` 可选

是 `"NFC"`、`"NFD"`、`"NFKC"` 或 `"NFKD"` 其中之一，用于指定 Unicode 标准化形式。如果省略或为 `undefined`，则使用 `"NFC"`。

这些值具有以下含义：

`"NFC"`

规范分解，然后进行规范组合。

`"NFD"`

规范分解。

`"NFKC"`

兼容分解，然后进行规范组合。

`"NFKD"`

兼容分解。

### 返回值

一个包含给定字符串的 Unicode 标准化形式的字符串。

### 异常

`RangeError`

如果 `form` 不是上述指定的值之一，将抛出该异常。

描述
--

Unicode 为每个字符分配一个唯一的数值，称为*码位*。例如，字母 `"A"` 的码位被表示为 U+0041。然而，有时候一个抽象字符可以由一个或多个码位或码位序列来表示，比如字母 `"ñ"` 可以被以下任意一种方式表示：

* 单个码位 U+00F1。
* 字母 `"n"` 的码位（U+006E）后跟组合波浪符的码位（U+0303）。

```js
const string1 = "\u00F1";
const string2 = "\u006E\u0303";

console.log(string1); // ñ
console.log(string2); // ñ
```

然而，由于码位不同，字符串比较不会将它们视为相等。而且由于每个版本中的码位数量不同，它们甚至具有不同的长度。

```js
const string1 = "\u00F1"; // ñ
const string2 = "\u006E\u0303"; // ñ

console.log(string1 === string2); // false
console.log(string1.length); // 1
console.log(string2.length); // 2
```

`normalize()` 方法将字符串转换为一种标准化形式，这有助于解决这个问题，该标准化形式适用于表示相同字符的所有码位序列。有两种主要的标准化形式，一种基于**规范等价性**，另一种基于**兼容性**。

### 规范等价标准化

在 Unicode 中，如果两个码位序列表示相同的抽象字符，并且它们应该始终具有相同的视觉外观和行为（例如，它们应该始终以相同的方式进行排序），则这两个序列具有规范等价性。

你可以使用 `normalize()` 方法并使用 `"NFD"` 或 `"NFC"` 参数来生成一个字符串的形式，该形式对于所有规范等价的字符串都是相同的。在下面的示例中，我们对字符 `"ñ"` 的两种表示进行标准化：

```js
let string1 = "\u00F1"; // ñ
let string2 = "\u006E\u0303"; // ñ

string1 = string1.normalize("NFD");
string2 = string2.normalize("NFD");

console.log(string1 === string2); // true
console.log(string1.length); // 2
console.log(string2.length); // 2
```

#### 组合和分解形式

请注意，在 `"NFD"` 下，标准化形式的长度为 `2`。这是因为 `"NFD"` 给出了规范形式的**分解**版本，其中单个码位被拆分为多个组合码位。对于 `"ñ"`，其分解的规范形式是 `"\u006E\u0303"`。

你可以指定 `"NFC"` 来获取**组合**的规范形式，其中多个码位在可行的情况下被替换为单个码位。对于 `"ñ"`，其组合的规范形式是 `"\u00F1"`：

```js
let string1 = "\u00F1"; // ñ
let string2 = "\u006E\u0303"; // ñ

string1 = string1.normalize("NFC");
string2 = string2.normalize("NFC");

console.log(string1 === string2); // true
console.log(string1.length); // 1
console.log(string2.length); // 1
console.log(string2.codePointAt(0).toString(16)); // f1
```

### 兼容标准化

在 Unicode 中，如果两个码位序列表示相同的抽象字符，并且在某些（但不一定是所有）应用程序中应该被类似地处理，则这两个序列是兼容的。

所有规范等价的序列也是兼容的，但反之不成立。

例如：

* 码位 U+FB00 表示连字 `"ﬀ"`。它与连续的两个码位 U+0066（`"ff"`）兼容。
* 码位 U+24B9 表示符号 `"Ⓓ"`。它与码位 U+0044（`"D"`）兼容。

在某些方面（例如排序）它们应该被视为等价的，而在某些方面（例如视觉外观）则不应该，因此它们不是规范等价的。

你可以使用 `normalize()` 方法并使用 `"NFKD"` 或 `"NFKC"` 参数来生成一个字符串的形式，该形式对于所有兼容的字符串都是相同的：

```js
let string1 = "\uFB00";
let string2 = "\u0066\u0066";

console.log(string1); // ﬀ
console.log(string2); // ff
console.log(string1 === string2); // false
console.log(string1.length); // 1
console.log(string2.length); // 2

string1 = string1.normalize("NFKD");
string2 = string2.normalize("NFKD");

console.log(string1); // ff <- 视觉外观改变了
console.log(string2); // ff
console.log(string1 === string2); // true
console.log(string1.length); // 2
console.log(string2.length); // 2
```

在应用兼容性标准化时，重要的是要考虑你打算如何使用这些字符串，因为标准化形式可能不适用于所有应用程序。在上面的示例中，标准化适用于搜索，因为它使用户可以通过搜索 `"f"` 来找到字符串。但是，对于显示来说可能不合适，因为视觉表示是不同的。

与规范化标准化一样，你可以通过分别传递 `"NFKD"` 或 `"NFKC"` 来请求分解或组合的兼容形式。

示例
--

### 使用 normalize()

```js
// 初始字符串

// U+1E9B: 上方带一个点的拉丁小写字母长 S
// U+0323: 下方组合一个点
const str = "\u1E9B\u0323";

// 规范组合形式（NFC）

// U+1E9B: 上方带一个点的拉丁小写字母长 S
// U+0323: 下方组合一个点
str.normalize("NFC"); // '\u1E9B\u0323'
str.normalize(); // 同上

// 规范分解形式（NFD）

// U+017F: 拉丁小写字母长 S
// U+0323: 下方组合一个点
// U+0307: 上方组合一个点
str.normalize("NFD"); // '\u017F\u0323\u0307'

// 兼容组合（NFKC）

// U+1E69: 拉丁小写字母 S 在上方和下方带一个点
str.normalize("NFKC"); // '\u1E69'

// 兼容分解（NFKD）

// U+0073: 拉丁小写字母 S
// U+0323: 下方组合一个点
// U+0307: 上方组合一个点
str.normalize("NFKD"); // '\u0073\u0323\u0307'
```

规范
--

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

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

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

参见
--

* Unicode 标准附件 #15，Unicode 规范化形式
* Unicode 等价


String.prototype.big() - JavaScript

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

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

`String` 值的 **`big()`** 方法创建一个 `<big>` 元素字符串，其中嵌入了调用的字符串（`<big>str</big>`），从而使该字符串以大字体显示。

**备注：** 所有的 HTML 包装方法都已被弃用，并且仅为了兼容性而标准化。对于 `big()` 方法来说，在 HTML5 中已经移除了 `<big>` 元素，不应再使用它。Web 开发者应该使用 CSS 属性来实现相应的效果。

语法
--

```js
big()
```

### 参数

无。

### 返回值

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

示例
--

### 使用 big()

下面的例子使用了字符串方法来改变一个字符串的字体大小：

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

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

使用 `element.style` 对象，你能更通用地获得和操作该元素的 `style` 属性，例如：

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.big` 的 polyfill
* `String.prototype.fontsize()`
* `String.prototype.small()`


String.prototype.sup() - JavaScript

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

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

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

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

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

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

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]() - JavaScript

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.localeCompare() - JavaScript

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

**`localeCompare()`** 方法返回一个数字，表示参考字符串在排序顺序中是在给定字符串之前、之后还是与之相同。在支持 `Intl.Collator` API 的实现中，该方法仅是调用了 `Intl.Collator` 方法。

当比较大量字符串时，例如对大型数组进行排序，最好创建一个 `Intl.Collator` 对象，并使用其 `compare()` (en-US) 方法提供的函数。

尝试一下
----

语法
--

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

### 参数

`locales` 和 `options` 参数可以自定义函数的行为，并让应用程序指定应使用哪种语言的格式约定。

在支持 `Intl.Collator` API 的实现中，这些参数与 `Intl.Collator()` 构造函数的参数完全对应。而对于不支持 `Intl.Collator` 的实现，应忽略这两个参数，使得返回的比较结果完全依赖于实现——只要求其保持*一致*。

* `compareString`
    + 与 `referenceStr` 进行比较的字符串。所有值都会被强制转换为字符串，因此省略该参数或传入 `undefined` 会导致 `localeCompare()` 与字符串 `"undefined"` 进行比较，这通常不是你想要的。
* `locales` 可选
    + : 表示缩写语言代码（BCP 47 language tag）的字符串，或由此类字符串组成的数组。对应于 `Intl.Collator()` 构造函数的 `locales` 参数。
     在不支持 `Intl.Collator` 的实现中，该参数会被忽略，并且通常会使用主机的区域设置。
* `options` 可选
    + : 一个调整输出格式的对象。对应于 `Intl.Collator()` 构造函数的 `options` 参数。
     在不支持 `Intl.Collator` 的实现中，该参数会被忽略。

参见 `Intl.Collator()` 构造函数以详细了解 `locales` 和 `options` 参数以及如何使用它们。

### 返回值

如果引用字符串（`referenceStr`）存在于比较字符串（`compareString`）之前则为**负数**；如果引用字符串存在于比较字符串之后则为**正数**；相等的时候返回 `0`。

在支持 `Intl.Collator` 的实现中，此方法等价于 `new Intl.Collator(locales, options).compare(referenceStr, compareString)`。

描述
--

返回一个数字表示 `referenceStr` 在排序中是否位于 `compareString` 的前面、后面或二者相同。

* 当 `referenceStr` 在 `compareString` 前面时返回负数
* 当 `referenceStr` 在 `compareString` 后面时返回正数
* 当两者相等时返回 `0`

**警告：** 切勿依赖于 `-1` 或 `1` 这样特定的返回值。

不同浏览器之间（以及不同浏览器版本之间）返回的正负数的值各有不同，因为 W3C 规范中只要求返回值是正值和负值，而没有规定具体的值。一些浏览器可能返回 `-2` 或 `2` 或一些其他的负、正值。

示例
--

### 使用 localeCompare()

```js
// 字母 "a" 在 "c" 之前，产生负值
"a".localeCompare("c"); // -2 or -1 (or some other negative value)

// 按字母顺序，"check" 一词出现在 "against" 之后，产生正值
"check".localeCompare("against"); // 2 or 1 (or some other positive value)

// "a" 和 "a" 相等，产生中性值 0
"a".localeCompare("a"); // 0
```

### 对数组进行排序

`localeCompare()` 可以对数组进行大小写不敏感的排序。

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

### 检查浏览器对扩展参数的支持

`locales` 和 `options` 参数还没有被所有浏览器支持。检查是否被支持，可以使用 `"i"` 参数（使用错误的语言代码会抛出异常）判断是否抛出 `RangeError` 异常：

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

### 使用 locales

在不同的语言下 `localeCompare()` 所提供的结果是不一致的。为了能让用户得到正确的比较值，通过使用 `locales` 参数来提供要比较的语言（可能还需要设置某些回退语言）：

```js
console.log("ä".localeCompare("z", "de")); // 负值：在德语中，ä 排在 z 之前
console.log("ä".localeCompare("z", "sv")); // 正值：在瑞典语中，ä 排在 z 之后
```

### 使用 options

`localeCompare()` 所提供的结果可以通过 `options` 参数自定义：

```js
// 在德语中，ä 以 a 为基础字母
console.log("ä".localeCompare("a", "de", { sensitivity: "base" })); // 0

// 在瑞典语中，ä 与 a 有着不同的基础字母
console.log("ä".localeCompare("a", "sv", { sensitivity: "base" })); // a positive value
```

### 数字排序

```js
// 默认情况下，"2" > "10"
console.log("2".localeCompare("10")); // 1

// 使用 options：
console.log("2".localeCompare("10", undefined, { numeric: true })); // -1

// 使用区域代码：
console.log("2".localeCompare("10", "en-u-kn-true")); // -1
```

规范
--

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

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

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

参见
--

* `Intl.Collator`


String.prototype.valueOf() - JavaScript

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

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

尝试一下
----

语法
--

```js
valueOf()
```

### 返回值

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

描述
--

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

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

示例
--

### 使用 `valueOf()`

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

规范
--

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

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

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

参见
--

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


String.prototype.toUpperCase() - JavaScript

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.replace() - JavaScript

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

**`replace()`** 方法返回一个新字符串，其中一个、多个或所有匹配的 `pattern` 被替换为 `replacement`。`pattern` 可以是字符串或 `RegExp`，`replacement` 可以是字符串或一个在每次匹配时调用的函数。如果 `pattern` 是字符串，则只会替换第一个匹配项。原始的字符串不会改变。

尝试一下
----

语法
--

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

### 参数

`pattern`

可以是字符串或者一个带有 `Symbol.replace` 方法的对象，典型的例子就是正则表达式。任何没有 `Symbol.replace` 方法的值都会被强制转换为字符串。

`replacement`

可以是字符串或函数。

* 如果是字符串，它将替换由 `pattern` 匹配的子字符串。支持一些特殊的替换模式，请参阅下面的指定字符串作为替换项部分。
* 如果是函数，将为每个匹配调用该函数，并将其返回值用作替换文本。下面的指定函数作为替换项部分描述了提供给此函数的参数。

### 返回值

一个新的字符串，其中一个、多个或所有的匹配项都被指定的替换项替换。

描述
--

该方法并不改变调用它的字符串本身，而是返回一个新的字符串。

字符串模式只会被替换一次。要执行全局搜索和替换，请使用带有 `g` 标志的正则表达式或使用 `replaceAll()`。

如果 `pattern` 是一个带有 `Symbol.replace` 方法的对象（包括 `RegExp` 对象），则该方法将被调用，传入目标字符串和 `replacement` 作为参数。它的返回值成为 `replace()` 的返回值。在这种情况下，`replace()` 的行为完全由 `@@replace` 方法定义——例如，下面的说明中提到的任何"捕获组"都实际上是由 `RegExp.prototype[@@replace]` 提供的功能。

如果 `pattern` 是一个空字符串，则替换项将被插入到字符串的开头。

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

`replace()` 替换多次的唯一情况是传入带有 `g` 标志的正则表达式。有关正则表达式属性（特别是 sticky 标志）如何与 `replace()` 交互的更多信息，请参阅 `RegExp.prototype[@@replace]()`。

### 指定字符串作为替换项

替换字符串可以包括以下特殊替换模式：

| 模式 | 插入值 |
| --- | --- |
| `$$` | 插入一个 `"$"`。 |
| `$&` | 插入匹配的子字符串。 |
| `$`` | 插入匹配子字符串之前的字符串片段。 |
| `$'` | 插入匹配子字符串之后的字符串片段。 |
| `$n` | 插入第 `n`（索引从 1 开始）个捕获组，其中 `n` 是小于 100 的正整数。 |
| `$` | 插入名称为 `Name` 的命名捕获组。 |

只有当 `pattern` 参数是一个 `RegExp` 对象时，`$n` 和 `$<Name>` 才可用。如果 `pattern` 是字符串，或者相应的捕获组在正则表达式中不存在，则该模式将被替换为一个字面量。如果该组存在但未匹配（因为它是一个分支的一部分），则将用空字符串替换它。

```js
"foo".replace(/(f)/, "$2");
// "$2oo"；正则表达式没有第二个组

"foo".replace("f", "$1");
// "$1oo"；pattern 是一个字符串，所以它没有任何组

"foo".replace(/(f)|(g)/, "$2");
// "oo"；第二个组存在但未匹配
```

### 指定函数作为替换项

你可以将第二个参数指定为函数。在这种情况下，匹配完成后将调用该函数。函数的结果（返回值）将用作替换字符串。

**备注：** 上述特殊替换模式*不*适用于替换器函数返回的字符串。

该函数具有以下签名：

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

该函数的参数如下所示：

`match`

匹配的子字符串。（对应于上面的 `$&`。）

`p1, p2, …, pN`

如果 `replace()` 的第一个参数是 `RegExp` 对象，则为捕获组（包括命名捕获组）找到的第 `n` 个字符串。（对应于上面的 `$1`、`$2` 等。）例如，如果 `pattern` 是 `/(\d+)(\w+)/`，则 `p1` 是 `\a+` 的匹配项，`p2` 是 `\b+` 的匹配项。如果该组是分支的一部分（例如 `"abc".replace(/(a)|(b)/, Replacer)`），则不匹配的替代项将为 `undefined`。

`offset`

原始字符串中匹配子字符串的偏移量。例如，如果整个字符串是 `'abcd'`，而匹配的子字符串是 `'bc'`，那么这个参数将是 `1`。

`string`

正在检查的原始字符串。

`groups`

一个捕获组命名组成的对象，值是匹配的部分（如果没有匹配，则为 `undefined`）。仅在 `pattern` 包含至少一个命名捕获组时才存在。

参数的确切数量取决于第一个参数是否为 `RegExp` 对象，以及它有多少个捕获组。

以下示例将设置 `newString` 为 `'abc - 12345 - #$*%'`：

```js
function replacer(match, p1, p2, p3, offset, string) {
  // p1 是非数字，p2 是数字，且 p3 非字母数字
  return [p1, p2, p3].join(" - ");
}
const newString = "abc12345#$\*%".replace(/([^\d]\*)(\d\*)([^\w]\*)/, replacer);
console.log(newString); // abc - 12345 - #$\*%
```

如果第一个参数中的正则表达式是全局的，那么为了替换每个完全匹配的字符串，该函数将被多次调用。

示例
--

### 在 replace() 中定义正则表达式

在以下示例中，正则表达式在 `replace()` 中定义，并包括忽略大小写标志。

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

这将打印 `'Twas the night before Christmas...'`。

**备注：** 有关正则表达式的更多解释，请参阅正则表达式指南。

### 在 replace() 中使用 global 和 ignoreCase 标志

只能使用正则表达式进行全局替换。在以下示例中，正则表达式包括 global 和 ignoreCase 标志，允许 `replace()` 将字符串中每个出现的 `'apples'` 替换为 `'oranges'`。

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

这将打印 `'oranges are round, and oranges are juicy'`。

### 交换字符串中的两个单词

以下脚本交换字符串中的单词。对于替换文本，脚本使用捕获组以及 `$1` 和 `$2` 替换模式。

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

这将打印 `'Cruz, Maria'`。

### 使用内联函数来修改匹配到的字符

在这个例子中，字符串中所有出现的大写字母都被转换为小写，并且在匹配位置前插入一个连字符。重要的是，在将匹配项作为替换返回之前，需要对匹配项进行额外的操作。

在返回前，替换函数接受匹配的片段作为参数，并使用它来转换大小写并拼接连字符。

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

运行 `styleHyphenFormat('borderTop')`，将返回 `'border-top'`。

由于我们希望在最终替换之前进一步转变匹配*结果*，所以我们必须使用一个函数。这会强制在使用 `toLowerCase()` 方法之前对匹配进行求值。如果我们尝试在没有函数的情况下使用匹配来完成这个操作，`toLowerCase()` 方法将没有效果。

```js
// 不会产生作用
const newString = propertyName.replace(/[A-Z]/g, "-" + "$&".toLowerCase());
```

这是因为 `'$&'.toLowerCase()` 会首先作为一个字符串字面量进行求值（结果仍然是 `'$&'`），然后再将其作为匹配模式使用。

### 将华氏温度转换为相应的摄氏温度

下面的例子演示如何将华氏温度转换为相应的摄氏温度。华氏温度用一个数字加一个 `"F"` 来表示，这个函数将返回一个数字加 `"C"` 来表示的摄氏温度。例如，如果输入是 `"212F"`，这个函数将返回 `"100C"`。如果输入的数字是 `"0F"`，这个方法将返回 `"-17.77777777777778C"`。

正则表达式 `test` 用于检查以 `F` 结尾的任何数字。华氏度的数值通过函数的第二个参数 `p1` 传入函数。该函数根据传递给 `f2c()` 函数的字符串中的华氏度数值设置摄氏度数值，然后 `f2c()` 函数返回摄氏度数值。该函数实现了类似 Perl 的 `s///e` 标志的功能。

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

### 创建一个通用的替换器

假设我们想创建一个替换器，将偏移数据附加到每个匹配的字符串中。因为替换函数已经接收到 `offset` 参数，如果正则表达式是静态已知的，那么这将变得很简单。

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

然而，如果我们希望这个替换器能够适用于任何正则表达式模式，那么它将很难泛化。替换器是*可变*参数的，它接收的参数数量取决于存在的捕获组数量。我们可以使用剩余参数参数，但它也会将 `offset`、`string` 等收集到数组中。根据正则表达式的特性，`groups` 可能会被传递或者不会被传递，这也使得很难泛化地知道哪个参数对应于 `offset`。

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

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

在上面的 `addOffset` 示例中，当正则表达式包含一个命名组时，它无法正常工作，因为在这种情况下 `args.at(-2)` 是 `string` 而不是 `offset`。

相反，你需要根据类型提取最后几个参数，因为 `groups` 是一个对象，而 `string` 是一个字符串。

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

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

规范
--

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

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

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

参见
--

* `core-js` 中 `String.prototype.replace` 的 Polyfill，修复了一些问题，并实现了现代行为，比如 `Symbol.replace` 的支持
* `String.prototype.replaceAll()`
* `String.prototype.match()`
* `RegExp.prototype.exec()`
* `RegExp.prototype.test()`
* `Symbol.replace`
* `RegExp.prototype[@@replace]()`