Функции кодирования и декодирования

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

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

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

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

Функции декодирования

decode_base16

Декодирует значение (строка в формате Base16) в исходную строку.

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

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

значение

строка

Данные в формате Base16 для декодирования.

да

Ошибки

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

  • значение не является корректной закодированной строкой в формате Base16.

Примеры

Декодирование данных в формате Base16

Example 1. Исходный код
decode_base16!("796f7520686176652073 75636365737366756c6c79206465636f646564206d65")
Example 2. Результат
you have successfully decoded me

decode_base64

Декодирует значение (строка в формате Base64) в исходную строку.

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

decode_base64(значение: <строка>, [charset: <строка>])
:: <строка> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Данные в формате Base64 для декодирования.

да

charset

строка

Набор символов, используемый при декодировании данных:

  • standard — стандартный формат Base64;

  • url_safe — изменённый Base64 для URL.

standard

нет

Ошибки

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

  • значение не является корректной закодированной строкой в формате Base64.

Примеры

Декодирование данных в формате Base64 (по умолчанию)

Example 3. Исходный код
decode_base64!("eW91IGhhdmUgc3VjY2Vzc2Z1bGx5IGRlY29kZWQgbWU=")
Example 4. Результат
you can't make your heart feel something it won't

Декодирование данных в измененном формате Base64 для URL

Example 5. Исходный код
decode_base64!("eW91IGNhbid0IG1ha2UgeW91ciBoZWFydCBmZWVsIHNvbWV0aGluZyBpdCB3b24ndA==", charset: "url_safe")
Example 6. Результат
you can't make your heart feel something it won't

decode_gzip

Декодирует значение (строка в формате Gzip) в исходную строку.

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

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

значение

строка

Данные в формате Gzip для декодирования.

да

Ошибки

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

  • значение не является корректной строкой, закодированной в формате Gzip.

Примеры

Декодирование данных в формате Gzip

Example 7. Исходный код
encoded_text = decode_base64!("H4sIAHEAymMAA6vML1XISCxLVSguTU5OLS5OK83JqVRISU3OT0lNUchNBQD7BGDaIAAAAA==")
decode_gzip!(encoded_text)
Example 8. Результат
you have successfully decoded me

rv_decode_lz4

Декодирует значение как запись, сжатую с помощью алгоритма LZ4.

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

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

значение

строка

Запись, сжатая алгоритмом LZ4.

да

Ошибки

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

  • Не удается декодировать запись как LZ4.

Пример

Example 9. Исходный код
rv_decode_lz4!(decode_base64!("CQAAAJBlbmNvZGVfbWU="))
Example 10. Результат
encode_me

decode_mime_q

Заменяет подстроки закодированных слов в кодировке q или base64 в значение их исходной строкой.

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

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

значение

строка

Закодированная строка с кодировочным словом для декодирования.

да

Ошибки

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

  • значение содержит некорректную закодированную строку с кодировочными словами.

Примеры

Декодирование одиночной с кодировочными словами

Example 11. Исходный код
decode_mime_q!("=?utf-8?b?SGVsbG8sIFdvcmxkIQ==?=")
Example 12. Результат
Hello, World!

Встроенная

Example 13. Исходный код
decode_mime_q!("From: =?utf-8?b?SGVsbG8sIFdvcmxkIQ==?= <=?utf-8?q?hello=5Fworld=40example=2ecom?=>")
Example 14. Результат
From: Hello, World! <hello_world@example.com>

Без указания набора символов

Example 15. Исходный код
decode_mime_q!("?b?SGVsbG8sIFdvcmxkIQ==")
Example 16. Результат
Hello, World!

decode_percent

Декодирует строку значение, закодированную в формате percent, как URL.

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

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

значение

строка

Строка для декодирования.

да

Примеры

Процентное декодирование значения

Example 17. Исходный код
decode_percent("foo%20bar%3F")
Example 18. Результат
foo bar?

decode_punycode

Декодирует строку значение, закодированную в формате punycode, как IDN (интернационализированное доменное имя).

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

decode_punycode(значение: <строка>, [validate: <логическое значение>])
:: <строка>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для декодирования.

да

validate

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

Если true, проверяет, является ли входная строка валидным именем домена.

true

нет

Ошибки

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

  • значение не является корректной строкой punycode.

Примеры

Декодирование интернационализированного доменного имени, закодированного в punycode

Example 19. Исходный код
decode_punycode!("xn--e1afmkfd.xn--80akhbyknj4f")
Example 20. Результат
пример.испытание

Декодирование строки из символов ASCII

Example 21. Исходный код
decode_punycode!("example.com")
Example 22. Результат
example.com

