Класс Matcher

Все реализованные интерфейсы:
MatchResult
public final class Matcher
extends Object
implements MatchResult

Двигатель, выполняющий операции сопоставления с последовательностью символов с помощью интерпретации Pattern.

Matcher создается из шаблона с помощью вызова метода matcher шаблона. После создания matcher можно использовать для выполнения трёх типов операций сопоставления:

  • Метод matches пытается сопоставить всю входную последовательность с шаблоном.

  • Метод lookingAt пытается сопоставить входную последовательность, начиная с начала, с шаблоном.

  • Метод find сканирует входную последовательность в поисках следующей подпоследовательности, которая соответствует шаблону.

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

Matcher находит совпадения в подмножестве своего входного значения, называемого областью. По умолчанию область содержит все входные данные matcher. Область может быть изменена с помощью метода region и запрошена с помощью методов regionStart и regionEnd. Способ взаимодействия границ области с некоторыми конструкциями шаблона может быть изменён. Более подробную информацию см. в useAnchoringBounds и useTransparentBounds.

Этот класс также определяет методы для замены соответствующих подпоследовательностей новыми строками, содержимое которых, при необходимости, можно вычислить из результата сопоставления. Методы appendReplacement и appendTail могут быть использованы вместе для сбора результата в существующий буфер строк или билдер строк. В качестве альтернативы, можно использовать более удобный метод replaceAll для создания строки, в которой каждая соответствующая подпоследовательность во входной последовательности заменяется.

Явное состояние matcher включает начальные и конечные индексы последнего успешного совпадения. Он также включает начальные и конечные индексы входной подпоследовательности, захваченной каждой группой захвата в шаблоне, а также общее количество таких подпоследовательностей. Для удобства также предоставлены методы для возвращения этих захваченных подпоследовательностей в виде строк.

Явное состояние matcher поначалу не определено; попытка запросить любую его часть до успешного сопоставления вызовет исключение IllegalStateException. Явное состояние matcher пересчитывается каждой операцией сопоставления.

Неявное состояние matcher включает входную последовательность символов, а также позицию добавления, которая поначалу равна нулю и обновляется методом appendReplacement.

Matcher можно явно сбросить, вызвав его метод reset() или, если требуется новая входная последовательность, его метод reset(CharSequence). Сброс matcher отбрасывает информацию о его явном состоянии и устанавливает позицию добавления в ноль.

Экземпляры этого класса не являются безопасными для использования несколькими параллельными потоками.

С момента:
1.4

Методы

Модификатор и тип Метод Описание
Matcher appendReplacement​(StringBuffer sb, String replacement)

Реализует нетерминальную стадию добавления и замены.
Matcher appendReplacement​(StringBuilder sb, String replacement)

Реализует нетерминальную стадию добавления и замены.
StringBuffer appendTail​(StringBuffer sb)

Реализует терминальную стадию добавления и замены.
StringBuilder appendTail​(StringBuilder sb)

Реализует терминальную стадию добавления и замены.
int end()

Возвращает смещение после последнего совпавшего символа.
int end​(int group)

Возвращает смещение после последнего символа подпоследовательности, захваченной заданной группой во время предыдущей операции сопоставления.
int end​(String name)

Возвращает смещение после последнего символа подпоследовательности, захваченной заданной именованной группой захвата во время предыдущей операции сопоставления.
boolean find()

Попытка найти следующую подпоследовательность входной последовательности, которая соответствует шаблону.
boolean find​(int start)

Сбрасывает этот сопоставитель и затем пытается найти следующую подпоследовательность входной последовательности, которая соответствует шаблону, начиная с указанного индекса.
String group()

Возвращает подпоследовательность входных данных, соответствующую предыдущему сопоставлению.
String group​(int group)

Возвращает подпоследовательность входных данных, захваченную заданной группой во время предыдущей операции сопоставления.
String group​(String name)

Возвращает подпоследовательность входных данных, захваченную заданной именованной группой захвата во время предыдущей операции сопоставления.
int groupCount()

Возвращает количество групп захвата в шаблоне этого сопоставителя.
boolean hasAnchoringBounds()

Запрашивает привязку границ области для этого сопоставителя.
boolean hasTransparentBounds()

Запрашивает прозрачность границ области для этого сопоставителя.
boolean hitEnd()

