man/filehash-class.Rd

   1 \name{filehash-class}
   2 \docType{class}
   3 \alias{filehash-class}
   4 \alias{filehashDB-class}
   5 \alias{filehashRDS-class}
   6 \alias{filehashDB1-class}
   7 \alias{dbFetch}
   8 \alias{dbMultiFetch}
   9 \alias{dbInsert}
  10 \alias{dbExists}
  11 \alias{dbList}
  12 \alias{dbDelete}
  13 \alias{dbReorganize}
  14 \alias{dbUnlink}
  15 \alias{dbDelete,filehashDB,character-method}
  16 \alias{dbExists,filehashDB,character-method}
  17 \alias{dbFetch,filehashDB,character-method}
  18 \alias{dbInsert,filehashDB,character-method}
  19 \alias{dbList,filehashDB-method}
  20 \alias{dbUnlink,filehashDB-method}
  21 \alias{dbReorganize,filehashDB-method}
  22 \alias{dbMultiFetch,filehashDB1-method}
  23 \alias{dbDelete,filehashDB1,character-method}
  24 \alias{dbExists,filehashDB1,character-method}
  25 \alias{dbFetch,filehashDB1,character-method}
  26 \alias{dbMultiFetch,filehashDB1,character-method}
  27 \alias{dbInsert,filehashDB1,character-method}
  28 \alias{dbList,filehashDB1-method}
  29 \alias{dbUnlink,filehashDB1-method}
  30 \alias{dbReorganize,filehashDB1-method}
  31 \alias{dbDelete,filehashRDS,character-method}
  32 \alias{dbExists,filehashRDS,character-method}
  33 \alias{dbFetch,filehashRDS,character-method}
  34 \alias{dbInsert,filehashRDS,character-method}
  35 \alias{dbList,filehashRDS-method}
  36 \alias{dbUnlink,filehashRDS-method}
  37 \alias{show,filehash-method}
  38 \alias{with,filehash-method}
  39 \alias{coerce,filehashDB,filehashRDS-method}
  40 \alias{coerce,filehashRDS,filehashDB-method}
  41 \alias{coerce,filehashDB1,filehashRDS-method}
  42 \alias{coerce,filehashDB1,list-method}
  43 \alias{coerce,filehashDB,filehashDB1-method}
  44 \alias{lapply,filehash-method}
  45
  46 \alias{[,filehash,ANY,ANY,missing-method}
  47 \alias{[,filehashDB1,character,missing,missing-method}
  48 \alias{[[,filehash,character,missing-method}
  49 \alias{[[,filehash,numeric,missing-method}
  50 \alias{[[<-,filehash,character,missing-method}
  51 \alias{[[<-,filehash,numeric,missing-method}
  52 \alias{$<-,filehash,character-method}
  53 \alias{$,filehash,character-method}
  54
  55 \title{Class "filehash"}
  56
  57 \description{
  58   These functions form the interface for a simple file-based key-value
  59   database (i.e. hash table).
  60 }
  61
  62 \section{Objects from the Class}{
  63   Objects can be created by calls of the form \code{new("filehash", ...)}.
  64 }
  65
  66 \section{Slots}{
  67   \describe{
  68     \item{\code{name}:}{Object of class \code{"character"}, name of the
  69       database.}
  70   }
  71 }
  72
  73 \section{Additional slots for "filehashDB1"}{
  74   \describe{
  75     \item{\code{datafile}:}{full path to the database file.}
  76     \item{\code{meta}:}{list containing an environment for database
  77       metadata.}
  78   }
  79 }
  80
  81 \section{Additional slots for "filehashRDS"}{
  82   \describe{
  83     \item{dir:}{Directory where files are stored.}
  84   }
  85 }
  86
  87 \section{Methods}{
  88   \describe{
  89     \item{dbDelete}{The \code{dbDelete} function is for deleting
  90       elements, but for the \code{"DB1"} format all it does is remove the
  91       key from the lookup table.
  92       The actual data are still in the database (but inaccessible).  If
  93       you reinsert data for the same key, the new data are simply
  94       appended on to the end of the file.  Therefore, it's possible to
  95       have multiple copies of data lying around after a while,
  96       potentially making the database file big.  The \code{"RDS"} format
  97       does not have this problem.}
  98     \item{dbExists}{check to see if a key exists.}
  99     \item{dbFetch}{retrieve the value associated with a given key.}
 100     \item{dbMultiFetch}{retrieve values associated with multiple keys (a
 101       list of those values is returned).}
 102     \item{dbInsert}{insert a key-value pair into the database.  If
 103       that key already exists, its associated value is overwritten. For
 104       \code{"RDS"} type databases, there is a \code{safe} option
 105       (defaults to \code{TRUE}) which allows the user to insert objects
 106       somewhat more safely (objects should not be lost in the event of
 107       an interrupt).}
 108     \item{dbList}{list all keys in the database.}
 109     \item{dbReorganize}{The \code{dbReorganize} function is there for
 110       the purpose of rewriting the database to remove all of the stale
 111       entries.  Basically, this function creates a new copy of the
 112       database and then overwrites the old copy.  This function has not
 113       been tested extensively and so should be considered
 114       \emph{experimental}.  \code{dbReorganize} is not needed when using
 115       the \code{"RDS"} format.}
 116     \item{dbUnlink}{delete an entire database from the disk}
 117     \item{show}{print method}
 118     \item{with}{allows \code{with} to be used with \code{"filehash"}
 119       objects much like it can be used with lists or data frames}
 120     \item{[[,[[<-}{elements of a database can be accessed using the \code{[[}
 121       operator much like a list or environment, but only character
 122       indices are allowed}
 123     \item{$,$<-}{elements of a database can be accessed using the \code{$}
 124       operator much like with a list or environment}
 125     \item{lapply}{works much like \code{lapply} with lists; a list is
 126       returned.}
 127   }
 128 }
 129
 130 \author{Roger D. Peng \email{rpeng@jhsph.edu}}
 131
 132 \examples{
 133 dbCreate("myDB")  ## Create database 'myDB'
 134 db <- dbInit("myDB")
 135 dbInsert(db, "a", 1:10)
 136 dbInsert(db, "b", rnorm(1000))
 137 dbExists(db, "b")  ## 'TRUE'
 138
 139 dbList(db)  ## c("a", "b")
 140 dbDelete(db, "a")
 141 dbList(db) ## "b"
 142
 143 with(db, mean(b))
 144 }
 145 \keyword{classes}