Декодирование без валидации

Example 23. Исходный код
decode_punycode!("xn--8hbb.xn--fiba.xn--8hbf.xn--eib.", validate: false)
Example 24. Результат
١٠.٦٦.٣٠.٥.

decode_snappy

Декодирует значение, представленное в формате Snappy, в исходную строку.

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

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

значение

строка

Данные Snappy для декодирования.

да

Ошибки

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

  • значение не является корректной строкой, закодированной в формате Snappy.

Пример

Example 25. Исходный код
encoded_text = decode_base64!("G2hBIHVzZXIgYWNjb3VudCB3YXMgY3JlYXRlZC4=")
decode_snappy!(encoded_text)
Example 26. Результат
"A user account was created."

decode_zlib

Декодирует значение (строка в формате Zlib) в исходную строку.

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

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

значение

строка

Данные в формате Zlib для декодирования.

да

Ошибки

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

  • значение не является корректной закодированной строкой в формате Zlib.

Примеры

Декодирование данных в формате Zlib

Example 27. Исходный код
encoded_text = decode_base64!("eJwNy4ENwCAIBMCNXIlQ/KqplUSgCdvXAS41qPMHshCB2R1zJlWIVlR6UURX2+wx2YcuK3kAb9C1wd6dn7Fa+QH9gRxr")
decode_zlib!(encoded_text)
Example 28. Результат
you have successfully decoded me

decode_zstd

Декодирует значение (строка в формате Zstandard) в исходную строку.

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

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

значение

строка

Данные в формате Zstandard для декодирования.

да

Ошибки

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

  • значение не является корректной закодированной строкой в формате Zstd.

Примеры

Декодирование данных в формате Zstd

Example 29. Исходный код
encoded_text = decode_base64!("KLUv/QBY/QEAYsQOFKClbQBedqXsb96EWDax/f/F/z+gNU4ZTInaUeAj82KqPFjUzKqhcfDqAIsLvAsnY1bI/N2mHzDixRQA")
decode_zstd!(encoded_text)
Example 30. Результат
you have successfully decoded me

Функции кодирования и сериализации

encode_base16

Кодирует значение в Base16.

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

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

значение

строка

Строка, которую необходимо закодировать.

да

Примеры

Кодирование в Base16

Example 31. Исходный код
encode_base16("please encode me")
Example 32. Результат
706c6561736520656e636f6465206d65

encode_base64

Кодирует значение в Base64.

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

encode_base64(значение: <строка>, [padding: <логическое значение>, charset: <строка>])
:: <строка>
Аргумент Тип Описание По умолчанию Обязателен

vlaue

строка

Строка, которую необходимо закодировать.

да

padding

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

Дополняется ли вывод Base64.

true

нет

charset

строка

Набор символов, используемый при кодировании данных:

  • standard — стандартный формат Base64;

  • url_safe — изменённый Base64 для URL.

standard

нет

Примеры

Кодирование в Base64 (по умолчанию)

Example 33. Исходный код
encode_base64("please encode me")
Example 34. Результат
cGxlYXNlIGVuY29kZSBtZQ==

Кодирование в Base64 (без дополнения)

Example 35. Исходный код
encode_base64("please encode me, no padding though", padding: false)
Example 36. Результат
cGxlYXNlIGVuY29kZSBtZSwgbm8gcGFkZGluZyB0aG91Z2g

Кодирование в измененный Base64 для URL

Example 37. Исходный код
encode_base64("please encode me, but safe for URLs", charset: "url_safe")
Example 38. Результат
cGxlYXNlIGVuY29kZSBtZSwgYnV0IHNhZmUgZm9yIFVSTHM=

encode_gzip

Кодирует значение в формат Gzip.

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

encode_gzip(значение: <строка>, [compression_level: <целое число>])
:: <строка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка, которую необходимо закодировать.

да

compression_level

целое значение

Уровень сжатия по умолчанию.

6

нет

Примеры

Кодирование в Gzip

Example 39. Исходный код
encoded_text = encode_gzip("please encode me")
encode_base64(encoded_text)
Example 40. Результат
H4sIAAAAAAAA/yvISU0sTlVIzUvOT0lVyE0FAI4R4vcQAAAA

encode_json

Кодирует значение в JSON.

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

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

значение

любое

Значение, которое необходимо преобразовать в JSON-строку.

да

Примеры

Кодирование в JSON

Example 41. Исходный код
.payload = encode_json({"hello": "world"})
Example 42. Результат
{"hello":"world"}

encode_key_value

Кодирует значение в формат "ключ — значение" с настраиваемыми разделителями. По умолчанию используются разделители, соответствующие формату logfmt.

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

