Squashed 'third_party/boostorg/serialization/' content from commit 738695b
Change-Id: I48528198ad1f62b90288d249eb2243d4db02fd5d
git-subtree-dir: third_party/boostorg/serialization
git-subtree-split: 738695b70733f9d592a570fb17a505d6a029b48a
diff --git a/doc/archives.html b/doc/archives.html
new file mode 100644
index 0000000..0f16227
--- /dev/null
+++ b/doc/archives.html
@@ -0,0 +1,458 @@
+<!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>