###

# Serialization

## Tutorial

A Very Simple Case
Non Intrusive Version
Serializable Members
Derived Classes
Pointers
Arrays
STL Collections
Class Versioning
Splitting `serialize` into `save/load`
Archives

An output archive is similar to an output data stream. Data can be saved to the archive with either the << or the & operator:

    ar << data;
    ar & data;

An input archive is similar to an input datastream. Data can be loaded from the archive with either the >> or the & operator.

    ar >> data;
    ar & data;

When these operators are invoked for primitive data types, the data is simply saved/loaded to/from the archive. When invoked for class data types, the class `serialize` function is invoked. Each `serialize` function is uses the above operators to save/load its data members. This process will continue in a recursive manner until all the data contained in the class is saved/loaded.

### A Very Simple Case

These operators are used inside the `serialize` function> to save and load class data members.

Included in this library is a program called demo.cpp which illustrates how to use this system. Below we excerpt code from this program to illustrate with the simplest possible case how this library is intended to be used.

    #include <fstream>

    // include headers that implement a archive in simple text format
    #include <boost/archive/text_oarchive.hpp>
    #include <boost/archive/text_iarchive.hpp>

    /////////////////////////////////////////////////////////////
    // gps coordinate
    //
    // illustrates serialization for a simple type
    //
    class gps_position
    {
    private:
        friend class boost::serialization::access;
        // When the class Archive corresponds to an output archive, the
        // & operator is defined similar to <<.  Likewise, when the class Archive
        // is a type of input archive the & operator is defined similar to >>.
        template<class Archive>
        void serialize(Archive & ar, const unsigned int version)
        {
            ar & degrees;
            ar & minutes;
            ar & seconds;
        }
        int degrees;
        int minutes;
        float seconds;
    public:
        gps_position(){};
        gps_position(int d, int m, float s) :
            degrees(d), minutes(m), seconds(s)
        {}
    };

    int main() {
        // create and open a character archive for output
        std::ofstream ofs("filename");
        boost::archive::text_oarchive oa(ofs);

        // create class instance
        const gps_position g(35, 59, 24.567f);
        // write class instance to archive
        oa << g;
        // close archive
        ofs.close();

        // ... some time later restore the class instance to its orginal state
        // create and open an archive for input
        std::ifstream ifs("filename", std::ios::binary);
        boost::archive::text_iarchive ia(ifs);
        // read class state from archive
        gps_position newg;
        ia >> newg;
        // close archive
        ifs.close();
        return 0;
    }

For each class to be saved via serialization, there must exist a function to save all the class members which define the state of the class. For each class to be loaded via serialization, there must exist a function to load theese class members in the same sequence as they were saved. In the above example, these functions are generated by the template member function `serialize`.

### Non Intrusive Version

The above formulation is intrusive. That is, it requires that classes whose instances are to be serialized be altered. This can be inconvenient in some cases. An equivalent alternative formulation permitted by the system would be:

    #include <boost/archive/text_oarchive.hpp>
    #include <boost/archive/text_iarchive.hpp>

    class gps_position
    {
    public:
        int degrees;
        int minutes;
        float seconds;
        gps_position(){};
        gps_position(int d, int m, float s) :
            degrees(d), minutes(m), seconds(s)
        {}
    };

    namespace boost {
    namespace serialization {

    template<class Archive>
    void serialize(Archive & ar, gps_position & g, const unsigned int version)
    {
        ar & g.degrees;
        ar & g.minutes;
        ar & g.seconds;
    }

    } // namespace serialization
    } // namespace boost

In this case the generated serialize functions are not members of the `gps_position` class. The two formulations function in exactly the same way.

The main application of non-intrusive serialization is to permit serialization to be implemented for classes without changing the class definition. In order for this to be possible, the class must expose enough information to reconstruct the class state. In this example, we presumed that the class had `public` members - not a common occurence. Only classes which expose enough information to save and restore the class state will be serializable without changing the class definition.

### Serializable Members