Возвращает true, если в последней операции сопоставления, выполненной этим сопоставителем, поисковый движок достиг конца входных данных.
boolean lookingAt()

Пытается сопоставить входную последовательность, начиная с начала области, с шаблоном.
boolean matches()

Пытается сопоставить всю область с шаблоном.
Pattern pattern()

Возвращает шаблон, интерпретируемый этим сопоставителем.
static String quoteReplacement​(String s)

Возвращает литеральное значение замены String для указанного String.

Matcher region​(int start, int end)

Устанавливает границы области этого сопоставителя.
int regionEnd()

Сообщает конечный индекс (исключительно) области этого сопоставителя.
int regionStart()

Сообщает начальный индекс области этого сопоставителя.
String replaceAll​(String replacement)

Заменяет каждую подпоследовательность входной последовательности, которая соответствует шаблону, заданной строкой замены.
String replaceAll​(Function<MatchResult,​String> replacer)

Заменяет каждую подпоследовательность входной последовательности, которая соответствует шаблону, результатом применения данной функции замены к результату сопоставления этого сопоставителя, соответствующему этой подпоследовательности.
String replaceFirst​(String replacement)

Заменяет первую подпоследовательность входной последовательности, которая соответствует шаблону, заданной строкой замены.
String replaceFirst​(Function<MatchResult,​String> replacer)

Заменяет первую подпоследовательность входной последовательности, которая соответствует шаблону, результатом применения данной функции замены к результату сопоставления этого сопоставителя, соответствующему этой подпоследовательности.
boolean requireEnd()

Возвращает true, если дополнительные входные данные могут изменить положительное сопоставление на отрицательное.
Matcher reset()

Сбрасывает этот сопоставитель.
Matcher reset​(CharSequence input)

Сбрасывает этот сопоставитель с новой входной последовательностью.
Stream<MatchResult> results()

Возвращает поток результатов сопоставления для каждой подпоследовательности входной последовательности, которая соответствует шаблону.
int start()

Возвращает начальный индекс предыдущего сопоставления.
int start​(int group)

Возвращает начальный индекс подпоследовательности, захваченной данной группой во время предыдущей операции сопоставления.
int start​(String name)

Возвращает начальный индекс подпоследовательности, захваченной заданной именованной группой захвата во время предыдущей операции сопоставления.
MatchResult toMatchResult()

Возвращает состояние сопоставления этого сопоставителя как MatchResult.
String toString()

Возвращает строковое представление этого сопоставителя.
Matcher useAnchoringBounds​(boolean b)

Устанавливает привязку границ области для этого сопоставителя.
Matcher usePattern​(Pattern newPattern)

Изменяет Pattern, которое этот Matcher использует для поиска совпадений.
Matcher useTransparentBounds​(boolean b)

Устанавливает прозрачность границ области для этого сопоставителя.

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Методы

pattern

public Pattern pattern()

Возвращает шаблон, интерпретируемый этим совпадением.

Возвращает:
Шаблон, для которого был создан этот объект совпадения

toMatchResult

public MatchResult toMatchResult()

Возвращает состояние совпадения этого объекта совпадения в виде MatchResult. Результат не зависит от последующих операций, выполняемых над этим объектом совпадения.

Возвращает:
объект MatchResult со статусом этого объекта совпадения
С момента:
1.5

usePattern

public Matcher usePattern(Pattern newPattern)

Изменяет Pattern , который этот Matcher использует для поиска совпадений.

Этот метод приводит к тому, что этот объект совпадения теряет информацию о группах последнего совпадения. Позиция объекта совпадения во входной строке сохраняется, а последняя позиция добавления не изменяется.

Параметры:
newPattern - Новый шаблон, используемый этим объектом совпадения
Возвращает:
Этот объект совпадения
Исключение:
IllegalArgumentException - Если newPattern является null
С момента:
1.5

reset

public Matcher reset()

Сбрасывает этот объект совпадения.

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

Возвращает:
Этот объект совпадения

reset

public Matcher reset(CharSequence input)

Сбрасывает этот объект совпадения с новой последовательностью ввода.

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

Параметры:
input - Новая последовательность входных символов
Возвращает:
Этот объект совпадения

start

public int start()

Возвращает начальный индекс предыдущего совпадения.

