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

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

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

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

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

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

decode_base16

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

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

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

value

строка

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

да

Ошибки

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

Пример

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

Пример 1. Исходный код
decode_base16!("796f752068617665207375636365737366756c6c79206465636f646564206d65")
Пример 2. Результат
"you have successfully decoded me"

decode_base64

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

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

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

value

строка

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

да

charset

строка

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

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

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

standard

нет

Ошибки

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

Примеры

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

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

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

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

decode_charset

Преобразует строку, закодированную не в UTF-8, в строку UTF-8, используя заданную кодировку.

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

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

value

строка

Строка не в UTF-8, которую нужно декодировать.

да

from_charset

строка

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

да

Ошибки

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

Примеры

Декодирование строки в кодировке EUC-KR

Пример 7. Исходный код
decode_charset!(decode_base64!("vsiz58fPvLy/5A=="), "euc-kr")
Пример 8. Результат
"안녕하세요"

Декодирование строки в кодировке EUC-JP

Пример 9. Исходный код
decode_charset!(decode_base64!("pLOk86TLpMGkzw=="), "euc-jp")
Пример 10. Результат
"こんにちは"

Декодирование строки в кодировке GB2312

Пример 11. Исходный код
decode_charset!(decode_base64!("xOO6ww=="), "gb2312")
Пример 12. Результат
"你好"

decode_gzip

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

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

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

value

строка

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

да

Ошибки

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

Пример

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

Пример 13. Исходный код
encoded_text = decode_base64!("H4sIAHEAymMAA6vML1XISCxLVSguTU5OLS5OK83JqVRISU3OT0lNUchNBQD7BGDaIAAAAA==")
decode_gzip!(encoded_text)
Пример 14. Результат
you have successfully decoded me

rv_decode_lz4

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

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

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

value

строка

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

да

Ошибки

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

Пример

Пример 15. Исходный код
rv_decode_lz4!(decode_base64!("CQAAAJBlbmNvZGVfbWU="))
Пример 16. Результат
"encode_me"

decode_mime_q

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

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

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

value

строка

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

да

Ошибки

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

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

Примеры

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

Пример 17. Исходный код
decode_mime_q!("=?utf-8?b?SGVsbG8sIFdvcmxkIQ==?=")
Пример 18. Результат
"Hello, World!"

Встроенная

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

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

Пример 21. Исходный код
decode_mime_q!("?b?SGVsbG8sIFdvcmxkIQ==")
Пример 22. Результат
"Hello, World!"

decode_percent

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

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

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

value

строка

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

да

Пример

Декодирование строки в процентном кодировании

Пример 23. Исходный код
decode_percent("foo%20bar%3F")
Пример 24. Результат
"foo bar?"

decode_punycode

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

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

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

value

строка

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

да

validate

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

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

true

нет

Ошибки

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

Примеры

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

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

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

Пример 27. Исходный код
decode_punycode!("example.com")
Пример 28. Результат
"example.com"

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

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

decode_snappy

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

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

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

value

строка

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

да

Ошибки

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

Пример

Пример 31. Исходный код
encoded_text = decode_base64!("G2hBIHVzZXIgYWNjb3VudCB3YXMgY3JlYXRlZC4=")
decode_snappy!(encoded_text)
Пример 32. Результат
"A user account was created."

decode_zlib

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

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

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

value

строка

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

да

Ошибки

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

Пример

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

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

decode_zstd

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

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

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

value

строка

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

да

Ошибки

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

Пример

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

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

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

encode_base16

Кодирует value в Base16.

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

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

value

строка

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

да

Пример

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

Пример 37. Исходный код
encode_base16("please encode me")
Пример 38. Результат
"706c6561736520656e636f6465206d65"

encode_base64

Кодирует value в Base64.

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

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

value

строка

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

да

padding

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

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

true

нет

charset

строка

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

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

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

standard

нет

Примеры

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

Пример 39. Исходный код
encode_base64("please encode me")
Пример 40. Результат
"cGxlYXNlIGVuY29kZSBtZQ=="

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

Пример 41. Исходный код
encode_base64("please encode me, no padding though", padding: false)
Пример 42. Результат
"cGxlYXNlIGVuY29kZSBtZSwgbm8gcGFkZGluZyB0aG91Z2g"

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

Пример 43. Исходный код
encode_base64("please encode me, but safe for URLs", charset: "url_safe")
Пример 44. Результат
"cGxlYXNlIGVuY29kZSBtZSwgYnV0IHNhZmUgZm9yIFVSTHM="

encode_charset

Преобразует строку, закодированную в UTF-8, в строку заданной кодировки.

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

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

value

строка

Строка в UTF-8, которую нужно кодировать.

да

to_charset

строка

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

да

Ошибки

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

Примеры

Кодирование строки UTF-8 в EUC-KR

Пример 45. Исходный код
encode_base64(encode_charset!("안녕하세요", "euc-kr"))
Пример 46. Результат
"vsiz58fPvLy/5A=="

