Библиотека dart:convert

Кодировщики и декодировщики для преобразования между различными представлениями данных, включая JSON и UTF-8.

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

Чтобы использовать эту библиотеку в коде:

import 'dart:convert';

Два часто используемых конвертера — это экземпляры верхнего уровня JsonCodec и Utf8Codec, названные соответственно json и utf8.

JSON

JSON — это простой текстовый формат для представления структурированных объектов и коллекций.

JsonCodec кодирует объекты JSON в строки и декодирует строки в объекты JSON. Кодировщик/декодировщик json преобразует строки в структуры объектов, например списки и карты, и обратно, используя формат JSON.

json — это реализация JsonCodec по умолчанию.

Примеры

var encoded = json.encode([1, 2, { "a": null }]);
var decoded = json.decode('["foo", { "bar": 499 }]');

Подробнее см. также JsonEncoder и JsonDecoder.

UTF-8

Utf8Codec кодирует строки в кодовые единицы UTF-8 (байты) и декодирует кодовые единицы UTF-8 в строки.

utf8 — это реализация Utf8Codec по умолчанию.

Пример:

var encoded = utf8.encode('Îñţérñåţîöñåļîžåţîờñ');
var decoded = utf8.decode([
  195, 142, 195, 177, 197, 163, 195, 169, 114, 195, 177, 195, 165, 197,
  163, 195, 174, 195, 182, 195, 177, 195, 165, 196, 188, 195, 174, 197,
  190, 195, 165, 197, 163, 195, 174, 225, 187, 157, 195, 177]);

Подробнее см. также Utf8Encoder и Utf8Decoder.

ASCII

AsciiCodec кодирует строки в виде кодов ASCII, сохранённых как байты, и декодирует байты ASCII в строки. Не все символы можно представить в ASCII, поэтому не все строки можно успешно преобразовать.

ascii — это реализация AsciiCodec по умолчанию.

Пример:

var encoded = ascii.encode('This is ASCII!');
var decoded = ascii.decode([0x54, 0x68, 0x69, 0x73, 0x20, 0x69, 0x73,
                            0x20, 0x41, 0x53, 0x43, 0x49, 0x49, 0x21]);

Подробнее см. также AsciiEncoder и AsciiDecoder.

Latin-1

Latin1Codec кодирует строки в байты ISO Latin-1 (также известной как ISO-8859-1) и декодирует байты Latin-1 в строки. Не все символы можно представить в Latin-1, поэтому не все строки можно успешно преобразовать.

latin1 — это реализация Latin1Codec по умолчанию.

Пример:

var encoded = latin1.encode('blåbærgrød');
var decoded = latin1.decode([0x62, 0x6c, 0xe5, 0x62, 0xe6,
                             0x72, 0x67, 0x72, 0xf8, 0x64]);

Подробнее см. также Latin1Encoder и Latin1Decoder.

Base64

Base64Codec кодирует байты с использованием стандартного алфавита base64, декодирует данные с использованием алфавитов base64 и base64url, не допускает недопустимые символы и требует заполнения.

base64 — это реализация Base64Codec по умолчанию.

Пример:

var encoded = base64.encode([0x62, 0x6c, 0xc3, 0xa5, 0x62, 0xc3, 0xa6,
                             0x72, 0x67, 0x72, 0xc3, 0xb8, 0x64]);
var decoded = base64.decode('YmzDpWLDpnJncsO4ZAo=');

Подробнее см. также Base64Encoder и Base64Decoder.

Конвертеры

Конвертеры часто используют с потоками для преобразования поступающих через поток данных по мере их появления. В следующем коде используются два конвертера. Первый — это декодировщик UTF-8, который преобразует данные из байтов в UTF-8 при чтении из файла. Второй — экземпляр LineSplitter, который разделяет данные по символам новой строки.

const showLineNumbers = true;
var lineNumber = 1;
var stream = File('quotes.txt').openRead();

stream.transform(utf8.decoder)
      .transform(const LineSplitter())
      .forEach((line) {
        if (showLineNumbers) {
          stdout.write('${lineNumber++} ');
        }
        stdout.writeln(line);
      });

Сведения о создании собственных конвертеров см. в документации классов Codec и Converter.

Экранирование HTML

Конвертер HtmlEscape экранирует символы, имеющие специальное значение в HTML. Конвертер находит символы, значимые в исходном коде HTML, и заменяет их соответствующими HTML-сущностями.

Пользовательские режимы экранирования можно создать с помощью конструктора HtmlEscapeMode.HtmlEscapeMode.

Пример:

const htmlEscapeMode = HtmlEscapeMode(
  name: 'custom',
  escapeLtGt: true,
  escapeQuot: false,
  escapeApos: false,
  escapeSlash: false,
 );

const HtmlEscape htmlEscape = HtmlEscape(htmlEscapeMode);
String unescaped = 'Text & subject';
String escaped = htmlEscape.convert(unescaped);
print(escaped); // Text & subject

