carb::dictionary::ISerializer
Defined in carb/dictionary/ISerializer.h
-
struct ISerializer
Interface intended to serialize dictionary objects to and from plain C strings.
Each implementation of this interface is intended to handle a different format for the string data. The current implementations include support for JSON and TOML strings. It is left as an exercise for the caller to handle reading the string from a file before serializing or writing it to a file after serializing. Each implementation is assumed that it will be passed a dictionary item object has been created by the carb::dictionary::IDictionary interface implemented by the
carb.dictionary.pluginplugin or that the only IDictionary interface that can be acquired is also the one that created the item object.Note
If multiple plugins that implement IDictionary are loaded, behavior may be undefined.
Public Functions
-
inline dictionary::Item *createDictionaryFromStringBuffer(const char *string, size_t len = size_t(-1), DeserializerOptions options = kDeserializerOptionNone)
Creates a new dictionary object from the contents of a string.
On failure,
nullptris returned. This call can fail if the input string is not in the correct format (ie: in TOML format when using the JSON serializer or vice versa), if the string is malformed, or has a syntax error in it.- Parameters
string – [in] The string containing the data to be serialized into a new dictionary object. This is assumed to be in the format that is supported by this specific interface object’s implementation (for example, JSON or TOML for the default built-in implementations). If this string is not formatted correctly for the implementation, the operation will fail. Must be
NUL-terminated even if the length is known.len – [in] The length of the string data, if known. If not known, provide
size_t(-1)as the length, which is also the default. The length should not include theNULterminator.options – [in] Options, if any, to pass to the deserializer. If no options are desired, pass kDeserializerOptionNone.
- Returns
On success, this returns a new dictionary item object containing the serialized data from the string. When this dictionary is no longer needed, it must be destroyed using the carb::dictionary::IDictionary::destroyItem() function.
Public Members
-
const char *(*createStringBufferFromDictionary)(const dictionary::Item *dictionary, SerializerOptions serializerOptions)
Creates a new string representation of a dictionary.
On failure,
nullptris returned. This call can fail if an allocation error occurs, if a bad dictionary item object is encountered, or an error occurs formatting the output to the string.- Param dictionary
[in] The dictionary to be serialized. This must not be
nullptrbut may be an empty dictionary. The entire contents of the dictionary and all its children will be serialized to the output string.- Param serializerOptions
[in] Option flags to control how the output string is created. These flags can affect both the formatting and the content of the string.
- Return
On success, this returns a string containing the serialized dictionary. When this string is no longer needed, it must be destroyed using a call to ISerializer::destroyStringBuffer().
-
void (*destroyStringBuffer)(const char *serializedString)
Destroys a string buffer returned from ISerializer::createStringBufferFromDictionary().
- Param serializedString
[in] The string buffer to be destroyed. This must have been returned from a previous successful call to createStringBufferFromDictionary().
- Return
No return value.
Public Static Functions
-
static inline constexpr carb::InterfaceDesc getInterfaceDesc() noexcept
Returns information about this interface.
Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.
- Returns
The carb::InterfaceDesc struct with information about this interface.
-
static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc() noexcept
Returns information about the latest version of this interface.
Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.
- Returns
The carb::InterfaceDesc struct with information about the latest version of this interface.
-
inline dictionary::Item *createDictionaryFromStringBuffer(const char *string, size_t len = size_t(-1), DeserializerOptions options = kDeserializerOptionNone)