nlohmann/json для C++: полное руководство с примерами

Введение в nlohmann/json: что это и зачем нужно

Библиотека nlohmann/json (также известная как JSON for Modern C++) — это одна из самых популярных и удобных библиотек для работы с JSON в языке C++. Она разработана Niels Lohmann и распространяется под лицензией MIT. Основная цель библиотеки — предоставить интуитивно понятный, современный и безопасный интерфейс для парсинга, создания, модификации и сериализации JSON-данных.

Зачем она нужна? В современной разработке JSON (JavaScript Object Notation) является стандартом де-факто для обмена данными между сервисами, хранения конфигураций, работы с API и веб-приложениями. Стандартная библиотека C++ не имеет встроенной поддержки JSON, поэтому разработчикам приходится либо писать собственные парсеры, либо использовать сторонние решения. nlohmann/json решает эту проблему, предлагая:

• Простой синтаксис — работа с JSON напоминает работу с встроенными контейнерами STL (std::map, std::vector).
• Безопасность типов — автоматическое преобразование между типами C++ и JSON.
• Высокую производительность — библиотека оптимизирована для скорости и памяти.
• Кроссплатформенность — работает на Windows, Linux, macOS, а также на встраиваемых системах.
• Полную поддержку стандарта JSON — включая вложенные объекты, массивы, null, булевы значения, числа и строки.

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

Установка nlohmann/json

В отличие от Python (где используется pip), в C++ установка библиотек может быть выполнена несколькими способами. Рассмотрим самые популярные.

Способ 1: Header-only (рекомендуется для новичков)

Библиотека nlohmann/json является header-only — это значит, что для её использования достаточно просто скачать один заголовочный файл json.hpp и подключить его в проекте. Никакой компиляции, линковки или установки зависимостей не требуется.

1. Скачайте файл json.hpp с официального репозитория (последняя версия — v3.11.3).
2. Поместите его в папку с вашим проектом, например, include/json.hpp.
3. В исходном коде подключите: #include "json.hpp".

Способ 2: Установка через пакетные менеджеры

Если вы используете современные системы сборки, можно установить библиотеку через менеджер пакетов:

• vcpkg (Windows, Linux, macOS): vcpkg install nlohmann-json
• Conan: conan install nlohmann_json/3.11.3@
• Homebrew (macOS): brew install nlohmann-json
• APT (Ubuntu/Debian): sudo apt install nlohmann-json3-dev

Способ 3: CMake FetchContent

Для проектов на CMake можно автоматически скачать библиотеку во время сборки:

include(FetchContent)
FetchContent_Declare(
  json
  GIT_REPOSITORY https://github.com/nlohmann/json.git
  GIT_TAG v3.11.3
)
FetchContent_MakeAvailable(json)
target_link_libraries(your_target PRIVATE nlohmann_json::nlohmann_json)

Быстрый старт: первый пример

Давайте напишем простую программу, которая создаёт JSON-объект, выводит его на экран, а затем парсит строку JSON обратно.

#include <iostream>
#include "json.hpp"

using json = nlohmann::json;

int main() {
    // 1. Создание JSON-объекта
    json person = {
        {"name", "Alice"},
        {"age", 30},
        {"is_student", false},
        {"skills", {"C++", "Python", "JSON"}},
        {"address", {
            {"city", "Moscow"},
            {"zip", 101000}
        }}
    };

    // 2. Вывод в отформатированном виде
    std::cout << person.dump(4) << std::endl;

    // 3. Парсинг строки JSON
    std::string json_string = R"({"name":"Bob","age":25})";
    json parsed = json::parse(json_string);
    std::cout << "Name: " << parsed["name"] << std::endl;
    std::cout << "Age: " << parsed["age"] << std::endl;

    return 0;
}

Вывод программы:

{
    "address": {
        "city": "Moscow",
        "zip": 101000
    },
    "age": 30,
    "is_student": false,
    "name": "Alice",
    "skills": ["C++", "Python", "JSON"]
}
Name: "Bob"
Age: 25

Основные методы и функции nlohmann/json

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

