###  | # Serialization ## Archive Concept

Saving
Loading
Models
Exceptions
Character Sets

An Archive contains a sequence of bytes created from an arbitrary nested set of C++ data structures.

#### Saving

An object that saves data to an archive implements the following interface.

    class oarchive : ...
    {
        ...
    public:
        // called to save objects
        template<class T>
        oarchive & operator<<(const T & t);

        template<class T>
        oarchive & operator&(T & t){
            return *this << t;
        }

        void save_binary(const void *address, std::size_t count);

        template<class T>
        register_type(T * t = NULL);

        unsigned int library_version() const;

        struct is_saving {
            typedef mpl::bool_<true> type;
            BOOST_STATIC_CONSTANT(bool, value=true);
        };

        struct is_loading {
            typedef mpl::bool_<false> type;
            BOOST_STATIC_CONSTANT(bool, value=false);
        };
        ...
    };

The template parameter `T` must correspond to a type which models the Serializable concept.

#### `template<class T> oarchive & operator<<(const T & t); template<class T> oarchive & operator&(T & t);`

  Appends an object of type T to the archive. The object may be

  - A primitive data type such as int, char, float, etc.
  - A class or struct for which a `serialize` function has been defined.
  - A pointer to a serializable object.

#### `void save_binary(const void *address, std::size_t count);`

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

#### `template<class T> register_type(T * t = NULL);`

  Appends a sequential integer to the archive. This integer becomes the "key" used to look up the class type when the archive is later loaded. This process is referred to as "class registration". It is only necessary to invoke this function for objects of derived classes which are serialized through a base class pointer. This is explained in detail in Special Considerations - Derived Pointers.

#### `unsigned int library_version() const;`

  Returns the version number of the serialization library that created the archive. 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.

#### `is_saving::type = mpl::bool<true>; is_saving::value= true; is_loading::type = mpl::bool<false>; is_loading::value= false;`

  These integral constants permit archive attributes to be queried at compiler or execution time. They can used to generate code with boost mpl . For and example showing how these can beused, see the implementation of split_free.hpp.

#### Loading

An object that saves data to an archive implements the following interface.

    class iarchive : ...
    {
        ...
    public:
        // called to load objects
        template<class T>
        iarchive & operator>>(T & t);

        template<class T>
        iarchive & operator&(T & t){
            return *this >> t;
        }

        void delete_created_pointers();

        void load_binary(void *address, std::size_t count);

        template<class T>
        register_type(T * t = NULL);

        reset_object_address(void * old_address, void * new_address);

        unsigned int library_version() const;

        struct is_saving {
            typedef mpl::bool_<false> type;
            BOOST_STATIC_CONSTANT(bool, value=false);
        };

        struct is_loading {
            typedef mpl::bool_<true> type;
            BOOST_STATIC_CONSTANT(bool, value=true);
        };
        ...
    };

    } //namespace archive
    ) //namespace boost

The template parameter `T` must correspond to a type which models the Serializable concept.

#### `template<class T> iarchive & operator>>(T & t); template<class T> iarchive & operator&(T & t);`

  Retrieves an object of type T from the archive. The object may be

  - A primitive data type such as int, char, float, etc.
  - A class or struct for which a `serialize` function has been defined.
  - A pointer to a serializable object.

#### `void load_binary(void *address, std::size_t count);`

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

#### `void delete_created_pointers();`

  Deletes all objects created by the loading of pointers. This can be used to avoid memory leaks that might otherwise occur if pointers are being loaded and the archive load encounters an exception.

#### `template<class T> register_type(T * t = NULL);`

  Retrieves the next integer from the archive and adds an entry to a table which relates the integer to the type T. When pointers are loaded, this integer is used to indicate which object type should be created. This process is referred to as "class registration". It is only necessary to invoke this function for objects of derived classes which are serialized through a base class pointer. If this function is called during the saving of data to the archive, it should be called during the loading of the data from the archive at the same point in the serialization process. This is explained in detail in Special Considerations - Derived Pointers

#### `void reset_object_address(void * new_address, void * old_address);`

  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 case.

#### `unsigned int library_version() const;`

  Returns the version number of the serialization library that created the archive. 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.

#### `is_saving::type = mpl::bool<false>; is_saving::value= false; is_loading::type = mpl::bool<true>; is_loading::value= true;`

  These integral constants permit archive attributes to be queried at compiler or execution time. They can used to generate code with boost mpl . For and example showing how these can beused, see the implementation of split_free.hpp.

There are archives based on text, binary and XML file formats but all have the above interface. Given that all archives present the same public interface, specifcation of serialization is exactly the same for all archives. Archive classes have other members not mentioned here. However they are related to the internal functioning of the library and are not meant to be called by users of an archive. Implementation of new archives is discussed in New Archives - Implementation.

The existence of the `<<` and `>>` suggest 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.

### Archive Models

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. An archive is defined by two complementary classes. One is for saving data while the other is for loading it. To invoke serialization using one of 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

    // a portable text archive using a wide character stream
    boost::archive::text_woarchive(wostream &s) // saving
    boost::archive::text_wiarchive(wistream &s) // loading

    // a non-portable native binary archive
    boost::archive::binary_oarchive(ostream &s) // saving
    boost::archive::binary_iarchive(istream &s) // loading

    // a portable XML archive
    boost::archive::xml_oarchive(ostream &s) // saving
    boost::archive::xml_iarchive(istream &s) // 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

All of these archives implement the same inteface. Hence, it should suffice to describe only one of them in detail. For this purpose we will use the text archive.

    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 {

    template<class OStream>
    class text_oarchive : ...
    {
        ...
    public:
        ... // implementation of Archive concept
        oarchive(OStream & os, unsigned int flags = 0);
        ~oarchive();
    };

    } // archive
    } // boost

#### Template parameter `OStream`

  An class derived from `basic_istream<char>`

#### `oarchive(OStream & os, unsigned int flags = 0);`

  Contructs an archive given an open `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.

#### `~oarchive();`

  Destructor for an archive. This should be called before the stream is closed. It restores any altered stream facets to their state before the the archive was opened.

    namespace boost {
    namespace archive {

    template<class IStream>
    class text_iarchive : ...
    {
        ...
    public:
        ... // implementation of Archive concept
        iarchive(IStream & is, unsigned int flags = 0);
        ~iarchive();
    };

    } //namespace archive
    ) //namespace boost

#### Template parameter `IStream`

  An class derived from `basic_ostream<char>`

#### `iarchive(IStream & is, unsigned int flags = 0);`

  Contructs an archive given an open `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.

#### `~iarchive();`

  Destructor for an archive. This should be called before the stream is closed. It restores any altered stream facets to thier state before the the archive was opened.

### Exceptions

All of the archive classes included may throw exceptions. The list of exceptions that might be throw can be found in section Archive Exceptions of this documentation.

### Character Sets

This library includes two archive classes for XML. The wide character version (`xml_w?archive`) renders it 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)