Boost_1_39_0/libs/serialization/doc/archives.html

   1 <!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <link rel="stylesheet" type="text/css" href="../../../boost.css">
   6 <link rel="stylesheet" type="text/css" href="style.css">
   7 <title>Serialization - Archives</title>
   8 </head>
   9 <body link="#0000ff" vlink="#800080">
  10 <table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
  11   <tr>
  12     <td valign="top" width="300">
  13       <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
  14     </td>
  15     <td valign="top">
  16       <h1 align="center">Serialization</h1>
  17       <h2 align="center">Archive Concepts</h2>
  18     </td>
  19   </tr>
  20 </table>
  21 <hr>
  22 <dl class="page-index">
  23   <dt><a href="#saving_interface">Saving Archive Concept</a>
  24   <dt><a href="#loading_interface">Loading Archive Concept</a>
  25   <dt><a href="#archive_models">Models</a>
  26   <dt><a href="#exceptions">Exceptions</a>
  27   <dt><a href="#charactersets">Character Sets</a>
  28 </dl>
  29 <h4>Notation</h4>
  30 In the following descriptions
  31 <ul>
  32   <li><code>SA</code> is an type modeling the <a href="#saving_interface">Saving Archive Concept</a>
  33   <li><code>sa</code> is an instance of type SA.
  34   <li><code>LA</code> is an type modeling the <a href="#loading_interface">Loading Archive Concept</a>
  35   <li><code>la</code> is an instance of type LA.
  36   <li><code>T</code> is an <a href="serialization.html"><strong>Serializable</strong></a> Type
  37   <li><code>x</code> is an instance of type T Type</li>.
  38   <li><code>u,v</code> is a pointer to a an instance of type T
  39   <li><code>count</code> is an instance of a type that can be converted to <code>std::size_t</code>.
  40 </ul>
  41 <h4><a name="saving_interface">Saving Archive Concept</a></h4>
  42 <h4>Associated Types</h4>
  43 Intuitively, a type modeling this concept will generate a sequence of bytes
  44 corresponding to an arbitrary set of C++ data structures.  Each type modeling the
  45 Saving Archive concept (SA) may be associated with another type modeling the
  46 <a href="#loading_interface">Loading Archive Concept</a>(LA).
  47 This associated type will perform the inverse operation.
  48 That is, given a sequence of bytes generated by SA, it will generate a set of
  49 C++ data structures that is equivalent to the original.
  50 The notion of equivalence is defined by the implementations of the pair of archives and the
  51 way the data are rendered <a href="serialization.html">serializable</a>.
  52 <p>
  53 <h4>Valid Expressions</h4>
  54 <dl>
  55   <dt><h4><code>
  56     SA::is_saving
  57   </code></h4></dt>
  58   <dd>
  59     Returns the Boost MPL Integral Constant type boost::mpl::bool_&lt;true&gt;
  60   </dd>
  61   <dt><h4><code>
  62     SA::is_loading
  63   </code></h4></dt>
  64   <dd>
  65     Returns the Boost MPL Integral Constant type boost::mpl::bool_&lt;false&gt;
  66   </dd>
  67   <dt><h4><code>
  68     sa &lt;&lt; x
  69     <br>
  70     sa &amp; x
  71   </code></h4></dt>
  72   <dd>
  73     These expressions must perform exactly the same function.  They append the
  74     value of <code style="white-space: normal">x</code> along with other information to <code>sa</code>.
  75     This other information is defined by the implementation of the archive.
  76     Typically this information is that which is required by a corresponding
  77     Loading Archive type to properly restore the value of <code>x</code>.
  78     <p>
  79     Returns a reference to <code>sa</code>.
  80   </dd>
  81   <dt><h4><code>
  82     sa.save_binary(u, count)
  83   </code></h4></dt>
  84   <dd>
  85     Appends to the archive <code style="white-space: normal">size_t(count)</code> bytes found at
  86     <code style="white-space: normal">u</code>.
  87   </dd>
  88   <dt><h4><code>
  89     sa.register_type&lt;T&gt;()
  90     <br>
  91     sa.register_type(u)
  92   </code></h4></dt>
  93   <dd>
  94     Appends information about class T to the archive.  This information is used to
  95     construct the correct class when a derived pointer is loaded by a corresponding
  96     Loading Archive type.
  97     Invocation of this member function is referred to as "class registration".
  98     This is explained in detail in
  99     <a href="special.html#derivedpointers">Special Considerations - Derived Pointers</a>.
 100     The second syntax is included to permit this function to be called on non-conforming
 101     compilers when <code style="white-space: normal">sa</code> is a template argument.
 102     For more information, see <a target="detail" href="implementation.html#tempatesyntax">Template Invocation syntax</a>
 103   </dd>
 104   <dt><h4><code>
 105     sa.library_version()
 106   </code></h4></dt>
 107   <dd>
 108     Returns an unsigned integer containing the current version number of the serialization
 109     library. This number will be incremented each time the library is altered in such a
 110     way that serialization could be altered for some type.  For example, suppose the type
 111     used for a count of collection members is changed. The code that loads collections
 112     might be conditioned on the library version to make sure that libraries created by
 113     previous versions of the library can still be read.
 114   </dd>
 115 </dl>
 116
 117 <h4><a name="loading_interface">Loading Archive Concept</a></h4>
 118 <h4>Associated Types</h4>
 119 Each model of this concept presumes the
 120 existence of a corresponding type modeling the
 121 <a href="#saving_interface">Saving Archive Concept</a>.
 122 The purpose of an instance of this concept is to convert a sequence of bytes
 123 generated by this corresponding type to a set of C++ data structures
 124 equivalent to the original.
 125 <h4>Valid Expressions</h4>
 126 <dl>
 127   <dt><h4><code>
 128     LA::is_saving
 129   </code></h4></dt>
 130   <dd>
 131     Returns the Boost MPL Integral Constant type boost::mpl::bool_&lt;false&gt;
 132   </dd>
 133   <dt><h4><code>
 134     LA::is_loading
 135   </code></h4></dt>
 136   <dd>
 137     Returns the Boost MPL Integral Constant type boost::mpl::bool_&lt;true&gt;
 138   </dd>
 139   <dt><h4><code>
 140     la &gt;&gt; x
 141     <br>
 142     la &amp; x
 143   </code></h4></dt>
 144   <dd>
 145     These expressions must perform exactly the same function.
 146     Sets <code>x</code> to a value retrieved from <code>la</code>.
 147     <p>
 148     Returns a reference to <code>la</code>.
 149   </dd>
 150   <dt><h4><code>
 151     la.load_binary(u, count)
 152   </code></h4></dt>
 153   <dd>
 154     Retrieves from <code style="white-space: normal">la</code> <code style="white-space: normal">size_t(count)</code> bytes and stores
 155     them in memory starting at <code style="white-space: normal">u</code>.
 156   </dd>
 157   <dt>
 158   <dt><h4><code>
 159     la.register_type&lt;T&gt;()
 160     <br>
 161     la.register_type(u)
 162   </code></h4></dt>
 163   <dd>
 164     Retrieves information about class T from the archive.  This information is used to
 165     construct the correct class when loading a pointer to a derived class not
 166     otherwise referred to in the program by name.
 167     Invocation of this member function is referred to as "class registration".
 168     This is explained in detail in
 169     <a href="special.html#derivedpointers">Special Considerations - Derived Pointers</a>.
 170     The second syntax is included to permit this function to be called on non-conforming
 171     compilers when <code style="white-space: normal">la</code> is a template argument.
 172     For more information, see <a target="detail" href="implementation.html#tempatesyntax">Template Invocation syntax</a>
 173   </dd>
 174   <dt><h4><code>
 175     la.library_version()
 176   </code></h4></dt>
 177   <dd>
 178     Returns an unsigned integer containing the version number of the serialization
 179     library that created the archive. This number will be incremented each time the
 180     library is altered in such a way that serialization could be altered for some type.
 181     For example, suppose the type used for a count of collection members is changed.
 182     The code that loads collections might be conditioned on the library version to make
 183     sure that libraries created by previous versions of the library can still be read.
 184   </dd>
 185   <dt><h4><code>
 186     la.reset_object_address(v, u)
 187   </code></h4></dt>
 188   <dd>
 189     Communicates to the archive that the object originally at address u has been
 190     moved to address v.
 191     <p>
 192     When an object is loaded to a temporary variable and later moved to another location,
 193     this function must be called in order communicate this fact.  This permits the
 194     archive to properly implement object tracking.  Object tracking is required in order
 195     to correctly implement serialization of pointers to instances of derived classes.
 196   </dd>
 197   <dt><h4><code>
 198     la.delete_created_pointers()
 199   </code></h4></dt>
 200   <dd>
 201     Deletes all objects created by the loading of pointers.  This can be used to
 202     avoid memory leaks that might otherwise occur if pointers are being loaded
 203     and the archive load encounters an exception.
 204   </dd>
 205 </dl>
 206
 207 There are archives based on text, binary and XML file
 208 formats but all have the above interface.  Given that all archives present
 209 the same public interface, specifcation of serialization is exactly the same
 210 for all archives.  Archive classes have other members not mentioned here.
 211 However they are related to the internal functioning of the library and
 212 are not meant to be called by users of an archive.  Implementation of new
 213 archives is discussed in
 214 <a href="archive_reference.html#implementation">New Archives - Implementation</a>.
 215
 216 <p>
 217 The existence of the <code style="white-space: normal">&lt;&lt;</code>
 218 and <code style="white-space: normal">&gt;&gt;</code> suggests
 219 a relationship between archives and C++ i/o streams. <strong>Archives are not
 220 C++ i/o streams</strong>. All the archives included with this system take a stream
 221 as an argument in the constructor and that stream is used for output or input.
 222 However, this is not a requirement of the serialization functions or the
 223 archive interface. It just turns out that the archives written so far have
 224 found it useful to base their implementation on streams.
 225
 226 <h3><a name="archive_models">Archive Models</a></h3>
 227 This library includes various implementations of the Archive concept.
 228
 229 An archive is defined by two complementary classes.  One is for saving data while
 230 the other is for loading it.
 231
 232 This library includes a number of archive implementations that are "ready to go" for the
 233 most common requirements.  These classes implement the archive concept for differing data formats.
 234 They can be used "as is" or as a basis for developing one's own particular type of archive.
 235 An archive is defined by two complementary classes. One is for saving data while the other is for loading it.
 236
 237 To invoke serialization using one of
 238 these archives, one or more of the following header files must be
 239 included in the code module containing the serialization code.
 240 <pre><code>
 241 // a portable text archive</a>
 242 <a href="../../../boost/archive/text_oarchive.hpp" target="text_oarchive_cpp">boost::archive::text_oarchive</a> // saving
 243 <a href="../../../boost/archive/text_iarchive.hpp" target="text_iarchive_cpp">boost::archive::text_iarchive</a> // loading
 244
 245 // a portable text archive using a wide character stream</a>
 246 <a href="../../../boost/archive/text_woarchive.hpp">boost::archive::text_woarchive</a> // saving
 247 <a href="../../../boost/archive/text_wiarchive.hpp">boost::archive::text_wiarchive</a> // loading
 248
 249 // a portable XML archive</a>
 250 <a href="../../../boost/archive/xml_oarchive.hpp" target="xml_oarchive_cpp">boost::archive::xml_oarchive</a> // saving
 251 <a href="../../../boost/archive/xml_iarchive.hpp" target="xml_iarchive_cpp">boost::archive::xml_iarchive</a> // loading
 252
 253 // a portable XML archive which uses wide characters - use for utf-8 output</a>
 254 <a href="../../../boost/archive/xml_woarchive.hpp" target="xml_woarchive_cpp">boost::archive::xml_woarchive</a> // saving
 255 <a href="../../../boost/archive/xml_wiarchive.hpp" target="xml_wiarchive_cpp">boost::archive::xml_wiarchive</a> // loading
 256
 257 // a non-portable native binary archive</a>
 258 <a href="../../../boost/archive/binary_oarchive.hpp" target="binary_oarchive_cpp">boost::archive::binary_oarchive</a> // saving
 259 <a href="../../../boost/archive/binary_iarchive.hpp" target="binary_iarchive_cpp">boost::archive::binary_iarchive</a> // loading
 260
 261 <!--
 262 // a non-portable native binary archive which use wide character streams
 263 <a href="../../../boost/archive/binary_woarchive.hpp">boost::archive::binary_woarchive</a> // saving
 264 <a href="../../../boost/archive/binary_wiarchive.hpp">boost::archive::binary_wiarchive</a> // loading
 265 -->
 266
 267 </code></pre>
 268
 269 All of these archives implement the same inteface. Hence, it should suffice to describe only one
 270 of them in detail.  For this purpose we will use the text archive.
 271
 272
 273 <pre><code>
 274 namespace boost {
 275 namespace archive {
 276
 277 enum archive_flags {
 278     no_header = 1,          // suppress archive header info
 279     no_codecvt = 2,         // suppress alteration of codecvt facet
 280     no_xml_tag_checking = 4 // suppress checking of xml tags - igored on saving
 281 };
 282
 283 } // archive
 284 } // boost
 285 </code></pre>
 286
 287 <pre><code>
 288 namespace boost {
 289 namespace archive {
 290
 291 class text_oarchive : ...
 292 {
 293     ...
 294 public:
 295     ... // implementation of the <strong>Saving Archive</strong> concept
 296     text_oarchive(std::ostream & os, unsigned int flags = 0);
 297     ~text_oarchive();
 298 };
 299
 300 } // archive
 301 } // boost
 302 </code></pre>
 303
 304 <dl>
 305
 306 <dt><h4><code>
 307 text_oarchive(std::ostream & os, unsigned int flags = 0);
 308 </code></h4></dt>
 309 <dd>
 310 Constructs an archive given an open <code style="white-space: normal">stream</code> as
 311 an argument and optional flags. For most applications there will be no need to use flags.
 312 Flags are defined by <code style="white-space: normal">enum archive_flags</code> enumerator.
 313 Multiple flags can be combined with the <code style="white-space: normal">|</code> operator.
 314
 315 By default, archives prepend
 316 output with initial data which helps identify them as archives produced by this system.
 317 This permits a more graceful handling of the case where an attempt is made to load an archive
 318 from an invalid file format. In addition to this, each type of archive might have
 319 its own information.  For example, native binary archives include information about
 320 sizes of native types and endianess to gracefully handle the case where it has been
 321 erroneously assumed that such an archive is portable across platforms.  In some cases,
 322 where this extra overhead might be considered objectionable, it can be suppressed with the
 323 <code style="white-space: normal">no_header</code> flag.
 324 <p>
 325 In some cases, an archive may alter (and later restore)
 326 the codecvt facet of the stream locale.  To suppress this action,
 327 include the <code style="white-space: normal">no_codecvt</code> flag.
 328 <p>
 329 XML archives contain nested tags signifying the start and end of data fields.
 330 These tags are normally checked for agreement with the object name when
 331 data is loaded.  If a mismatch occurs an exception is thrown.  It's possible
 332 that this may not be desired behavior.  To suppress this checking of XML
 333 tags, use <code style="white-space: normal">no_xml_tag_checking</code> flag.
 334 </dd>
 335
 336 <dt><h4><code>
 337 ~text_oarchive();
 338 </code></h4></dt>
 339 <dd>
 340 Destructor for an archive.  This should be called before the stream is
 341 closed.  It restores any altered stream facets to their state before the
 342 archive was opened.
 343 </dd>
 344
 345 </dl>
 346
 347 <pre><code>
 348 namespace boost {
 349 namespace archive {
 350
 351 class text_iarchive : ...
 352 {
 353     ...
 354 public:
 355     ... // implementation of the <strong>Loading Archive</strong> concept
 356     text_iarchive(std::istream & is, unsigned int flags = 0);
 357     ~text_iarchive();
 358 };
 359
 360 } //namespace archive
 361 ) //namespace boost
 362
 363 </code></pre>
 364
 365 <dl>
 366
 367 <dt><h4><code>
 368 text_iarchive(std::istream & is, unsigned int flags = 0);
 369 </code></h4></dt>
 370 <dd>
 371 Contructs an archive given an open <code style="white-space: normal">stream</code> as
 372 an argument and optional flags. If flags are used, they should be the same
 373 as those used when the archive was created. Function and usage of flags is described
 374 above.
 375 </dd>
 376
 377 <dt><h4><code>
 378 ~text_iarchive();
 379 </code></h4></dt>
 380 <dd>
 381 Destructor for an archive.  This should be called before the stream is
 382 closed.  It restores any altered stream facets to thier state before the
 383 the archive was opened.
 384 </dd>
 385 </dl>
 386 <p>
 387 The <code style="white-space: normal">binary_oarchive</code> and
 388 <code style="white-space: normal">binary_iarchive</code> classes are
 389 implemented in terms of the more basic
 390 <code style="white-space: normal">std::streambuf</code>.  So, in addition
 391 to the common class interface described above, they include the following
 392 constructors:
 393 <dl>
 394 <dt><h4><code>
 395 binary_oarchive(std::streambuf & bsb, unsigned int flags = 0);
 396 </code></h4></dt>
 397 and
 398 <dt><h4><code>
 399 binary_iarchive(std::streambuf & bsb, unsigned int flags = 0);
 400 </code></h4></dt>
 401 </dl>
 402
 403 <h3><a name="exceptions">Exceptions</h3>
 404 All of the archive classes included may throw exceptions.  The list of exceptions that might
 405 be thrown can be found in section <a target="detail" href="exceptions.html">Archive Exceptions</a>
 406 of this documentation.
 407
 408 <h3><a name="charactersets">Character Sets</h3>
 409 This library includes two archive classes for XML. The wide character
 410 version (<code style="white-space: normal">xml_w?archive</code>) renders its output as UTF-8 which can
 411 handle any wide character without loss of information.
 412 <code style="white-space: normal">std::string</code> data is converted from multi-byte format to wide
 413 character format using the current <code style="white-space: normal">
 414 locale</code>.  Hence this version should give a fair rendering of all
 415 C++ data for all cases.  This could result in some unexpected behavior.
 416 Suppose an <code style="white-space: normal">std::string</code>
 417 is created with the <code style="white-space: normal">locale</code> character
 418 set to hebrew characters.  On output this is converted to wide characters.
 419 On input however, there could be a problem if the <code style="white-space: normal">locale</code> is
 420 not set the same as when the archive is created.
 421 <p>
 422 The normal character version (<code style="white-space: normal">xml_?archive</code>) renders
 423 <code style="white-space: normal">std::string</code> output without any conversion.  Though this may work
 424 fine for serialization,  it may create difficulties if the XML archive is used
 425 for some other purpose.
 426 <hr>
 427 <p><i>&copy; Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004.
 428 Distributed under the Boost Software License, Version 1.0. (See
 429 accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 430 </i></p>
 431 </body>
 432 </html>