mirror of
https://github.com/boostorg/serialization.git
synced 2026-01-28 07:32:10 +00:00
513 lines
18 KiB
HTML
513 lines
18 KiB
HTML
<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link rel="stylesheet" type="text/css" href="../../../boost.css">
|
|
<link rel="stylesheet" type="text/css" href="style.css">
|
|
<title>Serialization - Archives</title>
|
|
</head>
|
|
<body link="#0000ff" vlink="#800080">
|
|
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
|
|
<tr>
|
|
<td valign="top" width="300">
|
|
<h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
|
|
</td>
|
|
<td valign="top">
|
|
<h1 align="center">Serialization</h1>
|
|
<h2 align="center">Archive Concept</h2>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<dl class="page-index">
|
|
<dt><a href="#saving_interface">Saving</a>
|
|
<dt><a href="#loading_interface">Loading</a>
|
|
<dt><a href="#archive_models">Models</a>
|
|
<dt><a href="#exceptions">Exceptions</a>
|
|
<dt><a href="#charactersets">Character Sets</a>
|
|
</dl>
|
|
|
|
An <strong>Archive</strong> contains a sequence of bytes created from
|
|
an arbitrary nested set of C++ data structures.
|
|
|
|
<h4><a name="saving_interface">Saving</a></h4>
|
|
An object that saves data to an archive implements the following interface.
|
|
<pre><code>
|
|
class oarchive : ...
|
|
{
|
|
...
|
|
public:
|
|
// called to save objects
|
|
template<class T>
|
|
oarchive & operator<<(const T & t);
|
|
|
|
template<class T>
|
|
oarchive & operator&(T & t){
|
|
return *this << t;
|
|
}
|
|
|
|
void save_binary(const void *address, std::size_t count);
|
|
|
|
template<class T>
|
|
register_type(T * t = NULL);
|
|
|
|
unsigned int library_version() const;
|
|
|
|
struct is_saving {
|
|
typedef mpl::bool_<true> type;
|
|
BOOST_STATIC_CONSTANT(bool, value=true);
|
|
};
|
|
|
|
struct is_loading {
|
|
typedef mpl::bool_<false> type;
|
|
BOOST_STATIC_CONSTANT(bool, value=false);
|
|
};
|
|
...
|
|
};
|
|
</code></pre>
|
|
|
|
The template parameter <code>T</code> must correspond to a type which
|
|
models the <a href="serialization.html"><strong>Serializable</strong></a> concept.
|
|
|
|
<dl>
|
|
|
|
<dt><h4><code>
|
|
template<class T>
|
|
oarchive & operator<<(const T & t);
|
|
|
|
template<class T>
|
|
oarchive & operator&(T & t);
|
|
</code></h4></dt>
|
|
<dd>
|
|
<p>
|
|
Appends an object of type T to the archive. The object may be
|
|
<ul>
|
|
<li>A primitive data type such as int, char, float, etc.
|
|
<li>A class or struct for which a <code style="white-space: normal">serialize</code>
|
|
function has been defined.
|
|
<li>A pointer to a serializable object.
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt><h4><code>
|
|
void save_binary(const void *address, std::size_t count);
|
|
</code></h4></dt>
|
|
<dd>
|
|
Appends to the archive <code style="white-space: normal">count</code> bytes found at
|
|
<code style="white-space: normal">address</code>.
|
|
</dd>
|
|
<dt><h4><code>
|
|
template<class T>
|
|
register_type(T * t = NULL);
|
|
</code></h4></dt>
|
|
<dd>
|
|
Appends a sequential integer to the archive. This integer becomes the "key" used
|
|
to look up the class type when the archive is later loaded. This process is
|
|
referred to as "class registration". It is only necessary to invoke this function for
|
|
objects of derived classes which are serialized through a base class pointer. This
|
|
is explained in detail in
|
|
<a href="special.html#derivedpointers">Special Considerations - Derived Pointers</a>.
|
|
</dd>
|
|
|
|
<dt><h4><code>
|
|
unsigned int library_version() const;
|
|
</code></h4></dt>
|
|
<dd>
|
|
Returns the version number of the serialization library that created the archive.
|
|
This number will be incremented each time the library is altered in such a way
|
|
that serialization could be altered for some type. For example, suppose the type
|
|
used for a count of collection members is changed. The code that loads collections
|
|
might be conditioned on the library version to make sure that libraries created by
|
|
previous versions of the library can still be read.
|
|
</dd>
|
|
|
|
<dt><h4><code>
|
|
is_saving::type = mpl::bool<true>;
|
|
is_saving::value= true;
|
|
is_loading::type = mpl::bool<false>;
|
|
is_loading::value= false;
|
|
</code></h4></dt>
|
|
<dd>
|
|
These integral constants permit archive attributes to be queried at compiler
|
|
or execution time. They can used to generate code with boost
|
|
<a href="../../mpl/doc/index.html">mpl</a>
|
|
. For and example
|
|
showing how these can beused, see the implementation of
|
|
<a target="splithpp" href="../../../boost/serialization/split_free.hpp">split_free.hpp</a>.
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<h4><a name="loading_interface">Loading</a></h4>
|
|
An object that saves data to an archive implements the following interface.
|
|
|
|
<pre><code>
|
|
class iarchive : ...
|
|
{
|
|
...
|
|
public:
|
|
// called to load objects
|
|
template<class T>
|
|
iarchive & operator>>(T & t);
|
|
|
|
template<class T>
|
|
iarchive & operator&(T & t){
|
|
return *this >> t;
|
|
}
|
|
|
|
void delete_created_pointers();
|
|
|
|
void load_binary(void *address, std::size_t count);
|
|
|
|
template<class T>
|
|
register_type(T * t = NULL);
|
|
|
|
reset_object_address(void * old_address, void * new_address);
|
|
|
|
unsigned int library_version() const;
|
|
|
|
struct is_saving {
|
|
typedef mpl::bool_<false> type;
|
|
BOOST_STATIC_CONSTANT(bool, value=false);
|
|
};
|
|
|
|
struct is_loading {
|
|
typedef mpl::bool_<true> type;
|
|
BOOST_STATIC_CONSTANT(bool, value=true);
|
|
};
|
|
...
|
|
};
|
|
|
|
} //namespace archive
|
|
) //namespace boost
|
|
|
|
</code></pre>
|
|
|
|
<dl>
|
|
|
|
The template parameter <code>T</code> must correspond to a type which
|
|
models the <a href="serialization.html"><strong>Serializable</strong></a> concept.
|
|
|
|
<dt><h4><code>
|
|
template<class T>
|
|
iarchive & operator>>(T & t);
|
|
|
|
template<class T>
|
|
iarchive & operator&(T & t);
|
|
</code></h4></dt>
|
|
<dd>
|
|
<p>
|
|
Retrieves an object of type T from the archive. The object may be
|
|
<ul>
|
|
<li>A primitive data type such as int, char, float, etc.
|
|
<li>A class or struct for which a <code style="white-space: normal">serialize</code>
|
|
function has been defined.
|
|
<li>A pointer to a serializable object.
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt><h4><code>
|
|
void load_binary(void *address, std::size_t count);
|
|
</code></h4></dt>
|
|
<dd>
|
|
Retrieves from the archive <code style="white-space: normal">count</code> bytes and stores
|
|
them in memory starting at <code style="white-space: normal">address</code>.
|
|
</dd>
|
|
|
|
<dt><h4><code>
|
|
void delete_created_pointers();
|
|
</code></h4></dt>
|
|
<dd>
|
|
Deletes all objects created by the loading of pointers. This can be used to
|
|
avoid memory leaks that might otherwise occur if pointers are being loaded
|
|
and the archive load encounters an exception.
|
|
</dd>
|
|
|
|
<dt><h4><code>
|
|
template<class T>
|
|
register_type(T * t = NULL);
|
|
</code></h4></dt>
|
|
<dd>
|
|
Retrieves the next integer from the archive and adds an entry to a table which
|
|
relates the integer to the type T. When pointers are loaded, this integer is
|
|
used to indicate which object type should be created. This process is
|
|
referred to as "class registration". It is only necessary to invoke this function for
|
|
objects of derived classes which are serialized through a base class pointer. If this
|
|
function is called during the saving of data to the archive, it should be called during the
|
|
loading of the data from the archive at the same point in the serialization process.
|
|
This is explained in detail in
|
|
<a href="special.html#derivedpointers">Special Considerations - Derived Pointers</a>
|
|
</dd>
|
|
|
|
<dt><h4><code>
|
|
void reset_object_address(void * new_address, void * old_address);
|
|
</code></h4></dt>
|
|
<dd>
|
|
In order to facilitate loading of objects through a pointer
|
|
and to elminate redundant loading of objects, this system implements object address tracking.
|
|
Normally this is done automatically with no action required on the part of the user. However,
|
|
there are cases when an object must be de-serialized to a temporary location then
|
|
moved to its final destination. This is common in loading collections.
|
|
<p>
|
|
In such cases, reset_object_address should be invoked to communicate the final address
|
|
of the last item loaded. This permits the internal tables to be correctly maintained
|
|
in these special case.
|
|
</dd>
|
|
|
|
<dt><h4><code>
|
|
unsigned int library_version() const;
|
|
</code></h4></dt>
|
|
<dd>
|
|
Returns the version number of the serialization library that created the archive.
|
|
This number will be incremented each time the library is altered in such a way
|
|
that serialization could be altered for some type. For example, suppose the type
|
|
used for a count of collection members is changed. The code that loads collections
|
|
might be conditioned on the library version to make sure that libraries created by
|
|
previous versions of the library can still be read.
|
|
</dd>
|
|
|
|
<dt><h4><code>
|
|
is_saving::type = mpl::bool<false>;
|
|
is_saving::value= false;
|
|
is_loading::type = mpl::bool<true>;
|
|
is_loading::value= true;
|
|
</code></h4></dt>
|
|
<dd>
|
|
These integral constants permit archive attributes to be queried at compiler
|
|
or execution time. They can used to generate code with boost
|
|
<a href="../../mpl/doc/index.html">mpl</a>
|
|
. For and example
|
|
showing how these can beused, see the implementation of
|
|
<a target="splithpp" href="../../../boost/serialization/split_free.hpp">split_free.hpp</a>.
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
There are archives based on text, binary and XML file
|
|
formats but all have the above interface. Given that all archives present
|
|
the same public interface, specifcation of serialization is exactly the same
|
|
for all archives. Archive classes have other members not mentioned here.
|
|
However they are related to the internal functioning of the library and
|
|
are not meant to be called by users of an archive. Implementation of new
|
|
archives is discussed in
|
|
<a href="archive_reference.html#implementation">New Archives - Implementation</a>.
|
|
|
|
<p>
|
|
The existence of the <code style="white-space: normal"><<</code>
|
|
and <code style="white-space: normal">>></code> suggest
|
|
a relationship between archives and C++ i/o streams. <strong>Archives are not
|
|
C++ i/o streams</strong>. All the archives included with this system take a stream
|
|
as an argument in the constructor and that stream is used for output or input.
|
|
However, this is not a requirement of the serialization functions or the
|
|
archive interface. It just turns out that the archives written so far have
|
|
found it useful to base their implementation on streams.
|
|
|
|
<h3><a name="archive_models">Archive Models</a></h3>
|
|
This library includes a various implementation of the Archive concept.
|
|
|
|
An archive is defined by two complementary classes. One is for saving data while
|
|
the other is for loading it.
|
|
|
|
|
|
This library includes a number of archive implementations that are "ready to go" for the
|
|
most common requirements. These classes implement the archive concept for differing data formats.
|
|
They can be used "as is" or as a basis for developing one's own particular type of archive.
|
|
An archive is defined by two complementary classes. One is for saving data while the other is for loading it.
|
|
|
|
To invoke serialization using one of
|
|
these archives, one or more of the following header files must be
|
|
included in the code module containing the serialization code.
|
|
<pre><code>
|
|
// a portable text archive</a>
|
|
<a href="../../../boost/archive/text_oarchive.hpp" target="text_oarchive_cpp">boost::archive::text_oarchive(ostream &s)</a> // saving
|
|
<a href="../../../boost/archive/text_iarchive.hpp" target="text_iarchive_cpp">boost::archive::text_iarchive(istream &s)</a> // loading
|
|
|
|
// a portable text archive using a wide character stream</a>
|
|
<a href="../../../boost/archive/text_woarchive.hpp">boost::archive::text_woarchive(wostream &s)</a> // saving
|
|
<a href="../../../boost/archive/text_wiarchive.hpp">boost::archive::text_wiarchive(wistream &s)</a> // loading
|
|
|
|
// a non-portable native binary archive</a>
|
|
<a href="../../../boost/archive/binary_oarchive.hpp" target="binary_oarchive_cpp">boost::archive::binary_oarchive(ostream &s)</a> // saving
|
|
<a href="../../../boost/archive/binary_iarchive.hpp" target="binary_iarchive_cpp">boost::archive::binary_iarchive(istream &s)</a> // loading
|
|
<!--
|
|
// a non-portable native binary archive which use wide character streams
|
|
<a href="../../../boost/archive/binary_woarchive.hpp">boost::archive::binary_woarchive(wostream &s)</a> // saving
|
|
<a href="../../../boost/archive/binary_wiarchive.hpp">boost::archive::binary_wiarchive(wistream &s)</a> // loading
|
|
-->
|
|
// a portable XML archive</a>
|
|
<a href="../../../boost/archive/xml_oarchive.hpp" target="xml_oarchive_cpp">boost::archive::xml_oarchive(ostream &s)</a> // saving
|
|
<a href="../../../boost/archive/xml_iarchive.hpp" target="xml_iarchive_cpp">boost::archive::xml_iarchive(istream &s)</a> // loading
|
|
|
|
// a portable XML archive which uses wide characters - use for utf-8 output</a>
|
|
<a href="../../../boost/archive/xml_woarchive.hpp" target="xml_woarchive_cpp">boost::archive::xml_woarchive(wostream &s)</a> // saving
|
|
<a href="../../../boost/archive/xml_wiarchive.hpp" target="xml_wiarchive_cpp">boost::archive::xml_wiarchive(wistream &s)</a> // loading
|
|
</code></pre>
|
|
|
|
All of these archives implement the same inteface. Hence, it should suffice to describe only one
|
|
of them in detail. For this purpose we will use the text archive.
|
|
|
|
|
|
<pre><code>
|
|
namespace boost {
|
|
namespace archive {
|
|
|
|
enum archive_flags {
|
|
no_header = 1, // suppress archive header info
|
|
no_codecvt = 2, // suppress alteration of codecvt facet
|
|
no_xml_tag_checking = 4 // suppress checking of xml tags - igored on saving
|
|
};
|
|
|
|
} // archive
|
|
} // boost
|
|
</code></pre>
|
|
|
|
<pre><code>
|
|
namespace boost {
|
|
namespace archive {
|
|
|
|
template<class OStream>
|
|
class text_oarchive : ...
|
|
{
|
|
...
|
|
public:
|
|
... // implementation of <strong>Archive</strong> concept
|
|
oarchive(OStream & os, unsigned int flags = 0);
|
|
~oarchive();
|
|
};
|
|
|
|
} // archive
|
|
} // boost
|
|
</code></pre>
|
|
|
|
<dl>
|
|
|
|
<dt><h4>
|
|
Template parameter <code>OStream</code>
|
|
</h4></dt>
|
|
<dd>
|
|
An class derived from <code style="white-space: normal">basic_istream<char>
|
|
</code>
|
|
</dd>
|
|
|
|
<dt><h4><code>
|
|
oarchive(OStream & os, unsigned int flags = 0);
|
|
</code></h4></dt>
|
|
<dd>
|
|
Contructs an archive given an open <code style="white-space: normal">stream</code> as
|
|
an argument and optional flags. For most applications there will be no need to use flags.
|
|
Flags are defined by <code style="white-space: normal">enum archive_flags</code> enumerator.
|
|
Multiple flags can be combined with the <code style="white-space: normal">|</code> operator.
|
|
|
|
By default, archives prepend
|
|
output with initial data which helps identify them as archives produced by this system.
|
|
This permits a more graceful handling of the case where an attempt is made to load an archive
|
|
from an invalid file format. In addition to this, each type of archive might have
|
|
its own information. For example, native binary archives include information about
|
|
sizes of native types and endianess to gracefully handle the case where it has been
|
|
erroneously assumed that such an archive is portable across platforms. In some cases,
|
|
where this extra overhead might be considered objectionable, it can be suppressed with the
|
|
<code style="white-space: normal">no_header</code> flag.
|
|
<p>
|
|
In some cases, an archive may alter (and later restore)
|
|
the codecvt facet of the stream locale. To suppress this action,
|
|
include the <code style="white-space: normal">no_codecvt</code> flag.
|
|
<p>
|
|
XML archives contain nested tags signifying the start and end of data fields.
|
|
These tags are normally checked for agreement with the object name when
|
|
data is loaded. If a mismatch occurs an exception is thrown. It's possible
|
|
that this may not be desired behavior. To suppress this checking of XML
|
|
tags, use <code style="white-space: normal">no_xml_tag_checking</code> flag.
|
|
</dd>
|
|
|
|
<dt><h4><code>
|
|
~oarchive();
|
|
</code></h4></dt>
|
|
<dd>
|
|
Destructor for an archive. This should be called before the stream is
|
|
closed. It restores any altered stream facets to their state before the
|
|
the archive was opened.
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<pre><code>
|
|
namespace boost {
|
|
namespace archive {
|
|
|
|
template<class IStream>
|
|
class text_iarchive : ...
|
|
{
|
|
...
|
|
public:
|
|
... // implementation of <strong>Archive</strong> concept
|
|
iarchive(IStream & is, unsigned int flags = 0);
|
|
~iarchive();
|
|
};
|
|
|
|
} //namespace archive
|
|
) //namespace boost
|
|
|
|
</code></pre>
|
|
|
|
<dl>
|
|
|
|
<dt><h4>
|
|
Template parameter <code>IStream</code>
|
|
</h4></dt>
|
|
<dd>
|
|
An class derived from <code style="white-space: normal">basic_ostream<char>
|
|
</code>
|
|
</dd>
|
|
|
|
<dt><h4><code>
|
|
iarchive(IStream & is, unsigned int flags = 0);
|
|
</code></h4></dt>
|
|
<dd>
|
|
Contructs an archive given an open <code style="white-space: normal">stream</code> as
|
|
an argument and optional flags. If flags are used, they should be the same
|
|
as those used when the archive was created. Function and usage of flags is described
|
|
above.
|
|
</dd>
|
|
|
|
<dt><h4><code>
|
|
~iarchive();
|
|
</code></h4></dt>
|
|
<dd>
|
|
Destructor for an archive. This should be called before the stream is
|
|
closed. It restores any altered stream facets to thier state before the
|
|
the archive was opened.
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<h3><a name="exceptions">Exceptions</h3>
|
|
All of the archive classes included may throw exceptions. The list of exceptions that might
|
|
be throw can be found in section <a target="detail" href="exceptions.html">Archive Exceptions</a>
|
|
of this documentation.
|
|
|
|
<h3><a name="charactersets">Character Sets</h3>
|
|
This library includes two archive classes for XML. The wide character
|
|
version (<code style="white-space: normal">xml_w?archive</code>) renders it output as UTF-8 which can
|
|
handle any wide character without loss of information.
|
|
<code style="white-space: normal">std::string</code> data is converted from multi-byte format to wide
|
|
character format using the current <code style="white-space: normal">
|
|
locale</code>. Hence this version should give a fair rendering of all
|
|
C++ data for all cases. This could result in some unexpected behavior.
|
|
Suppose an <code style="white-space: normal">std::string</code>
|
|
is created with the <code style="white-space: normal">locale</code> character
|
|
set to hebrew characters. On output this is converted to wide characters.
|
|
On input however, there could be a problem if the <code style="white-space: normal">locale</code> is
|
|
not set the same as when the archive is created.
|
|
<p>
|
|
The normal character version (<code style="white-space: normal">xml_?archive</code>) renders
|
|
<code style="white-space: normal">std::string</code> output without any conversion. Though this may work
|
|
fine for serialization, it may create difficulties if the XML archive is used
|
|
for some other purpose.
|
|
<hr>
|
|
<p><i>© Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004.
|
|
Distributed under the Boost Software License, Version 1.0. (See
|
|
accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
</i></p>
|
|
</body>
|
|
</html>
|