encode_key_value(значение: <объект>, [fields_ordering: <массив>, key_value_delimiter: <строка>, field_delimiter: <строка>, flatten_boolean: <логическое значение>])
:: <строка>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

объект

Значение, которое необходимо преобразовать в строку.

да

fields_ordering

массив

Упорядочивание полей для сохранения порядка. Любые поля, отсутствующие в этом списке, будут отображаться неупорядоченными, после всех упорядоченных полей.

нет

key_value_delimiter

строка

Строка, разделяющая ключ и значение.

=

нет

field_delimiter

строка

Строка, разделяющая каждую пару "ключ значение".

(пробел)

нет

flatten_boolean

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

Указывает, следует ли кодировать "ключ — значение" с логическим значением как отдельный ключ.

false

нет

Примечания

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

  • Если указан fields_ordering, функция может возвращать ошибку, иначе она ошибки не возвращает.

Ошибки

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

  • В fields_ordering содержится элемент, не являющийся строкой.

Примеры

Кодирование с разделителями по умолчанию (без упорядочивания)

Example 43. Исходный код
encode_key_value({"ts": "2021-06-05T17:20:00Z", "msg": "This is a message", "lvl": "info"})
Example 44. Результат
lvl=info msg="This is a message" ts=2021-06-05T17:20:00Z

Кодирование с разделителями по умолчанию (с упорядочиванием полей)

Example 45. Исходный код
encode_key_value!({"ts": "2021-06-05T17:20:00Z", "msg": "This is a message", "lvl": "info", "log_id": 12345}, ["ts", "lvl", "msg"])
Example 46. Результат
ts=2021-06-05T17:20:00Z lvl=info msg="This is a message" log_id=12345

Кодирование с разделителями по умолчанию (вложенные поля)

Example 47. Исходный код
encode_key_value({"agent": {"name": "vector"}, "log": {"file": {"path": "my.log"}}, "event": "log"})
Example 48. Результат
agent.name=vector event=log log.file.path=my.log

Кодирование с разделителями по умолчанию (вложенные поля с упорядочиванием)

Example 49. Исходный код
encode_key_value!({"agent": {"name": "vector"}, "log": {"file": {"path": "my.log"}}, "event": "log"}, ["event", "log.file.path", "agent.name"])
Example 50. Результат
event=log log.file.path=my.log agent.name=vector

Кодирование с пользовательскими разделителями (без упорядочивания)

Example 51. Исходный код
encode_key_value(
{"ts": "2021-06-05T17:20:00Z", "msg": "This is a message", "lvl": "info"},
field_delimiter: ",",
key_value_delimiter: ":"
)
Example 52. Результат
lvl:info,msg:"This is a message",ts:2021-06-05T17:20:00Z

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

Example 53. Исходный код
encode_key_value(
{"ts": "2021-06-05T17:20:00Z", "msg": "This is a message", "lvl": "info", "beta": true, "dropped": false},
field_delimiter: ",",
key_value_delimiter: ":",
flatten_boolean: true
)
Example 54. Результат
beta,lvl:info,msg:"This is a message",ts:2021-06-05T17:20:00Z

encode_logfmt

Кодирует значение в формат logfmt.

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

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

значение

объект

Значение, которое необходимо преобразовать в строку в формате logfmt.

да

fields_ordering

массив

Упорядочивание полей для сохранения порядка. Любые поля, отсутствующие в этом списке, будут отображаться неупорядоченными, после всех упорядоченных полей.

нет

Примечания

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

  • Если указан fields_ordering, функция может возвращать ошибку, иначе она ошибки не возвращает.

Ошибки

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

  • В fields_ordering содержится элемент, не являющийся строкой.

Примеры

Кодирование в формат logfmt (без упорядочивания)

Example 55. Исходный код
encode_logfmt({"ts": "2021-06-05T17:20:00Z", "msg": "This is a message", "lvl": "info"})
Example 56. Результат
lvl=info msg="This is a message" ts=2021-06-05T17:20:00Z

Кодирование в формат logfmt (с упорядочиванием полей)

Example 57. Исходный код
encode_logfmt!({"ts": "2021-06-05T17:20:00Z", "msg": "This is a message", "lvl": "info", "log_id": 12345}, ["ts", "lvl", "msg"])
Example 58. Результат
ts=2021-06-05T17:20:00Z lvl=info msg="This is a message" log_id=12345

Кодирование в формат logfmt (вложенные поля)

Example 59. Исходный код
encode_logfmt({"agent": {"name": "vector"}, "log": {"file": {"path": "my.log"}}, "event": "log"})
Example 60. Результат
agent.name=vector event=log log.file.path=my.log

