diff --git a/doc/archives.html b/doc/archives.html index ef1bee68..deed9bb8 100644 --- a/doc/archives.html +++ b/doc/archives.html @@ -14,79 +14,165 @@

Serialization

-

Archive Concept

+

Archive Concepts

-
Saving -
Loading +
Saving Archive Concept +
Loading Archive Concept
Models
Exceptions
Character Sets
- -There are two Archive concepts. Given a set of C++ data structures consisting -of Serializable types, a -Saving Archive will create a sequence of bytes. Given a sequence of bytes -created by a Saving Archive, a Loading Archive will reconstitute the orginal -configuration of C++ data structures. - -Both Archive concepts are derived from the more basic concept of Archive. -

Notation

-In the following descriptions, it is assumed that: +In the following descriptions - -

Common Type Definitions in all Archives

+

Saving Archive Concept

+

Associated Types

+Intuitively, a type modeling this concept will generate a sequence of bytes +correpsonding to an arbitrary set of C++ data structures. Each type modeling the +Saving Archive concept (SA) may be associated with another type modeling the +Loading Archive Concept(LA). +This associated type will perform the inverse operation. +That is, given a sequence of bytes generated by SA, it will generate a set of +C++ data structures the is equivalent to the original. +The notion of equivalence is defined by the implementations of the pair of archives and the +way the data is are rendered serializable. +

+

Valid Expressions

- A::is_saving + SA::is_saving

- An integral constant of type boost::mpl::bool_. - Value is boost::mpl::bool_<true> if the Archive is a Saving Archive (see below) - and boost::mpl::bool_<false> otherwise. + Returns the Boost MPL Integral Constant type boost::mpl::bool_<true>

- A::is_loading + SA::is_loading

- An integral constant of type boost::mpl::bool_. - Value is boost::mpl::bool_<true> if the Archive is a Loading Archive (see below) - and boost::mpl::bool_<false> otherwise. + Returns the Boost MPL Integral Constant type boost::mpl::bool_<false>
-
- -

Common Member Functions in all Archives

-

- ar & x + sa << x +
+ sa & x

- Returns a reference to ar. - Appends the value of x along with other information to ar. + These expressions must perform exactly the same function. They append the + value of 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.

- ar.template register_type<T>();
- ar.register_type(u); + sa.save_binary(u, count)

- Append information about class T to the archive. This information is used to - construct the correct class when a derived pointer is loaded. + Appends to the archive size_t(count) bytes found at + u. +
+

+ sa.register_type<T>() +
+ sa.register_type(u) +

+
+ Appends information about class T to the archive. This information is used to + construct the correct class when a derived pointer is loaded by a corresponding + Loading Archive type. Invocation of this member function is referred to as "class registration". This is explained in detail in Special Considerations - Derived Pointers. + The second syntax is included to permit this function to be called on non-conforming + compilers when sa is a template argument. + For more information, see Template Invocation syntax

- ar.library_version() + sa.library_version() +

+
+ Returns an unsigned integer containing the current version number of the serialization + library. This number will be incremented each time the library is altered in such a + way that serialization could be altered for some type. For example, suppose the type + used for a count of collection members is changed. The code that loads collections + might be conditioned on the library version to make sure that libraries created by + previous versions of the library can still be read. +
+
+ +

Loading Archive Concept

+

Associated Types

+Each model of this concept presumes the +existence of a corresponding type modeling the +Saving Archive Concept. +The purpose of an instance of this concept is to convert a sequence of bytes +generated by this corresponding type to a set of C++ data structures +equivalent to the original. +

Valid Expressions

+
+

+ LA::is_saving +

+
+ Returns the Boost MPL Integral Constant type boost::mpl::bool_<false> +
+

+ LA::is_loading +

+
+ Returns the Boost MPL Integral Constant type boost::mpl::bool_<true> +
+

+ la >> x +
+ la & x +

+
+ These expressions must perform exactly the same function. + Sets x to a value retrieved from la. +

+ Returns a reference to la. +

+

+ la.load_binary(u, count) +

+
+ Retrieves from la size_t(count) bytes and stores + them in memory starting at u. +
+
+

