Функции коллекций

В данном разделе при описании функций приняты следующие обозначения:

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

Функции для работы с коллекциями предоставляют набор операций для манипуляции массивами и объектами.

Функции извлечения данных

includes

Определяет, включает ли массив value указанный элемент element.

Спецификация функции

includes(value: <массив>, element: <любой тип>)
:: <логическое значение>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	массив	Массив.		да
`element`	любое	Элемент для проверки.		да

value

массив

Массив.

да

element

любое

Элемент для проверки.

да

Пример

Массив включает указанный элемент

Пример 1. Исходный код

includes(["apple", "orange", "banana"], "banana")

Пример 2. Результат

true

keys

Возвращает ключи переданного в функцию объекта.

Спецификация функции

keys(value: <объект>)
:: <массив>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	объект	Объект, из которого нужно извлечь ключи.		да

value

объект

Объект, из которого нужно извлечь ключи.

да

Пример

Получение ключей из объекта

Пример 3. Исходный код

keys({"key1": "val1", "key2": "val2"})

Пример 4. Результат

[
  "key1",
  "key2"
]

length

Возвращает длину value. Результат зависит от типа value:

для массива возвращает количество элементов;
для объекта возвращает количество ключей на верхнем уровне;
для строки возвращает количество байтов в строке. Если нужно получить количество символов, используйте функцию strlen.

Спецификация функции

length(value: <массив | объект | строка>)
:: <целое число>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	массив объект строка	Массив, объект или строка.		да

value

массив объект строка

Массив, объект или строка.

да

Примеры

Длина объекта

Пример 5. Исходный код

length({
  "portland": "Trail Blazers",
  "seattle": "Supersonics"
})

Пример 6. Результат

Длина объекта со вложенными объектами

Пример 7. Исходный код

length({
  "home": {
    "city": "Portland",
    "state": "Oregon"
  },
  "name": "Trail Blazers",
  "mascot": {
    "name": "Blaze the Trail Cat"
  }
})

Пример 8. Результат

Длина массива

Пример 9. Исходный код

length(["Trail Blazers", "Supersonics", "Grizzlies"])

Пример 10. Результат

Длина строки

Пример 11. Исходный код

length("The Planet of the Apes Musical")

Пример 12. Результат

values

Возвращает значения из переданного объекта.

Чтобы получить срез массива, используйте функцию slice.

Спецификация функции

values(value: <объект>)
:: <массив>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	объект	Объект, из которого извлекаются значения.		да

value

объект

Объект, из которого извлекаются значения.

да

Пример

Получение значений из объекта

Пример 13. Исходный код

values({"key1": "val1", "key2": "val2"})

Пример 14. Результат

[
  "val1",
  "val2"
]

Функции фильтрации

compact

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

Спецификация функции

compact(value: <массив | объект>, [recursive: <логическое значение>, null: <логическое значение>, string: <логическое значение>, object: <логическое значение>, array: <логическое значение>, nullish: <логическое значение>])
:: <массив | объект>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	массив объект	Объект или массив для сжатия.		да
`recursive`	логическое значение	Будет ли сжатие рекурсивным, то есть удаляются ли пустые элементы вложенных объектов и массивов.	`true`	нет
`null`	логическое значение	Рассматривается ли `null` как пустое значение.	`true`	нет
`string`	логическое значение	Рассматривается ли пустая строка как пустое значение.	`true`	нет
`object`	логическое значение	Рассматривается ли объект без элементов как пустое значение.	`true`	нет
`array`	логическое значение	Рассматривается ли массив без элементов как пустое значение.	`true`	нет
`nullish`	логическое значение	Рассматриваются ли "нулевые" значения, которые определены функцией `is_nullish`, как пустые.	`false`	нет

value

массив объект

Объект или массив для сжатия.

да

recursive

логическое значение

Будет ли сжатие рекурсивным, то есть удаляются ли пустые элементы вложенных объектов и массивов.

true

нет

null

логическое значение

Рассматривается ли null как пустое значение.

true

нет

string

логическое значение

