(index ("open-database" 0) ("close-database" 1592) ("fetch" 1710) ("store!" 2013) ("delete!" 2458) ("pair-iterator" 2631) ("next-pair" 2874) ("pair-fold" 3171))
(def (sig (procedure "(open-database pathname #!key flags mode page-block-power dir-block-power) -> db" (id open-database))) (p "Opens existing SDBM database " (tt "pathname") " or creates an empty database if " (tt "pathname") " does not exist.  The database resides in two files: " (tt "pathname.dir") " (directory file) and " (tt "pathname.pag") " (page file). Returns an opaque database object.") (p "Optional keyword arguments are:") (dl (dt "flags") (dd "flags passed to " (tt "file-open") ", default: " (tt "(+ open/rdwr open/creat)")) (dt "mode") (dd "permissions passed to " (tt "file-open") ", default: " (tt "(+ perm/irwxu perm/irgrp perm/iroth)")) (dt "page-block-power") (dd "bytes in each data page, as a power of 2; default: 12 (4096 bytes)") (dt "dir-block-power") (dd "bytes in each directory block, as a power of 2; default: 12 (4096 bytes)")) (p "The data page size limits the length of a key/value pair, so you may need to increase it to correspond with your maximum pair size. An undersized page can lead to frequent hash bucket splits and a bloated file size with many holes.  An oversized page can incur disk performance overhead on read and write, since an entire page is read or written for every operation.  Values between 4096 and 16384 bytes seem reasonable.") (p "Note: The SDBM format has no database header, so you must always specify the same " (tt "page-block-power") " and " (tt "dir-block-power") " for a given database.  The reference implementation uses " (tt "page-block-power") " of 10 (1024 bytes) and " (tt "dir-block-power") " of 12 (4096 bytes)."))
(def (sig (procedure "(close-database db)" (id close-database))) (p "Close database associated with " (tt "db") "."))
(def (sig (procedure "(fetch db key) -> val" (id fetch))) (p "Fetch " (tt "key") " from SDBM database " (tt "db") ", returning the associated value or " (tt "#f") " if the key did not exist.  The returned value is a string. " (tt "key") " is normally a string; if not, it is converted into a string."))
(def (sig (procedure "(store! db key val #!optional (replace #t))" (id store!))) (p "Store " (tt "key") ", " (tt "val") " pair into SDBM database " (tt "db") ".  " (tt "val") " must be a string; " (tt "key") " is converted into a string if not already.") (p "If the key exists, and optional argument " (tt "replace") " is " (tt "#t") " (the default) then the pair will be replaced.  If replace is " (tt "#f") " instead, an error is returned."))
(def (sig (procedure "(delete! db key)" (id delete!))) (p "Delete " (tt "key") " from SDBM database " (tt "db") ".  If " (tt "key") " does not exist, an error is raised."))
(def (sig (procedure "(pair-iterator db) -> iter" (id pair-iterator))) (p "Return a new pair iterator object that can be used to iterate over pairs in the SDBM database " (tt "db") ".  Pass this iterator to " (tt "next-pair") " repeatedly."))
(def (sig (procedure "(next-pair iter) -> (key . val)" (id next-pair))) (p "Return the next pair that " (tt "iter") ", a " (tt "pair-iterator") ", sees in the database.  If there are no more pairs, returns " (tt "#f") ". Otherwise, it returns a (key . val) pair, where both values are strings."))
(def (sig (procedure "(pair-fold db kons knil) -> kvs" (id pair-fold))) (p "Perform a fold over all pairs in SDBM database " (tt "db") ".  " (tt "knil") " is the initial value.  " (tt "kons") " is a procedure of three arguments: " (tt "(key val kvs)") ".  The return value of " (tt "kons") " is passed to the next execution of " (tt "kons") " in " (tt "kvs") "."))
