Write R object with corresponding stamp (hash digest)

The st_write function is intended to be a wrapper of several other functions in different packages that save data disk. Yet, it goes several steps beyond that. First it creates the stamps (e.g., hashes) as part of the attributes of the object and saves it in a different file for easy access. Also, it may create vintage files of the object to keep track of changes. The philosophy of this package is increase speed in processes that work with many files, avoiding the need to load files to check whether the data has changed or not. Since disk space is cheap and time is not, stamp may be redundant in the files it saves.

Usage

st_write(
  x,
  file,
  ext = fs::path_ext(file),
  st_dir = NULL,
  st_name = NULL,
  save_stamp = TRUE,
  complete_stamp = getOption("stamp.completestamp"),
  recurse = FALSE,
  force = FALSE,
  algo = getOption("stamp.digest.algo"),
  save_vintage = getOption("stamp.vintage"),
  vintage_dir = NULL,
  verbose = getOption("stamp.verbose"),
  ...
)

Arguments

x

R object to write to disk as per limitations of file format.

file

character: File or connection to write to

ext

character: format or extension of file. Default is fs::path_ext(file)

st_dir

character: Directory to store stamp files. By default it is a subdirectory at the same level of file.

st_name

character: name of stamp in file. All stamp files are prefixed with value in option "stamp.stamp_prefix", which by default is "st_". You don't need to add the prefix.

save_stamp

logical: Whether to save a stamp in a separate file. Default is TRUE. It doesn't make a lot of sense to use st_write() when save_stamp = FALSE, as saving data along with the stamp is the main functionality of st_write().

complete_stamp

logical: Whether to add a complete report of data.frame to stamp file. You need the skimr package. If skimr is not in namespace, limited but lighter report will be added.

recurse

logical: is TRUE if directory in file does not it will be created. Default is FALSE

force

logical: replace file in disk even if has hasn't changed

algo

character: Algorithm to be used in digest::digest(). Default is "sha1"

save_vintage

logical: Whether to save vintage versions x. Default TRUE

vintage_dir

character: Directory to save vintages of x. By default it is a subdirectory at the same level of file

verbose

logical: whether to display additional information. This could be changed in option "stamp.verbose". Default is TRUE

...

Arguments passed on to stamp_get

serialize: A logical variable indicating whether the object should be serialized using serialize (in ASCII form). Setting this to FALSE allows to compare the digest output of given character strings to known control output. It also allows the use of raw vectors such as the output of non-ASCII serialization.
length: Number of characters to process. By default, when length is set to Inf, the whole string or file is processed.
skip: Number of input bytes to skip before calculating the digest. Negative values are invalid and currently treated as zero. Special value "auto" will cause serialization header to be skipped if serialize is set to TRUE (the serialization header contains the R version number thus skipping it allows the comparison of hashes across platforms and some R versions).
ascii: This flag is passed to the serialize function if serialize is set to TRUE, determining whether the hash is computed on the ASCII or binary representation.
raw: A logical variable with a default value of FALSE, implying digest returns digest output as ASCII hex values. Set to TRUE to return digest output in raw (binary) form. Note that this option is supported by most but not all of the implemented hashing algorithms
seed: an integer to seed the random number generator. This is only used in the xxhash32, xxhash64 and murmur32 functions and can be used to generate additional hashes for the same input if desired.
errormode: A character value denoting a choice for the behaviour in the case of error: ‘stop’ aborts (and is the default value), ‘warn’ emits a warning and returns NULL and ‘silent’ suppresses the error and returns an empty string.

Value

TRUE is object was saved successfully. FALSE otherwise.

Details

Object x is stored in file but its hash (i.e., stamp) is stored in subdirectory st_file.

Vintage files Vintage files are optional but play an important role for

replicability purposes. We highly recommend you turn this option off if you don't have enough space in your disk.

Examples

if (FALSE) {
  tfile <- fs::file_temp(ext = "qs")
  st_write(df, tfile)
}