| 1 |
// |
| 2 |
// The following program illustrates how to use references to search for |
| 3 |
// items in "geners" archives together with the various methods that |
| 4 |
// can be used to retrieve the items |
| 5 |
// |
| 6 |
#include <cassert> |
| 7 |
#include <iostream> |
| 8 |
|
| 9 |
#include "geners/StringArchive.hh" |
| 10 |
#include "geners/Record.hh" |
| 11 |
#include "geners/Reference.hh" |
| 12 |
|
| 13 |
using namespace gs; |
| 14 |
using namespace std; |
| 15 |
|
| 16 |
// We will use the following function to print out the items found |
| 17 |
// in the archive by an archive reference. All items considered in |
| 18 |
// this example are simple strings. |
| 19 |
// |
| 20 |
static void print_items(const Reference<string>& ref) |
| 21 |
{ |
| 22 |
// Total number of items found by the reference |
| 23 |
const unsigned long nItems = ref.size(); |
| 24 |
|
| 25 |
// Print the info about the reference to the standard output |
| 26 |
cout << "Found " << nItems << " item" |
| 27 |
<< (nItems == 1 ? "" : "s") |
| 28 |
<< " in the archive using name pattern \"" |
| 29 |
<< ref.namePattern().pattern() << '"' |
| 30 |
<< (ref.namePattern().useRegex() ? " (regex)" : " (exact)") |
| 31 |
<< "\nand category pattern \"" |
| 32 |
<< ref.categoryPattern().pattern() << '"' |
| 33 |
<< (ref.categoryPattern().useRegex() ? " (regex)" : " (exact)") |
| 34 |
<< (nItems ? ":\n" : ".\n"); |
| 35 |
|
| 36 |
// Cycle over the items found, retrieve them from the archive, |
| 37 |
// and print them |
| 38 |
for (unsigned long i=0; i<nItems; ++i) |
| 39 |
{ |
| 40 |
// Here, we will overwrite a string on the stack with a stored |
| 41 |
// string. See the code of "main" for other retrieval methods. |
| 42 |
string item; |
| 43 |
ref.restore(i, &item); |
| 44 |
cout << i+1 << ". " << item << '\n'; |
| 45 |
} |
| 46 |
} |
| 47 |
|
| 48 |
|
| 49 |
int main(int, char**) |
| 50 |
{ |
| 51 |
// The archive to use |
| 52 |
StringArchive ar; |
| 53 |
|
| 54 |
// A number of items to store in the archive |
| 55 |
const string st1 = "Hello, world!"; |
| 56 |
const string st2 = "Goodbye world"; |
| 57 |
const string st3 = "Casablanka"; |
| 58 |
const string st4 = "Gone with the Wind"; |
| 59 |
const string st5 = "Tomorrow Never Dies"; |
| 60 |
const string st6 = "Quantum of Solace"; |
| 61 |
const string st7 = "Titanic"; |
| 62 |
const string st8 = "Avatar"; |
| 63 |
|
| 64 |
// Store the items |
| 65 |
ar << Record(st1, "hello", "Greetings") |
| 66 |
<< Record(st2, "goodbye", "Greetings") |
| 67 |
<< Record(st3, "classics", "Movies") |
| 68 |
<< Record(st4, "classics", "Movies") |
| 69 |
<< Record(st5, "tomorrow", "Movies/James Bond") |
| 70 |
<< Record(st6, "quantum", "Movies/James Bond") |
| 71 |
<< Record(st7, "movie 1", "Movies/Cameron") |
| 72 |
<< Record(st8, "movie 2", "Movies/Cameron"); |
| 73 |
|
| 74 |
// Find an exact item using unique name/category combination. |
| 75 |
// In this case the "size()" method of the reference will |
| 76 |
// return 1 and "unique()" will return "true". |
| 77 |
// |
| 78 |
cout << "\n** Searching for a unique name/category combination" << endl; |
| 79 |
Reference<string> ref1(ar, "hello", "Greetings"); |
| 80 |
assert(ref1.unique()); |
| 81 |
print_items(ref1); |
| 82 |
|
| 83 |
// What happens if name/category combination does not |
| 84 |
// exist? The reference "size()" method will return 0 |
| 85 |
// and "empty()" will return "true". |
| 86 |
// |
| 87 |
cout << "\n** What if name/category combination does not exist?" << endl; |
| 88 |
Reference<string> ref2(ar, "no such name", "Greetings"); |
| 89 |
assert(ref2.empty()); |
| 90 |
print_items(ref2); |
| 91 |
|
| 92 |
// What happens if more than one item exists with the given |
| 93 |
// name/category combination? The reference will simply |
| 94 |
// collect all such items. |
| 95 |
// |
| 96 |
cout << "\n** What if there is more than one item " |
| 97 |
<< "with given name/category?" << endl; |
| 98 |
Reference<string> ref3(ar, "classics", "Movies"); |
| 99 |
print_items(ref3); |
| 100 |
|
| 101 |
// Archive references support regular expressions for names |
| 102 |
// and categories. If the "geners" package was compiled with |
| 103 |
// a C++11-enabled compiler, the standard C++11 "regex" engine |
| 104 |
// is used, otherwise POSIX extended regular expressions are used. |
| 105 |
// Note that the default mode of C++11 regex is "ECMAScript" |
| 106 |
// which is somewhat different from POSIX extended regular |
| 107 |
// expressions. If you really want to know the details of the |
| 108 |
// ECMAScript regex syntax, read the "RegExp" section of |
| 109 |
// http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-262.pdf |
| 110 |
// |
| 111 |
// The number of operations needed to search for an item in |
| 112 |
// an archive using exact name and category typically scales as |
| 113 |
// O(log(C) + log(N)), where C is the number of categories and N |
| 114 |
// is the number of items in the category to which the item belongs. |
| 115 |
// If regular expressions are used, the scaling behavior changes. |
| 116 |
// In general, this behavior depends on the details of the archive |
| 117 |
// catalog implementation. The catalogs currently implemented |
| 118 |
// in the "geners" package typically need O(N*log(C)) |
| 119 |
// operations if regular expression search is used for item name |
| 120 |
// only, O(C_m*log(N)) if regular expression search is used for |
| 121 |
// category only (where C_m is the number of categories matching |
| 122 |
// the expression), and O(C_m*N) if regular expressions are used |
| 123 |
// for both name and category. Therefore, regex searching can take |
| 124 |
// a considerable amount of time for large catalogs. |
| 125 |
// |
| 126 |
// In the examples below, a special constructor is used for the |
| 127 |
// "SearchSpecifier" objects with which references are made. |
| 128 |
// This is because we want to be able to print the regular |
| 129 |
// expressions used, and C++11 regular expressions do not |
| 130 |
// have a method to retrieve the original expression string |
| 131 |
// from them. When this special constructor is used, |
| 132 |
// "SearchSpecifier" stores this string for subsequent retrieval. |
| 133 |
// |
| 134 |
cout << "\n** Regex example -- arbitrary name" << endl; |
| 135 |
Reference<string> ref4(ar, SearchSpecifier(".*", true), "Greetings"); |
| 136 |
print_items(ref4); |
| 137 |
|
| 138 |
cout << "\n** Regex example -- same search, but using regex argument " |
| 139 |
<< "directly. Note\n that the regular expression itself can no " |
| 140 |
<< "longer be extracted from such\n an argument. This example " |
| 141 |
<< "prints an empty string instead." << endl; |
| 142 |
Reference<string> ref5(ar, Regex(".*"), "Greetings"); |
| 143 |
print_items(ref5); |
| 144 |
|
| 145 |
cout << "\n** Regex example -- arbitrary category" << endl; |
| 146 |
Reference<string> ref6(ar, "quantum", SearchSpecifier(".*", true)); |
| 147 |
print_items(ref6); |
| 148 |
|
| 149 |
cout << "\n** Regex example -- name matching a substring, " |
| 150 |
<< "arbitrary category" << endl; |
| 151 |
Reference<string> ref7(ar, SearchSpecifier("(.*)movie(.*)", true), |
| 152 |
SearchSpecifier(".*", true)); |
| 153 |
print_items(ref7); |
| 154 |
|
| 155 |
// There are three main methods by which items can be retrieved from |
| 156 |
// the archive: |
| 157 |
// |
| 158 |
// 1. Overwrite another item of the same type present on the stack. |
| 159 |
// This method is appropriate for built-in types, standard |
| 160 |
// containers, and user-defined classes or templates that have |
| 161 |
// a default constructor (in addition, these classes or templates |
| 162 |
// should not be members of any inheritance hierarchy). |
| 163 |
// |
| 164 |
// 2. Get a unique pointer (std::unique_ptr for C++11, std::auto_ptr |
| 165 |
// before that) to an item built on the heap. "geners" package |
| 166 |
// uses "CPP11_auto_ptr" macro to name such a unique pointer. |
| 167 |
// This method is most typical for types that do not have a default |
| 168 |
// constructor or for members of some inheritance hierarchy. Items |
| 169 |
// of derived types can be retrieved using a pointer to their base |
| 170 |
// class if they are stored in the archive by reference to the base |
| 171 |
// class. |
| 172 |
// |
| 173 |
// 3. Get a shared pointer (std::shared_ptr for C++11, std::tr1::shared_ptr |
| 174 |
// before that) to an item built on the heap. "geners" package |
| 175 |
// uses "CPP11_shared_ptr" macro to name such a shared pointer. |
| 176 |
// Use this method whenever joint item ownership via a shared |
| 177 |
// pointer is appropriate for your code. |
| 178 |
// |
| 179 |
// Method 1 is how the "print_items" function defined earlier in this |
| 180 |
// file retrieves the strings from the archive. The following code |
| 181 |
// illustrates the other two methods. |
| 182 |
// |
| 183 |
cout << "\n** Placing an item on the heap using a unique pointer" << endl; |
| 184 |
CPP11_auto_ptr<string> p1 = ref1.get(0); |
| 185 |
cout << *p1 << endl; |
| 186 |
|
| 187 |
cout << "\n** Placing an item on the heap using a shared pointer" << endl; |
| 188 |
CPP11_shared_ptr<string> p2 = ref1.getShared(0); |
| 189 |
cout << *p2 << endl; |
| 190 |
|
| 191 |
// We are done |
| 192 |
return 0; |
| 193 |
} |