Функции строк
В данной статье при описании функций приняты следующие обозначения:
|
Функции поиска и сопоставления
contains
Определяет, содержит ли строка значение
указанную подстроку
.
Чтобы проверить наличие нескольких подстрок, используйте функцию rv_contains_any . Функция вернет true , если хотя бы одна из переданных подстрок присутствует в строке.
|
Спецификация функции
contains(значение: <строка>, подстрока: <строка>, [case_sensitive: <логическое значение>]) :: <логическое значение>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Текст для поиска. |
да |
|
подстрока |
строка |
Подстрока, которую нужно найти в |
да |
|
case_sensitive |
логическое значение |
Должен ли поиск учитывать регистр символов. |
|
нет |
Примеры
Проверка наличия подстроки в строке (с учетом регистра)
contains("The Needle In The Haystack", "Needle")
true
Проверка наличия подстроки в строке (без учета регистра)
contains("The Needle In The Haystack", "needle", case_sensitive: false)
true
contains_all
Определяет, содержит ли строка значение
все указанные подстроки
.
Чтобы проверить наличие в строке хотя бы одной из подстрок, используйте функцию rv_contains_any . Функция вернет true , если одна из переданных подстрок присутствует в строке.
|
Спецификация функции
contains_all(значение: <строка>, подстроки: <массив>, [case_sensitive: <логическое значение>]) :: <логическое значение>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Текст для поиска. |
да |
|
подстрока |
массив |
Массив подстрок, которые нужно найти в |
да |
|
case_sensitive |
логическое значение |
Должен ли поиск учитывать регистр символов. |
|
нет |
Примеры
Проверка наличия подстрок в строке (с учетом регистра)
contains_all("The Needle In The Haystack", ["Needle", "Haystack"])
true
Проверка наличия подстроки в строке (без учета регистра)
contains_all("the NEEDLE in the haystack", ["needle", "haystack"], case_sensitive: false)
true
rv_contains_any
Определяет, содержится ли в строке значение
хотя бы одна подстрока из массива подстроки
.
Массив строк должен быть представлен литералом, без использования переменных. Это позволяет оптимизировать выполнение, заранее построив структуру для поиска конкретных подстрок. |
Спецификация функции
rv_contains_any(значение: <строка>, подстроки: <массив>, [case_sensitive: <логическое значение>]) :: <логическое значение>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Строка, в которой производится поиск подстрок. |
да |
|
подстроки |
массив |
Литерал массива строк, которые ищутся в |
да |
|
case_sensitive |
логическое значение |
Определяет, учитывается ли регистр символов при поиске. |
|
нет |
Ошибки
Функция rv_contains_any
может возвращать ошибки, для которых требуется обработка:
-
Подстроки содержат недопустимые данные.
Примеры
Одна из подстрок содержится в значении
rv_contains_any("eqwas_)xz!123", ["asd", "xz"])
true
Одна из подстрок содержится в значении без учета регистра
rv_contains_any("eqwas_)xZ!123", ["asd", "Xz"], case_sensitive: false)
true
Ни одна подстрока не содержится в значении
rv_contains_any("eqwas_)xz!123", ["asd", "xz1"])
false
starts_with
Определяет, начинается ли значение
с подстроки
.
Чтобы проверить несколько подстрок, используйте функцию rv_starts_with_any . Функция вернет true , если строка начинается хотя бы с одной из переданных подстрок.
|
Спецификация функции
starts_with(значение: <строка>, подстрока: <строка>, [case_sensitive: <логическое значение>]) :: <логическое значение>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Строка для поиска. |
да |
|
подстрока |
строка |
Подстрока, с которой |
да |
|
case_sensitive |
логическое значение |
Определяет, должен ли поиск быть чувствительным к регистру. |
|
нет |
Примеры
Строка начинается с подстроки (с учетом регистра)
starts_with("The Needle In The Haystack", "The Needle")
true
Строка начинается с подстроки (без учета регистра)
starts_with("The Needle In The Haystack", "the needle", case_sensitive: false)
true
rv_starts_with_any
Определяет, начинается ли строка значение
хотя бы с одной подстроки из массива подстроки
.
Массив строк должен быть представлен литералом, без использования переменных. Это позволяет оптимизировать выполнение, заранее построив структуру для поиска конкретных подстрок. |
Спецификация функции
rv_starts_with_any(значение: <строка>, подстроки: <массив>, [case_sensitive: <логическое значение>]) :: <логическое значение>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Строка, в которой производится поиск подстрок. |
да |
|
подстроки |
массив |
Литерал массива строк, которые ищутся в |
да |
|
case_sensitive |
логическое значение |
Определяет, учитывается ли регистр символов при поиске. |
|
нет |
Ошибки
Функция rv_contains_any
может возвращать ошибки, для которых требуется обработка:
-
Подстроки содержат недопустимые данные.
Примеры
Значение начинается с одной из подстрок
rv_starts_with_any("xzeqwas_)xz!123", ["asd", "xz"])
true
Значение начинается с одной из подстрок без учета регистра
rv_starts_with_any("xZeqwas_)xz!123", ["asd", "Xz"], case_sensitive: false)
true
Значение не начинается ни с одной из подстрок
rv_starts_with_any("xzeqwas_)xz1!123", ["asd", "xz1"])
false
ends_with
Определяет, заканчивается ли строка значение
указанной подстрокой
.
Чтобы проверить несколько подстрок, используйте функцию rv_ends_with_any . Функция вернет true , если строка заканчивается хотя бы одной из переданных подстрок.
|
Спецификация функции
ends_with(значение: <строка>, подстрока: <строка>, [case_sensitive: <логическое значение>]) :: <логическое значение>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Строка для поиска. |
да |
|
подстрока |
строка |
Подстрока, которой должно заканчиваться |
да |
|
case_sensitive |
логическое значение |
Определяет, должен ли поиск быть чувствительным к регистру. |
|
нет |
Примеры
Строка заканчивается (с учетом регистра)
ends_with("The Needle In The Haystack", "The Haystack")
true
Строка заканчивается (без учета регистра)
ends_with("The Needle In The Haystack", "the haystack", case_sensitive: false)
true
rv_ends_with_any
Определяет, заканчивается ли строка значение
хотя бы одной подстрокой из массива подстроки
.
Массив строк должен быть представлен литералом, без использования переменных. Это позволяет оптимизировать выполнение, заранее построив структуру для поиска конкретных подстрок. |
Спецификация функции
rv_ends_with_any(значение: <строка>, подстроки: <массив>, [case_sensitive: <логическое значение>]) :: <логическое значение>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Строка, в которой производится поиск подстрок. |
да |
|
подстроки |
массив |
Литерал массива строк, которые ищутся в |
да |
|
case_sensitive |
логическое значение |
Определяет, учитывается ли регистр символов при поиске. |
|
нет |
Ошибки
Функция rv_contains_any
может возвращать ошибки, для которых требуется обработка:
-
Подстроки содержат недопустимые данные.
Примеры
Значение заканчивается одной из подстрок
rv_ends_with_any("eqwas_)xz!123xz", ["asd", "xz"])
true
Значение заканчивается одной из подстрок без учета регистра
rv_ends_with_any("eqwas_)xz!123xZ", ["asd", "Xz"], case_sensitive: false)
true
Значение не заканчивается ни одной из подстрок
rv_ends_with_any("eqwas_)xz!123xz", ["asd", "xz1"])
false
find
Определяет позицию начала первого найденного элемента в строке значение
, слева направо, который соответствует шаблону
, или возвращает -1, если элемент не найден.
Спецификация функции
find(значение: <строка>, шаблон: <регулярное выражение | строка>, [from: <целое число>]) :: <целое число>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Строка для поиска паттерна. |
да |
|
шаблон |
регулярное выражение строка |
Регулярное выражение или строка для сравнения. |
да |
|
from |
целое число |
Смещение, с которого начинается поиск. |
|
нет |
Примеры
Поиск текста
find("foobar", "foo")
0
Поиск по регулярному выражению
find("foobar", r'b.r')
3
Нет совпадений
find("foobar", "baz")
-1
С учетом смещения
find("foobarfoobarfoo", "bar", 4)
9
match
Определяет, соответствует ли значение
указанному шаблону
.
Спецификация функции
match(значение: <строка>, шаблон: <регулярное выражение>) :: <логическое значение>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Значение для проверки на соответствие. |
да |
|
шаблон |
регулярное выражение |
Регулярное выражение для проверки соответствия. |
да |
Примеры
Проверка на соответствие регулярному выражению
match("I'm a little teapot", r'teapot')
true
match_any
Определяет, соответствует ли значение
хотя бы одному из указанных шаблонов
. Все шаблоны проверяются за один проход по целевой строке, что дает этой функции преимущество в производительности перед многократным вызовом функции match
.
Спецификация функции
match_any(значение: <строка>, шаблоны: <массив>) :: <логическое значение>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Значение для проверки на соответствие. |
да |
|
шаблоны |
массив |
Массив регулярных выражений для проверки соответствия. |
да |
Примеры
Проверка на соответствие хотя бы одному регулярному выражению
match_any("I'm a little teapot", [r'frying pan', r'teapot'])
true
strlen
Возвращает количество символов UTF-8 в значении
. Это отличается от length
, который бы подсчитал количество байтов в строке.
Обратите внимание, что это подсчет значений Unicode, который иногда может отличаться от кодовых точек Unicode.
Спецификация функции
strlen(значение: <строка>) :: <целое число>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Строка |
да |
Примеры
strlen
strlen("ñandú")
5
Функции разбиения и слияния
join
Объединяет каждую строку в массиве значение
в одну строку с возможным разделителем separator
.
Спецификация функции
join(значение: <массив>, [separator: <строка>]) :: <строка>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
массив |
Массив строк, которые нужно объединить. |
да |
|
separator |
строка |
Строка, разделяющая каждый элемент при объединении. |
нет |
Примеры
Объединение массива (без разделителя)
join!(["bring", "us", "together"])
bringustogether
Объединение массива (разделитель — запятая)
join!(["sources", "transforms", "sinks"], separator: ", ")
sources, transforms, sinks
slice
Возвращает срез значения
между позициями start
и end
.
Если параметры start
и end
отрицательные, они отсчитываются справа от строки или массива. Если end
указывает на позицию, которая больше длины строки или массива, возвращается срез до конца строки или массива.
Спецификация функции
slice(значение: <массив | строка>, start: <целое число>, [end: <целое число>]) :: <строка>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
массив строка |
Строка или массив для среза. |
да |
|
start |
целое число |
Включительная начальная позиция. Индекс с нуля, который может быть отрицательным. |
да |
|
end |
целое число |
Исключительная конечная позиция. Индекс с нуля, который может быть отрицательным. |
|
нет |
Примеры
Срез строки (положительный индекс)
slice!("Supercalifragilisticexpialidocious", start: 5, end: 13)
califrag
Срез строки (отрицательный индекс)
slice!("Supercalifragilisticexpialidocious", start: 5, end: -14)
califragilistic
split
Разделяет строку значение
с использованием шаблона
.
Спецификация функции
split(значение: <строка>, шаблон: <строка | регулярное выражение>, [limit: <целое число>]) :: <массив>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Строка для разделения. |
да |
|
шаблон |
строка регулярное выражение |
Строка разделяется каждый раз, когда совпадает с этим шаблоном. Может быть строкой или регулярным выражением. |
да |
|
limit |
целое число |
Максимальное количество подстрок для возврата. |
нет |
Примеры
Разделение строки (без ограничения)
split("apples and pears and bananas", " and ")
["apples", "pears", "bananas"]
Разделение строки (с ограничением)
split("apples and pears and bananas", " and ", limit: 2)
["apples", "pears and bananas"]
Функции редактирования строк
redact
Скрывает конфиденциальные данные, такие как номера социального страхования США (SSN) и другие виды личной информации, с помощью пользовательских шаблонов. Это помогает соблюдать правила и гарантировать, что конфиденциальные данные не покидают вашу сеть.
Поведение функции зависит от типа значения
:
-
Для строк — скрывает конфиденциальные данные и возвращает новую строку.
-
Для массивов — скрывает конфиденциальные данные в каждом элементе строки.
-
Для объектов — маскирует конфиденциальные данные в каждом значении строки, но не в ключах.
В массивах и объектах функция рекурсивно применяет эти операции ко всем вложенным массивам и объектам. Любые нестроковые элементы будут пропущены.
Любой скрытый текст будет заменен на [REDACTED]
.
Спецификация функции
redact(значение: <строка | объект | массив>, фильтры: <массив>, [redactor: <строка | объект> ])) :: <строка | объект | массив>
Аргумент | Тип | Описание | По умолчанию | Обязателен | ||
---|---|---|---|---|---|---|
значение |
строка объект массив |
Значение, в котором требуется скрыть конфиденциальные данные. |
да |
|||
filters |
массив |
Список фильтров, которые будут применены к Каждый фильтр может быть указан одним из следующих способов:
Именованный фильтр
|
да |
|||
redactor |
строка объект |
Указывает, на что заменить совпадения с фильтрами. Аргумент задается как объект вида
Этот параметр должен быть представлен статическим выражением. Нельзя использовать переменные или другие динамические выражения. Это позволяет выполнить проверку аргумента на этапе компиляции и исключить ошибки во время выполнения. |
|
нет |
Для часто используемых шаблонов замены можно использовать сокращения в виде строк:
|
Примеры
Замена текста с помощью регулярного выражения
redact("my id is 123456", filters: [r'\d+'])
my id is [REDACTED]
Замена номеров социального страхования США в любом поле
redact({ "name": "John Doe", "ssn": "123-12-1234"}, filters: ["us_social_security_number"])
{ "name": "John Doe", "ssn": "[REDACTED]" }
Замена произвольным текстом
redact("my id is 123456", filters: [r'\d+'], redactor: {"type": "text", "replacement": "***"})
my id is ***
Замена хешем SHA-3
redact("my id is 123456", filters: [r'\d+'], redactor: "sha3")
my id is ZNCdmTDI7PeeUTFnpYjLdUObdizo+bIupZdl8yqnTKGdLx6X3JIqPUlUWUoFBikX+yTR+OcvLtAqWO11NPlNJw==
Замена хешем SHA-256 в шестнадцатеричной кодировке
redact("my id is 123456", filters: [r'\d+'], redactor: {"type": "sha2", "variant": "SHA-256", "encoding": "base16"})
my id is 8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92
replace
Заменяет все совпадения с шаблоном
из значения
на строку чем_заменить
.
В аргументе чем_заменить
могут использоваться именованные группы.
Строки, начинающиеся с символа $ ($foo ), интерпретируются в VRL-блоках элементов экспертизы как переменные окружения. Чтобы избежать этого, экранируйте такие строки символом $ ($$foo ).
|
Спецификация функции
replace(значение: <строка>, шаблон: <регулярное выражение | строка>, чем_заменить: <строка>, [count: <целое число>]) :: <строка>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Исходная строка. |
да |
|
шаблон |
регулярное выражение строка |
Заменяет все совпадения с этим шаблоном. Может быть статической строкой или регулярным выражением. |
да |
|
чем_заменить |
строка |
Строка, которой заменяются совпадения. |
да |
|
count |
целое число |
Максимальное количество замен. |
|
нет |
Примеры
Замена текста
replace("Apples and Bananas", "and", "not")
Apples not Bananas
Замена с помощью регулярного выражения
replace("Apples and Bananas", r'(?i)bananas', "Pineapples")
Apples and Pineapples
Замена только первого совпадения
replace("Bananas and Bananas", "Bananas", "Pineapples", count: 1)
Pineapples and Bananas
Замена с захватом групп
replace("foo123bar", r'foo(?P<num>\d+)bar', "$num")
В VRL-блоках элементов экспертизы используйте $$num .
|
123
replace_with
Заменяет все совпадения с шаблоном
из значения
с помощью замыкания.
Аргумент шаблон
принимает регулярное выражение, которое может использовать захват групп.
Синтаксис замыкания используется, чтобы вычислить строку, на которую заменяются совпадения. Замыкание принимает единственный аргумент, представляющий собой объект со следующими полями:
-
captures
— массив, элементами которого являются захваченные группы.Если группа является незахватывающей (то есть обозначена
?:
) то значение соответствующего элемента равноnull
. -
string
— строка, включающая полное совпадение. -
поля, соответствующие именованным группам.
В результате функции возвращается новая строка с заменой совпадений, исходная строка не изменяется.
Спецификация функции
replace_with(значение: <строка>, шаблон: <регулярное выражение>, [count: <целое число> ]) -> |<переменная>| { <блок> } :: <строка>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Исходная строка. |
да |
|
шаблон |
регулярное выражение |
Шаблон для поиска совпадений. Может содержать захват групп. Нельзя использовать имена групп |
да |
|
count |
целое число |
Максимальное количество замен. |
|
нет |
Примеры
Сделать первые буквы слов прописными
replace_with("no server available", r'\b(\w)(\w*)') -> |match| { upcase!(match.captures[0]) + string!(match.captures[1]) }
No Server Available
Замена на хэш
replace_with("email from test@example.com", r'\w+@example.com') -> |match| { sha2(match.string, variant: "SHA-512/224") }
email from adf6e1bc4415d24912bd93072ad34ef825a7b6eb3bf53f68def1fc17
Замена на хэш
replace_with("email from test@example.com", r'\w+@example.com') -> |match| { sha2(match.string, variant: "SHA-512/224") }
email from adf6e1bc4415d24912bd93072ad34ef825a7b6eb3bf53f68def1fc17
Замена первого вхождения
replace_with("The file was not found, check the file name.", r'(?i)file', count: 1) -> |match| { "object" }
The object was not found, check the file name.
Именованная группа
replace_with("level=error A message", r'level=(?P<level>\w+)') -> |match| { lvl = upcase!(match.level) "[{{lvl}}]" }
[ERROR] A message
sieve
Сохраняет в значении
только совпадения с шаблоном
.
Функцию можно использовать для определения символов, которые разрешены в строке, и удаления всего остального.
Спецификация функции
sieve(значение: <строка>, шаблон: <регулярное выражение>, [replace_single: <строка> , replace_repeated: <строка> ]) :: <строка>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Исходная строка. |
да |
|
шаблон |
регулярное выражение |
Шаблон, совпадения с которым должны остаться в строке. |
да |
|
replace_single |
строка |
Строка, на которую будут заменены отдельные символы, не совпадающие с шаблоном. |
нет |
|
replace_repeated |
строка |
Строка, на которую будут заменены последовательности нескольких символов, не совпадающих с шаблоном. |
нет |
Примеры
Очистка строки с помощью регулярного выражения
sieve("test123%456.فوائد.net.", r'[a-z0-9.]')
test123456..net.
Очистка с указанием заменяющих строк
sieve("test123%456.فوائد.net.", r'[a-z.0-9]', replace_single: "X", replace_repeated: "<REMOVED>")
test123X456.<REMOVED>.net.
truncate
Обрезает строку значение
до количества символов limit
.
Спецификация функции
truncate(значение: <строка>, limit: <целое число | число с плавающей точкой>, ellipsis: <логическое значение>) :: <строка>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Строка для обрезания. |
да |
|
limit |
целое число число с плавающей точкой |
Количество символов, после которых будет обрезана строка. |
да |
|
ellipsis |
логическое значение |
Добавлять многоточие при обрезании строки. Если параметр равен |
|
нет |
suffix |
строка |
Суффикс, который добавляется к обрезанным строкам. Если |
нет |
Примеры
Обрезка с многоточием
truncate("A rather long sentence.", limit: 11, ellipsis: true)
A rather lo...
Обрезка с произвольным суффиксом
truncate("A rather long sentence.", limit: 11, suffix: "[TRUNCATED]")
A rather lo[TRUNCATED]
Функции изменения регистра
downcase
Преобразует строку значение
в нижний регистр, где "нижний регистр" определяется по свойству Unicode Lowercase
.
Спецификация функции
downcase(значение: <строка>) :: <строка>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Строка, которую необходимо преобразовать к нижнему регистру. |
да |
Примеры
Преобразование строки к нижнему регистру
downcase("Hello, World!")
hello, world!
upcase
Приводит значение
к верхнему регистру, который определяется согласно свойству Unicode Uppercase
.
Спецификация функции
upcase(значение: <строка>) :: <строка>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
значение |
строка |
Строка, которую нужно привести к верхнему регистру |
да |
Примеры
Приведение строки к верхнему регистру
upcase("Hello, World!")
HELLO, WORLD!