Рассматривается ли пустая строка как пустое значение.

true

нет

object

логическое значение

Рассматривается ли объект без элементов как пустое значение.

true

нет

array

логическое значение

Рассматривается ли массив без элементов как пустое значение.

true

нет

nullish

логическое значение

Рассматриваются ли "нулевые" значения, которые определены функцией is_nullish, как пустые.

false

нет

Примеры

Сжатие массива

Пример 15. Исходный код

compact(["foo", "bar", "", null, [], "buzz"], string: true, array: true, null: true)

Пример 16. Результат

[
  "foo",
  "bar",
  "buzz"
]

Сжатие объекта

Пример 17. Исходный код

compact({"field1": 1, "field2": "", "field3": [], "field4": null}, string: true, array: true, null: true)

Пример 18. Результат

{
  "field1": 1
}

filter

Отбирает элементы из коллекции.

Эта функция не поддерживает рекурсивную итерацию.

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

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

Спецификация функции

filter(value: <массив | объект>) -> |<переменная ключа или индекса>, <переменная значения>| {
    <блок>
}
:: <массив | объект>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	массив объект	Массив или объект для фильтрации.		да

value

массив объект

Массив или объект для фильтрации.

да

Пример

Фильтрация элементов

Пример 19. Исходный код

filter(array!(.tags)) -> |_index, value| {
  # Оставить элементы, которые не равны "foo".
  value != "foo"
}

Пример 20. Результат

[
  "bar",
  "baz"
]

rv_coalesce_nullish

Возвращает первый элемент массива, значение которого не является "nullish", то есть первый элемент со значимым содержанием. Значениями "nullish" считаются следующие:

null;
"-";
состоящие только из пробелов, то есть символов со свойством Unicode White_Space.

Если все значения в массиве являются "nullish", функция возвращает null.

Спецификация функции

rv_coalesce_nullish(value: <массив>)
:: <любой тип>, <ошибка>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	массив	массив, в котором производится поиск элементов, не являющихся "nullish"		да

value

массив

массив, в котором производится поиск элементов, не являющихся "nullish"

да

Ошибки

Функция rv_coalesce_nullish возвращает ошибку, для которой требуется обработка, если value не является массивом.

Примеры

Есть и значения "nullish", и значимые

Пример 21. Исходный код

rv_coalesce_nullish(["  ", "-", "test"])

Пример 22. Результат

"test"

Все элементы имеют значимое содержание

Пример 23. Исходный код

rv_coalesce_nullish(["123132", "test"])

Пример 24. Результат

"123132"

Все элементы являются "nullish"

Пример 25. Исходный код

rv_coalesce_nullish(["-", "   ", "", null, ""])

Пример 26. Результат

null

unique

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

Сохраняется только первое вхождение каждого элемента.

Спецификация функции

unique(value: <массив>)
:: <массив>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	массив	Массив, из которого будут возвращены уникальные элементы.		да

value

массив

Массив, из которого будут возвращены уникальные элементы.

да

Пример

Уникальные значения

Пример 27. Исходный код

unique(["foo", "bar", "foo", "baz"])

Пример 28. Результат

[
  "foo",
  "bar",
  "baz"
]

Функции итерации по элементам коллекции

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

Функция join, объединяющая элементы массива в строку, описана в разделе Функции строк.

all

Проверяет, что все элементы value соответствуют условию, указанному в синтаксисе замыкания вида |<переменная ключа>, <переменная значения>| { <блок> }, где:

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

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

Спецификация функции

all(value: <массив или объект>) -> |<переменная ключа или индекс>, <переменная значения>| { <блок> }
:: <логическое значение>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	массив или объект	Массив или объект для проверки		да

value

массив или объект

Массив или объект для проверки

да

Примеры

Итерация объекта

Пример 29. Исходный код

all({ "a": 1, "b": 2 }) -> |_key, value| { value > 0 }

Пример 30. Результат

true

Итерация массива

Пример 31. Исходный код

all([1, 2, 3, 4, 5]) -> |index, value| { value > 0 }