Кодирование строки UTF8 в EUC-JP

Пример 47. Исходный код
encode_base64(encode_charset!("こんにちは", "euc-jp"))
Пример 48. Результат
"pLOk86TLpMGkzw=="

Кодирование строки UTF-8 в GB2312

Пример 49. Исходный код
encode_base64(encode_charset!("你好", "gb2312"))
Пример 50. Результат
"xOO6ww=="

encode_gzip

Кодирует value в формат Gzip.

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

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

value

строка

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

да

compression_level

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

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

6

нет

Примеры

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

Пример 51. Исходный код
encoded_text = encode_gzip("please encode me")
encode_base64(encoded_text)
Пример 52. Результат
"H4sIAAAAAAAA/yvISU0sTlVIzUvOT0lVyE0FAI4R4vcQAAAA"

encode_percent

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

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

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

value

строка

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

да

ascii_set

строка

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

NON_ALPHANUMERIC

нет

Примеры

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

Пример 53. Исходный код
encode_percent("foo bar?")
Пример 54. Результат
"foo%20bar%3F"

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

Пример 55. Исходный код
encode_percent("foo bar", ascii_set: "CONTROLS")
Пример 56. Результат
"foo %09bar"

encode_proto

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

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

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

value

объект

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

да

desc_file

строка

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

да

message_type

строка

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

да

Ошибки

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

  • Файл, указанный в аргументе desc_file, не существует.

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

Пример

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

encode_punycode

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

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

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

value

строка

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

да

validate

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

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

true

нет

Ошибки

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

Примеры

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

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

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

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

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

Пример 63. Исходный код
encode_punycode!("example.com")
Пример 64. Результат
"example.com"

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

Пример 65. Исходный код
encode_punycode!("xn--8hbb.xn--fiba.xn--8hbf.xn--eib.", validate: false)
Пример 66. Результат
"xn--8hbb.xn--fiba.xn--8hbf.xn--eib."

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

Пример 67. Исходный код
encode_punycode!("www.CAFé.example")
Пример 68. Результат
"www.xn--caf-dma.example"

encode_snappy

Кодирует value в формат Snappy.

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

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

value

строка

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

да

Ошибки

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

Пример

Пример 69. Исходный код
encoded_text = encode_snappy!("A user account was created.")
encode_base64(encoded_text)
Пример 70. Результат
"G2hBIHVzZXIgYWNjb3VudCB3YXMgY3JlYXRlZC4="

encode_zlib

Кодирует value в формат Zlib.

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

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

value

строка

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

да

compression_level

целое число

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

6

нет

Пример

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

Пример 71. Исходный код
encoded_text = encode_zlib("please encode me")
encode_base64(encoded_text)
Пример 72. Результат
"eJwryElNLE5VSM1Lzk9JVchNBQA0RQX7"

encode_zstd

Кодирует value в формат Zstandard.

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

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

value

строка

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

да

compression_level

целое число

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

3

нет

Пример

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

Пример 73. Исходный код
encoded_text = encode_zstd("please encode me")
encode_base64(encoded_text)
Пример 74. Результат
"KLUv/QBYgQAAcGxlYXNlIGVuY29kZSBtZQ=="

Функции сериализации

encode_json

Кодирует value в JSON.

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

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

value

любое

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

да

Пример

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

Пример 75. Исходный код
.payload = encode_json({"hello": "world"})
Пример 76. Результат
"{"hello":"world"}"

encode_key_value

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

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

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

value

объект

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

да

fields_ordering

массив

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

нет

key_value_delimiter

строка

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

=

нет

field_delimiter

строка

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

(пробел)

нет

flatten_boolean

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

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

false

нет

Ошибки

Функция encode_key_value возвращает ошибку, для которой требуется обработка, если в fields_ordering содержится элемент, не являющийся строкой.

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

Примеры

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

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

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

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

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

Пример 81. Исходный код
encode_key_value({"agent": {"name": "vector"}, "log": {"file": {"path": "my.log"}}, "event": "log"})
Пример 82. Результат
"agent.name=vector event=log log.file.path=my.log"

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

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

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

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

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

Пример 87. Исходный код
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
)
Пример 88. Результат
"beta,lvl:info,msg:\"This is a message\",ts:2021-06-05T17:20:00Z"

encode_logfmt

Кодирует value в формат logfmt.

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

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

value

объект

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

да

fields_ordering

массив

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

нет

Ошибки

Функция encode_logfmt возвращает ошибку, для которой требуется обработка, если в fields_ordering содержится элемент, не являющийся строкой.

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

Примеры

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

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

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

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

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

Пример 93. Исходный код
encode_logfmt({"agent": {"name": "vector"}, "log": {"file": {"path": "my.log"}}, "event": "log"})
Пример 94. Результат
"agent.name=vector event=log log.file.path=my.log"

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

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