cereal
A C++11 library for serialization
Classes | List of all members
cereal::XMLOutputArchive Class Reference

An output archive designed to save data to XML. More...

#include </home/shane/workspace/cereal/include/cereal/archives/xml.hpp>

Inheritance diagram for cereal::XMLOutputArchive:
cereal::OutputArchive< XMLOutputArchive > cereal::traits::TextArchive cereal::detail::OutputArchiveBase

Classes

struct  NodeInfo
 A struct that contains metadata about a node. More...
 
class  Options
 A class containing various advanced options for the XML archive. More...
 

Public Member Functions

Common Functionality

Common use cases for directly interacting with an XMLOutputArchive

 XMLOutputArchive (std::ostream &stream, Options const &options=Options::Default())
 Construct, outputting to the provided stream upon destruction. More...
 
 ~XMLOutputArchive () CEREAL_NOEXCEPT
 Destructor, flushes the XML.
 
void saveBinaryValue (const void *data, size_t size, const char *name=nullptr)
 Saves some binary data, encoded as a base64 string, with an optional name. More...
 
Internal Functionality

Functionality designed for use by those requiring control over the inner mechanisms of the XMLOutputArchive

void startNode ()
 Creates a new node that is a child of the node at the top of the stack. More...
 
void finishNode ()
 Designates the most recently added node as finished.
 
void setNextName (const char *name)
 Sets the name for the next node created with startNode.
 
template<class T >
void saveValue (T const &value)
 Saves some data, encoded as a string, into the current top level node. More...
 
void saveValue (uint8_t const &value)
 Overload for uint8_t prevents them from being serialized as characters.
 
void saveValue (int8_t const &value)
 Overload for int8_t prevents them from being serialized as characters.
 
template<class T >
void insertType ()
 Causes the type to be appended as an attribute to the most recently made node if output type is set to true.
 
void appendAttribute (const char *name, const char *value)
 Appends an attribute to the current top level node.
 
- Public Member Functions inherited from cereal::OutputArchive< XMLOutputArchive >
 OutputArchive (XMLOutputArchive *const derived)
 Construct the output archive. More...
 
OutputArchiveoperator= (OutputArchive const &)=delete
 
XMLOutputArchiveoperator() (Types &&...args)
 Serializes all passed in data. More...
 
std::uint32_t registerSharedPointer (void const *addr)
 Registers a shared pointer with the archive. More...
 
std::uint32_t registerPolymorphicType (char const *name)
 Registers a polymorphic type name with the archive. More...
 
XMLOutputArchiveoperator& (T &&arg)
 Serializes passed in data. More...
 
XMLOutputArchiveoperator<< (T &&arg)
 Serializes passed in data. More...
 
- Public Member Functions inherited from cereal::detail::OutputArchiveBase
 OutputArchiveBase (OutputArchiveBase &&) CEREAL_NOEXCEPT
 
OutputArchiveBaseoperator= (OutputArchiveBase &&) CEREAL_NOEXCEPT
 

Additional Inherited Members

- Public Types inherited from cereal::OutputArchive< XMLOutputArchive >
using is_loading = std::false_type
 Indicates this archive is not intended for loading. More...
 
using is_saving = std::true_type
 Indicates this archive is intended for saving. More...
 

Detailed Description

An output archive designed to save data to XML.

This archive uses RapidXML to build an in memory XML tree of the data it serializes before outputting it to its stream upon destruction. This archive should be used in an RAII fashion, letting the automatic destruction of the object cause the flush to its stream.

XML archives provides a human readable output but at decreased performance (both in time and space) compared to binary archives.

XML benefits greatly from name-value pairs, which if present, will name the nodes in the output. If these are not present, each level of the output tree will be given an automatically generated delimited name.

The precision of the output archive controls the number of decimals output for floating point numbers and should be sufficiently large (i.e. at least 20) if there is a desire to have binary equality between the numbers output and those read in. In general you should expect a loss of precision when going from floating point to text and back.

XML archives can optionally print the type of everything they serialize, which adds an attribute to each node.

XML archives do not output the size information for any dynamically sized structure and instead infer it from the number of children for a node. This means that data can be hand edited for dynamic sized structures and will still be readable. This is accomplished through the cereal::SizeTag object, which will also add an attribute to its parent field.

Constructor & Destructor Documentation

cereal::XMLOutputArchive::XMLOutputArchive ( std::ostream &  stream,
Options const &  options = Options::Default() 
)
inline

Construct, outputting to the provided stream upon destruction.

Parameters
streamThe stream to output to. Note that XML is only guaranteed to flush its output to the stream upon destruction.
optionsThe XML specific options to use. See the Options struct for the values of default parameters

Member Function Documentation

void cereal::XMLOutputArchive::saveBinaryValue ( const void *  data,
size_t  size,
const char *  name = nullptr 
)
inline

Saves some binary data, encoded as a base64 string, with an optional name.

This can be called directly by users and it will automatically create a child node for the current XML node, populate it with a base64 encoded string, and optionally name it. The node will be finished after it has been populated.

template<class T >
void cereal::XMLOutputArchive::saveValue ( T const &  value)
inline

Saves some data, encoded as a string, into the current top level node.

The data will be be named with the most recent name if one exists, otherwise it will be given some default delimited value that depends upon the parent node

void cereal::XMLOutputArchive::startNode ( )
inline

Creates a new node that is a child of the node at the top of the stack.

Nodes will be given a name that has either been pre-set by a name value pair, or generated based upon a counter unique to the parent node. If you want to give a node a specific name, use setNextName prior to calling startNode.

The node will then be pushed onto the node stack.


The documentation for this class was generated from the following file: