95 lines
3.8 KiB
TeX
95 lines
3.8 KiB
TeX
\section{Built-in Module \sectcode{gdbm}}
|
|
\label{module-gdbm}
|
|
\bimodindex{gdbm}
|
|
|
|
% Note that if this section appears on the same page as the first
|
|
% paragraph of the dbm module section, makeindex will produce the
|
|
% warning:
|
|
%
|
|
% ## Warning (input = lib.idx, line = 1184; output = lib.ind, line = 852):
|
|
% -- Conflicting entries: multiple encaps for the same page under same key.
|
|
%
|
|
% This is because the \bimodindex{gdbm} and \refbimodindex{gdbm}
|
|
% entries in the .idx file are slightly different (the \bimodindex{}
|
|
% version includes "|textbf" at the end to make the defining occurance
|
|
% bold). There doesn't appear to be anything that can be done about
|
|
% this; it's just a little annoying. The warning can be ignored, but
|
|
% the index produced uses the non-bold version.
|
|
|
|
This module is quite similar to the \code{dbm} module, but uses \code{gdbm}
|
|
instead to provide some additional functionality. Please note that
|
|
the file formats created by \code{gdbm} and \code{dbm} are incompatible.
|
|
\refbimodindex{dbm}
|
|
|
|
The \code{gdbm} module provides an interface to the GNU DBM
|
|
library. \code{gdbm} objects behave like mappings
|
|
(dictionaries), except that keys and values are always strings.
|
|
Printing a \code{gdbm} object doesn't print the keys and values, and the
|
|
\code{items()} and \code{values()} methods are not supported.
|
|
|
|
The module defines the following constant and functions:
|
|
|
|
\setindexsubitem{(in module gdbm)}
|
|
\begin{excdesc}{error}
|
|
Raised on \code{gdbm}-specific errors, such as I/O errors. \code{KeyError} is
|
|
raised for general mapping errors like specifying an incorrect key.
|
|
\end{excdesc}
|
|
|
|
\begin{funcdesc}{open}{filename\, \optional{flag\, \optional{mode}}}
|
|
Open a \code{gdbm} database and return a \code{gdbm} object. The
|
|
\var{filename} argument is the name of the database file.
|
|
|
|
The optional \var{flag} argument can be
|
|
\code{'r'} (to open an existing database for reading only --- default),
|
|
\code{'w'} (to open an existing database for reading and writing),
|
|
\code{'c'} (which creates the database if it doesn't exist), or
|
|
\code{'n'} (which always creates a new empty database).
|
|
|
|
Appending \code{f} to the flag opens the database in fast mode;
|
|
altered data will not automatically be written to the disk after every
|
|
change. This results in faster writes to the database, but may result
|
|
in an inconsistent database if the program crashes while the database
|
|
is still open. Use the \code{sync()} method to force any unwritten
|
|
data to be written to the disk.
|
|
|
|
The optional \var{mode} argument is the \UNIX{} mode of the file, used
|
|
only when the database has to be created. It defaults to octal
|
|
\code{0666}.
|
|
\end{funcdesc}
|
|
|
|
In addition to the dictionary-like methods, \code{gdbm} objects have the
|
|
following methods:
|
|
|
|
\begin{funcdesc}{firstkey}{}
|
|
It's possible to loop over every key in the database using this method
|
|
and the \code{nextkey()} method. The traversal is ordered by \code{gdbm}'s
|
|
internal hash values, and won't be sorted by the key values. This
|
|
method returns the starting key.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{nextkey}{key}
|
|
Returns the key that follows \var{key} in the traversal. The
|
|
following code prints every key in the database \code{db}, without having to
|
|
create a list in memory that contains them all:
|
|
\begin{verbatim}
|
|
k=db.firstkey()
|
|
while k!=None:
|
|
print k
|
|
k=db.nextkey(k)
|
|
\end{verbatim}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{reorganize}{}
|
|
If you have carried out a lot of deletions and would like to shrink
|
|
the space used by the \code{gdbm} file, this routine will reorganize the
|
|
database. \code{gdbm} will not shorten the length of a database file except
|
|
by using this reorganization; otherwise, deleted file space will be
|
|
kept and reused as new (key,value) pairs are added.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{sync}{}
|
|
When the database has been opened in fast mode, this method forces any
|
|
unwritten data to be written to the disk.
|
|
\end{funcdesc}
|
|
|