Указано в:
start в интерфейсе MatchResult
Возвращает:
Индекс первого сопоставленного символа
Исключение:
IllegalStateException - Если совпадение еще не было предпринято или предыдущая операция совпадения не удалась

start

public int start(int group)

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

Группы захвата индексируются слева направо, начиная с единицы. Ноль обозначает весь шаблон, поэтому выражение m.start(0) эквивалентно m.start().

Указано в:
start в интерфейсе MatchResult
Параметры:
group - Индекс группы захвата в шаблоне этого объекта совпадения
Возвращает:
Индекс первого символа, захваченного группой, или -1 , если совпадение прошло успешно, но сама группа ничего не сопоставила
Исключение:
IllegalStateException - Если совпадение еще не было предпринято или предыдущая операция совпадения не удалась
IndexOutOfBoundsException - Если в шаблоне нет группы захвата с заданным индексом

start

public int start(String name)

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

Параметры:
name - Имя именованной группы захвата в шаблоне этого объекта совпадения
Возвращает:
Индекс первого символа, захваченного группой, или -1 , если совпадение прошло успешно, но сама группа ничего не сопоставила
Исключение:
IllegalStateException - Если совпадение еще не было предпринято или предыдущая операция совпадения не удалась
IllegalArgumentException - Если в шаблоне нет группы захвата с заданным именем
С момента:
1.8

end

public int end()

Возвращает смещение после последнего сопоставленного символа.

Указано в:
end в интерфейсе MatchResult
Возвращает:
Смещение после последнего сопоставленного символа
Исключение:
IllegalStateException - Если совпадение еще не было предпринято или предыдущая операция совпадения не удалась

end

public int end(int group)

Возвращает смещение после последнего символа подпоследовательности, захваченной заданной группой во время предыдущей операции совпадения.

Группы захвата индексируются слева направо, начиная с единицы. Ноль обозначает весь шаблон, поэтому выражение m.end(0) эквивалентно m.end().

Указано в:
end в интерфейсе MatchResult
Параметры:
group - Индекс группы захвата в шаблоне этого объекта совпадения
Возвращает:
Смещение после последнего символа, захваченного группой, или -1 , если совпадение прошло успешно, но сама группа ничего не сопоставила
Исключение:
IllegalStateException - Если совпадение еще не было предпринято или предыдущая операция совпадения не удалась
IndexOutOfBoundsException - Если в шаблоне нет группы захвата с заданным индексом

end

public int end(String name)

Возвращает смещение после последнего символа подпоследовательности, захваченной заданной именованной группой захвата во время предыдущей операции совпадения.

Параметры:
name - Имя именованной группы захвата в шаблоне этого объекта совпадения
Возвращает:
Смещение после последнего символа, захваченного группой, или -1 , если совпадение прошло успешно, но сама группа ничего не сопоставила
Исключение:
IllegalStateException - Если совпадение еще не было предпринято или предыдущая операция совпадения не удалась
IllegalArgumentException - Если в шаблоне нет группы захвата с заданным именем
С момента:
1.8

group

public String group()

Возвращает подпоследовательность входных данных, сопоставленную с предыдущим совпадением.

Для объекта совпадения m с последовательностью ввода s выражения m.group() и s.substring(m.start(), m. end()) эквивалентны.

Обратите внимание, что некоторые шаблоны, например a*, соответствуют пустой строке. Этот метод вернет пустую строку, когда шаблон успешно сопоставится с пустой строкой во входных данных.

Указано в:
group в интерфейсе MatchResult
Возвращает:
Подпоследовательность (возможно, пустая), сопоставленная с предыдущим совпадением, в виде строки
Исключение:
IllegalStateException - Если совпадение еще не было предпринято или предыдущая операция совпадения не удалась

group

public String group(int group)

Возвращает подпоследовательность входных данных, захваченную заданной группой во время предыдущей операции совпадения.

Для объекта совпадения m, последовательности ввода s и индекса группы g выражения m.group(g) и s.substring(m.start(g ), m.end(g)) эквивалентны.

Группы захвата индексируются слева направо, начиная с единицы. Ноль обозначает весь шаблон, поэтому выражение m.group(0) эквивалентно m.group().

