Module vibe.data.serialization

Supported types

The following rules are applied in order when serializing or deserializing a certain type:

1. An enum type is serialized as its raw value, except if @byName is used, in which case the name of the enum value is serialized.
2. Any type that is specifically supported by the serializer is directly serialized. For example, the BSON serializer supports BsonObjectID directly.
3. Arrays and tuples (std.typecons.Tuple) are serialized using the array serialization functions where each element is serialized again according to these rules.
4. Associative arrays are serialized similar to arrays. The key type of the AA must satisfy the isStringSerializable trait and will always be serialized as a string.
5. Any Nullable!T will be serialized as either null, or as the contained value (subject to these rules again).
6. Any Typedef!T will be serialized as if it were just T.
7. Any BitFlags!T value will be serialized as T[]
8. Types satisfying the isPolicySerializable trait for the supplied Policy will be serialized as the value returned by the policy toRepresentation function (again subject to these rules).
9. Types satisfying the isCustomSerializable trait will be serialized as the value returned by their toRepresentation method (again subject to these rules).
10. Types satisfying the isISOExtStringSerializable trait will be serialized as a string, as returned by their toISOExtString method. This causes types such as SysTime to be serialized as strings.
11. Types satisfying the isStringSinkSerializable trait will be serialized as a string using the toString(sink) method. sink can either be a delegate that takes a char array argument, or an output range of char.
12. Types satisfying the isStringSerializable trait will be serialized as a string, as returned by their toString method.
13. Struct and class types by default will be serialized as associative arrays, where the key is the name of the corresponding field (can be overridden using the @name attribute). If the struct/class is annotated with @asArray, it will instead be serialized as a flat array of values in the order of declaration. Null class references will be serialized as null.
14. Pointer types will be serialized as either null, or as the value they point to.
15. Built-in integers and floating point values, as well as boolean values will be converted to strings, if the serializer doesn't support them directly.

Note that no aliasing detection is performed, so that pointers, class references and arrays referencing the same memory will be serialized as multiple copies. When in turn deserializing the data, they will also end up as separate copies in memory.

Field names

By default, the field name of the serialized D type (for struct and class aggregates) is represented as-is in the serialized result. To circumvent name clashes with D's keywords, a single trailing underscore of any field name is stipped, so that a field name of version_ results in just "version" as the serialized value. Names can also be freely customized using the @name annotation.

Associative array keys are always represented using their direct string representation.

Serializer implementation

Serializers are implemented in terms of a struct with template methods that get called by the serialization framework:

struct ExampleSerializer {
	enum isSupportedValueType(T) = is(T == string) || is(T == typeof(null));

	// serialization
	auto getSerializedResult();
	void beginWriteDocument(TypeTraits)();
	void endWriteDocument(TypeTraits)();
	void beginWriteDictionary(TypeTraits)(size_t length); [OR] void beginWriteDictionary(TypeTraits)();
	void endWriteDictionary(TypeTraits)();
	void beginWriteDictionaryEntry(ElementTypeTraits)(string name);
	void endWriteDictionaryEntry(ElementTypeTraits)(string name);
	void beginWriteArray(TypeTraits)(size_t length);
	void endWriteArray(TypeTraits)();
	void beginWriteArrayEntry(ElementTypeTraits)(size_t index);
	void endWriteArrayEntry(ElementTypeTraits)(size_t index);
	void writeValue(TypeTraits, T)(T value);

	// deserialization

	void readDictionary(TypeTraits)(scope void delegate(string) entry_callback);
	void beginReadDictionaryEntry(ElementTypeTraits)(string);
	void endReadDictionaryEntry(ElementTypeTraits)(string);
	void readArray(TypeTraits)(scope void delegate(size_t) size_callback, scope void delegate() entry_callback);
	void beginReadArrayEntry(ElementTypeTraits)(size_t index);
	void endReadArrayEntry(ElementTypeTraits)(size_t index);
	T readValue(TypeTraits, T)();
	bool tryReadNull(TypeTraits)();

	// skipValue() is optional. It will be called by the entry_callback in readDictionary
	// whenever the key passed to the entry_callback cannot be found.
	void skipValue();
}

The TypeTraits type passed to the individual methods has the following members:

• Type: The original type of the field to serialize
• Attributes: User defined attributes attached to the field
• Policy: An alias to the policy used for the serialization process

ElementTypeTraits have the following additional members:

• ContainerType: The original type of the enclosing container type
• ContainerAttributes: User defined attributes attached to the enclosing container