0c8a1d615a
fixes warnings Seen with all versions of msvc from (at least) 9.0 up to 14.1. Signed-off-by: Daniela Engert dani@ngrt.de fixed pr #53, #52, #50, #49, #34, #29, #23, #25, #20, #14, #7
459 lines
19 KiB
HTML
459 lines
19 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=UTF-8">
|
|
<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 Concepts</h2>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<dl class="page-index">
|
|
<dt><a href="#saving_interface">Saving Archive Concept</a>
|
|
<dt><a href="#loading_interface">Loading Archive Concept</a>
|
|
<dt><a href="#archive_models">Models</a>
|
|
<dt><a href="#exceptions">Exceptions</a>
|
|
<dt><a href="#charactersets">Character Sets</a>
|
|
</dl>
|
|
<h4>Notation</h4>
|
|
In the following descriptions
|
|
<ul>
|
|
<li><code>SA</code> is an type modeling the <a href="#saving_interface">Saving Archive Concept</a>.
|
|
<li><code>sa</code> is an instance of type SA.
|
|
<li><code>LA</code> is an type modeling the <a href="#loading_interface">Loading Archive Concept</a>.
|
|
<li><code>la</code> is an instance of type LA.
|
|
<li><code>T</code> is an <a href="serialization.html"><strong>Serializable</strong></a> Type.
|
|
<li><code>x</code> is an instance of type T Type.
|
|
<li><code>u,v</code> is a pointer to a an instance of type T.
|
|
<li><code>count</code> is an instance of a type that can be converted to <code>std::size_t</code>.
|
|
</ul>
|
|
<h4><a name="saving_interface">Saving Archive Concept</a></h4>
|
|
<h4>Associated Types</h4>
|
|
Intuitively, a type modeling this concept will generate a sequence of bytes
|
|
corresponding to an arbitrary set of C++ data structures. Each type modeling the
|
|
Saving Archive concept (SA) may be associated with another type modeling the
|
|
<a href="#loading_interface">Loading Archive Concept</a>(LA).
|
|
This associated type will perform the inverse operation.
|
|
That is, given a sequence of bytes generated by SA, it will generate a set of
|
|
C++ data structures that is equivalent to the original.
|
|
The notion of equivalence is defined by the implementations of the pair of archives and the
|
|
way the data are rendered <a href="serialization.html">serializable</a>.
|
|
<p>
|
|
<h4>Valid Expressions</h4>
|
|
<dl>
|
|
<dt><h4><code>
|
|
SA::is_saving
|
|
</code></h4></dt>
|
|
<dd>
|
|
Returns the Boost MPL Integral Constant type boost::mpl::bool_<true>
|
|
</dd>
|
|
<dt><h4><code>
|
|
SA::is_loading
|
|
</code></h4></dt>
|
|
<dd>
|
|
Returns the Boost MPL Integral Constant type boost::mpl::bool_<false>
|
|
</dd>
|
|
<dt><h4><code>
|
|
sa << x
|
|
<br>
|
|
sa & x
|
|
</code></h4></dt>
|
|
<dd>
|
|
These expressions must perform exactly the same function. They append the
|
|
value of <code style="white-space: normal">x</code> along with other information to <code>sa</code>.
|
|
This other information is defined by the implementation of the archive.
|
|
Typically this information is that which is required by a corresponding
|
|
Loading Archive type to properly restore the value of <code>x</code>.
|
|
<p>
|
|
Returns a reference to <code>sa</code>.
|
|
</dd>
|
|
<dt><h4><code>
|
|
sa.save_binary(u, count)
|
|
</code></h4></dt>
|
|
<dd>
|
|
Appends to the archive <code style="white-space: normal">size_t(count)</code> bytes found at
|
|
<code style="white-space: normal">u</code>.
|
|
</dd>
|
|
<dt><h4><code>
|
|
sa.register_type<T>()
|
|
<br>
|
|
sa.register_type(u)
|
|
</code></h4></dt>
|
|
<dd>
|
|
Appends information about class T to the archive. This information is used to
|
|
construct the correct class when a derived pointer is loaded by a corresponding
|
|
Loading Archive type.
|
|
Invocation of this member function is referred to as "class registration".
|
|
This is explained in detail in
|
|
<a href="special.html#derivedpointers">Special Considerations - Derived Pointers</a>.
|
|
The second syntax is included to permit this function to be called on non-conforming
|
|
compilers when <code style="white-space: normal">sa</code> is a template argument.
|
|
For more information, see <a target="detail" href="implementation.html#tempatesyntax">Template Invocation syntax</a>
|
|
</dd>
|
|
<dt><h4><code>
|
|
sa.get_library_version()
|
|
</code></h4></dt>
|
|
<dd>
|
|
Returns an unsigned integer containing the current version number of the serialization
|
|
library. 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>
|
|
sa.get_helper<Helper>(void * const helper_instance_id = 0)
|
|
</code></h4></dt>
|
|
<dd>
|
|
See <code>la.get_helper<Helper>(void * const helper_instance_id = 0)</code>
|
|
below.
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<h4><a name="loading_interface">Loading Archive Concept</a></h4>
|
|
<h4>Associated Types</h4>
|
|
Each model of this concept presumes the
|
|
existence of a corresponding type modeling the
|
|
<a href="#saving_interface">Saving Archive Concept</a>.
|
|
The purpose of an instance of this concept is to convert a sequence of bytes
|
|
generated by this corresponding type to a set of C++ data structures
|
|
equivalent to the original.
|
|
<h4>Valid Expressions</h4>
|
|
<dl>
|
|
<dt><h4><code>
|
|
LA::is_saving
|
|
</code></h4></dt>
|
|
<dd>
|
|
Returns the Boost MPL Integral Constant type boost::mpl::bool_<false>
|
|
</dd>
|
|
<dt><h4><code>
|
|
LA::is_loading
|
|
</code></h4></dt>
|
|
<dd>
|
|
Returns the Boost MPL Integral Constant type boost::mpl::bool_<true>
|
|
</dd>
|
|
<dt><h4><code>
|
|
la >> x
|
|
<br>
|
|
la & x
|
|
</code></h4></dt>
|
|
<dd>
|
|
These expressions must perform exactly the same function.
|
|
Sets <code>x</code> to a value retrieved from <code>la</code>.
|
|
<p>
|
|
Returns a reference to <code>la</code>.
|
|
</dd>
|
|
<dt><h4><code>
|
|
la.load_binary(u, count)
|
|
</code></h4></dt>
|
|
<dd>
|
|
Retrieves from <code style="white-space: normal">la</code> <code style="white-space: normal">size_t(count)</code> bytes and stores
|
|
them in memory starting at <code style="white-space: normal">u</code>.
|
|
</dd>
|
|
<dt>
|
|
<dt><h4><code>
|
|
la.register_type<T>()
|
|
<br>
|
|
la.register_type(u)
|
|
</code></h4></dt>
|
|
<dd>
|
|
Retrieves information about class T from the archive. This information is used to
|
|
construct the correct class when loading a pointer to a derived class not
|
|
otherwise referred to in the program by name.
|
|
Invocation of this member function is referred to as "class registration".
|
|
This is explained in detail in
|
|
<a href="special.html#derivedpointers">Special Considerations - Derived Pointers</a>.
|
|
The second syntax is included to permit this function to be called on non-conforming
|
|
compilers when <code style="white-space: normal">la</code> is a template argument.
|
|
For more information, see <a target="detail" href="implementation.html#tempatesyntax">Template Invocation syntax</a>
|
|
</dd>
|
|
<dt><h4><code>
|
|
la.get_library_version()
|
|
</code></h4></dt>
|
|
<dd>
|
|
Returns an unsigned integer containing 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>
|
|
la.get_helper<Helper>(void * const helper_instance_id)
|
|
</code></h4></dt>
|
|
<dd>
|
|
Some otherwise unserializable types can be made serializable by inclusion of
|
|
a helper object. The iconic example of this is shared_ptr which needs this
|
|
helper object to keep track of previously loaded shared_ptr instances so they
|
|
can be "matched up" with subsequently loaded ones.
|
|
The first time <code style="white-space: normal">la.get_helper<Helper>(void * const helper_instance_id)</code>
|
|
is invoked for a given helper_instance_id, <code style="white-space: normal">Helper</code>, a default-constructed
|
|
<code style="white-space: normal">Helper</code> object is created, attached to
|
|
<code style="white-space: normal">la</code> and a reference to it is returned. Subsequent
|
|
invocations of <code style="white-space: normal">la.get_helper<Helper>(void * const helper_instance_id)</code> with the same id value return
|
|
a reference to the formerly constructed object. All objects created in this manner are
|
|
destroyed upon <code style="white-space: normal">la</code> destruction time. The purpose
|
|
of helper objects is discussed in
|
|
<a href="special.html#helpersupport">Special Considerations - Helper Support</a>.
|
|
</dd>
|
|
<dt><h4><code>
|
|
la.reset_object_address(v, u)
|
|
</code></h4></dt>
|
|
<dd>
|
|
Communicates to the archive that the object originally at address u has been
|
|
moved to address v.
|
|
<p>
|
|
When an object is loaded to a temporary variable and later moved to another location,
|
|
this function must be called in order communicate this fact. This permits the
|
|
archive to properly implement object tracking. Object tracking is required in order
|
|
to correctly implement serialization of pointers to instances of derived classes.
|
|
</dd>
|
|
<dt><h4><code>
|
|
la.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>
|
|
</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> suggests
|
|
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 various implementations 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</a> // saving
|
|
<a href="../../../boost/archive/text_iarchive.hpp" target="text_iarchive_cpp">boost::archive::text_iarchive</a> // loading
|
|
|
|
// a portable text archive using a wide character stream</a>
|
|
<a href="../../../boost/archive/text_woarchive.hpp">boost::archive::text_woarchive</a> // saving
|
|
<a href="../../../boost/archive/text_wiarchive.hpp">boost::archive::text_wiarchive</a> // loading
|
|
|
|
// a portable XML archive</a>
|
|
<a href="../../../boost/archive/xml_oarchive.hpp" target="xml_oarchive_cpp">boost::archive::xml_oarchive</a> // saving
|
|
<a href="../../../boost/archive/xml_iarchive.hpp" target="xml_iarchive_cpp">boost::archive::xml_iarchive</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</a> // saving
|
|
<a href="../../../boost/archive/xml_wiarchive.hpp" target="xml_wiarchive_cpp">boost::archive::xml_wiarchive</a> // loading
|
|
|
|
// a non-portable native binary archive</a>
|
|
<a href="../../../boost/archive/binary_oarchive.hpp" target="binary_oarchive_cpp">boost::archive::binary_oarchive</a> // saving
|
|
<a href="../../../boost/archive/binary_iarchive.hpp" target="binary_iarchive_cpp">boost::archive::binary_iarchive</a> // loading
|
|
|
|
<!--
|
|
// a non-portable native binary archive which use wide character streams
|
|
<a href="../../../boost/archive/binary_woarchive.hpp">boost::archive::binary_woarchive</a> // saving
|
|
<a href="../../../boost/archive/binary_wiarchive.hpp">boost::archive::binary_wiarchive</a> // loading
|
|
-->
|
|
|
|
</code></pre>
|
|
|
|
All of these archives implement the same interface. 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 {
|
|
|
|
class text_oarchive : ...
|
|
{
|
|
...
|
|
public:
|
|
... // implementation of the <strong>Saving Archive</strong> concept
|
|
text_oarchive(std::ostream & os, unsigned int flags = 0);
|
|
~text_oarchive();
|
|
};
|
|
|
|
} // archive
|
|
} // boost
|
|
</code></pre>
|
|
|
|
<dl>
|
|
|
|
<dt><h4><code>
|
|
text_oarchive(std::ostream & os, unsigned int flags = 0);
|
|
</code></h4></dt>
|
|
<dd>
|
|
Constructs 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>
|
|
~text_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
|
|
archive was opened.
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<pre><code>
|
|
namespace boost {
|
|
namespace archive {
|
|
|
|
class text_iarchive : ...
|
|
{
|
|
...
|
|
public:
|
|
... // implementation of the <strong>Loading Archive</strong> concept
|
|
text_iarchive(std::istream & is, unsigned int flags = 0);
|
|
~text_iarchive();
|
|
};
|
|
|
|
} //namespace archive
|
|
) //namespace boost
|
|
|
|
</code></pre>
|
|
|
|
<dl>
|
|
|
|
<dt><h4><code>
|
|
text_iarchive(std::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>
|
|
~text_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 their state before the
|
|
the archive was opened.
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
The <code style="white-space: normal">binary_oarchive</code> and
|
|
<code style="white-space: normal">binary_iarchive</code> classes are
|
|
implemented in terms of the more basic
|
|
<code style="white-space: normal">std::streambuf</code>. So, in addition
|
|
to the common class interface described above, they include the following
|
|
constructors:
|
|
<dl>
|
|
<dt><h4><code>
|
|
binary_oarchive(std::streambuf & bsb, unsigned int flags = 0);
|
|
</code></h4></dt>
|
|
and
|
|
<dt><h4><code>
|
|
binary_iarchive(std::streambuf & bsb, unsigned int flags = 0);
|
|
</code></h4></dt>
|
|
</dl>
|
|
|
|
<h3><a name="exceptions">Exceptions</h3>
|
|
All of the archive classes included may throw exceptions. The list of exceptions that might
|
|
be thrown 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 its 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>
|