Supported Types Overview - liuli-neko/NekoProtoTools GitHub Wiki

NekoProtoTools aims to serialize a wide range of C++ types into different formats like JSON, Binary, and XML. This page provides an overview of how type support works and links to detailed lists for each specific serializer.

How Type Support Works

NekoProtoTools achieves type support primarily in two ways:

  1. Built-in & Standard Library Types:

    • Support for fundamental C++ types (bool, int, float, double, etc.) is generally built into the core serializer classes (like JsonSerializer, BinarySerializer).
    • Support for most common C++ Standard Library types (like std::string, std::vector, std::map, std::optional, etc.) is provided through dedicated header files located in the nekoproto/proto/types/ directory (e.g., <nekoproto/proto/types/string.hpp>, <nekoproto/proto/types/vector.hpp>).
    • You must include the relevant header from nekoproto/proto/types/ for each standard library type you intend to serialize or deserialize. Alternatively, <nekoproto/proto/types/types.hpp> includes support for most common types.

  2. Custom struct and class Types:

    • You can make any struct or class serializable by using the NEKO_SERIALIZER(...) macro within its definition.
    • This macro tells NekoProtoTools which members to process.
    • Crucially, all members listed within NEKO_SERIALIZER must themselves be of a type that NekoProtoTools already supports (either fundamentally, through an included type header, or because they are also custom types using NEKO_SERIALIZER).

Generally Supported Type Categories

While the specifics depend on the serializer format, NekoProtoTools generally provides support for:

  • Fundamental Types: bool, integral types (int8_t to int64_t, uint8_t to uint64_t), floating-point types (float, double).
  • Strings: std::string, std::u8string (C++20).
  • STL Containers:
    • Sequence Containers: std::vector, std::list, std::deque, std::array.
    • Associative Containers: std::map, std::set, std::multimap, std::multiset.
    • Unordered Associative Containers: std::unordered_map, std::unordered_set, std::unordered_multimap, std::unordered_multiset.
  • Container Adaptors: Generally not directly supported (serialize the underlying container if needed).
  • Wrappers & Tuples: std::optional, std::variant, std::pair, std::tuple.
  • Smart Pointers: std::shared_ptr, std::unique_ptr (serialize the managed object or null).
  • Enums: enum and enum class (often serialized as strings or underlying integers).
  • Bitsets: std::bitset.
  • Atomics: std::atomic<T> (serializes the contained value T).
  • Custom Types: Any struct or class using NEKO_SERIALIZER.
  • Nested Protocols: Custom types that are also declared as protocols (NEKO_DECLARE_PROTOCOL).

Important Considerations

  • Format-Specific Representation: The way a C++ type is represented can differ significantly between serialization formats. For example, a std::map<int, std::string> might become a JSON object if the key were std::string, but an array of key-value pairs in JSON or Binary if the key is int.
  • Serializer Limitations: Not all serializers support all features equally. For instance, the current XmlSerializer primarily supports deserialization (input) only.
  • Header Inclusion: Remember to include the necessary <nekoproto/proto/types/...> headers for the standard library types you use in your serializable structures.

Detailed Support by Serializer Format

For the exact list of supported types and their representation within each format, please refer to the specific pages:

Unsupported Types & Customization

  • Types relying heavily on type erasure like std::any are generally not supported directly due to the difficulty of determining the contained type during deserialization.
  • If you need to support a type not covered by the built-in mechanisms or require a completely custom format, you can implement your own serializer. See: Implementing Custom Serializer.