Пример 32. Результат

true

any

Проверяет, что хотя бы один элемент value соответствует условию, указанному в синтаксисе замыкания вида |<переменная ключа>, <переменная значения>| { <блок> }, где:

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

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

Спецификация функции

any(value: <массив или объект>) -> |<переменная ключа или индекс>, <переменная значения>| { <блок> }
:: <логическое значение>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	массив или объект	Массив или объект для проверки		да

value

массив или объект

Массив или объект для проверки

да

Примеры

Итерация объекта

Пример 33. Исходный код

any({ "a": 1, "b": 2 }) -> |_key, value| { value == 2 }

Пример 34. Результат

true

Итерация массива

Пример 35. Исходный код

all([1, 2, 3, 4, 5]) -> |index, value| { value == 2 }

Пример 36. Результат

true

for_each

Итерирует по коллекции.

В настоящее время функция не поддерживает рекурсивную итерацию.

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

Спецификация функции

for_each(value: <массив | объект>) -> |<переменная ключа или индекса>, <переменная значения>| {
    <блок>
}
:: <пустое значение>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	массив объект	Массив или объект для итерации.		да

value

массив объект

Массив или объект для итерации.

да

Примеры

Подсчет элементов

Пример 37. Исходный код

tally = {}
for_each(array!(.tags)) -> |_index, value| {
  # Получение текущего подсчета для `value` или установка его в `0`.
  count = int(get!(tally, [value])) ?? 0
  # Увеличение подсчета для значения на `1`.
  tally = set!(tally, [value], count + 1)
}
tally

Пример 38. Результат

{
  "foo": 2,
  "bar": 1,
  "baz": 1
}

map_keys

Отображает ключи объекта.

Если включен параметр recursive, функция обрабатывает вложенные объекты согласно следующим правилам:

Итерация начинается с корневого объекта.
Для каждого вложенного объекта:
- Сначала возвращается ключ самого объекта.
- Затем происходит рекурсивный вызов функции для объекта, и происходит возврат к пункту 1.
- Любые изменения, сделанные во вложенном объекте до его рекурсивного вызова, сохраняются.
Для каждого вложенного массива:
- Сначала возвращается ключ самого массива.
- Затем происходит поиск всех объектов внутри массива и применение к каждому из них правил из пункта 2.

На практике эти правила означают, что map_keys с включенным параметром recursive найдет все ключи в целевом объекте, независимо от того, находятся ли вложенные объекты внутри массивов.

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

Спецификация функции

map_keys(value: <объект>, [recursive: <логическое значение>]) -> |<переменная ключа>| { <блок> }
:: <объект>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	объект	Объект для итерации.		да
`recursive`	логическое значение	Определяет, следует ли выполнять рекурсивную итерацию по коллекции.	`false`	нет

value

объект

Объект для итерации.

да

recursive

логическое значение

Определяет, следует ли выполнять рекурсивную итерацию по коллекции.

false

нет

Примеры

Приведение ключей к верхнему регистру

Пример 39. Исходный код

map_keys(.) -> |key| { upcase(key) }

Пример 40. Результат

{
  "FOO": "foo",
  "BAR": "bar"
}

Замена точек в ключах на подчеркивания

Пример 41. Исходный код

map_keys(., recursive: true) -> |key| { replace(key, ".", "_") }

Пример 42. Результат

{
  "labels": {
    "app_kubernetes_io/name": "mysql"
  }
}

map_values

Отображает значения внутри коллекции.

Если включен параметр recursive, функция обрабатывает вложенные коллекции согласно следующим правилам:

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

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

Спецификация функции

map_values(value: <массив | объект>, [recursive: <логическое значение>]) -> |<переменная значения>| { <блок> }
:: <массив | объект>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	массив объект	Коллекция (массив или объект) для итерации.		да
`recursive`	логическое значение	Определяет, следует ли выполнять рекурсивную итерацию по коллекции.	`false`	нет

value

массив объект

Коллекция (массив или объект) для итерации.

да

recursive

логическое значение

