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

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

  • Типы значений, которые принимает аргумент, указаны в угловых скобках.

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

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

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

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

includes

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

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

includes(value: <массив>, element: <любой тип>)
:: <логическое значение>
Аргумент Тип Описание По умолчанию Обязателен

value

массив

Массив.

да

element

любое

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

да

Примеры

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

Пример 1. Исходный код
includes(["apple", "orange", "banana"], "banana")
Пример 2. Результат
true

keys

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

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

keys(value: <объект>)
:: <массив>
Аргумент Тип Описание По умолчанию Обязателен

value

объект

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

да

Примеры

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

Пример 3. Исходный код
keys({"key1": "val1", "key2": "val2"})
Пример 4. Результат
[
  "key1",
  "key2"
]

length

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

  • для массива возвращает количество элементов;

  • для объекта возвращает количество ключей на верхнем уровне;

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

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

length(value: <массив | объект | строка>)
:: <целое число>
Аргумент Тип Описание По умолчанию Обязателен

value

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

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

да

Примеры

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

Пример 5. Исходный код
length({
  "portland": "Trail Blazers",
  "seattle": "Supersonics"
})
Пример 6. Результат
2

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

Пример 7. Исходный код
length({
  "home": {
    "city": "Portland",
    "state": "Oregon"
  },
  "name": "Trail Blazers",
  "mascot": {
    "name": "Blaze the Trail Cat"
  }
})
Пример 8. Результат
3

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

Пример 9. Исходный код
length(["Trail Blazers", "Supersonics", "Grizzlies"])
Пример 10. Результат
3

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

Пример 11. Исходный код
length("The Planet of the Apes Musical")
Пример 12. Результат
30

values

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

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

values(value: <объект>)
:: <массив>
Аргумент Тип Описание По умолчанию Обязателен

value

объект

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

да

Примеры

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

Пример 13. Исходный код
values({"key1": "val1", "key2": "val2"})
Пример 14. Результат
[
  "val1",
  "val2"
]
Чтобы получить срез массива, используйте функцию slice.

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

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

нет

Примеры

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

Пример 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

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

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

да

Примеры

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

Пример 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"

да

Ошибки

Функция 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

массив

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

да

Примеры

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

Пример 27. Исходный код
unique(["foo", "bar", "foo", "baz"])
Пример 28. Результат
[
  "foo",
  "bar",
  "baz"
]

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

all

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

  • в вертикальные черты заключены аргументы — ключ (для объектов) или индекс (для массивов) и значение элемента;

  • в фигурных скобках указано собственно условие. В условии можно изменять внешние переменные.

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

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

all(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

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

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

да

Примеры

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

Пример 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

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

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

да

Примеры

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

Пример 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. Для каждого вложенного объекта:

    • Сначала возвращается ключ самого объекта.

    • Затем происходит рекурсивный вызов функции для объекта, и происходит возврат к пункту 1 в этом списке.

    • Любые изменения, сделанные во вложенном объекте до его рекурсивного вызова, сохраняются.

  3. Для каждого вложенного массива:

    • Сначала возвращается ключ самого массива.

    • Затем происходит поиск всех объектов внутри массива и применение к каждому из них правил из пункта 2.

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

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

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

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

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

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. Итерация начинается с корневой коллекции.

  2. Для каждой вложенной коллекции:

    • Сначала возвращается сам тип коллекции.

    • Затем происходит рекурсивный вызов функции для коллекции, и происходит возврат к пункту 1 в этом списке.

    • Любые изменения, сделанные в коллекции до ее рекурсивного вызова, сохраняются.

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

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

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

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

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

да

Примеры

Запрос 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
Чтобы объединить все элементы массива в одну строку, используйте функцию join.

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

chunks

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

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

chunks(value: <массив | строка>, chunk_size: <целое число>)
:: <массив> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

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

строка

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

.

нет

Примеры

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

Пример 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

нет

Примеры

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

Пример 61. Исходный код
unflatten({
  "foo.bar.baz": true,
  "foo.bar.qux": false,
  "foo.quux": 42
})
Пример 62. Результат
{
  "foo": {
    "bar": {
      "baz": true,
      "qux": false
    },
    "quux": 42
  }
}

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

Пример 63. Исходный код
unflatten({
  "flattened.parent": {
    "foo.bar": true,
    "foo.baz": false
  }
})
Пример 64. Результат
{
  "flattened": {
    "parent": {
      "foo": {
        "bar": true,
        "baz": false
      }
    }
  }
}

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

Пример 65. Исходный код
unflatten({
  "flattened.parent": {
    "foo.bar": true,
    "foo.baz": false
  }
},
recursive: false)
Пример 66. Результат
{
  "flattened": {
    "parent": {
      "foo.bar": true,
      "foo.baz": false
    }
  }
}

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

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

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

Пример 67. Исходный код
unflatten({
  "a": 3,
  "a.b": 2,
  "a.c": 4
})
Пример 68. Результат
{
  "a": {
    "b": 2,
    "c": 4
  }
}

merge

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

  • Поля, которые есть только в одном из объектов, возвращаются в результирующем объекте без изменений.

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

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

merge(to: <объект>, from: <объект>, [deep: <логическое значение>])
:: <объект>
Аргумент Тип Описание По умолчанию Обязателен

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
  }
}

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