Кодирование в формат logfmt (вложенные поля с упорядочиванием)

Example 61. Исходный код
encode_logfmt!({"agent": {"name": "vector"}, "log": {"file": {"path": "my.log"}}, "event": "log"}, ["event", "log.file.path", "agent.name"])
Example 62. Результат
event=log log.file.path=my.log agent.name=vector

encode_percent

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

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

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

значение

строка

Строка, которую необходимо преобразовать.

да

ascii_set

строка

Набор символов ASCII, используемый при преобразовании данных.

NON_ALPHANUMERIC

нет

Примеры

Процентное кодирование всех символов, не являющихся буквенно-цифровыми (по умолчанию)

Example 63. Исходный код
encode_percent("foo bar?")
Example 64. Результат
foo%20bar%3F

Процентное кодирование только управляющих символов

Example 65. Исходный код
encode_percent("foo bar", ascii_set: "CONTROLS")
Example 66. Результат
foo %09bar

encode_proto

Кодирует значение в payload — полезную нагрузку Protocol Buffers.

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

encode_proto(значение: <объект>, файл_дескрипторов: <строка>, тип_сообщения: <строка>)
:: <строка>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

объект

Объект для преобразования в payload Protocol Buffers.

да

файл_дескрипторов

строка

Путь к файлу набора дескрипторов Protocol Buffers. Должен быть строковым литерал. Этот файл является результатом работы команды protoc -o.

да

тип_сообщения

строка

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

да

Ошибки

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

  • Файл, указанный в аргументе файл_дескрипторов, не существует.

  • Тип сообщения, указанный в аргументе тип_сообщения, отсутствует в файле дескрипторов.

Пример

Example 67. Исходный код
.payload = encode_base64(encode_proto!({"name": "someone", "phones": [{"number": "123456"}]}, "resources/protobuf_descriptor_set.desc", "test_protobuf.Person"))
Example 68. Результат
Cgdzb21lb25lIggKBjEyMzQ1Ng==

encode_punycode

Кодирует значение в формат punycode. Полезно для IDN.

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

encode_punycode(значение: <строка>, [validate: <логическое значение>])
:: <строка>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для кодирования.

да

validate

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

Проверять ли, что входная строка является валидным именем домена.

true

нет

Ошибки

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

  • значение нельзя закодировать в punycode.

Примеры

Кодирование интернационализированного доменного имени

Example 69. Исходный код
encode_punycode!("пример.испытание")
Example 70. Результат
xn--e1afmkfd.xn--80akhbyknj4f

Кодирование интернационализированного доменного имени в смешанном регистре

Example 71. Исходный код
encode_punycode!("пРИМер.испытание")
Example 72. Результат
xn--e1afmkfd.xn--80akhbyknj4f

Кодирование строки из символов ASCII

Example 73. Исходный код
encode_punycode!("example.com")
Example 74. Результат
example.com

Кодирование без валидации

Example 75. Исходный код
encode_punycode!("xn--8hbb.xn--fiba.xn--8hbf.xn--eib.", validate: false)
Example 76. Результат
xn--8hbb.xn--fiba.xn--8hbf.xn--eib.

encode_snappy

Кодирует значение в формат Snappy.

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

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

значение

строка

Строка для кодирования.

да

Ошибки

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

  • значение нельзя закодировать в формат Snappy.

Пример

Example 77. Исходный код
encoded_text = encode_snappy!("A user account was created.")
encode_base64(encoded_text)
Example 78. Результат
G2hBIHVzZXIgYWNjb3VudCB3YXMgY3JlYXRlZC4=

encode_zlib

Кодирует значение в формат Zlib.

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

encode_zlib(значение: <строка>, [compression_level: <целое число>])
:: <строка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка, которую необходимо закодировать.

да

compression_level

целое число

Уровень сжатия по умолчанию.

6

нет

Примеры

Кодирование в формат Zlib

Example 79. Исходный код
encoded_text = encode_zlib("please encode me")
encode_base64(encoded_text)
Example 80. Результат
eJwryElNLE5VSM1Lzk9JVchNBQA0RQX7

encode_zstd

Кодирует значение в формат Zstandard.

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

encode_zstd(значение: <строка>, [compression_level: <целое число>])
:: <строка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка, которую необходимо закодировать.

да

compression_level

целое число

Уровень сжатия по умолчанию.

3

нет

Примеры

Кодирование в формат Zstandard

Example 81. Исходный код
encoded_text = encode_zstd("please encode me")
encode_base64(encoded_text)
Example 82. Результат
KLUv/QBYgQAAcGxlYXNlIGVuY29kZSBtZQ==