RegExp.prototype[Symbol.search]()

¥Syntax

regexp[Symbol.search](str)

¥Parameters

str

作为搜索目标的 String。

¥Return value

正则表达式和给定字符串之间的第一个匹配项的索引，如果未找到匹配项，则为 -1。

¥The index of the first match between the regular expression and the given string, or -1 if no match was found.

¥Description

该方法在 String.prototype.search() 内部被调用。例如，以下两个示例返回相同的结果。

¥This method is called internally in String.prototype.search(). For example, the following two examples return the same result.

"abc".search(/a/);

/a/[Symbol.search]("abc");

与 [Symbol.split]() 或 [Symbol.matchAll]() 不同，此方法不复制正则表达式。不过，与 [Symbol.match]() 或 [Symbol.replace]() 不同，它会在执行开始时将 lastIndex 设置为 0，并在退出时将其恢复为之前的值，因此通常可以避免副作用。这意味着 g 标志对此方法不起作用，并且即使 lastIndex 非零，它也始终返回字符串中的第一个匹配项。这也意味着粘性正则表达式将始终严格在字符串的开头进行搜索。

¥This method does not copy the regular expression, unlike [Symbol.split]() or [Symbol.matchAll](). However, unlike [Symbol.match]() or [Symbol.replace](), it will set lastIndex to 0 when execution starts and restore it to the previous value when it exits, therefore generally avoiding side effects. This means that the g flag has no effect with this method, and it always returns the first match in the string even when lastIndex is non-zero. This also means sticky regexps will always search strictly at the beginning of the string.

const re = /[abc]/g;
re.lastIndex = 2;
console.log("abc".search(re)); // 0

const re2 = /[bc]/y;
re2.lastIndex = 1;
console.log("abc".search(re2)); // -1
console.log("abc".match(re2)); // [ 'b' ]

[Symbol.search]() 始终只调用正则表达式的 exec() 方法一次，并返回结果的 index 属性，如果结果是 null，则返回 -1。

¥[Symbol.search]() always calls the regex's exec() method exactly once, and returns the index property of the result, or -1 if the result is null.

该方法用于自定义 RegExp 子类中的搜索行为。

¥This method exists for customizing the search behavior in RegExp subclasses.

¥Examples

¥Direct call

除了 this 的值不同以及参数顺序不同之外，该方法的使用方式与 String.prototype.search() 几乎相同。

¥This method can be used in almost the same way as String.prototype.search(), except for the different value of this and the different arguments order.

const re = /-/g;
const str = "2016-01-02";
const result = re[Symbol.search](str);
console.log(result); // 4

¥Using [Symbol.search]() in subclasses

RegExp 的子类可以重写 [Symbol.search]() 方法来修改行为。

¥Subclasses of RegExp can override [Symbol.search]() method to modify the behavior.

class MyRegExp extends RegExp {
  constructor(str) {
    super(str);
    this.pattern = str;
  }
  [Symbol.search](str) {
    return str.indexOf(this.pattern);
  }
}

const re = new MyRegExp("a+b");
const str = "ab a+b";
const result = str.search(re); // String.prototype.search calls re[Symbol.search]().
console.log(result); // 3

¥See also

• core-js 中 RegExp.prototype[Symbol.search] 的 Polyfill
• String.prototype.search()
• RegExp.prototype[Symbol.match]()
• RegExp.prototype[Symbol.matchAll]()
• RegExp.prototype[Symbol.replace]()
• RegExp.prototype[Symbol.split]()
• RegExp.prototype.exec()
• RegExp.prototype.test()
• Symbol.search