Debian Codegraph @

examples/use_of_references.cc

raw
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 }