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

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

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

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

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

includes

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

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

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

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

значение

массив

Массив.

да

элемент

любое

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

да

Примеры

Массив включает

Example 1. Исходный код

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

Example 2. Результат

true

keys

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

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

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

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

значение

объект

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

да

Примеры

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

Example 3. Исходный код

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

Example 4. Результат

[
"key1",
"key2"
]

length

Возвращает длину значение.

Если значение — это массив, возвращает количество элементов.
Если значение — это объект, возвращает количество ключей на верхнем уровне.
Если значение — это строка, возвращает количество байтов в строке. Если вам нужно количество символов, см. strlen.

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

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

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

значение

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

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

да

Примеры

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

Example 5. Исходный код

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

Example 6. Результат

Длина (вложенный объект)

Example 7. Исходный код

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

Example 8. Результат

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

Example 9. Исходный код

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

Example 10. Результат

Длина (строка)

Example 11. Исходный код

length("The Planet of the Apes Musical")

Example 12. Результат

values

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

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

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

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

значение

объект

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

да

Примеры

Получить значения из объекта.

Example 13. Исходный код

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

Example 14. Результат

[
"val1",
"val2"
]

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

compact

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

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

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

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

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

значение

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

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

да

recursive

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

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

true

нет

null

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

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

true

нет

string

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

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

true

нет

объект

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

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

true

нет

array

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

Должен ли пустой массив рассматриваться как пустое значение.

true

нет

nullish

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

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

false

нет

Примеры

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

Example 15. Исходный код

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

Example 16. Результат

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

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

Example 17. Исходный код

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

Example 18. Результат

{
"field1": 1
}

filter

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

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

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

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

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

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

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

значение

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

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

да

Примеры

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

Example 19. Исходный код

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

Example 20. Результат

[
"bar",
"baz"
]

rv_coalesce_nullish

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

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

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

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

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

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

значение

массив

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

да

Ошибки

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

Значение не является массивом

Примеры

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

Example 21. Исходный код

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

Example 22. Результат

"test"

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

Example 23. Исходный код

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

Example 24. Результат

"123132"

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

Example 25. Исходный код

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

Example 26. Результат

null

unique

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

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

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

unique(значение: <массив>)
:: <массив>

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

значение

массив

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

да

Примеры

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

Example 27. Исходный код

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

Example 28. Результат

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

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

all

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

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

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

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

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

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

значение

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

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

да

Примеры

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

Example 29. Исходный код

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

Example 30. Результат

true

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

Example 31. Исходный код

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

Example 32. Результат

true

any

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

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

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

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

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

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

значение

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

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

да

Примеры

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

Example 33. Исходный код

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

Example 34. Результат

true

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

Example 35. Исходный код

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

Example 36. Результат

true

for_each

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

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

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

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

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

значение

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

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

да

Примеры

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

Example 37. Исходный код

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


# Увеличение подсчета для значения на `1`.
tally = set!(tally, [value], count + 1)
}


tally

Example 38. Результат

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

map_keys

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

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

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

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

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

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

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

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

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

значение

объект

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

да

recursive

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

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

false

нет

Примеры

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

Example 39. Исходный код

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

Example 40. Результат

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

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

Example 41. Исходный код

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

Example 42. Результат

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

map_values

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

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

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

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

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

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

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

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

значение

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

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

да

recursive

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

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

false

нет

Примеры

Преобразование значений в верхний регистр

Example 43. Исходный код

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

Example 44. Результат

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

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

chunks

Разбивает значение на части длиной размер_фрагмента в байтах.

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

chunks(значение: <массив | строка>, размер_фрагмента: <целое число>)
:: <массив> , <ошибка>

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

значение

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

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

да

размер_фрагмента

целое число

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

да

Ошибки

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

размер_фрагмента менее 1 байта.
размер_фрагмента слишком велик.

Примеры

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

Example 45. Исходный код

chunks("abcdefgh", 4)

Example 46. Результат

[
"abcd",
"efgh"
]

Фрагменты не соблюдают границы кодовой точки Unicode

Example 47. Исходный код

chunks("ab你好", 4)

Example 48. Результат

[
"ab�",
"�好"
]

flatten

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

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

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

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

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

значение

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

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

да

separator

строка

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

.

нет

Примеры

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

Example 49. Исходный код

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

Example 50. Результат

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

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

Example 51. Исходный код

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

Example 52. Результат

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

merge

Сливает объект from в объект to.

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

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

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

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

от

объект

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

да

до

объект

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

да

deep

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

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

false

нет

Примеры

Слияние объектов (поверхностное)

Example 53. Исходный код

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

Example 54. Результат

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

Слияние объектов (глубокое)

Example 55. Исходный код

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

Example 56. Результат

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

rv_rename_keys

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

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

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

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

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

значение

объект

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

да

table

строка

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

да

from

строка

Колонка с текущими именами.

да

строка

Колонка с новыми именами.

да

separator

строка

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

нет

join_separator

