mirror of
https://github.com/boostorg/serialization.git
synced 2026-01-30 08:12:09 +00:00
156 lines
6.5 KiB
HTML
156 lines
6.5 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=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="../../../c++boost.gif" 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>Revised
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
|
24 January, 2003
|
|
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
|
|
</p>
|
|
<p><i>© Copyright <a href="http://www.rrsd.com">Robert Ramey</a>
|
|
2002-2004. All Rights Reserved.</i></p>
|
|
</body>
|