Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/serialization/doc/wrappers.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 6.4 KB
Line 
1<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!--
4(C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com .
5Use, modification and distribution is subject to the Boost Software
6License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
7http://www.boost.org/LICENSE_1_0.txt)
8-->
9<head>
10<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
11<link rel="stylesheet" type="text/css" href="../../../boost.css">
12<link rel="stylesheet" type="text/css" href="style.css">
13<title>Serialization - Serialization Wrappers</title>
14</head>
15<body link="#0000ff" vlink="#800080">
16<table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
17  <tr> 
18    <td valign="top" width="300"> 
19      <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
20    </td>
21    <td valign="top"> 
22      <h1 align="center">Serialization</h1>
23      <h2 align="center">Serialization Wrappers</h2>
24    </td>
25  </tr>
26</table>
27<hr>
28<dl class="page-index">
29  <dt><a href="#binaryobjects">Binary Objects</a>
30  <dt><a href="#strong_type"><code style="white-space: normal">BOOST_STRONG_TYPEDEF</code></a>
31  <dt><a href="#nvp">Name-Value Pairs</a>
32  <dt><a href="#composition">Composition</a>
33</dl>
34Sometimes it convenient to create a temporary object just to support serialization
35of some underlying data. This permits an archive class to define special
36handling of this type.  The library includes several such types for varying
37purposes.
38<p>
39
40<h3><a name="binaryobjects">Binary Objects</a></h3>
41A binary object is just an sequence of bytes stored as raw
42binary data.  This would most likely be used for a large amount
43of "light weight" data such as a pixel map or embedded binary file.
44The header file
45<a href="../../../boost/serialization/binary_object.hpp" target="binary_object_hpp">
46binary_object.hpp
47</a>
48includes the constructors:
49<pre><code>
50boost::serialization::binary_object(void * t, size_t size);
51boost::serialization::make_binary_object(void * t, size_t size);
52</code></pre>
53which will construct a temporary binary object that can be serialized just like any other object.
54Its default serialization is to use archive class primitives
55<code style="white-space: normal">save_binary</code> and <code>load_binary</code>. 
56Note that it doesn't allocated any storage or create any objects.
57Its sole purpose is to pass the data size and address as pair to the archive class. 
58
59<h3><a name="strong_type"><code style="white-space: normal">BOOST_STRONG_TYPEDEF</code></h3>
60Another example of a serialization wrapper is the
61<a href="strong_typedef.html"><code style="white-space: normal">BOOST_STRONG_TYPEDEF</code></a> template.
62The serialization libraries uses these to pass particular kinds of integers such
63as object_id, version, etc. to an archive class. Given that these integers
64are now distinguishable according to their type,  XML archives can apply
65special handling to these types.  For example, a version number is rendered
66as an XML attribute in the form "version=12".  In the absence of any specific override,
67these types are automatically converted to the underlying integer type so the
68special overrides used for XML archives aren't needed for other archives.
69
70<h3><a name="nvp">Name-Value Pairs</h3>
71XML archives present a somewhat special case. XML format has a nested
72structure that maps well to the "recursive class member visitor" pattern used
73by the serialization system.  However, XML differs from other formats
74in that it requires a name for each class data member.  Our goal is to
75add this information to the class serialization specification while
76still permiting the the serialization code to be used with any archive.
77<p>
78Our solution is to wrap class members to be serialized in a
79<strong>name-value-pair</strong>. This structure is defined in
80<a href="../../../boost/serialization/nvp.hpp" target="nvp_hpp">nvp.hpp</a>.
81It is just a reference to the data member coupled with a pointer to
82to a <code style="white-space: normal">const char *</code> which
83corresponds to the XML name.  It implements the default
84serialization functions for a name-value pair.  This default
85action is to just ignore the item name and serialize the
86data value in the normal manner.  For archive classes that
87don't make any special provision for name-value pairs, this
88is the action which will be invoked when the name-value pair
89is serialized.  Hence, wrapping a data value into a name-value
90pair will have no effect when used with archives which
91make no special provision for this wrapper.
92<p>
93The xml archive classes contain code similar to:
94<pre><code>
95// special treatment for name-value pairs.
96template&lt;class T&gt;
97xml_oarchive & operator&(const boost::serialization::nvp<T> & t)
98{
99    // write an xml start tag
100    start_tag(t.name());
101
102    // serialize the data as usual
103    *this & t.value();
104
105    // write an xml end tag
106    end_tag(t.name());
107}
108</code></pre>
109The most obvious and convient name to assign to as the XML data item name
110is - surpise! - the name of the C++ class data member.  So our serialization
111code will look like:
112<pre><code>
113ar & make_nvp("my_variable", my_variable);
114</code></pre>
115To simplify typing and enhance readability a macro is defined so we can write:
116<pre><code>
117ar & BOOST_SERIALIZATION_NVP(my_variable);
118</code></pre>
119Similarly there exists a macro definition that permits us to write:
120<pre><code>
121BOOST_SERIALIZATION_BASE_OBJECT_NVP(my_base_class)
122</code></pre>
123<p>
124Included is
125<a href="../example/demo_xml.hpp" target="demo_xml_hpp">demo_xml.hpp<a>
126which renders it's data members as <strong>name-value-pair</strong>s and
127<a href="../example/demo_xml.cpp" target="demo_xml_cpp">demo_xml.cpp<a>
128which saves and loads data to an XML archive.
129<a href="../example/demo_save.xml" target="demo_save_xml">Here</a>
130is example of the XML Archive corresponding to our tutorial example.
131
132<h3><a name="composition">Composition</h3>
133Wrappers should be designed so that they can be composed as necessary.
134For example, to pass binary data as a name value pair use:
135<pre><code>
136ar & make_nvp("named_binary_object", make_binary_object(address, size));
137</code></pre>
138</html>
139<hr>
140<p><i>&copy; Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004.
141Distributed under the Boost Software License, Version 1.0. (See
142accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
143</i></p>
144</body>
145</html>
146
Note: See TracBrowser for help on using the repository browser.