Serialize R objects to disk (with backup)

The rotate_rds*() functions are wrappers around base::saveRDS() that create a backup of the destination file (if it exists) instead of just overwriting it.

rotate_rds(
  object,
  file = "",
  ascii = FALSE,
  version = NULL,
  compress = TRUE,
  refhook = NULL,
  ...,
  on_change_only = FALSE
)

rotate_rds_date(
  object,
  file = "",
  ascii = FALSE,
  version = NULL,
  compress = TRUE,
  refhook = NULL,
  ...,
  age = -1L,
  on_change_only = FALSE
)

rotate_rds_time(
  object,
  file = "",
  ascii = FALSE,
  version = NULL,
  compress = TRUE,
  refhook = NULL,
  ...,
  age = -1L,
  on_change_only = FALSE
)

Arguments

object	R object to serialize.
file	a connection or the name of the file where the R object is saved to or read from.
ascii	a logical. If `TRUE` or `NA`, an ASCII representation is written; otherwise (default), a binary one is used. See the comments in the help for `save`.
version	the workspace format version to use. `NULL` specifies the current default version (3). The only other supported value is 2, the default from R 1.4.0 to R 3.5.0.
compress	a logical specifying whether saving to a named file is to use `"gzip"` compression, or one of `"gzip"`, `"bzip2"` or `"xz"` to indicate the type of compression to be used. Ignored if `file` is a connection.
refhook	a hook function for handling reference objects.
...	Arguments passed on to `rotate`, `rotate_date`, `rotate_time` `max_backups` maximum number of backups to keep an `integer` scalar: Maximum number of backups to keep In addition for timestamped backups the following value are supported: a `Date` scalar: Remove all backups before this date a `character` scalar representing a Date in ISO format (e.g. `"2019-12-31"`) a `character` scalar representing an Interval in the form `"<number> <interval>"` (see below for more info) `size` scalar `integer`, `character` or `Inf`. Backup/rotate only if `file` is larger than this size. `Integers` are interpreted as bytes. You can pass `character` vectors that contain a file size suffix like `1k` (kilobytes), `3M` (megabytes), `4G` (gigabytes), `5T` (terabytes). Instead of these short forms you can also be explicit and use the IEC suffixes `KiB`, `MiB`, `GiB`, `TiB`. In Both cases `1` kilobyte is `1024` bytes, 1 `megabyte` is `1024` kilobytes, etc... .(if `age` and `size` are provided, both criteria must be `TRUE` to trigger rotation) `dir` `character` scalar. The directory in which the backups of `file` are stored (defaults to `dirname(file)`) `compression` Whether or not backups should be compressed `FALSE` for uncompressed backups, `TRUE` for zip compression; uses `zip()` a scalar `integer` between `1` and `9` to specify a compression level (requires the zip package, see its documentation for details) the `character` scalars `"utils::zip()"` or `"zip::zipr"` to force a specific zip command `dry_run` `logical` scalar. If `TRUE` no changes are applied to the file system (no files are created or deleted) `verbose` `logical` scalar. If `TRUE` additional informative `messages` are printed `create_file` `logical` scalar. If `TRUE` create an empty file in place of `file` after rotating. `format` a scalar `character` that can be a subset of of valid `strftime()` formatting strings. The default setting is `"%Y-%m-%d--%H-%M-%S"`. You can use an arbitrary number of dashes anywhere in the format, so `"%Y-%m-%d--%H-%M-%S"` and `"%Y%m%d%H%M%S"` are both legal. `T` and `_` can also be used as separators. For example, the following datetime formats are also possible: `%Y-%m-%d_%H-%M-%S` (Python logging default), `%Y%m%dT%H%M%S` (ISO 8601) All datetime components except `%Y` are optional. If you leave out part of the timestamp, the first point in time in the period is assumed. For example (assuming the current year is 2019) `%Y` is identical to `2019-01-01--00-00-00`. The timestamps must be lexically sortable, so `"%Y-%m-%d"` is legal, `"%m-%d-%Y"` and `%Y-%d` are not. `now` The current `Date` or time (`POSIXct`) as a scalar. You can pass a custom value here to to override the real system time. As a convenience you can also pass in `character` strings that follow the guidelines outlined above for `format`, but please note that these differ from the formats understood by `as.POSIXct()` or `as.Date()`. `overwrite` `logical` scalar. If `TRUE` overwrite backups if a backup of the same name (usually due to timestamp collision) exists.
on_change_only	`logical` scalaror a `list`. Rotate only if `object` is different from the object saved in `file`. If a `list`, arguments that will be passed on to `data.table::all.equal` (only when both obects are `data.tables`)
age	minimum age after which to backup/rotate a file; can be a `character` scalar representing an Interval in the form `"<number> <interval>"` (e.g. `"2 months"`, see Intervals section below). a `Date` or a `character` scalar representing a Date for a fixed point in time after which to backup/rotate. See `format` for which Date/Datetime formats are supported by rotor. (if `age` and `size` are provided, both criteria must be `TRUE` to trigger rotation)

Value

the path to file (invisibly)

Note

The default value for age is different for rotate_rds_date() (-1) than for rotate_date() (1) to make it a bit safer. This means if you execute rotate_date() twice on the same file on a given day it will silently not rotate the file, while rotate_rds_date() will throw an error.

Examples

dest <- tempfile()
rotate_rds(iris, dest)
rotate_rds(iris, dest)
rotate_rds(iris, dest)

list_backups(dest)
#> [1] "/tmp/RtmpOlTNDu/file236366852c1e.1" "/tmp/RtmpOlTNDu/file236366852c1e.2"

# cleanup
unlink(list_backups(dest))
unlink(dest)