Определяет, следует ли выполнять рекурсивную итерацию по коллекции.

false

нет

Пример

Приведение значений к верхнему регистру

Пример 43. Исходный код

map_values(.) -> |value| { upcase!(value) }

Пример 44. Результат

{
  "foo": "FOO",
  "bar": "BAR"
}

match_datadog_query

Сопоставляет объект value с запросом Datadog Search Syntax.

Спецификация функции

match_datadog_query(value: <объект> , query: <строка> )
:: <логическое значение>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	объект	Коллекция (объект)		да
`query`	строка	Запрос Datadog Search Syntax		да

value

объект

Коллекция (объект)

да

query

строка

Запрос Datadog Search Syntax

да

Примеры

Запрос OR

Пример 45. Исходный код

match_datadog_query({"message": "contains this and that"}, "this OR that")

Пример 46. Результат

true

Запрос AND

Пример 47. Исходный код

match_datadog_query({"message": "contains only this"}, "this AND that")

Пример 48. Результат

false

Символ подстановки в атрибутах

Пример 49. Исходный код

match_datadog_query({"name": "foobar"}, "@name:foo*")

Пример 50. Результат

true

Диапазон тегов

Пример 51. Исходный код

match_datadog_query({"tags": ["a:x", "b:y", "c:z"]}, s'b:["x" TO "z"]')

Пример 52. Результат

true

Функции изменения структуры коллекции

chunks

Разбивает value на части длиной chunk_size в байтах.

Спецификация функции

chunks(value: <массив | строка>, chunk_size: <целое число>)
:: <массив> , <ошибка>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	массив строка	Массив байтов или строка для разделения.		да
`chunk_size`	целое число	Желаемая длина каждого фрагмента в байтах, не менее 1 байта. Длина может быть ограничена архитектурой хост-платформы.		да

value

массив строка

Массив байтов или строка для разделения.

да

chunk_size

целое число

Желаемая длина каждого фрагмента в байтах, не менее 1 байта. Длина может быть ограничена архитектурой хост-платформы.

да

Характеристики функции

При делении на фрагменты границы кодовых точек Unicode не соблюдаются.

Ошибки

Функция chunks может возвращать ошибки, для которых требуется обработка:

chunk_size менее 1 байта.
chunk_size слишком велик.

Примеры

Разделение строки на фрагменты

Пример 53. Исходный код

chunks("abcdefgh", 4)

Пример 54. Результат

[
  "abcd",
  "efgh"
]

Деление без учета границ кодовой точки Unicode

Пример 55. Исходный код

chunks("ab你好", 4)

Пример 56. Результат

[
  "ab�",
  "�好"
]

flatten

Выполняет преобразование value в представление с одним уровнем.

Спецификация функции

flatten(value: <массив | объект>, [separator: <строка>])
:: <массив | объект>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	массив объект	Массив или объект, которые необходимо преобразовать.		да
`separator`	строка	Разделитель, используемый для объединения вложенных ключей.	`.`	нет

value

массив объект

Массив или объект, которые необходимо преобразовать.

да

separator

строка

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

.

нет

Примеры

Преобразование массива

Пример 57. Исходный код

flatten([1, [2, 3, 4], [5, [6, 7], 8], 9])

Пример 58. Результат

[
  1,
  2,
  3,
  4,
  5,
  6,
  7,
  8,
  9
]

Преобразование объекта

Пример 59. Исходный код

flatten({
  "parent1": {
    "child1": 1,
    "child2": 2
  },
  "parent2": {
    "child3": 3
  }
})

Пример 60. Результат

{
  "parent1.child1": 1,
  "parent1.child2": 2,
  "parent2.child3": 3
}

unflatten

Преобразует value во вложенное представление. Функция может быть полезна для возвращения плоского объекта, полученного с помощью функции flatten, в исходную форму.

Спецификация функции

unflatten(value: <объект>, [separator: <строка>, recursive: <логическое значение>])
:: <объект>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	объект	Массив или объект, которые необходимо преобразовать.		да
`separator`	строка	Разделитель, используемый для разделения ключей.	`.`	нет
`recursive`	логическое значение	Требуется ли рекурсивно преобразовывать значения объекта.	`true`	нет

value

объект

Массив или объект, которые необходимо преобразовать.

да

separator

строка

Разделитель, используемый для разделения ключей.

.

нет

recursive

логическое значение

Требуется ли рекурсивно преобразовывать значения объекта.

true

нет

Характеристики

Игнорирование неконсистентных значений ключей

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

В примере ниже для ключа а есть два возможных значения — число 3 и объект с ключами b и c. При применении функции unflatten числовое значение отбрасывается, сохраняется только объект.

Пример 61. Исходный код

unflatten({
  "a": 3,
  "a.b": 2,
  "a.c": 4
})

Пример 62. Результат

{
  "a": {
    "b": 2,
    "c": 4
  }
}

Примеры

Преобразование во вложенное представление

Пример 63. Исходный код

unflatten({
  "foo.bar.baz": true,
  "foo.bar.qux": false,
  "foo.quux": 42
})

Пример 64. Результат

{
  "foo": {
    "bar": {
      "baz": true,
      "qux": false
    },
    "quux": 42
  }
}

Рекурсивное преобразование во вложенное представление

Пример 65. Исходный код

unflatten({
  "flattened.parent": {
    "foo.bar": true,
    "foo.baz": false
  }
})

Пример 66. Результат

{
  "flattened": {
    "parent": {
      "foo": {
        "bar": true,
        "baz": false
      }
    }
  }
}

Нерекурсивное преобразование во вложенное представление

Пример 67. Исходный код

unflatten({
  "flattened.parent": {
    "foo.bar": true,
    "foo.baz": false
  }
},
recursive: false)

Пример 68. Результат

{
  "flattened": {
    "parent": {
      "foo.bar": true,
      "foo.baz": false
    }
  }
}

merge

Обновляет поля в объекте to на основе содержимого объекта from. При этом:

Поля, которые есть только в одном из объектов, возвращаются в результирующем объекте без изменений.
Если поле существует в обоих объектах, значение из объекта from заменяет значение из объекта to. Чтобы объединить при слиянии вложенные поля, используйте параметр deep=true.

Спецификация функции

merge(to: <объект>, from: <объект>, [deep: <логическое значение>])
:: <объект>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`to`	объект	Объект, в который выполняется слияние.		да
`from`	объект	Объект, из которого выполняется слияние.		да
`deep`	логическое значение	Выполняется глубокое слияние, если `true`, в противном случае слияние происходит только на верхнем уровне.	`false`	нет

to

объект

Объект, в который выполняется слияние.

да

from

объект

Объект, из которого выполняется слияние.

да

deep

логическое значение

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

false

нет

Примеры

Поверхностное слияние объектов

Пример 69. Исходный код

merge(
  {
    "parent1": {
      "child1": 1,
      "child2": 2
    },
    "parent2": {
      "child3": 3
    }
  },
  {
  "parent1": {
    "child2": 4,
    "child5": 5
  }
})

Пример 70. Результат

{
  "parent1": {
    "child2": 4,
    "child5": 5
  },
  "parent2": {
    "child3": 3
  }
}

Глубокое слияние объектов

Пример 71. Исходный код

merge(
  {
    "parent1": {
      "child1": 1,
      "child2": 2
  },
   "parent2": {
     "child3": 3
   }
  },
  {
    "parent1": {
      "child2": 4,
      "child5": 5
    }
  },
deep: true
)

Пример 72. Результат

{
  "parent1": {
    "child1": 1,
    "child2": 4,
    "child5": 5
  },
   "parent2": {
    "child3": 3
  }
}

object_from_array

Создает объект из пар "ключ — значение", итерируя либо единый массив массивов, либо два отдельных массива. Ключи, равные null, игнорируются.

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

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

Спецификация функции

object_from_array(values: <массив>, [keys: <массив>])
:: <объект> , <error>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`values`	массив	Массив значений, или массив входных массивов, если других аргументов не передано.		да
`keys`	массив	Массив ключей. Если аргумент не указан, массивы и ключей, и значений должны быть переданы в первом аргументе.		нет

