Глава 8

Поиск и замена подстрок

Проверить, встречается ли в тексте нужный фрагмент, узнать, где он стоит, и заменить его — три разные задачи, и для каждой в главе есть свои функции. CONTAINS, STARTSWITH и ENDSWITH отвечают на вопрос о наличии, INSTR и INSTRREV сообщают позицию, SUBSTRCOUNT считает вхождения, а REPLACE и REPLACEMANY возвращают изменённый текст. Сравнение во всех случаях точное и учитывает регистр.

Длина результата и остановка

Результаты REPLACE и REPLACEMANY подчиняются пределу STRING: не более 16 777 216 единиц UTF-16. Превышение вызывает MB3007, частичный результат при этом не возвращается.

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

CONTAINS

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

Синтаксис

Форма вызова:

CONTAINS(<текст>, <фрагмент>)

Аргументы

Аргумент	Что передать
`<текст>`	Передайте исходную строку типа STRING, которую функция должна обработать.
`<фрагмент>`	Передайте строку типа STRING, которую требуется найти в исходном тексте.

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

Функция возвращает логическое значение типа BOOLEAN: TRUE при выполнении условия и FALSE в остальных случаях.

Правила и пограничные случаи

Сравнение точное, с учётом регистра, без нормализации Unicode. Пустой фрагмент всегда даёт TRUE, в том числе для пустого текста. Непустой фрагмент в пустом тексте даёт FALSE.

Диагностика

Неверные типы и число аргументов отклоняются при проверке программы.

Пример

PRINT CONTAINS("Abc", "b")
PRINT CONTAINS("Abc", "B")
PRINT CONTAINS("", "")

Программа выводит:

TRUE
FALSE
TRUE

STARTSWITH

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

Синтаксис

Форма вызова:

STARTSWITH(<текст>, <фрагмент>)

Аргументы

Аргумент	Что передать
`<текст>`	Передайте исходную строку типа STRING, которую функция должна обработать.
`<фрагмент>`	Передайте строку типа STRING, которую требуется найти в исходном тексте.

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

Функция возвращает логическое значение типа BOOLEAN: TRUE при выполнении условия и FALSE в остальных случаях.

Правила и пограничные случаи

Диагностика

Неверные типы и число аргументов отклоняются при проверке программы.

Пример

PRINT STARTSWITH("Abc", "Ab")
PRINT STARTSWITH("Abc", "ab")
PRINT STARTSWITH("", "")

Программа выводит:

TRUE
FALSE
TRUE

ENDSWITH

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

Синтаксис

Форма вызова:

ENDSWITH(<текст>, <фрагмент>)

Аргументы

Аргумент	Что передать
`<текст>`	Передайте исходную строку типа STRING, которую функция должна обработать.
`<фрагмент>`	Передайте строку типа STRING, которую требуется найти в исходном тексте.

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

Функция возвращает логическое значение типа BOOLEAN: TRUE при выполнении условия и FALSE в остальных случаях.

Правила и пограничные случаи

Диагностика

Неверные типы и число аргументов отклоняются при проверке программы.

Пример

PRINT ENDSWITH("Abc", "bc")
PRINT ENDSWITH("Abc", "BC")
PRINT ENDSWITH("", "")

Программа выводит:

TRUE
FALSE
TRUE

INSTR

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

Синтаксис

Форма 1:

INSTR(<текст>, <фрагмент>)

Форма 2:

INSTR(<начальная позиция>, <текст>, <фрагмент>)

Аргументы

Аргумент	Что передать
`<текст>`	Передайте исходную строку типа STRING, которую функция должна обработать.
`<фрагмент>`	Передайте строку типа STRING, которую требуется найти в исходном тексте.
`<начальная позиция>`	Передайте целое число типа INTEGER с начальной позицией. Позиции отсчитываются от 1.

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

Функция возвращает целое число типа INTEGER — позицию начала совпадения в кодовых единицах UTF-16, считая от 1. Если совпадения нет, результат равен 0.

Правила и пограничные случаи

Без начальной позиции поиск начинается с 1. Сравнение учитывает регистр. Начало больше длины текста плюс 1 даёт 0. Пустой фрагмент возвращает начальную позицию, если она не больше длины текста плюс 1; поэтому INSTR("", "") возвращает 1.

Диагностика

Ошибка MB3007 возникает, если явно заданное начало меньше 1.

Пример

PRINT INSTR("abcabc", "bc")
PRINT INSTR(4, "abcabc", "bc")
PRINT INSTR("", "")

Программа выводит:

2
5
1

INSTRREV

Функция INSTRREV возвращает позицию вхождения фрагмента, найденного при поиске справа налево. Так находят последнее вхождение или ищут назад от заданной позиции. Вызов выполняется в выражении и не требует открытия экрана, холста или файла; исходные значения аргументов при этом не изменяются.

