| <!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>. |
| <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> |
| </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.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 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 { |
| |
| 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 thier 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> |
