.TH "cereal::XMLInputArchive" 3 "Mon Oct 26 2026 02:55:37" "cereal" \" -*- nroff -*- .ad l .nh .SH NAME cereal::XMLInputArchive \- An output archive designed to load data from XML\&. .SH SYNOPSIS .br .PP .PP \fR#include \fP .PP Inherits \fBcereal::InputArchive< XMLInputArchive >\fP, and \fBcereal::traits::TextArchive\fP\&. .SS "Classes" .in +1c .ti -1c .RI "struct \fBNodeInfo\fP" .br .RI "A struct that contains metadata about a node\&. " .in -1c .SS "Public Member Functions" .PP .RI "\fBCommon Functionality\fP" .br Common use cases for directly interacting with an \fBXMLInputArchive\fP .PP .in +1c .in +1c .ti -1c .RI "\fBXMLInputArchive\fP (std::istream &stream)" .br .RI "Construct, reading in from the provided stream\&. " .ti -1c .RI "void \fBloadBinaryValue\fP (void *data, size_t size, const char *name=nullptr)" .br .RI "Loads some binary data, encoded as a base64 string, optionally specified by some name\&. " .in -1c .in -1c Public Member Functions inherited from \fBcereal::InputArchive< XMLInputArchive >\fP .in +1c .ti -1c .RI "\fBInputArchive\fP (\fBXMLInputArchive\fP *const derived)" .br .RI "Construct the output archive\&. " .ti -1c .RI "\fBInputArchive\fP & \fBoperator=\fP (\fBInputArchive\fP const &)=delete" .br .ti -1c .RI "\fBXMLInputArchive\fP & \fBoperator()\fP (Types &&\&.\&.\&. args)" .br .RI "Serializes all passed in data\&. " .ti -1c .RI "void \fBserializeDeferments\fP ()" .br .RI "Serializes any data marked for deferment using defer\&. " .ti -1c .RI "std::shared_ptr< void > \fBgetSharedPointer\fP (std::uint32_t const id)" .br .RI "Retrieves a shared pointer given a unique key for it\&. " .ti -1c .RI "void \fBregisterSharedPointer\fP (std::uint32_t const id, std::shared_ptr< void > ptr)" .br .RI "Registers a shared pointer to its unique identifier\&. " .ti -1c .RI "std::string \fBgetPolymorphicName\fP (std::uint32_t const id)" .br .RI "Retrieves the string for a polymorphic type given a unique key for it\&. " .ti -1c .RI "void \fBregisterPolymorphicName\fP (std::uint32_t const id, std::string const &name)" .br .RI "Registers a polymorphic name string to its unique identifier\&. " .in -1c .in +1c .ti -1c .RI "\fBXMLInputArchive\fP & \fBoperator&\fP (T &&arg)" .br .RI "Serializes passed in data\&. " .in -1c .in +1c .ti -1c .RI "\fBXMLInputArchive\fP & \fBoperator>>\fP (T &&arg)" .br .RI "Serializes passed in data\&. " .in -1c Public Member Functions inherited from \fBcereal::detail::InputArchiveBase\fP .in +1c .ti -1c .RI "\fBInputArchiveBase\fP (InputArchiveBase &&) \fBCEREAL_NOEXCEPT\fP" .br .ti -1c .RI "InputArchiveBase & \fBoperator=\fP (InputArchiveBase &&) \fBCEREAL_NOEXCEPT\fP" .br .in -1c .SS "Internal Functionality" Functionality designed for use by those requiring control over the inner mechanisms of the \fBXMLInputArchive\fP .in +1c .ti -1c .RI "template::value, !std::is_same< T, bool >::value, !std::is_same< T, char >::value, !std::is_same< T, unsigned char >::value, sizeof(T)< sizeof(long long)>=traits::sfinae > inline void \fBloadValue\fP(T &value) { value=static_cast< T >(std::stoul(itsNodes\&.top()\&.node\->value()));} template< class T, traits::EnableIf< std::is_unsigned< T >::value, !std::is_same< T, bool >::value, sizeof(T) >=sizeof(long long)> = traits::sfinae> \fBvalue\fP" .br .RI "Loads a type best represented as an unsigned long from the current top node\&. " .ti -1c .RI "void \fBstartNode\fP ()" .br .RI "Prepares to start reading the next node\&. " .ti -1c .RI "void \fBfinishNode\fP ()" .br .RI "Finishes reading the current node\&. " .ti -1c .RI "const char * \fBgetNodeName\fP () const" .br .ti -1c .RI "void \fBsetNextName\fP (const char *name)" .br .RI "Sets the name for the next node created with startNode\&. " .ti -1c .RI "template\fB::value\fP, std::is_same< T, bool >\fB::value\fP > = traits::sfinae> void \fBloadValue\fP (T &value)" .br .RI "Loads a bool from the current top node\&. " .ti -1c .RI "template\fB::value\fP, !std::is_same< T, bool >\fB::value\fP, sizeof(T)==sizeof(char)> = traits::sfinae> void \fBloadValue\fP (T &value)" .br .RI "Loads a char (signed or unsigned) from the current top node\&. " .ti -1c .RI "void \fBloadValue\fP (int8_t &value)" .br .RI "Load an int8_t from the current top node (ensures we parse entire number)\&. " .ti -1c .RI "void \fBloadValue\fP (uint8_t &value)" .br .RI "Load a uint8_t from the current top node (ensures we parse entire number)\&. " .ti -1c .RI "\fBif\fP (std::fpclassify(\fBvalue\fP) !=FP_SUBNORMAL) throw" .br .ti -1c .RI "void \fBloadValue\fP (double &value)" .br .RI "Loads a type best represented as a double from the current top node\&. " .ti -1c .RI "void \fBloadValue\fP (long double &value)" .br .RI "Loads a type best represented as a long double from the current top node\&. " .ti -1c .RI "template void \fBloadValue\fP (std::basic_string< CharT, Traits, Alloc > &str)" .br .RI "Loads a string from the current node from the current top node\&. " .ti -1c .RI "template void \fBloadSize\fP (T &value)" .br .RI "Loads the size of the current top node\&. " .ti -1c .RI "static size_t \fBgetNumChildren\fP (rapidxml::xml_node<> *node)" .br .RI "Gets the number of children (usually interpreted as size) for the specified node\&. " .in -1c .SS "Additional Inherited Members" .in +1c .ti -1c .RI "using \fBis_loading\fP" .br .RI "Indicates this archive is intended for loading\&. " .in -1c .in +1c .ti -1c .RI "using \fBis_saving\fP" .br .RI "Indicates this archive is not intended for saving\&. " .in -1c .SH "Detailed Description" .PP An output archive designed to load data from XML\&. This archive uses RapidXML to build an in memory XML tree of the data in the stream it is given before loading any types serialized\&. .PP As with the output XML archive, the preferred way to use this archive is in an RAII fashion, ensuring its destruction after all data has been read\&. .PP Input XML should have been produced by the \fBXMLOutputArchive\fP\&. Data can only be added to dynamically sized containers - the input archive will determine their size by looking at the number of child nodes\&. Data that did not originate from an \fBXMLOutputArchive\fP is not officially supported, but may be possible to use if properly formatted\&. .PP The \fBXMLInputArchive\fP does not require that nodes are loaded in the same order they were saved by \fBXMLOutputArchive\fP\&. Using name value pairs (NVPs), it is possible to load in an out of order fashion or otherwise skip/select specific nodes to load\&. .PP The default behavior of the input archive is to read sequentially starting with the first node and exploring its children\&. When a given NVP does not match the read in name for a node, the archive will search for that node at the current level and load it if it exists\&. After loading an out of order node, the archive will then proceed back to loading sequentially from its new position\&. .PP Consider this simple example where loading of some data is skipped: .PP .PP .nf // imagine the input file has someData(1\-9) saved in order at the top level node ar( someData1, someData2, someData3 ); // XML loads in the order it sees in the file ar( cereal::make_nvp( "hello", someData6 ) ); // NVP given does not // match expected NVP name, so we search // for the given NVP and load that value ar( someData7, someData8, someData9 ); // with no NVP given, loading resumes at its // current location, proceeding sequentially .fi .PP .SH "Constructor & Destructor Documentation" .PP .SS "cereal::XMLInputArchive::XMLInputArchive (std::istream & stream)\fR [inline]\fP" .PP Construct, reading in from the provided stream\&. Reads in an entire XML document from some stream and parses it as soon as serialization starts .PP \fBParameters\fP .RS 4 \fIstream\fP The stream to read from\&. Can be a stringstream or a file\&. .RE .PP .SH "Member Function Documentation" .PP .SS "const char * cereal::XMLInputArchive::getNodeName () const\fR [inline]\fP" Retrieves the current node name will return \fRnullptr\fP if the node does not have a name .SS "void cereal::XMLInputArchive::loadBinaryValue (void * data, size_t size, const char * name = \fRnullptr\fP)\fR [inline]\fP" .PP Loads some binary data, encoded as a base64 string, optionally specified by some name\&. This will automatically start and finish a node to load the data, and can be called directly by users\&. .PP Note that this follows the same ordering rules specified in the class description in regards to loading in/out of order .SS "void cereal::XMLInputArchive::startNode ()\fR [inline]\fP" .PP Prepares to start reading the next node\&. This places the next node to be parsed onto the nodes stack\&. .PP By default our strategy is to start with the document root node and then recursively iterate through all children in the order they show up in the document\&. We don't need to know NVPs do to this; we'll just blindly load in the order things appear in\&. .PP We check to see if the specified NVP matches what the next automatically loaded node is\&. If they match, we just continue as normal, going in order\&. If they don't match, we attempt to find a node named after the NVP that is being loaded\&. If that NVP does not exist, we throw an exception\&. .SH "Member Data Documentation" .PP .SS "template::value, !std::is_same< T, bool >::value, !std::is_same< T, char >::value, !std::is_same< T, unsigned char >::value, sizeof(T)< sizeof(long long)>=traits::sfinae > inline void \fBloadValue\fP(T &value) { value=static_cast< T >(std::stoul(itsNodes\&.top()\&.node\->value()));} template< class T, traits::EnableIf< std::is_unsigned< T >::value, !std::is_same< T, bool >::value, sizeof(T) >=sizeof(long long)> = traits::sfinae> cereal::XMLInputArchive::value" .PP Loads a type best represented as an unsigned long from the current top node\&. .PP \fBTemplate Parameters\fP .RS 4 \fItraits::EnableIf<\fP std::is_unsigned< T >::value, !std::is_same< T, bool >::value, !std::is_same< T, char >::value, !std::is_same< T, unsigned char >::value, sizeof(T)< sizeof(long long)>=traits::sfinae > inline void \fBloadValue(T &value)\fP { value=static_cast< T >(std::stoul(itsNodes\&.top()\&.node->\fBvalue()\fP));} template< class T, traits::EnableIf< std::is_unsigned< T >::value, !std::is_same< T, bool >::value, sizeof(T) >=sizeof(long long)> Loads a type best represented as an unsigned long long from the current top node .RE .PP .SH "Author" .PP Generated automatically by Doxygen for cereal from the source code\&.