values

массив

Массив значений, или массив входных массивов, если других аргументов не передано.

да

keys

массив

Массив ключей. Если аргумент не указан, массивы и ключей, и значений должны быть переданы в первом аргументе.

нет

Ошибки

Функция object_from_array может возвращать ошибки, для которых требуется обработка:

values или keys не являются массивами;
values является единственным аргументом и содержит элементы, не являющиеся массивами.

Примеры

Создание объекта из массива массивов

Пример 73. Исходный код

object_from_array([["a", 1], [null, 2], ["b"], ["c", true, 3, 4]])

Пример 74. Результат

{
  "a": 1,
  "b": null,
  "c": true
}

Создание объекта из отдельных массивов ключей и значений

Пример 75. Исходный код

object_from_array([1, 2, 3, 4, 5], keys: ["one", null, "two"])

Пример 76. Результат

{
  "one": 1,
  "two": 3
}

rv_rename_keys

Переименовывает ключи в объекте согласно таблице обогащения.

Спецификация функции

rename_keys(value: <объект>, table: <строка>, from: <строка>, to <строка>, [separator: <строка>, join_separator:  <строка>, case_sensitive: <логическое>])
:: <объект> , <ошибка>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	объект	Объект, в котором нужно переименовать поля.		да
`table`	строка	Таблица обогащения.		да
`from`	строка	Столбец с текущими именами. Строка должна быть представлена литералом, без использования переменных.		да
`to`	строка	Столбец с новыми именами. Строка должна быть представлена литералом, без использования переменных.		да
`separator`	строка	Строка, разделяющая части сложных ключей. Строка должна быть представлена литералом, без использования переменных.		нет
`join_separator`	строка	Строка, соединяющая части сложных ключей после переименования. Если параметр не указан, то используется значение `separator`. Строка должна быть представлена литералом, без использования переменных.		нет
`case_sensitive`	логическое значение	Указывает, будет ли поиск ключей в таблице обогащения регистрозависимым. Значение должно быть представлено литералом `true` или `false`, без использования переменных.	`false`	нет

value

объект

Объект, в котором нужно переименовать поля.

да

table

строка

Таблица обогащения.

да

from

строка

Столбец с текущими именами.

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

да

to

строка

Столбец с новыми именами.

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

да

separator

строка

Строка, разделяющая части сложных ключей.

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

нет

join_separator

строка

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

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

нет

case_sensitive

логическое значение

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

Значение должно быть представлено литералом true или false, без использования переменных.

false

нет

Ошибки

Функция rv_rename_keys может возвращать ошибки, для которых требуется обработка:

Не найдена таблица обогащения.
Таблица не закодирована в UTF-8.
case_sensitive не является логическим значением.
from не является строкой
to не является строкой
separator не является строкой.
join_separator не является строкой.
Указан join_separator без параметра separator.
Не удается разобрать таблицу.

Примеры

Пример 77. Исходный код

rename_keys!(
  { "a/b": 123 },
  table: "table_name",
  from: "from_value",
  to: "to_value",
  separator: "/"
)

Пример 78. Результат

{
  "c/d": 123
}

unnest

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

Присваивание возвращенного массива корневому пути . приведет к созданию нескольких событий из remap.

Спецификация функции

unnest(path: <путь>)
:: <массив> , <ошибка>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`path`	путь	Путь к полю, которое нужно развернуть.		да

path

путь

Путь к полю, которое нужно развернуть.

да

Ошибки

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

Примеры

Развернуть поле

Пример 79. Исходный код

. = {"hostname": "localhost", "events": [{"message": "hello"}, {"message": "world"}]}
. = unnest(.events)

Пример 80. Результат

[
  {
    "events": {
      "message": "hello"
    },
    "hostname": "localhost"
  },
  {
    "events": {
      "message": "world"
    },
    "hostname": "localhost"
  }
]

Развернуть вложенное поле

