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{dbDisconnect}
  16 \alias{dbDelete,filehashDB,character-method}
  17 \alias{dbExists,filehashDB,character-method}
  18 \alias{dbFetch,filehashDB,character-method}
  19 \alias{dbInsert,filehashDB,character-method}
  20 \alias{dbList,filehashDB-method}
  21 \alias{dbUnlink,filehashDB-method}
  22 \alias{dbReorganize,filehashDB-method}
  23 \alias{dbMultiFetch,filehashDB1-method}
  24 \alias{dbDelete,filehashDB1,character-method}
  25 \alias{dbExists,filehashDB1,character-method}
  26 \alias{dbFetch,filehashDB1,character-method}
  27 \alias{dbMultiFetch,filehashDB1,character-method}
  28 \alias{dbInsert,filehashDB1,character-method}
  29 \alias{dbList,filehashDB1-method}
  30 \alias{dbUnlink,filehashDB1-method}
  31 \alias{dbDisconnect,filehashDB1-method}
  32 \alias{dbReorganize,filehashDB1-method}
  33 \alias{dbDelete,filehashRDS,character-method}
  34 \alias{dbExists,filehashRDS,character-method}
  35 \alias{dbFetch,filehashRDS,character-method}
  36 \alias{dbInsert,filehashRDS,character-method}
  37 \alias{dbList,filehashRDS-method}
  38 \alias{dbUnlink,filehashRDS-method}
  39 \alias{show,filehash-method}
  40 \alias{with,filehash-method}
  41 \alias{coerce,filehashDB,filehashRDS-method}
  42 \alias{coerce,filehashRDS,filehashDB-method}
  43 \alias{coerce,filehashDB1,filehashRDS-method}
  44 \alias{coerce,filehashDB1,list-method}
  45 \alias{coerce,filehashDB,filehashDB1-method}
  46 \alias{lapply,filehash-method}
  47
  48 \alias{[,filehash,ANY,ANY,missing-method}
  49 \alias{[,filehashDB1,character,missing,missing-method}
  50 \alias{[[,filehash,character,missing-method}
  51 \alias{[[,filehash,numeric,missing-method}
  52 \alias{[[<-,filehash,character,missing-method}
  53 \alias{[[<-,filehash,numeric,missing-method}
  54 \alias{$<-,filehash,character-method}
  55 \alias{$,filehash,character-method}
  56
  57 \title{Class "filehash"}
  58
  59 \description{
  60   These functions form the interface for a simple file-based key-value
  61   database (i.e. hash table).
  62 }
  63
  64 \section{Objects from the Class}{
  65   Objects can be created by calls of the form \code{new("filehash", ...)}.
  66 }
  67
  68 \section{Slots}{
  69   \describe{
  70     \item{\code{name}:}{Object of class \code{"character"}, name of the
  71       database.}
  72   }
  73 }
  74
  75 \section{Additional slots for "filehashDB1"}{
  76   \describe{
  77     \item{\code{datafile}:}{full path to the database file.}
  78     \item{\code{meta}:}{list containing an environment for database
  79       metadata.}
  80   }
  81 }
  82
  83 \section{Additional slots for "filehashRDS"}{
  84   \describe{
  85     \item{dir:}{Directory where files are stored.}
  86   }
  87 }
  88
  89 \section{Methods}{
  90   \describe{
  91     \item{dbDelete}{The \code{dbDelete} function is for deleting
  92       elements, but for the \code{"DB1"} format all it does is remove the
  93       key from the lookup table.
  94       The actual data are still in the database (but inaccessible).  If
  95       you reinsert data for the same key, the new data are simply
  96       appended on to the end of the file.  Therefore, it's possible to
  97       have multiple copies of data lying around after a while,
  98       potentially making the database file big.  The \code{"RDS"} format
  99       does not have this problem.}
 100     \item{dbExists}{check to see if a key exists.}
 101     \item{dbFetch}{retrieve the value associated with a given key.}
 102     \item{dbMultiFetch}{retrieve values associated with multiple keys (a
 103       list of those values is returned).}
 104     \item{dbInsert}{insert a key-value pair into the database.  If
 105       that key already exists, its associated value is overwritten.}
 106     \item{dbList}{list all keys in the database.}
 107     \item{dbReorganize}{The \code{dbReorganize} function is there for
 108       the purpose of rewriting the database to remove all of the stale
 109       entries.  Basically, this function creates a new copy of the
 110       database and then overwrites the old copy.  This function has not
 111       been tested extensively and so should be considered
 112       \emph{experimental}.  \code{dbReorganize} is not needed when using
 113       the \code{"RDS"} format.}
 114     \item{dbUnlink}{delete an entire database from the disk}
 115     \item{dbDisconnect}{close any open connections associated with a
 116       database object.}
 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}