Squashed 'third_party/boostorg/serialization/' content from commit 738695b
Change-Id: I48528198ad1f62b90288d249eb2243d4db02fd5d
git-subtree-dir: third_party/boostorg/serialization
git-subtree-split: 738695b70733f9d592a570fb17a505d6a029b48a
diff --git a/doc/exceptions.html b/doc/exceptions.html
new file mode 100644
index 0000000..cf3007b
--- /dev/null
+++ b/doc/exceptions.html
@@ -0,0 +1,276 @@
+<!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 - Archive Exceptions</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">Archive Exceptions</h2>
+ </td>
+ </tr>
+</table>
+<hr>
+<dl class="page-index">
+ <dt><a href="#unregistered_class"><code style="white-space: normal">unregistered_class</code></a>
+ <dt><a href="#invalid_signature"><code style="white-space: normal">invalid_signature</code></a>
+ <dt><a href="#unsupported_version"><code style="white-space: normal">unsupported_version</code></a>
+ <dt><a href="#unsupported_class_version"><code style="white-space: normal">unsupported_class_version</code></a>
+ <dt><a href="#pointer_conflict"><code style="white-space: normal">pointer_conflict</code></a>
+ <dt><a href="#incompatible_native_format"><code style="white-space: normal">incompatible_native_format</code></a>
+ <dt><a href="#array_size_too_short"><code style="white-space: normal">array_size_too_short</code></a>
+ <dt><a href="#input_stream_error"><code style="white-space: normal">input_stream_error</code></a>
+ <dt><a href="#output_stream_error"><code style="white-space: normal">output_stream_error</code></a>
+ <dt><a href="#invalid_class_name"><code style="white-space: normal">invalid_class_name</code></a>
+ <dt><a href="#unregistered_class"><code style="white-space: normal">unregistered_class</code></a>
+ <dt><a href="#multiple_code_instantiation"><code style="white-space: normal">multiple_code_instantiation</code></a>
+ <dt><a href="#xml_archive_parsing_error"><code style="white-space: normal">xml_archive_parsing_error</code></a>
+ <dt><a href="#xml_archive_tag_mismatch"><code style="white-space: normal">xml_archive_tag_mismatch</code></a>
+ <dt><a href="#xml_archive_tag_name_error"><code style="white-space: normal">xml_archive_tag_name_error</code></a>
+</dl>
+
+Archive operators can throw a <code style="white-space: normal">boost::archive_exception</code>
+object which can be caught by an application program. These exceptions are defined
+in the files <a target="archive_exception_hpp" href="../../../boost/archive/archive_exception.hpp">
+archive_exception.hpp</a>
+and <a target="basic_xml_archive_hpp" href="../../../boost/archive/basic_xml_archive.hpp">
+basic_xml_archive.hpp</a>.
+<pre><code>
+namespace boost {
+namespace archive {
+
+class archive_exception : public std::exception
+{
+public:
+ typedef enum {
+ unregistered_class, // attempt to serialize a pointer of
+ // an unregistered class
+ invalid_signature, // first line of archive does not contain
+ // expected string
+ unsupported_version, // archive created with library version subsequent
+ // to this one
+ pointer_conflict // an attempt has been made to directly serialize
+ // an object after having already serialized the same
+ // object through a pointer. Were this permitted,
+ // the archive load would result in the creation
+ // of an extraneous object.
+ incompatible_native_format, // attempt to read native binary format
+ // on incompatible platform
+ array_size_too_short, // array being loaded doesn't fit in array allocated
+ input_stream_error // error on stream input
+ invalid_class_name, // class name greater than the maximum permitted.
+ // most likely a corrupted archive or an attempt
+ // to insert virus via buffer overrun method.
+ unregistered_cast, // base - derived relationship not registered with
+ // void_cast_register
+ unsupported_class_version, // type saved with a version # greater than the
+ // one used by the program. This indicates that the proggram
+ // needs to be rebuilt.
+ multiple_code_instantiation, // code for implementing serialization for some
+ // type has been instantiated in more than one module.
+ output_stream_error // error on stream output
+ } exception_code;
+ exception_code code;
+ archive_exception(exception_code c) : code(c) {}
+ virtual const char *what( ) const throw();
+};
+
+class xml_archive_exception : public virtual archive_exception
+{
+public:
+ typedef enum {
+ xml_archive_parsing_error, // archive doesn't contain expected data
+ xml_archive_tag_mismatch, // start/end tag in archive doesn't match program
+ xml_archive_tag_name_error // tag name contains invalid characters
+
+ } exception_code;
+ xml_archive_exception(exception_code c){}
+ virtual const char *what( ) const throw();
+};
+
+} // archive
+} // boost
+</code></pre>
+<p>
+<h3><a name="unregistered_class"><code style="white-space: normal">unregistered_class</code></a></h3>
+An attempt has been made to serialize a polymorphic class through a pointer
+without either registering it or associating it with an export key. This can also occur
+when using a new archive whose class name has not been added to the system with the
+<code style="white-space: normal">BOOST_ARCHIVE_CUSTOM_ARCHIVE_TYPES</code> macro.
+
+<h3><a name="invalid_signature"><code style="white-space: normal">invalid_signature</code></a></h3>
+Archives are initiated with a known string. If this string is not found when
+the archive is opened, It is presumed that this file is not a valid archive and this
+exception is thrown.
+
+<h3><a name="unsupported_version"><code style="white-space: normal">unsupported_version</code></a></h3>
+This system records the current library version number to all archives created. Note that this is in
+no way related to version number of classes used by application programs. This refers
+to the version of the serialization system used to create the archive. Future versions
+of this serialization system will be able to identify archives created under a previous
+(i.e. this) system and alter the loading procedure accordingly. Hence, future enhancements
+to this serialization system should not obsolete any existing archive files. It is only
+necessary to increment this version number when the newer system creates archives
+incompatible in format with the current one.
+<p>Should it ever occur that an older program attempts to read newer archives whose
+format has changed, this exception is thrown.
+
+<h3><a name="unsupported_class_version"><code style="white-space: normal">unsupported_class_version</code></a></h3>
+An attempt has been made to load a class whose version has been incremented since the
+program was written. Suppose that a class has been assigned version number 3 and the program
+has been built and sent to third parties. Now suppose that the definition of that class
+has been altered, the version number has been incremented to 4 and new archives have been
+built. If one attempts to load these new archives with the original program, this
+exception will be thrown.
+
+<h3><a name="pointer_conflict"><code style="white-space: normal">pointer_conflict</code></a></h3>
+To understand what this exception means consider the following scenario
+<pre><code>
+template<class Archive>
+void T::save(Archive &ar) const
+{
+ const A * aptr = &a;
+ ar << aptr; // save an instance of object of class A through a pointer
+ ...
+ ar << a; // save an instance of an object of class A
+ assert(aptr == &a); // this must be true
+}
+
+template<class Archive>
+void T::load(Archive &ar)
+{
+ A * aptr;
+ ar >> aptr; // create and initialize a new instance of class A
+ ...
+ ar >> a; // restore state of on object of class A
+ assert(aptr == &a); // this won't be true
+}
+</pre></code>
+An object is saved first through a pointer then directly. Upon loading back
+in the same sequence, we first create an new object and load in its data. Then
+we load the data into another existing object. Where we started with one
+object during save, we have two objects after restore. In a more realistic
+situation, it could be very difficult to find this error. Fortunately,
+these situations can be detected when the archive is created. When
+this occurs, this exception is thrown.
+
+<h3><a name = "incompatible_native_format"><code style="white-space: normal">incompatible_native_format</code></a></h3>
+The library currently supports char text, wide char text and native binary
+archive files. At the beginning of every archive, a signature is written indicating
+the type of archive. This exception is thrown when an attempt is made to read
+an archive written in a different format.
+
+<h3><a name="array_size_too_short"><code style="white-space: normal">array_size_too_short</code></a></h3>
+An attempt has been made to read an array that is larger than the array size.
+This should only occur when the size of an array in code is reduced after an
+archive has already been created.
+
+<h3>
+<a name="input_stream_error"><code style="white-space: normal">input_stream_error</code></a>
+<br>
+<a name="output_stream_error"><code style="white-space: normal">output_stream_error</code></a>
+</h3>
+An error has occured during stream input or ouput. Aside from the common
+situations such as a corrupted or truncated input file, there are
+several less obvious ones that sometimes occur.
+<p>
+This includes
+an attempt to read past the end of the file. Text files need a terminating
+new line character at the end of the file which is appended when the
+archive destructor is invoked. Be sure that an output archive on a stream
+is destroyed before opening an input archive on that same stream. That is,
+rather than using something like:
+<pre><code>
+std::stringstream ss;
+std::vector<V> v;
+boost::archive::text_oarchive oa(ss);
+oa << v;
+boost::archive::text_iarchive ia(ss);
+ia >> v;
+</code></pre>
+use
+<pre><code>
+std::stringstream ss;
+std::vector<V> v;
+{
+ boost::archive::text_oarchive oa(ss);
+ oa << v;
+}
+{
+ boost::archive::text_iarchive ia(ss);
+ ia >> v;
+}
+</code></pre>
+<p>
+Another one is the passing of uninitialized data. In general, the behavior
+of the serialization library when passed uninitialized data is undefined.
+If it can be detected, it will invoke an assertion in debug builds.
+Otherwise, depending on the type of archive, it may pass through without
+incident or it may result in an archive with unexpected data in it.
+This, in turn, can result in the throwing of this exception.
+
+<h3><a name="invalid_class_name"><code style="white-space: normal">invalid_class_name</code></a></h3>
+Class name length greater than the maximum permitted. Most likely cause is a corrupted
+archive or an attempt to insert a virus via the buffer overrun method.
+
+<h3><a name="unregistered_cast"><code style="white-space: normal">unregistered_cast</code></a></h3>
+In order to support casting between pointers of base and derived classes
+at runtime, a collection of legitimate conversions is maintained by the system.
+Normally this collection is maintained without any explicit action
+on the part of the user of the library. However, there are special cases
+where this might have to be done explicitly and could be overlooked. This
+is described in <a href="serialization.html#runtimecasting">Runtime Casting</a>.
+This exception is thrown if an attempt is made to convert between two pointers
+whose relationship has not been registered,
+
+<h3><a name="multiple_code_instantiation"><code style="white-space: normal">multiple_code_instantiation</code></a></h3>
+This exception is thrown when it is detected that the serialization of the same type
+has been instantiated more than once. This might occur when
+serialization code is instantiated in both the mainline and one or more DLLS.
+
+<h3><a name="xml_archive_parsing_error"><code style="white-space: normal">xml_archive_parsing_error</code></a></h3>
+The XML generated by the serialization process is intimately coupled to the
+C++ class structure, relationships between objects and the serialization
+specifications. If these become out of sync in any way, the XML may not map
+to the loading serialization and this exception might be thrown. This might
+occur for one of the following reasons:
+<ul>
+ <li>The archive has been edited outside the serialization system. This might
+be possible if only the data is changed and the XML attributes and nesting
+structure are left unaltered. But any other editing is likely to render the
+archive unreadable by the serialization library.
+ <li>The serialization has been altered and an archive generated by the old
+code is being read. That is, versioning has not been properly employed to
+properly deserialize previously created archives.
+</ul>
+
+<h3><a name="xml_archive_tag_mismatch"><code style="white-space: normal">xml_archive_tag_mismatch</code></a></h3>
+This exception will be thrown if the start or end tag of an XML element doesn't match
+the name specified for the object in the program.
+
+<h3><a name="xml_archive_tag_name_error"><code style="white-space: normal">xml_archive_tag_name_error</code></a></h3>
+This exception will be thrown if the tag name contains invalid characters. Valid characters
+for an XML tag are: upper and lower case letters, digits, and the following punctuation: .(period),
+_(underscore), :(colon), and -(hyphen).
+
+<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>