Serializers Interface - liuli-neko/NekoProtoTools GitHub Wiki

This page provides a detailed reference for the core components within the NekoProtoTools Serilizers module.

Tutorial: Serialization Base

The Serilizers module provides the necessary tools for converting C++ objects to/from byte streams.

To use the features of this module, include the following primary header(s):

#include <nekoproto/proto/serializer_base.hpp>
// Add other commonly required headers for this module
#include <nekoproto/proto/binary_serializer.hpp>
// Or
#include <nekoproto/proto/json_serializer.hpp> // auto using rapid_json_serializer or simd_json_serializer by configuring optional features
#include <nekoproto/proto/types/types.hpp> // include all type support

The core components of this module reside primarily in the NekoProto namespace.

• Purpose: Marks members for serialization.
• Placement: Inside the class/struct definition.
• Syntax:

  struct MyUserData {
      // ... members ...
  
      NEKO_SERIALIZER(arg1, arg2, ...);
  };

• Effect: This macro will add several methods to the class, and the class that defines this macro will be considered serializable by other modules of the library.

• Purpose: Pack source information for value, like {"value", &value}.
• Placement: Custom serialize function.
• Syntax:

  struct MyUserData {
      // ... members ...
  
      template <typename SerializerT>
      bool serialize(SerializerT& serializer) {
          return serializer(NEKO_PROTO_NAME_VALUE_PAIR(value));
      }
  };

• Effect: This macro may effect raw data if value is lvalue variables.

• Purpose: Serializable Object.
• Attach Public Methods:
  • bool serialize(SerializerT& sa): This function must be has template , and return bool. It will be called by the serializer to serialize the object. User can use NEKO_SERIALIZER(...) to define the members to be serialized. or define custom serialize function.
• Interaction with User Types: It called by serializer.

• Purpose: Serializer Object.
• To be supplemented...

• Purpose: Deserializer Object.
• To be supplemented...

• Purpose: Serializer Object.
• To be supplemented...

• Purpose: Deserializer Object.
• To be supplemented...

• Purpose: Rename of enabled serializers.
• Usage: JsonSerializer::OutputSerializer, JsonSerializer::InputSerializer.

• Purpose: Serializer Object.
• To be supplemented...

• Purpose: Deserializer Object.
• To be supplemented...

• Purpose: Not implemented.

• Purpose: Deserializer Object.
• To be supplemented...

• Purpose: Serializer Object.
• Usage:

    auto str = serializable_to_string(my_object);

• Note: this string is not json, Just format it into a string that is easy to output and view

• Purpose: mark if the type is minimal serializable.
• Template Parameters:
  • template <typename T>: Type to mark.
• Usage Example:

// If you want to support serialization for a third-party type that can be treated as a primitive type such as a string or number, you can mark the class by partially specializing this template so that the serializer does not treat it as an object when entering serialization.
// If you not partially specializing this template, serializer will startObject/startNode befor serialize, detail can see in prologue function/epilogue function.
template <>
struct is_minimal_serializable<OtherType, void> : std::true_type {};

• Purpose: support a type of object to be deserialized.
• Template Parameters:
  • template <typename SerializerT>: Serializer Object.
  • ValueT: Must be a certain class that needs to be supported, or a template that does not cause conflicts.
• Usage Example:

    // if has a type OtherType, It comes from a third party that does not support serialization, and you cannot modify it to support serialization, you can use this function to support it.
    bool load(RapidJsonInputSerializer& serializer, OtherType& value) {
        return serializer(value.arg1, value.arg2, value.arg3, ...);
    }
    // The save method must also be implemented
    // detail see nekoproto/proto/types/

• Purpose: support a type of object to be serialized.
• Template Parameters:
  • template <typename SerializerT>: Serializer Object.
  • ValueT: Must be a certain class that needs to be supported, or a template that does not cause conflicts.
• Usage Example:

    // if has a type OtherType, It comes from a third party that does not support serialization, and you cannot modify it to support serialization, you can use this function to support it.
    bool save(RapidJsonOutputSerializer& serializer, const OtherType& value) {
        return serializer(value.arg1, value.arg2, value.arg3, ...);
    }
    // The load method must also be implemented
    // detail see nekoproto/proto/types/