Because dbstl is so much like C++ STL, its usage exactly
mirrors that of C++ STL, with the exception of a few optional
Berkeley DB specific configurations. In fact, the only
difference between a program using dbstl and one using C++ STL
is the class names. That is, vector
becomes db_vector, and
map becomes
db_map.
The typical procedure for using dbstl is:
Optionally create and open your own Berkeley DB environment and database handles using the DB C++ API. If you perform these opens using the C++ API, make sure to perform necessary environment and database configurations at that time.
Optionally pass environment and database handles to dbstl container constructors when you create dbstl container objects. Note that you can create a dbstl container without passing it an environment and database object. When you do this, an internal anonymous database is created for you. In this situation, dbstl provides no data persistence guarantees.
Perform dbstl-specific configurations. For example, you can configure cursor open flags, as well as database access for autocommit. You can also configure callback functions.
Interact with the data contained in your Berkeley DB databases using dbstl containers and iterators. This usage of dbstl is identical to C++ STL container and iterator usage.
At this time, you can also use dbstl calls that are specific to Berkeley DB. For example, you can use Berkeley DB specific calls that manage transaction begin/commit/abort, handle registration, and so forth. While these calls are part of dbstl, they have no equivalence in the C++ STL APIs.
When your application is done using Berkeley DB, you do not need to explicitly close any Berkeley DB handles (environments, database, cursors, and so forth). Dbstl automatically closes all such handles for you.
For examples of dbstl usage, see the example programs in
the $db/examples/stl directory.
The following program listing provides two code fragments.
You can find more example code in the
dbstl/examples/ and
dbstl/test directories.
//////////////// Code Snippet 1 ////////////////
db_vector<int, ElementHolder<int> > vctr(100);
for (int i = 0; i < 100; i++)
vctr[i] = i;
for (int i = 0; i < 100; i++) {
cout<<"\nvctr["<<i<<"] : "<<vctr[i];
vctr[i] = vctr[i] * vctr[i];
cout<<"\nvctr["<<i<<"] squre : "<<vctr[i];
}
//////////////// Code Snippet 2 ////////////////
typedef db_map<char *, const char *, ElementHolder<const char *> >
strmap_t2;
strmap_t2 strmap;
char str[2], str2[2];
str[1] = str2[1] = '\0';
for (char c = 0; c < 26; c++) {
str[0] = c + 'a';
str2[0] = 'z' - c;
strmap[str] = str2;
}
for (strmap_t2::iterator itr = strmap.begin(); itr != strmap.end(); ++itr)
cout<<endl<<itr->first<<" : "<<itr->second;
using namespace dbstl;
dbstl::db_map<char, int> v;
v['i'] = 1;
cout<<v['i'];
dbstl::db_map<char *, char *> name_addr_map;
// The strings rather than the memory pointers are stored into DB.
name_addr_map["Alex"] = "Sydney Australia";
name_addr_map["David"] = "Shenzhen China";
cout<<"Alex's address:"<<name_addr_map["Alex"];
dbstl::db_vector<Person> vi;
// Some callback configurations follow here.
// The strings and objects rather than pointers are stored into DB.
Person obj("David Zhao", "Oracle", new Office("Boston", "USA"));
vi.push_back(obj); // More person storage.
for (int I = 0; I < vi.size(); I++)
cout<<vi[I];
The first snippet initializes a db_vector container of 100
elements, with an in-memory anonymous database internally
created by dbstl. The only difference between this and C++ STL
is dbstl requires one more type parameter:
ElementHolder<int>. The
ElementHolder class template should
be used for every type of dbstl container that will store C++
primitive data types, such as int,
float, char *,
wchar_t *, and so forth. But these
class templates should not be used for class types for reasons
that we explain in the following chapters.
In the second code snippet, the assignment:
strmap[str] = str2;
is used to store a string pair ((str,
str2)) instead of pointers to the underlying
database.
The rest of the code used in these snippets is identical to the code you would use for C++ STL containers. However, by using dbstl, you are storing data into a Berkeley DB database. If you create your own database with backing files on disk, your data or objects can persist and be restored when the program runs again.