Синтаксис

Форма 1:

INSTRREV(<текст>, <фрагмент>)

Форма 2:

INSTRREV(<начальная позиция>, <текст>, <фрагмент>)

Аргументы

Аргумент	Что передать
`<текст>`	Передайте исходную строку типа STRING, которую функция должна обработать.
`<фрагмент>`	Передайте строку типа STRING, которую требуется найти в исходном тексте.
`<начальная позиция>`	Передайте положительное целое число типа INTEGER с правой границей поиска в кодовых единицах UTF-16. Без аргумента используется длина строки; значение больше длины ограничивается её длиной.

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

Функция возвращает целое число типа INTEGER — позицию начала найденного фрагмента, считая от 1. Если совпадения нет, результат равен 0.

Правила и пограничные случаи

Сравнение учитывает регистр. Пустой фрагмент возвращает правую границу поиска плюс 1. Особый случай: INSTRREV("", "") без начальной позиции возвращает 0, а INSTRREV(1, "", "") возвращает 1.

Диагностика

Ошибка MB3007 возникает, если явно заданное начало меньше 1.

Пример

PRINT INSTRREV("abcabc", "bc")
PRINT INSTRREV(3, "abcabc", "bc")
PRINT INSTRREV("", "")
PRINT INSTRREV(1, "", "")

Программа выводит:

SUBSTRCOUNT

Функция SUBSTRCOUNT возвращает количество неперекрывающихся вхождений фрагмента в строку. Она подходит для подсчёта слов, разделителей или других точных фрагментов. Вызов выполняется в выражении и не требует открытия экрана, холста или файла; исходные значения аргументов при этом не изменяются.

Синтаксис

Форма вызова:

SUBSTRCOUNT(<текст>, <фрагмент>)

Аргументы

Аргумент	Что передать
`<текст>`	Передайте исходную строку типа STRING, которую функция должна обработать.
`<фрагмент>`	Передайте непустую строку типа STRING с подсчитываемым фрагментом.

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

Функция возвращает неотрицательное целое число типа INTEGER.

Правила и пограничные случаи

Сравнение учитывает регистр. После совпадения поиск продолжается за его концом; перекрывающиеся вхождения не считаются. Пустой текст с непустым фрагментом даёт 0.

Диагностика

Ошибка MB3007 возникает, если искомый фрагмент пуст.

Пример

PRINT SUBSTRCOUNT("aaaa", "aa")
PRINT SUBSTRCOUNT("", "a")

Программа выводит:

2
0

REPLACE

Функция REPLACE возвращает строку, заменив все точные вхождения одного фрагмента другим. Она выполняет обычную текстовую замену без регулярного выражения. Вызов выполняется в выражении и не требует открытия экрана, холста или файла; исходные значения аргументов при этом не изменяются.

Синтаксис

Форма вызова:

REPLACE(<текст>, <исходный текст>, <новый текст>)

Аргументы

Аргумент	Что передать
`<текст>`	Передайте исходную строку типа STRING, которую функция должна обработать.
`<исходный текст>`	Передайте непустую строку типа STRING с заменяемым фрагментом.
`<новый текст>`	Передайте строку типа STRING с текстом замены. Пустая строка удаляет найденные фрагменты.

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

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

Правила и пограничные случаи

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

Диагностика

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

Пример

PRINT REPLACE("A a A", "A", "B")
PRINT REPLACE("banana", "na", "")

Программа выводит:

B a B
ba

REPLACEMANY

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

Синтаксис

Форма вызова:

REPLACEMANY(<текст>, <исходные элементы>, <новые элементы>)

Аргументы

Аргумент	Что передать
`<текст>`	Передайте исходную строку типа STRING, которую функция должна обработать.
`<исходные элементы>`	Передайте одномерный массив строк STRING[] с заменяемыми непустыми фрагментами.
`<новые элементы>`	Передайте одномерный массив строк STRING[] с соответствующими заменами. Длина должна совпадать с длиной массива исходных фрагментов; нижние границы могут различаться.

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

Функция возвращает строку типа STRING. Правила сопоставляются по порядку элементов массивов, а не по совпадению их индексов.

Правила и пограничные случаи

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

Диагностика

Ошибка MB3007 возникает при разных длинах наборов правил или пустой строке в массиве заменяемых фрагментов. Эти проверки выполняются и для пустого исходного текста.

Пример

DIM oldItems[5 TO 6] AS STRING
DIM newItems[8 TO 9] AS STRING
oldItems[5]="ab"
oldItems[6]="a"
newItems[8]="X"
newItems[9]="Y"
PRINT REPLACEMANY("aba", oldItems[], newItems[])

Программа выводит:

XY

См. также

Строковые функции Длина строки и фрагменты Обрезка, регистр и разворот Построение строк и массивы строк Коды символов Регулярные выражения