строка

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

нет

case_sensitive

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

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

false

нет

Ошибки

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

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

Примеры

Example 57. Исходный код

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

Example 58. Результат

{ "c/d": 123 }

unnest

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

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

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

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

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

путь

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

да

Ошибки

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

Поле, на которое ссылается путь, не является массивом.

Примеры

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

Example 59. Исходный код

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

Example 60. Результат

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

Раскроить вложенное поле

Example 61. Исходный код

. = unnest!(.event.messages)

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

append

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

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

append(значение: <массив>, элементы: <массив>)
:: <массив>

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

значение

массив

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

да

элементы

массив

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

да

Примеры

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

Example 62. Исходный код

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

Example 63. Результат

[
1,
2,
3,
4
]

del

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

Для удаления динамического пути см. функцию remove.

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

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

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

Аргумент	Тип	Описание	По умолчанию	Обязателен
путь	путь	Путь к удаляемому полю.		да
compact	логическое значение	Если `compact` установлен в true, после удаления, если остался пустой объект или массив, он также должен быть удален, рекурсивно вплоть до корневого элемента. Это применяется только к удаляемому пути и любым родительским путям.	`false`	нет

путь

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

да

compact

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

Если compact установлен в true, после удаления, если остался пустой объект или массив, он также должен быть удален, рекурсивно вплоть до корневого элемента. Это применяется только к удаляемому пути и любым родительским путям.

false

нет

Примечания

У этой функции есть особое поведение, о котором стоит знать:

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

Примеры

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

Example 64. Исходный код

del(.field1)

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

Example 65. Исходный код

.new_field = del(.old_field)

exists

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

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

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

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

Примеры

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

Example 66. Исходный код

exists(.field)

Example 67. Результат

true

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

Example 68. Исходный код

exists(.array[2])

Example 69. Результат

true

get

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

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

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

get(значение: <объект | массив>, путь: <массив>)
:: <любой тип>, <ошибка>

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

значение

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

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

да

path

массив

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

да

Ошибки

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

Сегмент пути должен быть либо "строкой", либо "целым числом".

Примеры

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

Example 70. Исходный код

get!(значение: { "foo": "bar" }, path: ["foo"])

Example 71. Результат

bar

Вложенное поле с несколькими сегментами

Example 72. Исходный код

get!(значение: { "foo": { "bar": "baz" } }, path: ["foo", "bar"])

Example 73. Результат

baz

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

Example 74. Исходный код

get!(значение: ["foo", "bar", "baz"], path: [-2])

Example 75. Результат

bar

push

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

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

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

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

значение

массив

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

да

item

любое

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

да

Примеры

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

Example 76. Исходный код

push([1, 2], 3)

Example 77. Результат

[
1,
2,
3
]

remove

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

Когда вы знаете путь, который хотите удалить, используйте функцию del и статические пути, такие как del(.foo.bar[1]), чтобы удалить значение по этому пути. Функция del возвращает удаленное значение и является более производительной, чем эта функция. Однако, когда вы не знаете заранее имена путей, вы можете использовать эту динамическую функцию для удаления значения по указанному пути.

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

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

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

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

значение

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

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

да

path

массив

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

да

compact

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

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

false

нет

Ошибки

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

сегмент пути должен быть либо "строкой", либо "целым числом"

Примеры

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

Example 78. Исходный код

remove!(значение: { "foo": "bar" }, path: ["foo"])

Example 79. Результат

{}

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

Example 80. Исходный код

remove!(значение: { "foo": { "bar": "baz" } }, path: ["foo", "bar"])

Example 81. Результат

{
"foo": {}
}

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

Example 82. Исходный код

remove!(значение: ["foo", "bar", "baz"], path: [-2])

Example 83. Результат

[
"foo",
"baz"
]

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

Example 84. Исходный код

remove!(значение: { "foo": { "bar": [42], "baz": true } }, path: ["foo", "bar", 0], compact: true)

Example 85. Результат

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

set

Динамически вставляет данные в указанный путь объекта или массива.

Когда вы знаете путь, которому хотите присвоить значение, следует использовать статические пути, такие как .foo.bar[1] = true, для улучшения производительности и читаемости. Однако, когда вы не знаете заранее имена путей, вы можете использовать эту динамическую функцию вставки для вставки данных в объект или массив.

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

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

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

Аргумент

Тип

Описание

По умолчанию

Обязателен

value

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

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

да

path

массив

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

да

data

любое

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

да

Ошибки

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

сегмент пути должен быть либо "строкой", либо "целым числом"

Примеры

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

Example 86. Исходный код

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

Example 87. Результат

{
"foo": "baz"
}

Вставка значения в многосегментное вложенное поле

Example 88. Исходный код

set!(значение: { "foo": { "bar": "baz" } }, path: ["foo", "bar"], data: "qux")

Example 89. Результат

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

Массив

Example 90. Исходный код

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

Example 91. Результат

[
"foo",
42,
"baz"
]