Пример 81. Исходный код

. = unnest!(.event.messages)

zip

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

Функция аналогична функции zip в Python, а также методам zip в Ruby и Rust.

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

Спецификация функции

zip(array_0: <массив>, [array_1: <массив>])

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`array_0`	массив	Первый массив элементов, или массив входных массивов, если других аргументов не передано.		да
`array_1`	массив	Второй массив элементов. Если аргумент не указан, оба массива должны быть переданы в первом аргументе.		нет

array_0

массив

Первый массив элементов, или массив входных массивов, если других аргументов не передано.

да

array_1

массив

Второй массив элементов. Если аргумент не указан, оба массива должны быть переданы в первом аргументе.

нет

Ошибки

Функция zip может возвращать ошибки, для которых требуется обработка:

array_0 или array_1 не являются массивами;
array_0 является единственным аргументом и содержит элементы, не являющиеся массивами.

Примеры

Слияние двух массивов разной длины

Пример 82. Исходный код

zip([1, 2, 3], [4, 5, 6, 7])

Пример 83. Результат

[[1, 4], [2, 5], [3, 6]]

Слияние трех массивов

Пример 84. Исходный код

zip([[1, 2], [3, 4], [5, 6]])

Пример 85. Результат

[[1, 3, 5], [2, 4, 6]]

Функции действий с отдельными элементами

append

Добавляет каждый элемент из массива items в конец массива value.

Спецификация функции

append(value: <массив>, items: <массив>)
:: <массив>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	массив	Исходный массив		да
`items`	массив	Элементы для добавления		да

value

массив

Исходный массив

да

items

массив

Элементы для добавления

да

Пример

Соединение массивов

Пример 86. Исходный код

append([1, 2], [3, 4])

Пример 87. Результат

[
  1,
  2,
  3,
  4
]

del

Удаляет из цели поле, указанное статическим путем path.

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

Чтобы удалить поле по динамическому пути, используйте функцию remove.

Спецификация функции

del(path: <путь>, [compact: <логическое значение>])
:: <любой тип>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`path`	путь	Путь к удаляемому полю.		да
`compact`	логическое значение	При значении `compact`, равном `true`, после удаления целевого поля функция рекурсивно удаляет родительские поля, вплоть до корневого, если они становятся пустыми.	`false`	нет

path

путь

Путь к удаляемому полю.

да

compact

логическое значение

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

false

нет

Примеры

Удаление поля

Пример 88. Исходный код

del(.field1)

Переименование поля

Пример 89. Исходный код

.new_field = del(.old_field)

exists

Проверяет, существует ли путь в цели.

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

Спецификация функции

exists(path: <путь>)
:: <логическое значение>

Примеры

Проверка существования поля

Пример 90. Исходный код

exists(.field)

Пример 91. Результат

true

Проверка существования элемента массива

Пример 92. Исходный код

exists(.array[2])

Пример 93. Результат

true

get

Динамически получает значение по указанному пути.

Если точный путь известен, используйте выражение пути, такое как .foo.bar[1], чтобы получить значение. Используйте функцию get, если имена сегментов пути не известны заранее.

Спецификация функции

get(value: <объект | массив>, path: <массив>)
:: <любой тип>, <ошибка>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	объект массив	Объект или массив для запроса.		да
`path`	массив	Массив из сегментов пути для поиска значения.		да

value

объект массив

Объект или массив для запроса.

да

path

массив

Массив из сегментов пути для поиска значения.

да

Ошибки

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

Примеры

Поле верхнего уровня с путем из одного сегмента

Пример 94. Исходный код

get!(value: { "foo": "bar" }, path: ["foo"])

Пример 95. Результат

bar

Вложенное поле с путем из нескольких сегментов

Пример 96. Исходный код

get!(value: { "foo": { "bar": "baz" } }, path: ["foo", "bar"])

Пример 97. Результат

baz

Индекс массива

Пример 98. Исходный код

get!(value: ["foo", "bar", "baz"], path: [-2])

Пример 99. Результат

bar

push

