Справочник JSON

Дополнения для v0.0.18 ниже пока приведены на английском; остальной перевод сохранён. English · 简体中文

json.encode / json.decode are available in v0.0.18 and share the stringify / parse implementations. Compatibility names remain available. The previous JSON implementation remains the default; yyjson is not used.

Импорт и интерфейсы

import json from "std.json"

Интерфейс	Возвращает	Значение
json.stringify(&value:any)	str!	Кодирование только для чтения в новый компактный текст JSON
json.parse(text:str)	KuValue!	Строгий разбор в динамическое значение с независимым владением
json.try_parse(text:str)	KuValue!	Совместимый псевдоним parse
json.encode(&value:any)	str!	Псевдоним stringify в ветке разработки
json.decode(text:str)	KuValue!	Псевдоним parse в ветке разработки

! обозначает Result. Используйте ? для передачи ошибок или try/catch для обработки. Кодирование не потребляет и не изменяет входное значение.

Кодирование и чтение значений

Это полный базовый пример. Ветка разработки содержит более широкий регрессионный пример в examples/json.ku.

import json from "std.json"

fn main(): null! {
    value = { name: "Ku", count: 7 }
    text = json.stringify(value)?
    println(text)

    decoded = json.parse(text)?
    println(decoded["name"]?.as_str()?)
    println(decoded["count"]?.as_int()? + 1)
    return ok(null)
}

Ключи объекта сортируются детерминированно. Ожидаемый вывод:

{"count":7,"name":"Ku"}
Ku
8

Разобранный KuValue не может напрямую участвовать в целочисленной арифметике. Сначала преобразуйте его через .as_int()? или .as_str()?. Несоответствие типа возвращает ошибку. Отсутствующие ключи объекта тоже возвращают ошибки, а не автоматические значения по умолчанию.

Данные и границы

Поддерживаемые входные данные: строки, логические значения, целые числа, конечные числа с плавающей точкой, null, вложенные массивы, объекты со строковыми ключами и представимые структуры. Функции, Tasks, дескрипторы ресурсов, Results, перечисления и циклические ссылки не кодируются.

Правило	Текущая реализация
Синтаксис JSON	Строгий; отклоняет комментарии, завершающие запятые, лишний ввод после значения и некорректный Unicode
Вход / выход	Каждый ограничен 1 000 000 байт
Глубина	Корневая глубина 0; отклоняет depth > 32; 33 уровня пустых контейнеров принимаются, 34 отклоняются
Целые числа	Знаковые 64-битные; переполнение — ошибка, без автоматического преобразования в float
Плавающая точка	Конечные binary64; исходная запись, метки float и отрицательный ноль не сохраняются
Unicode	Китайский текст, эмодзи, экранирование, встроенный NUL
Повторные ключи объекта	При разборе сохраняется последнее значение
Порядок ключей	Кодирование сортирует по порядку байтов UTF-8

A float such as 1.0 may encode as 1. When an integer-looking float is outside int64, the encoder adds .0 to keep decoding on the float path: 1e20 encodes as 100000000000000000000.0 and decodes again. Finite binary64 values do not preserve original spelling, a float tag or the sign of negative zero.

Ошибки

Обрабатываемые ошибки используют домен json. Частые коды: parse_error, stringify_error и out_of_memory. byte N в сообщении разбора — смещение в байтах UTF-8 от нуля. Минимальный обработчик некорректного ввода приведён в ошибках и устранении неполадок.

Поддержка бэкендов

Реализации JSON есть в интерпретаторе, упакованном средстве запуска по умолчанию и синхронном нативном C-бэкенде. Ограниченное нативное подмножество Task и LLVM не поддерживают JSON. Импорты обычного средства запуска всё ещё зависят от расположения исходных файлов; поддержка JSON не означает полностью независимый пакет.

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