Structure Polygdbm
(* Polygdbm -- interface to GNU gdbm, persistent polymorphic hashtables
Version 0.0, 1997-11-09
*)
type ('key, 'data) table
(* Read-only access is non-exclusive; read/write access excludes others *)
exception NotFound
exception AlreadyThere
exception NotWriter
exception Closed
exception GdbmError of string
val withtable : string * Gdbm.openmode -> (('key, 'data) table -> 'a) -> 'a
val add : ('key, 'data) table -> 'key * 'data -> unit
val insert : ('key, 'data) table -> 'key * 'data -> unit
val find : ('key, 'data) table -> 'key -> 'data
val peek : ('key, 'data) table -> 'key -> 'data option
val hasKey : ('key, 'data) table -> 'key -> bool
val remove : ('key, 'data) table -> 'key -> unit
val listKeys : ('key, 'data) table -> 'key list
val numItems : ('key, 'data) table -> int
val listItems : ('key, 'data) table -> ('key * 'data) list
val app : ('key * 'data -> unit) -> ('key, 'data) table -> unit
val map : ('key * 'data -> 'a) -> ('key, 'data) table -> 'a list
val fold : ('key * 'data * 'a -> 'a) -> 'a -> ('key, 'data) table -> 'a
val fastwrite : bool ref
val reorganize : ('key, 'data) table -> unit
(*
The type [('key, 'data) table] is the type of an opened table with
keys of type 'key and associated values of type 'data. The actual
values of type 'key and 'data cannot contain function closures or
abstract values. Values involving references (even circular
values) can be stored, but the identity of references is preserved
only with every single key or value stored, not across several
different values.
The Polygdbm table files of are not portable across platforms,
because word size and endianness affects the lay-out of values.
Note that the table can be used only inside the withtable function,
to make sure that the table is closed after use.
[withtable (nam, mod) f] first opens the table db in file nam with
mode mod, then applies f to db, then closes db. Makes sure to
close db even if an exception is raised during the evaluation of
f(db). Raises GdbmError with an informative message in case the
table cannot be opened. E.g. the table cannot be opened for
reading if already opened for writing, and cannot be opened for
writing if already opened for reading.
[add db (k,v)] adds the pair (k, v) to db. Raises AlreadyThere if
there is a pair (k, _) in db already. Raises NotWriter if db is
not opened in write mode.
[insert db (k, v)] adds the pair (k, v) to db, replacing any pair
(k, _) at k if present. Raises NotWriter if db is not opened in
write mode.
[find(db, k)] returns v if the pair (k, v) is in db; otherwise
raises NotFound.
[hasKey(db, k)] returns true if there is a pair (k, _) in db;
otherwise returns false.
[remove db k] deletes the pair (k, _) from the table if present;
otherwise raises NotFound. Raises NotWriter if db is not opened in
write mode.
[listKeys db] returns a list of all keys in db in an unspecified
order.
[numItems db] is the number of (key, value) pairs in db.
Equivalent to length(listKeys db).
[listItems db] returns a list of all (key, value) pairs in db in some
order. Equivalent to
List.map (fn key => (key, find(db,key))) (listKeys db)
[app f db] is equivalent to List.app f (listItems db), provided the
function f does not change the set of keys in the table.
Otherwise the effect is unpredictable.
[map f db] is equivalent to List.map f (listItems db), provided the
function f does not change the set of keys in the table.
Otherwise the result and effect are unpredictable.
[fold f a db] is equivalent to
List.foldr (fn ((k, v), r) => f(k, v, r)) a (listItems db)
provided the function f does not change the set of keys in the
table. Otherwise the result and effect are unpredictable.
[fastwrite] can be set to speed up writes to a table. By default,
!fastwrite is false and every write to a table will be followed by
file system synchronization. This is safe, but slow if you perform
thousands of writes. However, if !fastwrite is true when calling
withtable, then writes may not be followed by synchronization,
which may speed up writes considerably. In any case, the file
system is synchronized before withtable returns.
[reorganize db] has no visible effect, but may be called after a
lot of deletions to shrink the size of the table file.
*)
Moscow ML 1.43