Если совпадение прошло успешно, но указанная группа не смогла сопоставить никакой части входной последовательности, то возвращается null. Обратите внимание, что некоторые группы, например (a*), соответствуют пустой строке. Этот метод вернет пустую строку, когда такая группа успешно сопоставится с пустой строкой во входных данных.

Указано в:
group в интерфейсе MatchResult
Параметры:
group - Индекс группы захвата в шаблоне этого объекта совпадения
Возвращает:
Подпоследовательность (возможно, пустая), захваченная группой во время предыдущего совпадения, или null , если группа не смогла сопоставить часть входных данных
Исключение:
IllegalStateException - Если совпадение еще не было предпринято или предыдущая операция совпадения не удалась
IndexOutOfBoundsException - Если в шаблоне нет группы захвата с заданным индексом

group

public String group(String name)

Возвращает подпоследовательность входных данных, захваченную заданной именованной группой захвата во время предыдущей операции совпадения.

Если совпадение прошло успешно, но указанная группа не смогла сопоставить никакой части входной последовательности, то возвращается null. Обратите внимание, что некоторые группы, например (a*), соответствуют пустой строке. Этот метод вернет пустую строку, когда такая группа успешно сопоставится с пустой строкой во входных данных.

Параметры:
name - Имя именованной группы захвата в шаблоне этого объекта совпадения
Возвращает:
Подпоследовательность (возможно, пустая), захваченная именованной группой во время предыдущего совпадения, или null , если группа не смогла сопоставить часть входных данных
Исключение:
IllegalStateException - Если совпадение еще не было предпринято или предыдущая операция совпадения не удалась
IllegalArgumentException - Если в шаблоне нет группы захвата с заданным именем
С момента:
1.7

groupCount

public int groupCount()

Возвращает количество групп захвата в шаблоне этого объекта совпадения.

Группа ноль обозначает весь шаблон по соглашению. Она не включена в этот подсчёт.

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

Указано в:
groupCount в интерфейсе MatchResult
Возвращает:
Количество групп захвата в шаблоне этого объекта совпадения

matches

public boolean matches()

Попытка сопоставить всю область с шаблоном.

Если совпадение успешно, то дополнительную информацию можно получить с помощью методов start, end, и group.

Возвращает:
true только в том случае, если весь последовательность регионов соответствует шаблону этого матчера

find

public boolean find()

Попытка найти следующую подпоследовательность входной последовательности, которая соответствует шаблону.

Этот метод начинается с начала области этого матчера, или, если предыдущее вызов метода был успешным, и матчер с тех пор не был сброшен, с первого символа, не совпадающего с предыдущим совпадением.

Если совпадение успешно, то дополнительную информацию можно получить с помощью методов start, end, и group.

Возвращает:
true если, и только если, подпоследовательность входной последовательности соответствует шаблону этого матчера

find

public boolean find(int start)

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

Если совпадение успешно, дополнительную информацию можно получить с помощью методов start, end, и group, а последующие вызовы метода find() будут начинаться с первого символа, не совпадающего с этим совпадением.

Параметры:
start - индекс для начала поиска совпадения
Возвращает:
true если, и только если, подпоследовательность входной последовательности, начиная с данного индекса, соответствует шаблону этого матчера
Выбрасывает:
IndexOutOfBoundsException - Если start меньше нуля или если start больше длины входной последовательности.

lookingAt

public boolean lookingAt()

Пытается сопоставить входную последовательность, начиная с начала области, с шаблоном.

Как и метод matches, этот метод всегда начинается с начала области; в отличие от этого метода, он не требует, чтобы вся область была сопоставлена.

Если совпадение успешно, то дополнительную информацию можно получить с помощью методов start, end, и group.

Возвращает:
true если, и только если, префикс входной последовательности соответствует шаблону этого матчера

quoteReplacement

public static String quoteReplacement(String s)