нет

Ошибки

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

  • Не найдена таблица обогащения.

  • Таблица не закодирована в UTF-8.

  • case_sensitive не является логическим значением.

  • from не является строкой

  • to не является строкой

  • separator не является строкой.

  • join_separator не является строкой.

  • Указан join_separator без параметра separator.

  • Не удается разобрать таблицу.

Примеры

Пример 73. Исходный код
rename_keys!(
  { "a/b": 123 },
  table: "table_name",
  from: "from_value",
  to: "to_value",
  separator: "/"
)
Пример 74. Результат
{
  "c/d": 123
}

unnest

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

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

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

unnest(path: <путь>)
:: <массив> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

path

путь

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

да

Ошибки

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

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

Примеры

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

Пример 75. Исходный код
. = {"hostname": "localhost", "events": [{"message": "hello"}, {"message": "world"}]}
. = unnest(.events)
Пример 76. Результат
[
  {
    "events": {
      "message": "hello"
    },
    "hostname": "localhost"
  },
  {
    "events": {
      "message": "world"
    },
    "hostname": "localhost"
  }
]

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

Пример 77. Исходный код
. = unnest!(.event.messages)

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

append

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

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

append(value: <массив>, items: <массив>)
:: <массив>
Аргумент Тип Описание По умолчанию Обязателен

value

массив

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

да

items

массив

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

да

Примеры

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

Пример 78. Исходный код
append([1, 2], [3, 4])
Пример 79. Результат
[
  1,
  2,
  3,
  4
]

del

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

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

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

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

path

путь

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

да

compact

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

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

false

нет

Примечания

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

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

Примеры

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

Пример 80. Исходный код
del(.field1)

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

Пример 81. Исходный код
.new_field = del(.old_field)

exists

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

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

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

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

Примеры

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

Пример 82. Исходный код
exists(.field)
Пример 83. Результат
true

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

Пример 84. Исходный код
exists(.array[2])
Пример 85. Результат
true

get

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

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

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

get(value: <объект | массив>, path: <массив>)
:: <любой тип>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

value

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

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

да

path

массив

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

да

Ошибки

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

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

Примеры

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

Пример 86. Исходный код
get!(value: { "foo": "bar" }, path: ["foo"])
Пример 87. Результат
bar

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

Пример 88. Исходный код
get!(value: { "foo": { "bar": "baz" } }, path: ["foo", "bar"])
Пример 89. Результат
baz

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

Пример 90. Исходный код
get!(value: ["foo", "bar", "baz"], path: [-2])
Пример 91. Результат
bar

push

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

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

push(value: <массив>, item: <любой тип>)
:: <массив>
Аргумент Тип Описание По умолчанию Обязателен

value

массив

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

да

item

любое

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

да

Примеры

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

Пример 92. Исходный код
push([1, 2], 3)
Пример 93. Результат
[
  1,
  2,
  3
]

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

Пример 94. Исходный код
push([1, 2], [3, 4])
Пример 95. Результат
[
  1,
  2,
  [
    3,
    4
  ]
]

remove

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

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

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

remove(value: <объект | массив>, path: <массив>, [compact: <логическое значение>])
:: <объект | массив>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

value

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

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

да

path

массив

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

да

compact

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

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

false

нет

Ошибки

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

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

Примеры

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

Пример 96. Исходный код
remove!(value: { "foo": "bar" }, path: ["foo"])
Пример 97. Результат
{}

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

Пример 98. Исходный код
remove!(value: { "foo": { "bar": "baz" } }, path: ["foo", "bar"])
Пример 99. Результат
{
  "foo": {}
}

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

Пример 100. Исходный код
remove!(value: ["foo", "bar", "baz"], path: [-2])
Пример 101. Результат
[
  "foo",
  "baz"
]

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

Пример 102. Исходный код
remove!(value: { "foo": { "bar": [42], "baz": true } }, path: ["foo", "bar", 0], compact: true)
Пример 103. Результат
{
  "foo": {
    "baz": true
  }
}

set

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

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

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

set(value: <объект | массив>, path: <массив>, data: <любой тип>)
:: <объект | массив>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

value

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

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

да

path

массив

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

да

data

любое

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

да

Ошибки

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

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

Примеры

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

Пример 104. Исходный код
set!(value: { "foo": "bar" }, path: ["foo"], data: "baz")
Пример 105. Результат
{
  "foo": "baz"
}

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

Пример 106. Исходный код
set!(value: { "foo": { "bar": "baz" } }, path: ["foo", "bar"], data: "qux")
Пример 107. Результат
{
  "foo": {
    "bar": "qux"
  }
}

Массив

Пример 108. Исходный код
set!(value: ["foo", "bar", "baz"], path: [-2], data: 42)
Пример 109. Результат
[
  "foo",
  42,
  "baz"
]
+7 (499) 322 80 40 sales@rvision.ru

О компании Политика конфиденциальности Пользовательское соглашение