214 lines
8.8 KiB
HTML
214 lines
8.8 KiB
HTML
<!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=UTF-8">
|
|
<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="#arrays">Arrays</a>
|
|
<dt><a href="#strong_type"><code style="white-space: normal">BOOST_STRONG_TYPEDEF</code></a>
|
|
<dt><a href="#collection_size_type">Collection Sizes</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>
|
|
Wrappers need to be treated in a special way by some archives, and hence
|
|
the <A href="traits.html#wrappers"><code>is_wrapper</code></a> trait for
|
|
these wrapper classes is set to true.
|
|
|
|
<h3><a name="binaryobjects">Binary Objects</a></h3>
|
|
A binary object is just a 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 a pair to the archive class.
|
|
|
|
|
|
<h3><a name="arrays">Arrays</a></h3>
|
|
An array is a contiguous sequence of homogeneous data types, such as a builtin
|
|
C-array, a <code>boost::array<T></code> or a <code>std::vector<T></code>.
|
|
The purpose of this wrapper is to support archive types (such as binary
|
|
archives) that provide optimized serialization for contiguous sequences of
|
|
objects of the same type.
|
|
|
|
The header file
|
|
<a href="../../../boost/serialization/array.hpp" target="array_hpp">
|
|
array.hpp
|
|
</a>
|
|
includes the function
|
|
<pre><code>
|
|
template <T>
|
|
boost::serialization::make_array(T* t, std::size_t size);
|
|
</code></pre>
|
|
which will construct a temporary <code>array</code> object
|
|
<pre><code>
|
|
template<class T>
|
|
class array
|
|
{
|
|
public:
|
|
typedef T value_type;
|
|
array(value_type* t, std::size_t s);
|
|
value_type* address() const;
|
|
std::size_t count() const;
|
|
};
|
|
</code></pre>
|
|
that can be serialized just like any other object.
|
|
Its default serialization is to serialize each array element.
|
|
Note that it doesn't allocated any storage or create any objects.
|
|
Its sole purpose is to pass the data type, size and address to the archive class.
|
|
|
|
Archive types that can provide optimized implementations for contiguous
|
|
arrays of homogeneous data types should overload the serialization of
|
|
<code>array</code>.
|
|
|
|
|
|
<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="collection_size_type">Collection Sizes</h3>
|
|
An example of a strong typedef is the <code>collection_size_type</code> in the
|
|
header file
|
|
<a href="../../../boost/serialization/collection_size_type.hpp" target="collection_size_type_hpp">
|
|
collection_size_type.hpp
|
|
</a>. This type should be used for serializaing the size of a C++ collection, so
|
|
that the archive can pick the best integral representation for the serialization
|
|
of collection sizes. This is necessary since, although <code>std::size_t</code>
|
|
is guaranteed to be an integral type large enough to represent the size of
|
|
a collection on a specific platform, the archive might want to serialize
|
|
the size differently than this type. For example, the <code>collection_size_type</code>
|
|
might be serialized as a variable length integer in a portable binary archive.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<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. It implements the default
|
|
serialization functions for a name-value pair. This default
|
|
action is to just ignore the item name and serialize the
|
|
data value in the normal manner. For archive classes that
|
|
don't make any special provision for name-value pairs, this
|
|
is the action which will be invoked when the name-value pair
|
|
is serialized. Hence, wrapping a data value into a name-value
|
|
pair will have no effect when used with archives which
|
|
make no special provision for this wrapper.
|
|
<p>
|
|
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>
|
|
The most obvious and convient name to assign to as the XML data item name
|
|
is - surprise! - 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>
|
|
|
|
Note that these macros must be used in the namespace of the class,
|
|
and without qualifying the namespace in the argument.
|
|
|
|
<p>
|
|
<a href="../example/demo_gps.hpp" target="demo_gps_hpp">demo_gps.hpp<a>
|
|
includes NVP wrappers or all data members.
|
|
<a href="../example/demo_xml.cpp" target="demo_xml_cpp">demo_xml.cpp<a>
|
|
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>
|
|
|