| 1 |
// |
| 2 |
// The following program illustrates very basic usage of the archive I/O |
| 3 |
// in the "geners" package |
| 4 |
// |
| 5 |
#include <cassert> |
| 6 |
#include <iostream> |
| 7 |
|
| 8 |
#include "geners/StringArchive.hh" |
| 9 |
#include "geners/Record.hh" |
| 10 |
#include "geners/Reference.hh" |
| 11 |
|
| 12 |
// All "geners" facilities reside in the namespace "gs". |
| 13 |
using namespace gs; |
| 14 |
using namespace std; |
| 15 |
|
| 16 |
int main(int, char**) |
| 17 |
{ |
| 18 |
// The archive to use |
| 19 |
StringArchive ar; |
| 20 |
|
| 21 |
// The object which we want to store in the archive |
| 22 |
const string greeting = "Hello, world!"; |
| 23 |
|
| 24 |
// Store the object in the archive. Besides a reference to the object, |
| 25 |
// "Record" function takes two additional arguments: item name and |
| 26 |
// item category. Both of these are arbitrary C-strings (C++ strings |
| 27 |
// can be used as well), intended to be convenient for labelling the |
| 28 |
// object for subsequent retrieval. |
| 29 |
// |
| 30 |
ar << Record(greeting, "My greeting", "Greetings"); |
| 31 |
|
| 32 |
// It is worth emphasizing that, for performance reasons, "Record" takes |
| 33 |
// a reference to the object instead of making a copy. This means that |
| 34 |
// the "greeting" object in the above example must not go out of scope |
| 35 |
// before the archive writing is complete. For example, it would not be |
| 36 |
// a good idea to do something like this: |
| 37 |
// |
| 38 |
// ar << Record(std::string("Don't do this"), "Trouble", "Bugs"); |
| 39 |
// |
| 40 |
// even though this code will compile and might even work as intended |
| 41 |
// on some systems. The problem is that the object |
| 42 |
// std::string("Don't do this") can be destroyed after "Record" runs |
| 43 |
// to completion but before operator << starts executing. |
| 44 |
// |
| 45 |
// If you are ready to sacrifice some efficiency for API convenience, |
| 46 |
// use the "ValueRecord" function instead which stores a copy of the |
| 47 |
// argument object internally: |
| 48 |
// |
| 49 |
// ar << ValueRecord(std::string("This is OK"), "but less efficient", ""); |
| 50 |
|
| 51 |
// Now, we will find the object in the archive by creating an archive |
| 52 |
// reference. Here, we are simply looking up an item of type "string" |
| 53 |
// with the same name and category as in the record used above. |
| 54 |
// |
| 55 |
Reference<string> ref(ar, "My greeting", "Greetings"); |
| 56 |
|
| 57 |
// Make sure that exactly one item with the given name, category, |
| 58 |
// and type was found in the archive |
| 59 |
// |
| 60 |
assert(ref.unique()); |
| 61 |
|
| 62 |
// Retrieve the object from the archive. Here, we will overwrite |
| 63 |
// another object of the same type already present on the stack |
| 64 |
// (it is also possible to retrive archive items in other ways, |
| 65 |
// see "use_of_references.cc" example for illustrations). The first |
| 66 |
// argument of the "restore" method of the reference is the item |
| 67 |
// number in the set of items found by that particular reference. |
| 68 |
// In general, an archive reference may find more than one item |
| 69 |
// satisfying its search criteria. |
| 70 |
// |
| 71 |
string greeting2; |
| 72 |
ref.restore(0, &greeting2); |
| 73 |
|
| 74 |
// Print the retrieved and the original objects |
| 75 |
// |
| 76 |
cout << "Original greeting is \"" << greeting << '"' << endl; |
| 77 |
cout << "Archived greeting is \"" << greeting2 << '"' << endl; |
| 78 |
|
| 79 |
// We are done |
| 80 |
return 0; |
| 81 |
} |