diff options
| -rw-r--r-- | Doc/lib/libgdbm.tex | 81 | ||||
| -rw-r--r-- | Doc/libgdbm.tex | 81 |
2 files changed, 154 insertions, 8 deletions
diff --git a/Doc/lib/libgdbm.tex b/Doc/lib/libgdbm.tex index 96be165..4cf4cb2 100644 --- a/Doc/lib/libgdbm.tex +++ b/Doc/lib/libgdbm.tex @@ -1,8 +1,81 @@ \section{Built-in Module \sectcode{gdbm}} +\label{module-gdbm} \bimodindex{gdbm} -This module is nearly identical to the \code{dbm} module, but uses -GDBM instead. Its interface is identical, and not repeated here. - -Warning: the file formats created by gdbm and dbm are incompatible. +This module is quite similar to the \code{dbm} module, but uses {\sc gdbm} +instead to provide some additional functionality. Please note that +the file formats created by {\sc gdbm} and dbm are incompatible. \bimodindex{dbm} + +The \code{gdbm} module provides an interface to the GNU DBM +library. {\sc gdbm} objects behave like mappings +(dictionaries), except that keys and values are always strings. +Printing a {\sc 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: + +\renewcommand{\indexsubitem}{(in module dbm)} +\begin{excdesc}{error} +Raised on dbm-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 dbm database and return a dbm object. The \var{filename} +argument is the name of the database file (without the \file{.dir} or +\file{.pag} extensions). + +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, {\sc 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 {\sc 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: +\bcode\begin{verbatim} +k=db.firstkey() +while k!=None: + print k + k=db.nextkey(k) +\end{verbatim}\ecode +\end{funcdesc} + +\begin{funcdesc}{reorganize}{} +If you have carried out a lot of deletions and would like to shrink +the space used by the {\sc gdbm} file, this routine will reorganize the +database. {\sc 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} + diff --git a/Doc/libgdbm.tex b/Doc/libgdbm.tex index 96be165..4cf4cb2 100644 --- a/Doc/libgdbm.tex +++ b/Doc/libgdbm.tex @@ -1,8 +1,81 @@ \section{Built-in Module \sectcode{gdbm}} +\label{module-gdbm} \bimodindex{gdbm} -This module is nearly identical to the \code{dbm} module, but uses -GDBM instead. Its interface is identical, and not repeated here. - -Warning: the file formats created by gdbm and dbm are incompatible. +This module is quite similar to the \code{dbm} module, but uses {\sc gdbm} +instead to provide some additional functionality. Please note that +the file formats created by {\sc gdbm} and dbm are incompatible. \bimodindex{dbm} + +The \code{gdbm} module provides an interface to the GNU DBM +library. {\sc gdbm} objects behave like mappings +(dictionaries), except that keys and values are always strings. +Printing a {\sc 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: + +\renewcommand{\indexsubitem}{(in module dbm)} +\begin{excdesc}{error} +Raised on dbm-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 dbm database and return a dbm object. The \var{filename} +argument is the name of the database file (without the \file{.dir} or +\file{.pag} extensions). + +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, {\sc 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 {\sc 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: +\bcode\begin{verbatim} +k=db.firstkey() +while k!=None: + print k + k=db.nextkey(k) +\end{verbatim}\ecode +\end{funcdesc} + +\begin{funcdesc}{reorganize}{} +If you have carried out a lot of deletions and would like to shrink +the space used by the {\sc gdbm} file, this routine will reorganize the +database. {\sc 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} + |