+ la.register_type<T>() +
+ la.register_type(u) +

+
+ Retrieves information about class T from the archive. This information is used to + construct the correct class when loading a pointer to a derived class not + otherwise referred to in the program by name. + Invocation of this member function is referred to as "class registration". + This is explained in detail in + Special Considerations - Derived Pointers. + The second syntax is included to permit this function to be called on non-conforming + compilers when la is a template argument. + For more information, see Template Invocation syntax +
+

+ la.library_version()

Returns an unsigned integer containing the version number of the serialization @@ -96,84 +182,20 @@ In the following descriptions, it is assumed that: The code that loads collections might be conditioned on the library version to make sure that libraries created by previous versions of the library can still be read.
-
- -

Saving Archive

-A Saving Archive is a refinement of the Archive Concept. -

Notation

-In the following descriptions, it is assumed that: - - -

Common Member Functions

-

- ar << x -

-
- Returns a reference to ar. - Appends the value of x along with other information to ar. -
-

- ar.save_binary(u, count) -

-
- Appends to the archive count bytes found at - address. -
-
- -

Loading Archive

- -

Notation

-In the following descriptions, it is assumed that: - - -

Common Member Functions in all Archives

-
-

- ar >> x -

-
- Returns a reference to ar. - Sets x with a value retrieved from the ar. -
-

- ar.load_binary(u, count) -

-
- Retrieves from the archive count bytes and stores - them in memory starting at address. -
-
-

- ar.reset_object_address(v, u) + la.reset_object_address(v, u)

Communicates to the archive that the object originally at address u has been moved to address v.

- In order to facilitate loading of objects through a pointer - and to elminate redundant loading of objects, this system implements object address tracking. - Normally this is done automatically with no action required on the part of the user. However, - there are cases when an object must be de-serialized to a temporary location then - moved to its final destination. This is common in loading collections. -

- In such cases, reset_object_address should be invoked to communicate the final address - of the last item loaded. This permits the internal tables to be correctly maintained - in these special cases. + 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 is permits the + the archive to properly implement object tracking. Object tracking is required in order + to correctly implement serialization of pointers to instances of derived classes.

- ar.delete_created_pointers() + la.delete_created_pointers()

Deletes all objects created by the loading of pointers. This can be used to @@ -207,7 +229,6 @@ This library includes a various implementation of the Archive concept. An archive is defined by two complementary classes. One is for saving data while the other is for loading it. - This library includes a number of archive implementations that are "ready to go" for the most common requirements. These classes implement the archive concept for differing data formats. They can be used "as is" or as a basis for developing one's own particular type of archive. @@ -218,28 +239,28 @@ these archives, one or more of the following header files must be included in the code module containing the serialization code. 

 // a portable text archive
-boost::archive::text_oarchive(ostream &s) // saving
-boost::archive::text_iarchive(istream &s) // loading
+boost::archive::text_oarchive // saving
+boost::archive::text_iarchive // loading
 
 // a portable text archive using a wide character stream
-boost::archive::text_woarchive(wostream &s) // saving
-boost::archive::text_wiarchive(wistream &s) // loading
+boost::archive::text_woarchive // saving
+boost::archive::text_wiarchive // loading
 
 // a non-portable native binary archive
-boost::archive::binary_oarchive(ostream &s) // saving
-boost::archive::binary_iarchive(istream &s) // loading
+boost::archive::binary_oarchive // saving
+boost::archive::binary_iarchive // loading
 
 // a portable XML archive
-boost::archive::xml_oarchive(ostream &s) // saving
-boost::archive::xml_iarchive(istream &s) // loading
+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(wostream &s) // saving
-boost::archive::xml_wiarchive(wistream &s) // loading
+boost::archive::xml_woarchive // saving
+boost::archive::xml_wiarchive // loading
All of these archives implement the same inteface. Hence, it should suffice to describe only one diff --git a/doc/contents.html b/doc/contents.html index 0c191172..0e5dd940 100644 --- a/doc/contents.html +++ b/doc/contents.html @@ -113,10 +113,10 @@ function initialize() {
Reference