UniversalContainer Input/Output Routines

#include "ucio.h"

Overview

These routines allow for entire UniversalContainers to be read and written in various ways. All of the functions presented here are either serializers or deserializers, or convenience functions that wrap such functions.

If deserialization fails for any reason, a ucexception is thrown with error code uce_Deserialization_Error. Likewise, failure to serialize results in a ucexception with code uce_Serialization_Error. See the Exceptions section in the UniversalContainer Documentation.

Meta-data Convention

When serializing map type containers the various serializers ignore keys that begin with the # symbol. This includes the #boolean_value key used to set the true/false value of a map type container. This allows various type of meta-data to be easily added to a container, without changing the serialized form of that data.

Serialization Routines

Buffer* uc_encode_ini(const UniversalContainer& uc)

UniversalContainer uc_decode_ini(Buffer*)

The uc_encode_ini and uc_decode_ini functions convert a UniversalContainer to an ini format and decode that format back to a UniversalContainer. Map type containers are converted to a list of key/value pairs. The keys and values are separated by an equal sign, pairs are separated by a newline character. Arrays use a similar format with the integer indices replacing the keys. Nested containers are represented with a dot notation. Lines that being with a # symbol are ignored by uc_decode_ini. This format does not preserve the type information, it uses UniversalContainer::string_interpret to convert values to UniversalContainers.

UniversalContainer uc_decode_form(Buffer*)

Buffer* uc_encode_form(const UniversalContainer& uc)

This pair of routines encodes and decodes UniversalContainers in the application/x-www-form-urlencoded format used by browsers submitting forms to web servers via the HTTP POST method. This format does not preserve the type information, it uses UniversalContainer::string_interpret to convert values to UniversalContainers.

UniversalContainer uc_decode_binary(Buffer*)

Buffer* uc_encode_binary(const UniversalContainer&)

These routines implement a binary serializer and deserializer. This form is compact and efficient, and preserves the type of each component container.

UniversalContainer uc_decode_json(Buffer*)

Buffer* uc_encode_json(const UniversalContainer&)

Buffer* uc_encode_pretty_json(const UniversalContainer&, unsigned = 2)

The functions uc_decode_json and uc_encode_json implement Javascript object notation serialization and deserilaization. This format does not preserve the type information, it uses UniversalContainer::string_interpret to convert values to UniversalContainers. The buffer returned by uc_encode_json has a null terminator appended to the data, allowing the data member to be used as a string. The length of the buffer does not include the null terminator, so the buffer can be sent to a network connection or file without including the null terminator. The pretty version does a pretty print of the json object, with a default indent step of 2.

Convenience Routines

void print(UniversalContainer&)

Prints a UniversalContainer to stdout. This routine uses uc_encode_ini to serialize the container, and so any map keys starting with the # symbol are not displayed.

UniversalContainer load_ini_file(const char* filename)

This function reads a file in ini format, and returns a UniversalContainer containing the contents.

bool write_ini_file(const char* filename, UniversalContainer& uc)

This function writes out a UniversalContainer to the given file, using ini format.

UniversalContainer uc_from_json_file(const char* fname)

This function reads a file containing a JSON object and returns the corresponding UniversalContainer.