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