|
|
SerializationArchive Concepts |
SA is an type modeling the Saving Archive Concept.
sa is an instance of type SA.
LA is an type modeling the Loading Archive Concept.
la is an instance of type LA.
T is an Serializable Type.
x is an instance of type T Type.
u,v is a pointer to a an instance of type T.
count is an instance of a type that can be converted to std::size_t.
SA::is_saving
SA::is_loading
sa << x
sa & x
x along with other information to sa.
This other information is defined by the implementation of the archive.
Typically this information is that which is required by a corresponding
Loading Archive type to properly restore the value of x.
Returns a reference to sa.
sa.save_binary(u, count)
size_t(count) bytes found at
u.
sa.register_type<T>()
sa.register_type(u)
sa is a template argument.
For more information, see Template Invocation syntax
sa.get_library_version()
sa.get_helper<Helper>(void * const helper_instance_id = 0)
la.get_helper<Helper>(void * const helper_instance_id = 0)
below.
LA::is_saving
LA::is_loading
la >> x
la & x
x to a value retrieved from la.
Returns a reference to la.
la.load_binary(u, count)
la size_t(count) bytes and stores
them in memory starting at u.
la.register_type<T>()
la.register_type(u)
la is a template argument.
For more information, see Template Invocation syntax
la.get_library_version()
la.get_helper<Helper>(void * const helper_instance_id)
la.get_helper<Helper>(void * const helper_instance_id)
is invoked for a given helper_instance_id, Helper, a default-constructed
Helper object is created, attached to
la and a reference to it is returned. Subsequent
invocations of la.get_helper<Helper>(void * const helper_instance_id) with the same id value return
a reference to the formerly constructed object. All objects created in this manner are
destroyed upon la destruction time. The purpose
of helper objects is discussed in
Special Considerations - Helper Support.
la.reset_object_address(v, u)
When an object is loaded to a temporary variable and later moved to another location, this function must be called in order communicate this fact. This permits the archive to properly implement object tracking. Object tracking is required in order to correctly implement serialization of pointers to instances of derived classes.
la.delete_created_pointers()
The existence of the <<
and >> suggests
a relationship between archives and C++ i/o streams. Archives are not
C++ i/o streams. All the archives included with this system take a stream
as an argument in the constructor and that stream is used for output or input.
However, this is not a requirement of the serialization functions or the
archive interface. It just turns out that the archives written so far have
found it useful to base their implementation on streams.
// a portable text archive
boost::archive::text_oarchive // saving
boost::archive::text_iarchive // loading
// a portable text archive using a wide character stream
boost::archive::text_woarchive // saving
boost::archive::text_wiarchive // loading
// a portable XML archive
boost::archive::xml_oarchive // saving
boost::archive::xml_iarchive // loading
// a portable XML archive which uses wide characters - use for utf-8 output
boost::archive::xml_woarchive // saving
boost::archive::xml_wiarchive // loading
// a non-portable native binary archive
boost::archive::binary_oarchive // saving
boost::archive::binary_iarchive // loading
namespace boost {
namespace archive {
enum archive_flags {
no_header = 1, // suppress archive header info
no_codecvt = 2, // suppress alteration of codecvt facet
no_xml_tag_checking = 4 // suppress checking of xml tags - igored on saving
};
} // archive
} // boost
namespace boost {
namespace archive {
class text_oarchive : ...
{
...
public:
... // implementation of the Saving Archive concept
text_oarchive(std::ostream & os, unsigned int flags = 0);
~text_oarchive();
};
} // archive
} // boost
text_oarchive(std::ostream & os, unsigned int flags = 0);
stream as
an argument and optional flags. For most applications there will be no need to use flags.
Flags are defined by enum archive_flags enumerator.
Multiple flags can be combined with the | operator.
By default, archives prepend
output with initial data which helps identify them as archives produced by this system.
This permits a more graceful handling of the case where an attempt is made to load an archive
from an invalid file format. In addition to this, each type of archive might have
its own information. For example, native binary archives include information about
sizes of native types and endianess to gracefully handle the case where it has been
erroneously assumed that such an archive is portable across platforms. In some cases,
where this extra overhead might be considered objectionable, it can be suppressed with the
no_header flag.
In some cases, an archive may alter (and later restore)
the codecvt facet of the stream locale. To suppress this action,
include the no_codecvt flag.
XML archives contain nested tags signifying the start and end of data fields.
These tags are normally checked for agreement with the object name when
data is loaded. If a mismatch occurs an exception is thrown. It's possible
that this may not be desired behavior. To suppress this checking of XML
tags, use no_xml_tag_checking flag.
~text_oarchive();
namespace boost {
namespace archive {
class text_iarchive : ...
{
...
public:
... // implementation of the Loading Archive concept
text_iarchive(std::istream & is, unsigned int flags = 0);
~text_iarchive();
};
} //namespace archive
) //namespace boost
text_iarchive(std::istream & is, unsigned int flags = 0);
stream as
an argument and optional flags. If flags are used, they should be the same
as those used when the archive was created. Function and usage of flags is described
above.
~text_iarchive();
The binary_oarchive and
binary_iarchive classes are
implemented in terms of the more basic
std::streambuf. So, in addition
to the common class interface described above, they include the following
constructors:
binary_oarchive(std::streambuf & bsb, unsigned int flags = 0);
binary_iarchive(std::streambuf & bsb, unsigned int flags = 0);
xml_w?archive) renders its output as UTF-8 which can
handle any wide character without loss of information.
std::string data is converted from multi-byte format to wide
character format using the current
locale. Hence this version should give a fair rendering of all
C++ data for all cases. This could result in some unexpected behavior.
Suppose an std::string
is created with the locale character
set to hebrew characters. On output this is converted to wide characters.
On input however, there could be a problem if the locale is
not set the same as when the archive is created.
The normal character version (xml_?archive) renders
std::string output without any conversion. Though this may work
fine for serialization, it may create difficulties if the XML archive is used
for some other purpose.
© Copyright Robert Ramey 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)