{"id":15047828,"url":"https://github.com/wqking/jsonpp","last_synced_at":"2025-10-21T07:31:45.407Z","repository":{"id":45770784,"uuid":"514479966","full_name":"wqking/jsonpp","owner":"wqking","description":"C++ JSON parser and stringify","archived":false,"fork":false,"pushed_at":"2022-07-29T07:28:39.000Z","size":1005,"stargazers_count":26,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-10T01:05:53.742Z","etag":null,"topics":["cplusplus-11","cpp11","deserialization","json","parse","serialization","stringify"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wqking.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-07-16T04:48:11.000Z","updated_at":"2025-01-14T23:45:58.000Z","dependencies_parsed_at":"2022-09-01T22:40:10.647Z","dependency_job_id":null,"html_url":"https://github.com/wqking/jsonpp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wqking%2Fjsonpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wqking%2Fjsonpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wqking%2Fjsonpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wqking%2Fjsonpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wqking","download_url":"https://codeload.github.com/wqking/jsonpp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137888,"owners_count":21053775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cplusplus-11","cpp11","deserialization","json","parse","serialization","stringify"],"created_at":"2024-09-24T21:05:02.090Z","updated_at":"2025-10-21T07:31:45.305Z","avatar_url":"https://github.com/wqking.png","language":"C++","readme":"[//]: # (Auto generated file, don't modify this file.)\n\n# jsonpp -- easy to use and reusable C++ JSON library\n\u003c!--begintoc--\u003e\n- [Features](#mdtoc_bfc0dc13)\n- [Why jsonpp when there are hundreds of JSON libraries?](#mdtoc_27dc3eca)\n- [Basic information](#mdtoc_abc52c05)\n  - [License](#mdtoc_5768f419)\n  - [Version 1.0.0-RC](#mdtoc_48c15a2e)\n  - [Source code](#mdtoc_6b8a2c23)\n  - [Supported compilers](#mdtoc_215a5bea)\n- [Quick start](#mdtoc_ea7b0a9)\n  - [Namespace](#mdtoc_33e16b56)\n- [Example code](#mdtoc_3bb166c4)\n  - [Parse JSON document](#mdtoc_bdd95779)\n  - [Parse JSON document as specified type](#mdtoc_1598a37b)\n  - [Dump JSON object to text (stringify)](#mdtoc_a4e21f76)\n  - [Dump/parse class object](#mdtoc_9eda3b58)\n- [Performance](#mdtoc_82d79681)\n  - [Parse JSON file](#mdtoc_4563e049)\n  - [Stringify JSON document](#mdtoc_a7a220ec)\n- [Documentations](#mdtoc_aa76f386)\n- [Known compiler related quirks in MSVC](#mdtoc_2f938cf5)\n\u003c!--endtoc--\u003e\n\njsonpp is a cross platform C++ JSON library, focusing on easy to use and reusable technology.  \njsonpp can parse and stringify JSON document.\n\n![C++](https://img.shields.io/badge/C%2B%2B-11-blue)\n![Compilers](https://img.shields.io/badge/Compilers-GCC%2FMSVC%2FClang-blue)\n![License](https://img.shields.io/badge/License-Apache--2.0-blue)\n![CI](https://github.com/wqking/jsonpp/workflows/CI/badge.svg)\n\n\u003ca id=\"mdtoc_bfc0dc13\"\u003e\u003c/a\u003e\n## Features\n\n- **Reusable technology**. The core technology is from [C++ reflection library metapp](https://github.com/wqking/metapp) developed\nby the same developer (wqking) of jsonpp. The technology is not unique to jsonpp, it's reusable for other purposes such as\nruntime reflection system, serialization, script binding, etc.\n\n- **Very easy to use**. We can parse and stringify any C++ data structures, include STL containers, classes, etc.\nC++ native data types and STL containers are ready to use, no need extra work, because metapp already supports them.\nReflecting meta data for class is very easy. \n\n- **Very easy to learn**. jsonpp doesn't define any data types to represent JSON document, instead it uses native C++ data type\nand STL containers which you have already mastered. The only \"new\" data type is metapp::Variant, you only need to learn\nthe very basic knowledge.\n\n- **Multiple parser backends**. jsonpp uses existing matured and well tested JSON parser libraries as the parser backend, such as\n[simdjson 2.2.0](https://github.com/simdjson/simdjson) and [json-parser](https://github.com/json-parser/json-parser).\nThat means you can choose the best viable backend to achieve your goals and avoid the backends that make you trouble. Also adding\nnew backend is very easy.\n\n- **Decent performance**. Performance is not jsonpp strength and it's not close to high performance JSON libraries such as\nsimdjson. However, the performance is better than some existing popular JSON libraries which also focus on usability, thanks to\nthe high performance simdjson and well optimized metapp.\n\n- Support stringify and parse almost all C++ native types and STL containers, such as integers, float points, C string,\nstd::string, std::array, std::vector, std::list, std::deque, std::map, std::unordered_map, std::tuple, std::pair, etc.\nNew containers can be added via metapp reflection system.\n\n- JSON object can be parsed as sequence containers such as std::vector, and vice versa on dumping.\n\n- Support stringify and parse classes and enumerators.\n\n- Enumerators can be stringified as string names and parsed back to enum values.\n\n- Support stringify to different storage, such as `std::string`, `std::vector\u003cchar\u003e`, stream, or customized writer.\n\n- Cross platforms, cross compilers.\n\n- Written in standard and portable C++, only require C++11, and support later C++ standard.\n\n- Use CMake to build and install.\n\n\u003ca id=\"mdtoc_27dc3eca\"\u003e\u003c/a\u003e\n## Why jsonpp when there are hundreds of JSON libraries?\n\njsonpp is very easy to use and has good performance, and more important, the technology is reusable. For example, to parse/stringify\ncustomized classes, unlike the other libraries that require you to register read/write method to the JSON libraries, in jsonpp you\nonly need to reflect meta data using metapp, then jsonpp can read and write the type for you. The meta data is reusable, your\nknowledge and experience is reusable too.\n\n\u003ca id=\"mdtoc_abc52c05\"\u003e\u003c/a\u003e\n## Basic information\n\n\u003ca id=\"mdtoc_5768f419\"\u003e\u003c/a\u003e\n### License\n\nApache License, Version 2.0  \n\n\u003ca id=\"mdtoc_48c15a2e\"\u003e\u003c/a\u003e\n### Version 1.0.0-RC\n\nThe project is in release candidate stage and near the first release.  \nI will do more tests, code review, and gather feedbacks. After there is no critical bugs or serious design flaw, I will release\nthe first version.\n\nYou are welcome to try the project and give feedback. Your participation will help to make the development faster and better.\n\n\u003ca id=\"mdtoc_6b8a2c23\"\u003e\u003c/a\u003e\n### Source code\n\n[https://github.com/wqking/jsonpp](https://github.com/wqking/jsonpp)\n\n\u003ca id=\"mdtoc_215a5bea\"\u003e\u003c/a\u003e\n### Supported compilers\n\njsonpp requires C++ compiler that supports C++11 standard.  \nThe library is tested with MSVC 2022, 2019, MinGW (Msys) GCC 8.3 and 11.3.0, Clang (carried by MSVC).  \nIn brief, MSVC, GCC, Clang that has well support for C++11, or released after 2019, should be able to compile the library.\n\n\u003ca id=\"mdtoc_ea7b0a9\"\u003e\u003c/a\u003e\n## Quick start\n\n\u003ca id=\"mdtoc_33e16b56\"\u003e\u003c/a\u003e\n### Namespace\n\n`jsonpp`\n\nYou should not use any nested namespace in `jsonpp`.\n\n\u003ca id=\"mdtoc_3bb166c4\"\u003e\u003c/a\u003e\n## Example code\n\n\n\u003ca id=\"mdtoc_bdd95779\"\u003e\u003c/a\u003e\n### Parse JSON document\nHeader for Parser\n\n```c++\n#include \"jsonpp/parser.h\"\n```\n\nCreate a parser with default configuration and default backend which is simdjson.\n\n```c++\njsonpp::Parser parser;\n```\n\nThis is the JSON we are going to parse.\n\n```c++\nconst std::string jsonText = R\"(\n  [ 5, \"abc\", true, null, 3.14, [ 1, 2, 3 ], { \"one\": 1, \"two\": 2 } ]\n)\";\n```\n\nParse the JSON, the result is a `metapp::Variant`.\n\n```c++\nconst metapp::Variant var = parser.parse(jsonText);\n```\n\nThe result is an array.\n\n```c++\nASSERT(jsonpp::getJsonType(var) == jsonpp::JsonType::jtArray);\n```\n\nGet the underlying array. jsonpp::JsonArray is alias of `std::vector\u003cmetapp::Variant\u003e`\n\n```c++\nconst jsonpp::JsonArray \u0026 array = var.get\u003cconst jsonpp::JsonArray \u0026\u003e();\n```\n\nNow verify the elements. Don't feel strange on the types like JsonInt or JsonString, they are\njust aliases of C++ types. And we can parse JSON document as specified type, see next example.\n\n```c++\nASSERT(array[0].get\u003cjsonpp::JsonInt\u003e() == 5);\nASSERT(array[1].get\u003cconst jsonpp::JsonString \u0026\u003e() == \"abc\");\nASSERT(array[2].get\u003cjsonpp::JsonBool\u003e());\nASSERT(array[3].get\u003cjsonpp::JsonNull\u003e() == nullptr);\nASSERT(array[4].get\u003cjsonpp::JsonReal\u003e() == 3.14);\nconst jsonpp::JsonArray \u0026 nestedArray = array[5].get\u003cconst jsonpp::JsonArray \u0026\u003e();\nASSERT(nestedArray[0].get\u003cjsonpp::JsonInt\u003e() == 1);\nASSERT(nestedArray[1].get\u003cjsonpp::JsonInt\u003e() == 2);\nASSERT(nestedArray[2].get\u003cjsonpp::JsonInt\u003e() == 3);\njsonpp::JsonObject \u0026 nestedObject = array[6].get\u003cjsonpp::JsonObject \u0026\u003e();\nASSERT(nestedObject[\"one\"].get\u003cjsonpp::JsonInt\u003e() == 1);\nASSERT(nestedObject[\"two\"].get\u003cjsonpp::JsonInt\u003e() == 2);\n```\n\n\u003ca id=\"mdtoc_1598a37b\"\u003e\u003c/a\u003e\n### Parse JSON document as specified type\nCreate a parser.\n\n```c++\njsonpp::Parser parser;\n```\n\nThis is the JSON we are going to parse. It's an array of integer, so we can use `std::vector\u003cint\u003e`\nto represent it. Note the float point 567.1 will be converted to `int` automatically.\n\n```c++\nconst std::string jsonText = R\"(\n  [ 1, -2, 3, 567.1 ]\n)\";\n```\n\nParse the JSON as std::vector\u003cint\u003e.\n\n```c++\nconst std::vector\u003cint\u003e array = parser.parse\u003cstd::vector\u003cint\u003e \u003e(jsonText);\n```\n\nVerify the result.\n\n```c++\nREQUIRE(array[0] == 1);\nREQUIRE(array[1] == -2);\nREQUIRE(array[2] == 3);\nREQUIRE(array[3] == 567);\n```\n\n\u003ca id=\"mdtoc_a4e21f76\"\u003e\u003c/a\u003e\n### Dump JSON object to text (stringify)\nHeader for Dumper\n\n```c++\n#include \"jsonpp/dumper.h\"\n```\n\n```c++\nstd::string text;\n```\n\nCreate a dumper with default configuration.\n\n```c++\njsonpp::Dumper dumper;\n```\n\nDump a simple integer.\n\n```c++\ntext = dumper.dump(5);\nASSERT(text == \"5\");\n```\n\nDump a boolean.\n\n```c++\ntext = dumper.dump(true);\nASSERT(text == \"true\");\n```\n\nDump complicated data struct.\n\n```c++\ntext = dumper.dump(jsonpp::JsonObject {\n  { \"first\", \"hello\" },\n  { \"second\", nullptr },\n  { \"third\", std::vector\u003cint\u003e { 5, 6, 7 } },\n  { \"fourth\", jsonpp::JsonArray { \"abc\", 9.1 } },\n});\n// JsonObject is alias of std::map\u003cstd::string, metapp::Variant\u003e, so the keys are sorted alphabetically.\nASSERT(text == R\"({\"first\":\"hello\",\"fourth\":[\"abc\",9.1],\"second\":null,\"third\":[5,6,7]})\");\n```\n\n\u003ca id=\"mdtoc_9eda3b58\"\u003e\u003c/a\u003e\n### Dump/parse class object\nNow let's dump and parse customized class objects. First let's define the enum and classes that we will use later.\n\n```c++\nenum class Gender\n{\n  female,\n  male\n};\n\nstruct Skill\n{\n  std::string name;\n  int level;\n};\n\nstruct Person\n{\n  std::string name;\n  Gender gender;\n  int age;\n  std::vector\u003cSkill\u003e skills;\n};\n```\n\nNow make the enum and class information available to metapp. jsonpp uses the reflection information from metapp.\nThe information is not special to jsonpp, it's general reflection and can be used for other purposes such\nas serialization, script binding, etc.\n\n```c++\ntemplate \u003c\u003e\nstruct metapp::DeclareMetaType \u003cGender\u003e : metapp::DeclareMetaTypeBase \u003cGender\u003e\n{\n  static const metapp::MetaEnum * getMetaEnum() {\n    static const metapp::MetaEnum metaEnum([](metapp::MetaEnum \u0026 me) {\n        me.registerValue(\"female\", Gender::female);\n        me.registerValue(\"male\", Gender::male);\n      }\n    );\n    return \u0026metaEnum;\n  }\n};\n\ntemplate \u003c\u003e\nstruct metapp::DeclareMetaType \u003cSkill\u003e : metapp::DeclareMetaTypeBase \u003cSkill\u003e\n{\n  static const metapp::MetaClass * getMetaClass() {\n    static const metapp::MetaClass metaClass(\n      metapp::getMetaType\u003cSkill\u003e(),\n      [](metapp::MetaClass \u0026 mc) {\n        mc.registerAccessible(\"name\", \u0026Skill::name);\n        mc.registerAccessible(\"level\", \u0026Skill::level);\n      }\n    );\n    return \u0026metaClass;\n  }\n};\n\n// I don't encourage to use macros and I don't provide macros in metapp library.\n// But for jsonpp users that don't want to dig into metapp and only want to use jsonpp features,\n// jsonpp provides macros to ease the meta type declaration.\n// Note: the macros are not required by jsonpp. The code can be rewritten without macros,\n// same as how Skill is declared above.\nJSONPP_BEGIN_DECLARE_CLASS(Person)\n  JSONPP_REGISTER_CLASS_FIELD(name)\n  JSONPP_REGISTER_CLASS_FIELD(gender)\n  JSONPP_REGISTER_CLASS_FIELD(age)\n  JSONPP_REGISTER_CLASS_FIELD(skills)\nJSONPP_END_DECLARE_CLASS()\n```\n\nNow let's dump `person` to text, then parse the text back to `Person` object.\n`enableNamedEnum(true)` will use the name such as \"female\" for the Gender enum, instead of numbers such as 0.\nThis allows the enum value change without breaking the dumped object.\n\n```c++\nPerson person { \"Mary\", Gender::female, 26, { { \"Writing\", 8 }, { \"Cooking\", 6 } } };\njsonpp::Dumper dumper(jsonpp::DumperConfig().enableBeautify(true).enableNamedEnum(true));\n// We don't user `person` any more, so we can move it to `dump` to avoid copying.\nconst std::string jsonText = dumper.dump(std::move(person));\n```\n\nThe jsonText looks like,\n```\n{\n    \"name\": \"Mary\",\n    \"gender\": \"female\",\n    \"age\": 26,\n    \"skills\": [\n        {\n            \"name\": \"Writing\",\n            \"level\": 8\n        },\n        {\n            \"name\": \"Cooking\",\n            \"level\": 6\n        }\n    ]\n}\n```\n\nNow let's parse the JSON text back to Person object, and verify the values.\n\n```c++\njsonpp::Parser parser;\nconst Person parsedPerson = parser.parse\u003cPerson\u003e(jsonText);\nASSERT(parsedPerson.name == \"Mary\");\nASSERT(parsedPerson.gender == Gender::female);\nASSERT(parsedPerson.age == 26);\nASSERT(parsedPerson.skills[0].name == \"Writing\");\nASSERT(parsedPerson.skills[0].level == 8);\nASSERT(parsedPerson.skills[1].name == \"Cooking\");\nASSERT(parsedPerson.skills[1].level == 6);\n```\n\nWe can not only dump/parse a single object, but also any STL containers with the objects.\n\n```c++\nPerson personAlice { \"Alice\", Gender::female, 28, { { \"Excel\", 7 }, { \"Word\", 8 } } };\nPerson personTom { \"Tom\", Gender::male, 29, { { \"C++\", 9 }, { \"Python\", 10 }, { \"PHP\", 7 } } };\n\njsonpp::Dumper dumper(jsonpp::DumperConfig().enableBeautify(true).enableNamedEnum(true));\nconst std::string jsonText = dumper.dump(std::vector\u003cPerson\u003e { personAlice, personTom });\n\njsonpp::Parser parser;\nconst std::vector\u003cPerson\u003e parsedPersons = parser.parse\u003cstd::vector\u003cPerson\u003e \u003e(jsonText);\nASSERT(parsedPersons[0] == personAlice);\nASSERT(parsedPersons[1] == personTom);\n```\n\n\u003ca id=\"mdtoc_82d79681\"\u003e\u003c/a\u003e\n## Performance\n\nHardware: HP laptop, Intel(R) Core(TM) i5-8300H CPU @ 2.30GHz, 16 GB RAM.  \nSoftware: Windows 10 Pro, 21H2. MinGW gcc version 11.3.0, optimization level is -O3.  \n\nThere are two parts in each benchmark data. The first part is the time to parse/dump one file, in milliseconds. The second part\nis the per second throughput.\n\nAbsolute data doesn't make sense, so the other library \"JSON for Modern C++\" (nlohmann) is tested for comparison.\n\n\u003ca id=\"mdtoc_4563e049\"\u003e\u003c/a\u003e\n### Parse JSON file\n\n|File name           |File size|    jsonpp (simdjson)| jsonpp (json-parser)|             nlohmann|\n|:-------------------|--------:|--------------------:|--------------------:|--------------------:|\n|canada.json         | 2,198 KB|   18.7 ms,  114 MB/s|   41.2 ms,   52 MB/s|  108.8 ms,   19 MB/s|\n|citm_catalog.json   | 1,686 KB|   7.02 ms,  234 MB/s|  18.84 ms,   87 MB/s|  13.16 ms,  125 MB/s|\n|twitter.json        |   616 KB|   3.93 ms,  153 MB/s|   8.81 ms,   68 MB/s|      6 ms,  100 MB/s|\n|airlines.json       | 4,848 KB|   32.7 ms,  144 MB/s|   73.5 ms,   64 MB/s|   53.7 ms,   88 MB/s|\n|tiny.json           |    348 B| 0.0026 ms,  127 MB/s| 0.0058 ms,   57 MB/s|  0.007 ms,   47 MB/s|\n|Zurich_Building.json|   278 MB|   4187 ms,   66 MB/s|   9076 ms,   30 MB/s|  10388 ms,   26 MB/s|\n\n\u003ca id=\"mdtoc_a7a220ec\"\u003e\u003c/a\u003e\n### Stringify JSON document\n\n|File name           |    jsonpp (beautify)|      jsonpp (minify)|  nlohmann (beautify)|    nlohmann (minify)|\n|:-------------------|--------------------:|--------------------:|--------------------:|--------------------:|\n|canada.json         |   14.2 ms,  544 MB/s|   10.1 ms,  197 MB/s|   20.4 ms,  379 MB/s|   14.9 ms,  133 MB/s|\n|citm_catalog.json   |   4.11 ms,  461 MB/s|   2.65 ms,  180 MB/s|   4.86 ms,  338 MB/s|   4.12 ms,  115 MB/s|\n|twitter.json        |   2.05 ms,  364 MB/s|   1.52 ms,  292 MB/s|   4.08 ms,  179 MB/s|   3.22 ms,  138 MB/s|\n|airlines.json       |   21.1 ms,  275 MB/s|   17.9 ms,  187 MB/s|   23.8 ms,  244 MB/s|   21.8 ms,  154 MB/s|\n|tiny.json           | 0.0034 ms,  130 MB/s|  0.003 ms,   80 MB/s| 0.0017 ms,  251 MB/s| 0.0016 ms,  152 MB/s|\n|Zurich_Building.json|   3724 ms,  345 MB/s|   2649 ms,  105 MB/s|   2665 ms,  482 MB/s|   1943 ms,  143 MB/s|\n\n\u003ca id=\"mdtoc_aa76f386\"\u003e\u003c/a\u003e\n## Documentations\nBelow are tutorials and documents. Don't feel upset if you find issues or missing stuff in the documents, I'm not\nnative English speaker and it's not that exciting to write document. Any way, the code quality is always much better\nthan the document, for ever.  \nIf you want to contribute to the documents, be sure to read [How to generate documentations](doc/about_document.md).  \n\n- [Build and install the library](doc/build_install.md)\n- [Use class Parser to read and parse JSON document](doc/parser.md)\n- [Use class Dumper to dump and stringify JSON data](doc/dumper.md)\n- [Common and default data types](doc/common_types.md)\n- [Declare meta data, use classes and enumerators, use metapp](doc/metapp_basic.md)\n\n\n\u003ca id=\"mdtoc_2f938cf5\"\u003e\u003c/a\u003e\n## Known compiler related quirks in MSVC\n\nMSVC 2022 and 2019, can build the CMake generated test projects and the tests run correctly in Debug and RelWithDebugInfo\nconfigurations. But some tests fail in Release mode when incremental linking is disabled.  \nThose failed tests should not fail, because they work correct in MSVC debug mode and in GCC/Clang.\nAdding /Debug option to linking which generates debug information makes the tests success.  \nWithout /Debug option, but enabling incremental linking, will cause the tests success too.  \nSo if jsonpp shows weird behavior in MSVC, try to enable incremental linking.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwqking%2Fjsonpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwqking%2Fjsonpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwqking%2Fjsonpp/lists"}