String.prototype.replace()

Метод replace() возвращает новую строку с одним, несколькими или всеми совпадениями шаблона, замененными заменой. Шаблон может быть строкой или RegExp, а замена может быть строкой или функцией, вызываемой для каждого совпадения. Если шаблон является строкой, заменяется только первое вхождение. Исходная строка остается без изменений.

Попробовать

Синтаксис

Параметры

Может быть строкой или объектом с методом Symbol.replace – типичным примером является регулярное выражение. Любое значение, не имеющее метода Symbol.replace, будет преобразовано в строку.

Может быть строкой или функцией.

• Если это строка, то она заменит подстроку, совпадающую с шаблоном . Поддерживается несколько специальных шаблонов замены; см. раздел “Указание строки в качестве замены” ниже.
• Если это функция, то она будет вызываться для каждого совпадения, а ее возвращаемое значение будет использоваться в качестве заменяющего текста. Аргументы, передаваемые этой функции, описаны в разделе “Указание функции в качестве замены” ниже.

Возвращаемое значение

Новая строка, в которой одно, несколько или все совпадения шаблона заменены указанной заменой.

Описание

Этот метод не изменяет строковое значение, вызванное им. Он возвращает новую строку.

Строковый шаблон будет заменен только один раз. Чтобы выполнить глобальный поиск и замену, используйте регулярное выражение с флагом g или используйте replaceAll() вместо этого.

Если шаблон является объектом с методом Symbol.replace (включая объекты RegExp), то этот метод вызывается с целевой строкой и заменой в качестве аргументов. Его возвращаемое значение становится возвращаемым значением replace(). В этом случае поведение replace() полностью кодируется методом @@replace – например, любое упоминание о “захвате групп” в приведенном ниже описании на самом деле является функциональностью, предоставляемой RegExp.prototype[@@replace] .

Если шаблон является пустой строкой, замена добавляется в начало строки.

Regexp с флагом g – единственный случай, когда replace() заменяет более одного раза. Для получения дополнительной информации о том, как свойства regex (особенно флаг sticky) взаимодействуют с replace(), смотрите RegExp.prototype[@@replace]().

Указание строки в качестве замены

Строка замены может включать следующие специальные шаблоны замены:

Шаблон	Вставляет
$$	Вставляет символ “$” .
$&	Вставляет найденную подстроку.
$`	Вставляет часть строки, которая предшествует найденной подстроке.
$’	Вставляет часть строки, которая следует за найденной подстрокой.
$n	Вставляет n-ю ( 1-индексированную) группу захвата, где n – целое положительное число меньше 100.
$	Вставляет именованную группу захвата, где Name – имя группы.

В качестве второго параметра можно указать функцию. В этом случае функция будет вызвана после выполнения совпадения. Результат функции (возвращаемое значение) будет использован в качестве строки замены.

Примечание: Вышеупомянутые специальные схемы замены не применяются к строкам, возвращаемым функцией replacer.

Функция имеет следующую сигнатуру:

Аргументы функции следующие:

Совпадающая подстрока. (Соответствует $& выше.)

n-я строка, найденная группой захвата (включая именованные группы захвата), если первый аргумент replace() является объектом RegExp. (Соответствует $1 , $2 и т.д. выше.) Например, если шаблон /(a+)(b+)/, то p1 является совпадением для a+, а p2 – для b+. Если группа является частью дизъюнкции (например, “abc”.replace(/(a)|(b)/, replacer) ), то несопоставленная альтернатива будет неопределенной.

Смещение совпавшей подстроки в пределах всей исследуемой строки. Например, если вся строка была ‘abcd’, а совпавшая подстрока была ‘bc’, то этот аргумент будет равен 1.

Вся исследуемая строка.

Объект, ключами которого являются имена используемых групп, а значениями – совпавшие части (не определены, если не совпали). Присутствует, только если шаблон содержит хотя бы одну именованную группу захвата.

Точное количество аргументов зависит от того, является ли первый аргумент объектом RegExp – и если да, то сколько групп захвата он имеет.

В следующем примере newString будет иметь значение ‘abc – 12345 – #$*%’ :

Функция будет вызвана несколько раз для каждого полного совпадения для замены, если регулярное выражение в первом параметре является глобальным.

Примеры

Определение регулярного выражения в replace()

В следующем примере регулярное выражение определено в replace() и включает флаг игнорирования регистра.

Это регистрирует ‘Twas the night before Christmas. ‘ .

Примечание: Дополнительные пояснения по регулярным выражениям см. в руководстве по регулярным выражениям.

Использование флагов global и ignoreCase в replace()

Глобальная замена может быть выполнена только с помощью регулярного выражения. В следующем примере регулярное выражение включает флаги global и ignoreCase, что позволяет replace() заменить каждое вхождение ‘apples’ в строке на ‘oranges’.

Таким образом, в лог-файле будет написано ‘oranges are round, and oranges are juicy’.

Переключение слов в строке

Следующий скрипт меняет местами слова в строке. Для замены текста скрипт использует группы захвата и шаблоны замены $1 и $2.

Записывается ‘Cruz, Maria’ .

Использование встроенной функции, изменяющей совпадающие символы

В этом примере все заглавные буквы в строке преобразуются в строчные, а дефис вставляется непосредственно перед местом совпадения. Важно то, что для замены совпавшего элемента необходимо выполнить дополнительные операции.

Функция замены принимает совпавший фрагмент в качестве параметра и использует его для преобразования регистра и конкатенации дефиса перед возвратом.

Данный styleHyphenFor

Это происходит потому, что ‘$&’.toLowerCase() сначала оценивается как строковый литерал (в результате получается тот же ‘$&’), прежде чем использовать символы в качестве шаблона.

Замена градуса по Фаренгейту на его эквивалент по Цельсию

Следующий пример заменяет градус Фаренгейта на эквивалентный ему градус Цельсия. Градус Фаренгейта должен быть числом, заканчивающимся на “F”. Функция возвращает число градусов Цельсия, заканчивающееся на “C”. Например, если введенное число “212F”, функция возвращает “100C”. Если число “0F”, функция возвращает “-17.77777777777778C”.

Тест регулярного выражения проверяет любое число, которое заканчивается на F. Число градусов Фаренгейта доступно функции через ее второй параметр, p1 . Функция устанавливает число Цельсия на основе числа градусов Фаренгейта, переданного в строке функции f2c(). f2c() затем возвращает число Цельсия. Эта функция аппроксимирует флаг s///e языка Perl.

Создание универсального заменителя

Предположим, мы хотим создать заменитель, который добавляет данные о смещении к каждой совпавшей строке. Поскольку функция replacer уже получает параметр смещения, это будет тривиально, если регекс известен статически.

Однако этот заменитель будет трудно обобщить, если мы хотим, чтобы он работал с любым шаблоном regex. Заменитель является переменным – количество аргументов, которые он получает, зависит от количества присутствующих групп захвата. Мы можем использовать остальные параметры, но он также будет собирать в массив offset, string и т.д. Тот факт, что группы могут передаваться или не передаваться в зависимости от идентичности regex, также затруднит общее определение того, какой аргумент соответствует смещению.

Приведенный выше пример addOffset не работает, когда regex содержит именованную группу, потому что в этом случае args.at(-2) будет строкой, а не смещением.

Вместо этого нужно извлечь последние несколько аргументов на основе типа, потому что groups – это объект, а string – строка.