Возвращает буквальный заменитель String для указанного String. Этот метод создает String, который будет работать как буквальный заменитель s в методе appendReplacement класса Matcher. Созданный String будет соответствовать последовательности символов в s , рассматриваемой как буквальная последовательность. Слэши ('\') и знаки доллара ('$') не будут иметь особого значения.

Параметры:
s - Строка, которая должна быть буквализирована
Возвращает:
Буквальный строковый заменитель
С:
1.5

appendReplacement

public Matcher appendReplacement(StringBuffer sb,
                                 String replacement)

Реализует нетерминальную операцию добавления и замены.

Этот метод выполняет следующие действия:

  1. Он считывает символы из входной последовательности, начиная с позиции добавления, и добавляет их в заданный буфер строк. Он останавливается после чтения последнего символа, предшествующего предыдущему совпадению, то есть символа с индексом start() - 1.

  2. Он добавляет заданную строку замены в буфер строк.

  3. Он устанавливает позицию добавления этого матчера на индекс последнего сопоставленного символа плюс один, то есть на end().

Строка замены может содержать ссылки на подпоследовательности, захваченные во время предыдущего совпадения: каждое вхождение ${имя} или $g будет заменено результатом вычисления соответствующего group(name) или group(g) соответственно. Для $g, первая цифра после $ всегда рассматривается как часть ссылки на группу. Последующие цифры включаются в g, если они сформируют допустимую ссылку на группу. Только цифры от '0' до '9' рассматриваются как потенциальные компоненты ссылки на группу. Если вторая группа совпала со строкой "foo", например, то передача строки замены "$2bar" приведет к добавлению "foobar" в буфер строк. Знак доллара ($) может быть включен как буквальный в строке замены, предваряя его обратной косой чертой (\$).

Обратите внимание, что обратные косые черты (\) и знаки доллара ($) в строке замены могут привести к результатам, отличным от тех, которые были бы получены, если бы она обрабатывалась как строка буквальной замены. Знаки доллара могут обрабатываться как ссылки на захваченные подпоследовательности, как описано выше, а обратные косые черты используются для экранирования буквальных символов в строке замены.

Этот метод предназначен для использования в цикле вместе с методами appendTail и find. Например, следующий код выводит one dog two dogs in the yard в поток стандартного вывода: 

Pattern p = Pattern.compile("cat");
Matcher m = p.matcher("one cat two cats in the yard");
StringBuffer sb = new StringBuffer();
while (m.find()) {
    m.appendReplacement(sb, "dog");
}
m.appendTail(sb);
System.out.println(sb.toString());
Параметры:
sb - целевой буфер строк
replacement - строка замены
Возвращает:
Этот матчер
Выбрасывает:
IllegalStateException - Если совпадение еще не было предпринято или если предыдущая операция совпадения завершилась неудачей
IllegalArgumentException - Если строка замены ссылается на именованную группу захвата, которая не существует в шаблоне
IndexOutOfBoundsException - Если строка замены ссылается на группу захвата, которая не существует в шаблоне

appendReplacement

public Matcher appendReplacement(StringBuilder sb,
                                 String replacement)

Реализует нетерминальную операцию добавления и замены.

Этот метод выполняет следующие действия:

  1. Он считывает символы из входной последовательности, начиная с позиции добавления, и добавляет их в заданный буфер строк. Он останавливается после чтения последнего символа, предшествующего предыдущему совпадению, то есть символа с индексом start() - 1.

  2. Он добавляет заданную строку замены в буфер строк.

  3. Он устанавливает позицию добавления этого матчера на индекс последнего сопоставленного символа плюс один, то есть на end().

Строка замены может содержать ссылки на подпоследовательности, захваченные во время предыдущего совпадения: каждое вхождение $g будет заменено результатом вычисления group(g). Первая цифра после $ всегда рассматривается как часть ссылки на группу. Последующие цифры включаются в g, если они сформируют допустимую ссылку на группу. Только цифры от '0' до '9' рассматриваются как потенциальные компоненты ссылки на группу. Если вторая группа совпала со строкой "foo", например, то передача строки замены "$2bar" приведет к добавлению "foobar" в буфер строк. Знак доллара ($) может быть включен как буквальный в строке замены, предваряя его обратной косой чертой (\$).

Обратите внимание, что обратные косые черты (\) и знаки доллара ($) в строке замены могут привести к результатам, отличным от тех, которые были бы получены, если бы она обрабатывалась как строка буквальной замены. Знаки доллара могут обрабатываться как ссылки на захваченные подпоследовательности, как описано выше, а обратные косые черты используются для экранирования буквальных символов в строке замены.

Этот метод предназначен для использования в цикле вместе с методами appendTail и find. Например, следующий код выводит one dog two dogs in the yard в поток стандартного вывода: 

Pattern p = Pattern.compile("cat");
Matcher m = p.matcher("one cat two cats in the yard");
StringBuilder sb = new StringBuilder();
while (m.find()) {
    m.appendReplacement(sb, "dog");
}
m.appendTail(sb);
System.out.println(sb.toString());
Параметры:
sb - целевой буфер строк
replacement - строка замены
Возвращает:
Этот матчер
Выбрасывает:
IllegalStateException - Если совпадение еще не было предпринято или если предыдущая операция совпадения завершилась неудачей
IllegalArgumentException - Если строка замены ссылается на именованную группу захвата, которая не существует в шаблоне
IndexOutOfBoundsException - Если строка замены ссылается на группу захвата, которая не существует в шаблоне
С:
9

appendTail

public StringBuffer appendTail(StringBuffer sb)

Реализует терминальную операцию добавления и замены.

Этот метод считывает символы из входной последовательности, начиная с позиции добавления, и добавляет их в заданный буфер строк. Он предназначен для вызова после одного или нескольких вызовов метода appendReplacement для копирования остатка входной последовательности.

Параметры:
sb - целевой буфер строк
Возвращает:
Целевой буфер строк

appendTail

public StringBuilder appendTail(StringBuilder sb)

Реализует терминальную операцию добавления и замены.

Этот метод считывает символы из входной последовательности, начиная с позиции добавления, и добавляет их в заданный буфер строк. Он предназначен для вызова после одного или нескольких вызовов метода appendReplacement для копирования остатка входной последовательности.

Параметры:
sb - целевой буфер строк
Возвращает:
Целевой буфер строк
С:
9

replaceAll

public String replaceAll(String replacement)

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

Этот метод сначала сбрасывает этот матчер. Затем он сканирует входную последовательность, ища соответствия шаблону. Символы, которые не являются частью совпадения, непосредственно добавляются к строке результата; каждое совпадение заменяется в результате строкой замены. Строка замены может содержать ссылки на захваченные подпоследовательности, как в методе appendReplacement.

Обратите внимание, что обратные слэши (\) и знаки доллара ($) в строке замены могут привести к результатам, отличным от тех, если бы она обрабатывалась как строка замены буквально. Знаки доллара могут обрабатываться как ссылки на захваченные подпоследовательности, как описано выше, а обратные слэши используются для экранирования символов в строке замены.

При использовании регулярного выражения a*b, входной последовательности "aabfooaabfooabfoob", и строке замены "-", вызов этого метода для матчера этого выражения вернул бы строку "-foo-foo-foo-".

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

Parameters:
replacement - Строка замены
Returns:
Строка, построенная путем замены каждой соответствующей подпоследовательности строкой замены, заменяя при необходимости захваченные подпоследовательности.

replaceAll

public String replaceAll(Function<MatchResult,​String> replacer)

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

Этот метод сначала сбрасывает этот матчер. Затем он сканирует входную последовательность, ища совпадения шаблону. Символы, не являющиеся частью совпадения, добавляются непосредственно в строку результата; каждое совпадение заменяется в результате применением функции замены, которая возвращает строку замены. Каждая строка замены может содержать ссылки на захваченные подпоследовательности, как в методе appendReplacement.

Обратите внимание, что обратные слэши (\) и знаки доллара ($) в строке замены могут привести к результатам, отличным от тех, если бы она обрабатывалась как строка замены буквально. Знаки доллара могут обрабатываться как ссылки на захваченные подпоследовательности, как описано выше, а обратные слэши используются для экранирования символов в строке замены.

При использовании регулярного выражения dog, входной последовательности mr -> mr.group().toUpperCase(), и функции "zzzdogzzzdogzzz", вызов этого метода для матчера этого выражения вернул бы строку "zzzDOGzzzDOGzzz".

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

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

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

Implementation Note:
Эта реализация применяет функцию замены к этому матчеру, который является экземпляром MatchResult.
Parameters:
replacer - Функция, которая применяется к результату совпадения этого матчера, которая возвращает строку замены.
Returns:
Строка, построенная путем замены каждой соответствующей подпоследовательности результатом применения функции замены к этой подпоследовательности, заменяя при необходимости захваченные подпоследовательности.
Throws:
NullPointerException - если функция замены равна null
ConcurrentModificationException - если с наилучшими усилиями обнаружено, что функция замены изменила состояние этого матчера
Since:
9

results

public Stream<MatchResult> results()

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

Каждый результат совпадения создается так, как если бы он был получен из toMatchResult().

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

Если матчер должен быть использован для дальнейших операций сопоставления после завершения терминальной операции потока, то он должен быть сброшен.

Состояние этого матчера не должно изменяться во время выполнения потока возвращаемого потока. Источник возвращаемого потока Spliterator является *немедленно-быстрым* и будет, с наилучшими усилиями, выбрасывать ConcurrentModificationException, если такое изменение будет обнаружено.

Returns:
последовательный поток результатов совпадений.
Since:
9

replaceFirst

public String replaceFirst(String replacement)

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

Этот метод сначала сбрасывает этот матчер. Затем он сканирует входную последовательность, ища совпадение шаблону. Символы, не являющиеся частью совпадения, добавляются непосредственно в строку результата; совпадение заменяется в результате строкой замены. Строка замены может содержать ссылки на захваченные подпоследовательности, как в методе appendReplacement.

Обратите внимание, что обратные слэши (\) и знаки доллара ($) в строке замены могут привести к результатам, отличным от тех, если бы она обрабатывалась как строка замены буквально. Знаки доллара могут обрабатываться как ссылки на захваченные подпоследовательности, как описано выше, а обратные слэши используются для экранирования символов в строке замены.

При использовании регулярного выражения dog, входной последовательности "zzzdogzzzdogzzz", и строке замены "cat", вызов этого метода для матчера этого выражения вернул бы строку "zzzcatzzzdogzzz".

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

Parameters:
replacement - Строка замены
Returns:
Строка, построенная путем замены первого соответствующего подпоследовательности строкой замены, заменяя при необходимости захваченные подпоследовательности.

replaceFirst

public String replaceFirst(Function<MatchResult,​String> replacer)

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

Этот метод сначала сбрасывает этот матчер. Затем он сканирует входную последовательность, ища совпадение шаблону. Символы, не являющиеся частью совпадения, добавляются непосредственно в строку результата; совпадение заменяется в результате применением функции замены, которая возвращает строку замены. Строка замены может содержать ссылки на захваченные подпоследовательности, как в методе appendReplacement.

Обратите внимание, что обратные слэши (\) и знаки доллара ($) в строке замены могут привести к результатам, отличным от тех, если бы она обрабатывалась как строка замены буквально. Знаки доллара могут обрабатываться как ссылки на захваченные подпоследовательности, как описано выше, а обратные слэши используются для экранирования символов в строке замены.

При использовании регулярного выражения dog, входной последовательности "zzzdogzzzdogzzz", и функции mr -> mr.group().toUpperCase(), вызов этого метода для матчера этого выражения вернул бы строку "zzzDOGzzzdogzzz".

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

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

Состояние результата совпадения, переданного функции замены, гарантируется как постоянное только на время вызова функции замены и только если функция замены не изменяет состояние этого матчера.

Implementation Note:
Эта реализация применяет функцию замены к этому матчеру, который является экземпляром MatchResult.
Parameters:
replacer - Функция, которая применяется к результату совпадения этого матчера, которая возвращает строку замены.
Returns:
Строка, построенная путем замены первого соответствующего подпоследовательности результатом применения функции замены к этой подпоследовательности, заменяя при необходимости захваченные подпоследовательности.
Throws:
NullPointerException - если функция замены равна null
ConcurrentModificationException - если с наилучшими усилиями обнаружено, что функция замены изменила состояние этого матчера
Since:
9

region

public Matcher region(int start,
                      int end)

Устанавливает границы области поиска этого матчера. Область - часть входной последовательности, в которой будет производиться поиск совпадения. Вызов этого метода сбрасывает матчер и устанавливает область, начинающуюся с индекса, указанного параметром start, и заканчивающуюся индексом, указанным параметром end.

В зависимости от используемой прозрачности и привязки (см. useTransparentBounds и useAnchoringBounds), некоторые конструкции, такие как якоря, могут вести себя по-разному в или около границ области.

Parameters:
start - Индекс начала поиска (включительно)
end - Индекс окончания поиска (исключительно)
Returns:
этот матчер
Throws:
IndexOutOfBoundsException - Если start или end меньше нуля, если start больше длины входной последовательности, если end больше длины входной последовательности или если start больше end.
Since:
1.5

regionStart

public int regionStart()

Сообщает начальный индекс области этого сопоставителя. Поиски, выполняемые этим сопоставителем, ограничены нахождением совпадений в пределах regionStart (включительно) и regionEnd (исключительно).

Возвращает:
Начальная точка области этого сопоставителя
С:
1.5

regionEnd

public int regionEnd()

Сообщает конечный индекс (исключительно) области этого сопоставителя. Поиски, выполняемые этим сопоставителем, ограничены нахождением совпадений в пределах regionStart (включительно) и regionEnd (исключительно).

Возвращает:
конечная точка области этого сопоставителя
С:
1.5

hasTransparentBounds

public boolean hasTransparentBounds()

Запрашивает прозрачность границ области для этого сопоставителя.

Этот метод возвращает true если этот сопоставитель использует прозрачные границы, false если он использует непрозрачные границы.

См. useTransparentBounds для описания прозрачных и непрозрачных границ.

По умолчанию сопоставитель использует непрозрачные границы области.

Возвращает:
true если этот сопоставитель использует прозрачные границы, false в противном случае.
С:
1.5
См. также:
useTransparentBounds(boolean)

useTransparentBounds

public Matcher useTransparentBounds(boolean b)

Устанавливает прозрачность границ области для этого сопоставителя.

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

Используя прозрачные границы, границы области этого сопоставителя прозрачны для конструкций с опережающим и обратным просмотром, а также для сопоставления границ. Эти конструкции могут видеть за пределами границ области, чтобы определить, соответствует ли совпадение.

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

По умолчанию сопоставитель использует непрозрачные границы.

Параметры:
b - логическое значение, указывающее, использовать ли непрозрачную или прозрачную область
Возвращает:
этот сопоставитель
С:
1.5
См. также:
hasTransparentBounds()

hasAnchoringBounds

public boolean hasAnchoringBounds()

Запрашивает привязывание границ области для этого сопоставителя.

Этот метод возвращает true если этот сопоставитель использует привязанные границы, false в противном случае.

См. useAnchoringBounds для описания привязанных границ.

По умолчанию сопоставитель использует привязанные границы области.

Возвращает:
true если этот сопоставитель использует привязанные границы, false в противном случае.
С:
1.5
См. также:
useAnchoringBounds(boolean)

useAnchoringBounds

public Matcher useAnchoringBounds(boolean b)

Устанавливает привязывание границ области для этого сопоставителя.

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

Используя привязанные границы, границы области этого сопоставителя соответствуют якорям, таким как ^ и $.

Без привязанных границ, границы области этого сопоставителя не будут соответствовать якорям, таким как ^ и $.

По умолчанию сопоставитель использует привязанные границы области.

Параметры:
b - логическое значение, указывающее, использовать ли привязанные границы.
Возвращает:
этот сопоставитель
С:
1.5
См. также:
hasAnchoringBounds()

toString

public String toString()

Возвращает строковое представление этого сопоставителя. Строковое представление Matcher содержит информацию, которая может быть полезна для отладки. Точный формат не определен.

Переопределяет:
toString в классе Object
Возвращает:
Строковое представление этого сопоставителя
С:
1.5

hitEnd

public boolean hitEnd()

Возвращает true, если в последней операции поиска, выполненной этим сопоставителем, движок поиска достиг конца входных данных.

Когда этот метод возвращает true, то возможно, что дополнительные входные данные изменили бы результат последнего поиска.

Возвращает:
true, если в последнем поиске был достигнут конец входных данных; в противном случае false
С:
1.5

requireEnd

public boolean requireEnd()

Возвращает true, если дополнительные входные данные могут изменить положительное совпадение на отрицательное.

Если этот метод возвращает true, и совпадение было найдено, то дополнительные входные данные могут привести к потере совпадения. Если этот метод возвращает false, и совпадение было найдено, то дополнительные входные данные могут изменить совпадение, но совпадение не будет потеряно. Если совпадение не было найдено, то requireEnd не имеет значения.

Возвращает:
true, если дополнительные входные данные могут изменить положительное совпадение на отрицательное.
С:
1.5

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Matcher.html

Spec-Zone .ru
спецификации, руководства, описания, API