A serializable class with serializable members would look like this:

    class bus_stop
    {
        friend class boost::serialization::access;
        template<class Archive>
        void serialize(Archive & ar, const unsigned int version)
        {
            ar & latitude;
            ar & longitude;
        }
        gps_position latitude;
        gps_position longitude;
    protected:
        bus_stop(const gps_position & lat_, const gps_position & long_) :
        latitude(lat_), longitude(long_)
        {}
    public:
        bus_stop(){}
        // See item # 14 in Effective C++ by Scott Meyers.
        // re non-virtual destructors in base classes.
        virtual ~bus_stop(){}
    };

That is, members of class type are serialized just as members of primitive types are.

Note that saving an instance of the class `bus_stop` with one of the archive operators will invoke the `serialize` function which saves `latitude` and `longitude`. Each of these in turn will be saved by invoking `serialize` in the definition of `gps_position`. In this manner the whole data structure is saved by the application of an archive operator to just its root item.

### Derived Classes

Derived classes should include serializations of their base classes.

    #include <boost/serialization/base_object.hpp>

    class bus_stop_corner : public bus_stop
    {
        friend class boost::serialization::access;
        template<class Archive>
        void serialize(Archive & ar, const unsigned int version)
        {
            // serialize base class information
            ar & boost::serialization::base_object<bus_stop>(*this);
            ar & street1;
            ar & street2;
        }
        std::string street1;
        std::string street2;
        virtual std::string description() const
        {
            return street1 + " and " + street2;
        }
    public:
        bus_stop_corner(){}
        bus_stop_corner(const gps_position & lat_, const gps_position & long_,
            const std::string & s1_, const std::string & s2_
        ) :
            bus_stop(lat_, long_), street1(s1_), street2(s2_)
        {}
    };

Note the serialization of the base classes from the derived class. Do NOT directly call the base class serialize functions. Doing so might seem to work but will bypass the code that tracks instances written to storage to eliminate redundancies. It will also bypass the writing of class version information into the archive. For this reason, it is advisable to always make member `serialize` functions private. The declaration `friend boost::serialization::access` will grant to the serialization library access to private member variables and functions.

### Pointers

Suppose we define a bus route as an array of bus stops. Given that

1. we might have several types of bus stops (remember bus_stop is a base class)
2. a given bus_stop might appear in more than one route.

it's convenient to represent a bus route with an array of pointers to `bus_stop`.

    class bus_route
    {
        friend class boost::serialization::access;
        bus_stop * stops[10];
        template<class Archive>
        void serialize(Archive & ar, const unsigned int version)
        {
            int i;
            for(i = 0; i < 10; ++i)
                ar & stops[i];
        }
    public:
        bus_route(){}
    };

Each member of the array `stops` will be serialized. But, remember each member is a pointer - so what can this really mean? The whole object of this serialization is to permit reconstruction of the original data structures at another place and time. In order to accomplish this with a pointer, it is not sufficient to save the value of the pointer, rather the object it points to must be saved. When the member is later loaded, a new object has to be created and a new pointer has to be loaded into the class member.

All this is accomplished automatically by the serialization library. The above code is all that is necessary to accomplish the saving and loading of objects accessed through pointers.

### Arrays

The above formulation is in fact more complex than necessary. The serialization library detects when the object being serialized is an array and emits code equivalent to the above. So the above can be shortened to:

    class bus_route
    {
        friend class boost::serialization::access;
        bus_stop * stops[10];
        template<class Archive>
        void serialize(Archive & ar, const unsigned int version)
        {
            ar & stops;
        }
    public:
        bus_route(){}
    };

### STL Collections

The above example uses an array of members. More likely such an application would use an STL collection for such a purpose. The serialization library contains code for serialization of all STL classes. Hence, the reformulation below will also work as one would expect.

    #include <boost/serialization/list.hpp>

    class bus_route
    {
        friend class boost::serialization::access;
        std::list<bus_stop *> stops;
        template<class Archive>
        void serialize(Archive & ar, const unsigned int version)
        {
            ar & stops;
        }
    public:
        bus_route(){}
    };

### Class Versioning

Suppose we're satisfied with our `bus_route` class, build a program that uses it and ship the product. Some time later, it's decided that the program needs enhancement and the `bus_route` class is altered to include the name of the driver of the route. So the new version looks like:

    #include <boost/serialization/list.hpp>
    #include <boost/serialization/string.hpp>

    class bus_route
    {
        friend class boost::serialization::access;
        std::list<bus_stop *> stops;
        std::string driver_name;
        template<class Archive>
        void serialize(Archive & ar, const unsigned int version)
        {
            ar & driver_name;
            ar & stops;
        }
    public:
        bus_route(){}
    };

Great, we're all done. Except... what about people using our application who now have a bunch of files created under the previous program. How can these be used with our new program version?

In general, the serialization library stores a version number in the archive for each class serialized. By default this version number is 0. When the archive is loaded, the version number under which it was saved is read. The above code can be altered to exploit this

    #include <boost/serialization/list.hpp>
    #include <boost/serialization/string.hpp>
    #include <boost/serialization/version.hpp>

    class bus_route
    {
        friend class boost::serialization::access;
        std::list<bus_stop *> stops;
        std::string driver_name;
        template<class Archive>
        void serialize(Archive & ar, const unsigned int version)
        {
            // only save/load driver_name for newer archives
            if(version > 0)
                ar & driver_name;
            ar & stops;
        }
    public:
        bus_route(){}
    };

    BOOST_CLASS_VERSION(bus_route, 1)

By application of versioning to each class, there is no need to try to maintain a versioning of files. That is, a file version is the combination of the versions of all its constituent classes. This system permits programs to be always compatible with archives created by all previous versions of a program with no more effort than required by this example.

### Splitting `serialize` into `save/load`

The `serialize` function is simple, concise, and guarantees that class members are saved and loaded in the same sequence - the key to the serialization system. However, there are cases where the load and save operations are not as similar as the examples used here. For example, this could occur with a class that has evolved through multiple versions. The above class can be reformulated as:

    #include <boost/serialization/list.hpp>
    #include <boost/serialization/string.hpp>
    #include <boost/serialization/version.hpp>
    #include <boost/serialization/split_member.hpp>

    class bus_route
    {
        friend class boost::serialization::access;
        std::list<bus_stop *> stops;
        std::string driver_name;
        template<class Archive>
        void save(Archive & ar, const unsigned int version) const
        {
            // note, version is always the latest when saving
            ar  & driver_name;
            ar  & stops;
        }
        template<class Archive>
        void load(Archive & ar, const unsigned int version)
        {
            if(version > 0)
                ar & driver_name;
            ar  & stops;
        }
        BOOST_SERIALIZATION_SPLIT_MEMBER()
    public:
        bus_route(){}
    };

    BOOST_CLASS_VERSION(bus_route, 1)

The macro `BOOST_SERIALIZATION_SPLIT_MEMBER()` generates code which invokes the `save` or `load` depending on whether the archive is used for saving or loading.

### Archives

Our discussion here has focused on adding serialization capability to classes. The actual rendering of the data to be serialized is implemented in the archive class. Thus the stream of serialized data is a product of the serialization of the class and the archive selected. It is a key design decision that these two components be independent. This permits any serialization specification to be usable with any archive.

In this tutorial, we have used a particular archive class - `text_oarchive` for saving and `text_iarchive` for loading. There other archives included in with the library and their interfaces are identical (with one exception). Once serialization has been defined for a class, that class can be serialized to any type of archive.

If the current set of archives doesn't provide one with the attributes, format, or behavior need for a particular application, one can either make a new one or derive from an existing one. This is described later in the manual.

Note also that though our examples save and load the program data to an archive within the same program, this merely a convenience for purposes of illustration. In general, the archive may or may not be loaded by the same program that created it.

The complete demo program - demo.cpp does the following:

1. Creates a structure of differing kinds of stops, routes and schedules
2. Displays it
3. Serializes it to a file named "testfile.txt" with one statement
4. Restores to another structure
5. Displays the restored structure

Output of this program is sufficient to verify that all the originally stated requirements for a serialization system are met with this system. The contents of the archive file can also be displayed as serialization files are ASCII text.

© 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)