unescaped = '10 > 1 and 1 < 10';
escaped = htmlEscape.convert(unescaped);
print(escaped); // 10 &gt; 1 and 1 &lt; 10

unescaped = "Single-quoted: 'text'";
escaped = htmlEscape.convert(unescaped);
print(escaped); // Single-quoted: 'text'

unescaped = 'Double-quoted: "text"';
escaped = htmlEscape.convert(unescaped);
print(escaped); // Double-quoted: "text"

unescaped = 'Path: /system/';
escaped = htmlEscape.convert(unescaped);
print(escaped); // Path: /system/

Классы

AsciiCodec

AsciiCodec позволяет кодировать строки в байты ASCII и декодировать байты ASCII в строки.

AsciiDecoder

Преобразует байты ASCII в строку.

AsciiEncoder

Преобразует строки, состоящие только из символов ASCII, в байты.

Base64Codec

Кодировщик и декодировщик base64.

Base64Decoder

Декодировщик данных, закодированных в base64.

Base64Encoder

Конвертер для кодирования в base64 и base64url.

ByteConversionSink

ByteConversionSink предоставляет интерфейс, позволяющий конвертерам эффективно передавать байтовые данные.

ByteConversionSinkBase

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

ChunkedConversionSink<T>

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

ClosableStringSink

ClosableStringSink расширяет интерфейс StringSink, добавляя метод close.

Codec<S, T>

Codec кодирует данные и, если поддерживается, декодирует их.

Converter<S, T>

Converter преобразует данные из одного представления в другое.

Encoding

Открытый перечислимый тип Encoding.

HtmlEscape

Конвертер, экранирующий символы, имеющие специальное значение в HTML.

HtmlEscapeMode

Режимы экранирования HTML.

JsonCodec

JsonCodec кодирует объекты JSON в строки и декодирует строки в объекты JSON.

JsonDecoder

Этот класс разбирает строки JSON и создаёт соответствующие объекты.

JsonEncoder

Этот класс преобразует объекты JSON в строки.

JsonUtf8Encoder

Кодировщик, который кодирует один объект в строку JSON в кодировке UTF-8.

Latin1Codec

Latin1Codec кодирует строки в байты ISO Latin-1 (также известной как ISO-8859-1) и декодирует байты Latin-1 в строки.

Latin1Decoder

Этот класс преобразует байты Latin-1 (списки беззнаковых 8-битных целых чисел) в строку.

Latin1Encoder

Этот класс преобразует строки, состоящие только из символов ISO Latin-1, в байты.

LineSplitter

StreamTransformer, который разделяет String на отдельные строки.

StringConversionSink

Этот класс предоставляет интерфейс, позволяющий конвертерам эффективно передавать данные типа String.

StringConversionSinkBase

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

StringConversionSinkMixin

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

Utf8Codec

Utf8Codec кодирует строки в кодовые единицы UTF-8 (байты) и декодирует кодовые единицы UTF-8 в строки.

Utf8Decoder

Этот класс преобразует кодовые единицы UTF-8 (списки беззнаковых 8-битных целых чисел) в строку.

Utf8Encoder

Этот класс преобразует строки в соответствующие им кодовые единицы UTF-8 (список беззнаковых 8-битных целых чисел).

Константы

ascii → const AsciiCodec

Экземпляр реализации AsciiCodec по умолчанию.

AsciiCodec()

base64 → const Base64Codec

Кодировщик и декодировщик base64.

Base64Codec()

base64Url → const Base64Codec

Кодировщик и декодировщик base64url.

Base64Codec.urlSafe()

htmlEscape → const HtmlEscape

Конвертер String, преобразующий символы в HTML-сущности.

HtmlEscape()

json → const JsonCodec

Экземпляр реализации JsonCodec по умолчанию.

JsonCodec()

latin1 → const Latin1Codec

Экземпляр реализации Latin1Codec по умолчанию.

Latin1Codec()

unicodeBomCharacterRune → const int

Символ Unicode Byte Order Marker (BOM) U+FEFF.

0xFEFF

unicodeReplacementCharacterRune → const int

Символ замены Unicode U+FFFD (�).

0xFFFD

utf8 → const Utf8Codec

Экземпляр реализации Utf8Codec по умолчанию.

Utf8Codec()

Функции

base64Decode(String source) → Uint8List

Декодирует байты, закодированные в base64 или base64url.

base64Encode(List<int> bytes) → String

Кодирует bytes с использованием кодировки base64.

base64UrlEncode(List<int> bytes) → String

Кодирует bytes с использованием кодировки base64url.

jsonDecode(String source, {Object? reviver(Object? key, Object? value)?}) → dynamic

Разбирает строку и возвращает полученный объект JSON.

jsonEncode(Object? object, {Object? toEncodable(Object? nonEncodable)?}) → String

Преобразует object в строку JSON.

Исключения / ошибки

JsonCyclicError

Сообщает, что объект не удалось преобразовать в строку из-за циклических ссылок.

JsonUnsupportedObjectError

Ошибка, возникающая при сериализации JSON, если объект невозможно сериализовать.