JSON Type Support - liuli-neko/NekoProtoTools GitHub Wiki

This page details the specific C++ types supported by the NekoProto::JsonSerializer and how they are represented in the resulting JSON output.

Related Concepts:

• Serializers Interface|Serializers-Interface
• Supported Types Overview|Supported-Types-Overview

To use the JsonSerializer, ensure you have enabled a JSON backend (enable_rapidjson or enable_simdjson) in your xmake.lua configuration. See Installation.

Remember to include the necessary type support headers (<nekoproto/proto/types/...>) for the standard library types you wish to serialize/deserialize, or include the general <nekoproto/proto/types/types.hpp>. The fundamental types and std::optional are typically covered by including <nekoproto/proto/json_serializer.hpp>.

The following table outlines the mapping between C++ types and their JSON representation when using JsonSerializer:

C++ Type	Supported	JSON Representation	Required Type Header (nekoproto/proto/types/...)	Notes
bool	✅	boolean (true, false)	(builtin)	Included via json_serializer.hpp
int8_t, int16_t, int32_t, int64_t	✅	number (integer)	(builtin)	Included via json_serializer.hpp
uint8_t, uint16_t, uint32_t, uint64_t	✅	number (integer)	(builtin)	Included via json_serializer.hpp
float, double	✅	number (floating-point)	(builtin)	Included via json_serializer.hpp
std::string	✅	string	string.hpp
std::u8string (C++20)	✅	string	u8string.hpp	Requires C++20
enum class/enum	✅	string or number (int)	enum.hpp	Defaults to string; configurable to integer
std::optional<T>	✅	Value of T or null	(builtin)	T must be supported; included via json_serializer.hpp
std::vector<T>	✅	array ([ T, T, ... ])	vector.hpp	T must be supported
std::list<T>	✅	array ([ T, T, ... ])	list.hpp	T must be supported
std::deque<T>	✅	array ([ T, T, ... ])	deque.hpp	T must be supported
std::array<T, N>	✅	array ([ T, T, ... ])	array.hpp	T must be supported
std::set<T>	✅	array ([ T, T, ... ])	set.hpp	T must be supported; order depends on std::set
std::multiset<T>	✅	array ([ T, T, ... ])	multiset.hpp	T must be supported; order depends on std::multiset
std::unordered_set<T>	✅	array ([ T, T, ... ])	unordered_set.hpp	T must be supported; order is not guaranteed
std::unordered_multiset<T>	✅	array ([ T, T, ... ])	unordered_multiset.hpp	T must be supported; order is not guaranteed
std::map<std::string, V>	✅	object ({ "key": V, ... })	map.hpp	V must be supported
std::map<K, V> (K != std::string)	✅	array ([ [K, V], [K, V], ... ])	map.hpp	K, V must be supported; order depends on std::map
std::multimap<K, V>	✅	array ([ [K, V], [K, V], ... ])	multimap.hpp	K, V must be supported; order depends on std::multimap
std::unordered_map<std::string, V>	✅	object ({ "key": V, ... })	unordered_map.hpp	V must be supported; order is not guaranteed
std::unordered_map<K, V> (K != std::string)	✅	array ([ [K, V], [K, V], ... ])	unordered_map.hpp	K, V must be supported; order is not guaranteed
std::unordered_multimap<K, V>	✅	array ([ [K, V], [K, V], ... ])	unordered_multimap.hpp	K, V must be supported; order is not guaranteed
std::pair<T1, T2>	✅	object ({ "key": T1, "val": T2 })	pair.hpp	T1, T2 must be supported
std::tuple<T...>	✅	array ([ T1, T2, ... ])	tuple.hpp	All T types must be supported
std::variant<T...>	✅	object ({ "idx": i, "val": T_i })	variant.hpp	All T types must be supported; idx is 0-based index
std::bitset<N>	✅	string ("1011...")	bitset.hpp	Serialized as a string of '0's and '1's
std::shared_ptr<T>	✅	Value of T or null	shared_ptr.hpp	T must be supported
std::unique_ptr<T>	✅	Value of T or null	unique_ptr.hpp	T must be supported
std::atomic<T>	✅	Value of T	atomic.hpp	T must be supported
Custom struct/class (using macro)	✅	object ({ "member": val, ... })	(user-defined)	Defined via NEKO_SERIALIZER; members must be supported
Protocol class (using macros)	✅	object ({ "member": val, ... })	types/binary_data.hpp (may change/indirect)	Defined via NEKO_SERIALIZER & NEKO_DECLARE_PROTOCOL
std::any	❌	-	-	Not supported due to type erasure

(builtin): Support provided directly by <nekoproto/proto/types/types.hpp>.

• Maps with Non-String Keys: JSON objects require keys to be strings. Therefore, std::map and std::unordered_map with non-std::string key types are serialized as a JSON array, where each element is a two-element array representing [key, value].
• Enums: By default, enums are serialized to their string representation (if available via reflection helpers, otherwise potentially numeric). Configuration options may allow serialization as their underlying integer value.
• Nested Types: Containers (vector, map, etc.) and custom struct/class types can be nested arbitrarily, as long as all the constituent types are supported. The JSON structure will reflect the C++ structure.
• Pointers: Raw pointers are not directly supported for serialization. Use smart pointers (std::shared_ptr, std::unique_ptr) or manage object ownership and serialization explicitly if needed.

This comprehensive support allows for easy serialization of complex C++ data structures into the widely used JSON format.