1. json::parse() — парсинг строки JSON

Описание: Преобразует строку (std::string, std::string_view, C-string) в объект json. Если строка невалидна, выбрасывает исключение json::parse_error.

Параметры:

• s — строка для парсинга (обязательный).
• cb — опциональный callback для обработки комментариев (по умолчанию nullptr).
• allow_exceptions — булево значение, разрешать ли исключения (по умолчанию true).

Пример:

std::string data = R"({"x": 10, "y": 20})";
json j = json::parse(data);
std::cout << j["x"] << std::endl; // 10

2. json::dump() — сериализация в строку

Описание: Преобразует объект json обратно в строку. Позволяет задать отступы для форматирования.

Параметры:

• indent — количество пробелов для отступа (по умолчанию -1, что означает без отступов).
• indent_char — символ отступа (по умолчанию пробел).
• ensure_ascii — экранировать ли не-ASCII символы (по умолчанию false).

Пример:

json j = {{"name", "Анна"}, {"age", 28}};
std::string pretty = j.dump(2); // с отступом 2 пробела
std::string compact = j.dump(); // без отступов
std::cout << pretty << std::endl;

3. json::at() — доступ с проверкой границ

Описание: Возвращает ссылку на элемент по ключу (для объектов) или индексу (для массивов). В отличие от оператора [], выбрасывает исключение json::out_of_range, если ключ/индекс не существует.

Параметры:

• key — строка (для объектов) или целое число (для массивов).

Пример:

json j = {{"a", 1}, {"b", 2}};
try {
    int val = j.at("c"); // выбросит исключение
} catch (const json::out_of_range& e) {
    std::cerr << "Key not found: " << e.what() << std::endl;
}

4. json::contains() — проверка наличия ключа

Описание: Проверяет, существует ли указанный ключ в JSON-объекте. Возвращает true или false.

Параметры:

• key — строка, имя ключа.

Пример:

json j = {{"name", "Ivan"}, {"age", 35}};
if (j.contains("name")) {
    std::cout << "Name exists: " << j["name"] << std::endl;
}

5. json::size() — получение размера

Описание: Возвращает количество элементов в объекте (количество ключей) или массиве (количество элементов). Для примитивных типов (числа, строки) возвращает 0.

Параметры: нет.

Пример:

json obj = {{"a", 1}, {"b", 2}, {"c", 3}};
json arr = json::array({1, 2, 3, 4});
std::cout << "Object size: " << obj.size() << std::endl; // 3
std::cout << "Array size: " << arr.size() << std::endl;   // 4

6. json::empty() — проверка на пустоту

Описание: Возвращает true, если объект или массив не содержит элементов, или если значение равно null.

Параметры: нет.

Пример:

json empty_obj = json::object();
json empty_arr = json::array();
json non_empty = {{"key", "value"}};
std::cout << empty_obj.empty() << std::endl; // 1 (true)
std::cout << non_empty.empty() << std::endl;  // 0 (false)

7. json::type() — определение типа JSON-значения

Описание: Возвращает перечисление json::value_t, указывающее тип хранящегося значения (object, array, string, number_integer, number_float, boolean, null).

Параметры: нет.

Пример:

json j1 = "hello";
json j2 = 42;
json j3 = true;
json j4 = nullptr;
std::cout << (j1.type() == json::value_t::string) << std::endl; // 1
std::cout << (j2.type() == json::value_t::number_integer) << std::endl; // 1
std::cout << (j4.type() == json::value_t::null) << std::endl; // 1

8. json::push_back() — добавление элемента в массив

Описание: Добавляет элемент в конец JSON-массива. Аналог std::vector::push_back().

Параметры:

• val — значение любого типа, совместимого с json.

Пример:

json arr = json::array();
arr.push_back("first");
arr.push_back(2);
arr.push_back(true);
std::cout << arr.dump() << std::endl; // ["first",2,true]

9. json::erase() — удаление элемента

Описание: Удаляет элемент из объекта (по ключу) или из массива (по индексу или итератору).

Параметры: