Adding an Easy File Save and File Load Mechanism to Your C++ Program
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
When you create a software package, you want to focus on making the software do what it is intended to do. The last thing you want to worry about is spending hours writing something that could apply to millions of other software programs out there. That's what reuse is for, and hopefully somebody already wrote that piece of code for you.
A good example of this type of problem is giving your program the capability to save documents. For example, you might be writing the greatest astronomy program ever—in this program your users can easily put in the current time and coordinates, and the program maps the current sky. But suppose that you give the users the ability to highlight certain stars so they easily stand out in the map. And finally, you want the users to be able to save their configuration for later use.
Your program focuses on astronomy. You are not writing a general-purpose library for saving documents, so you shouldn't have to spend too much time on the saving features. You want to focus on the astronomy features of the program. If you're using C++, you can get help for such reusability from the Boost library. For saving files, the Boost library includes a serialization class, which is exactly what you need.
If you built your program well, you probably have a class containing the user information, or a document. For example, you might have a class that lists the names of the user's favorite stars favorite location. (I haven't written an astronomy program, so forgive me for the simplicity here!) And that's the information you want your users to be able to save to disk. After all, almost any program does file saving. Microsoft Word saves text and formatting data. Excel saves spreadsheet data. A mapping program such as Streets and Trips or Street Atlas saves favorite locations, GPS routes, trips, and so on.
With the help of the Boost serialization library, saving is easy. All you have to do is set up your classes correctly, and the library takes care of the rest—allowing you to focus on your real work.
The idea is simple: You create an object containing the user's data. When ready to save the information, the user chooses File, Save As and selects a filename from the file dialog box that opens. With the help of Boost, your program then saves the data to the chosen file. Later, when the user restarts the program, chooses File, Open, and selects the saved file, your program again uses Boost—but this time to reload the data, thereby re-creating the object. Voila, the user data is restored! Or, from the eyes of the user, the document has been opened.
Because I'm not an expert on astronomy programs, I've written a sample that instead demonstrates the saving and loading of some graphic classes. The first class, Vertex, represents a point in two dimensions. The second class, Polygon, contains a container of Vertex instances. The third class, Drawing, contains a container of Polygon instances.
Trying to save all this to a document might be nightmarish and it's not something you want to focus your time on. You want to have the best graphics program around because that's your field of expertise. Why waste your time figuring out an algorithm for storing things in a file? And why spend time debugging such code? Let the Boost library do it for you.
Serializing a Class
First, consider the Vertex class. That's the easiest one to serialize because it doesn't contain containers of other objects. It just contains two values, x and y, both of type double. I also gave the class some accessor functions for the x and y values, as well as a dump function, which prints out the values of x and y to the console. Finally, I also included two constructors, a default, and one that takes an initial x and y value. (To keep it simple, this program doesn't actually do any real drawing. Sorry!)
That's all pretty easy. The exciting part is adding the necessary lines to make the class serialized. Following is the class (the basic stuff is shown in regular text; the serialization lines are shown in bold):
class Vertex {
private:
friend class boost::serialization::access;
template<class Archive>
void serialize(Archive & ar, const unsigned int version)
{
ar & x;
ar & y;
}
double x;
double y;
public:
Vertex() {} // Serialization requires a default constructor
Vertex(double newX, double newY) : x(newX), y(newY) {}
double getX() const { return x; }
double getY() const { return y; }
void dump() {
cout << x << " " << y << endl;
}
};
Note that in the final program I won't actually be using the default constructor, Vertex(), but the serialization library does call it, so I need to include it.
The first of the serialization lines allows the serialization library access to the private members, particularly the serialize function, which comes next. The creator of the serialization library, Robert Ramey, points out that you do not want any functions, including those in derived classes, calling your serialize method; you want it called only by the serialization library. To give your class the right protection, therefore, you want to make the serialize function private and then grant restricted access to the serialization library by making the boost::serialization::access class a friend of your class, as I did in this code.
Next is the serialize function, which is a template function. If you're not that familiar with template functions, I have good news for you: You don't need to understand the template portions of this function to make it work. Whew! Instead, make sure that you understand the meat of the serialize function—the part in-between braces:
ar & x; ar & y;
First, let me be clear: These two lines of code do not declare reference variables, even though that's what they look like they do. Instead, they invoke an & operator and do the work of writing your members to a file or reading them in. Yes, you read that correctly; this function kills two birds with one stone (or to be more politically correct, accomplishes two tasks with one set of code). When you're saving a Vertex object to a file, the serialization library calls this serialize function; the first line writes the x value to the file, and the second line writes the y value to the file. Later, when you're reading a Vertex object back in from a file, the first line reads in the x value from the file, and the second line reads in the y value from the file.
That's some serious fancy-schmancy operator overloading! The & character is, in fact, an operator defined down in the bowels of the serialization library, and the good news is that you don't need to know how it works. (I didn't bother looking at the serialization source code. You can if you want, but you don't have to in order to use it.)
Well that's pretty simple. Here's some sample code for you in case you want to try out just saving a Vertex object into a file:
Vertex v1(1.5, 2.5);
std::ofstream ofs("myfile.vtx");
boost::archive::text_oarchive oa(ofs);
oa << v1;
ofs.close();
That's it! The first line creates the Vertex object. The next four lines open a file, associate a special serialization class with the file, write to the file, and close the file. Now here's some code to read in a Vertex object from this file:
Vertex v2;
std::ifstream ifs("myfile.vtx", std::ios::binary);
boost::archive::text_iarchive ia(ifs);
ia >> v2;
ifs.close();
v2.dump();
This code creates an instance of Vertex and then again opens a file (but this time for reading), associates a serialization class with the file, reads the object in, and closes the file. Finally, the code dumps out the values of the Vertex. If you put the two preceding blocks of code in a main function and run it, you'll see the original two values, 1.5 and 2.5, print out.