Добавляет item в конец массива value.

Спецификация функции

push(value: <массив>, item: <любой тип>)
:: <массив>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	массив	Целевой массив.		да
`item`	любое	Элемент для добавления.		да

value

массив

Целевой массив.

да

item

любое

Элемент для добавления.

да

Примеры

Добавление элемента в массив

Пример 100. Исходный код

push([1, 2], 3)

Пример 101. Результат

[
  1,
  2,
  3
]

Добавление массива в массив

Пример 102. Исходный код

push([1, 2], [3, 4])

Пример 103. Результат

[
  1,
  2,
  [
    3,
    4
  ]
]

remove

Динамически удаляет значение по указанному пути.

Если точный путь известен, используйте более производительную функцию del с выражением пути, таким как .foo.bar[1], чтобы удалить значение. Используйте функцию remove, если имена сегментов пути не известны заранее.

Спецификация функции

remove(value: <объект | массив>, path: <массив>, [compact: <логическое значение>])
:: <объект | массив>, <ошибка>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	По умолчанию	Обязателен
`value`	объект массив	Объект или массив, из которого требуется удалить данные.		да
`path`	массив	Массив сегментов пути для удаления значения.		да
`compact`	логическое значение	При значении `compact`, равном `true`, после удаления целевого поля функция рекурсивно удаляет родительские поля, вплоть до корневого, если они становятся пустыми.	`false`	нет

value

объект массив

Объект или массив, из которого требуется удалить данные.

да

path

массив

Массив сегментов пути для удаления значения.

да

compact

логическое значение

false

нет

Ошибки

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

Примеры

Удаление значения поля верхнего уровня с путем из одного сегмента

Пример 104. Исходный код

remove!(value: { "foo": "bar" }, path: ["foo"])

Пример 105. Результат

{}

Удаление значения вложенного поля с путем из нескольких сегментов

Пример 106. Исходный код

remove!(value: { "foo": { "bar": "baz" } }, path: ["foo", "bar"])

Пример 107. Результат

{
  "foo": {}
}

Удаление по индексу массива

Пример 108. Исходный код

remove!(value: ["foo", "bar", "baz"], path: [-2])

Пример 109. Результат

[
  "foo",
  "baz"
]

Удаление со сжатием

Пример 110. Исходный код

remove!(value: { "foo": { "bar": [42], "baz": true } }, path: ["foo", "bar", 0], compact: true)

Пример 111. Результат

{
  "foo": {
    "baz": true
  }
}

set

Динамически присваивает значение по указанному пути в объекте или массиве.

Если точный путь известен, используйте присваивание по статическому пути, такое как .foo.bar[1] = true. Используйте функцию set, если имена сегментов пути не известны заранее.

Спецификация функции

set(value: <объект | массив>, path: <массив>, data: <любой тип>)
:: <объект | массив>, <ошибка>

Аргумент Тип Описание По умолчанию Обязателен

Аргумент	Тип	Описание	Обязателен
`value`	объект массив	Объект или массив для вставки данных.	да
`path`	массив	Массив сегментов пути для вставки значения.	да
`data`	любое	Вставляемые данные.	да

value

объект массив

Объект или массив для вставки данных.

да

path

массив

Массив сегментов пути для вставки значения.

да

data

любое

Вставляемые данные.

да

Ошибки

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

Примеры

Присвоение значения полю верхнего уровня с путем из одного сегмента

Пример 112. Исходный код

set!(value: { "foo": "bar" }, path: ["foo"], data: "baz")

Пример 113. Результат

{
  "foo": "baz"
}

Присвоение значения вложенному полю с путем из нескольких сегментов

Пример 114. Исходный код

set!(value: { "foo": { "bar": "baz" } }, path: ["foo", "bar"], data: "qux")

Пример 115. Результат

{
  "foo": {
    "bar": "qux"
  }
}

Массив

Пример 116. Исходный код

set!(value: ["foo", "bar", "baz"], path: [-2], data: 42)

Пример 117. Результат

[
  "foo",
  42,
  "baz"
]