Метод replace()

Описание

Метод replace() ищет строку для указанного значения или регулярного выражения и возвращает новую строку, где указанные значения будут заменены.

Синтаксис

str.replace(regexp|substr, newSubStr|function[, flags])

regexp

Объект регулярного выражения RegExp. Сопоставление заменяется возвращаемым значением второго параметра.

substr

Строка, которая должна быть заменена на newSubStr. Обратите внимание, будет заменено только первое вхождение искомой строки.

newSubStr

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

function

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

flags

Строка, содержащая любую комбинацию флагов RegExp: g – глобальное соответствие, i – игнорировать регистр, m – соответствие по нескольким строкам. Этот параметр используется, только если первый параметр является строкой.

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

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

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

Примеры

Если первым аргументом является строка, заменяется только первое вхождение подстроки в строку:

В этом примере строка "at" передается в качестве первого аргумента в метод replace() для замены значением "ond". В результате в первом совпадении слово "cat" изменяется на "cond", но вся остальная часть строки остается неизменной.

Чтобы заменить все совпадения, нужно использовать для поиска не строку "at", а регулярное выражение /at/g, причём обязательно с флагом g:

Строка в качестве второго параметра

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

Пример использования скобок и $1, $2:

Пример, с использованием подстроки, совпадающей со всем шаблоном $&:

Функция в качестве второго параметра

Если вы указываете функцию в качестве второго параметра, то она вызывается при каждом совпадении. При наличии одного со­впадения в нее передаются три аргумента: совпадение, позиция совпадения в строке и вся строка. Если групп захвата несколько, каждая совпавшая строка передается в функцию как аргумент, при этом двумя последними аргументами являются по­зиция совпадения с шаблоном в строке и оригинальная строка. Результат вызова функции (её возвращаемое значение) будет использоваться в качестве строки замены.

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

1. match – найденное совпадение, (cоответствует шаблону замены $&, описанному выше).
2. p1, p2, ..., pn – содержимое скобок (если есть), из объекта RegExp в первом параметре метода replace() (cоответствует шаблонам замены $1, $2 и так далее, описанным выше). Например, если в качестве шаблона передано регулярное выражение /(\a+)(\b+)/, параметр p1 будет значение сопоставления с подгруппой \a+, а параметр p2 — с подгруппой \b+.
3. offset – позиция, на которой найдено совпадение (например, если вся строка равна 'abcd', а сопоставившаяся подстрока равна 'bc', то этот аргумент будет равен 1).
4. string – исходная строка.

Если скобок в регулярном выражении нет, то у функции всегда будет ровно 3 аргумента: replacer(match, offset, string).

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

При наличии в регулярном выражении двух скобок функция принимает уже 5 аргументов: