src/library/base/man/load.Rd

% File src/library/base/man/load.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2018 R Core Team
% Distributed under GPL 2 or later

\name{load}
\alias{load}
\title{Reload Saved Datasets}
\description{
  Reload datasets written with the function \code{save}.
}
\usage{
load(file, envir = parent.frame(), verbose = FALSE)
}
\arguments{
  \item{file}{a (readable binary-mode) \link{connection} or a character string
    giving the name of the file to load (when \link{tilde expansion}
    is done).}
  \item{envir}{the environment where the data should be loaded.}
  \item{verbose}{should item names be printed during loading?}
}
\details{
  \code{load} can load \R objects saved in the current or any earlier
  format.  It can read a compressed file (see \code{\link{save}})
  directly from a file or from a suitable connection (including a call
  to \code{\link{url}}).

  A not-open connection will be opened in mode \code{"rb"} and closed
  after use.  Any connection other than a \code{\link{gzfile}} or
  \code{\link{gzcon}} connection will be wrapped in \code{\link{gzcon}}
  to allow compressed saves to be handled: note that this leaves the
  connection in an altered state (in particular, binary-only), and that
  it needs to be closed explicitly (it will not be garbage-collected).

  Only \R objects saved in the current format (used since \R 1.4.0)
  can be read from a connection.  If no input is available on a
  connection a warning will be given, but any input not in the current
  format will result in a error.

  Loading from an earlier version will give a warning about the
  \sQuote{magic number}: magic numbers \code{1971:1977} are from \R <
  0.99.0, and \code{RD[ABX]1} from \R 0.99.0 to \R 1.3.1.  These are all
  obsolete, and you are strongly recommended to re-save such files in a
  current format.

  The \code{verbose} argument is mainly intended for debugging.  If it
  is \code{TRUE}, then as objects from the file are loaded, their
  names will be printed to the console.  If \code{verbose} is set to
  an integer value greater than one, additional names corresponding to
  attributes and other parts of individual objects will also be printed.
  Larger values will print names to a greater depth.

  Objects can be saved with references to namespaces, usually as part of
  the environment of a function or formula.  Such objects can be loaded
  even if the namespace is not available: it is replaced by a reference
  to the global environment with a warning.  The warning identifies the
  first object with such a reference (but there may be more than one).
}
\value{
  A character vector of the names of objects created, invisibly.
}
\section{Warning}{
  Saved \R objects are binary files, even those saved with
  \code{ascii = TRUE}, so ensure that they are transferred without
  conversion of end of line markers.  \code{load} tries to detect such a
  conversion and gives an informative error message.

  \code{load(<file>)} replaces all existing objects with the same names
  in the current environment (typically your workspace,
  \code{\link{.GlobalEnv}}) and hence potentially overwrites important data.
  It is considerably safer to use \code{envir = } to load into a
  different environment, or to \code{\link{attach}(file)} which
  \code{load()}s into a new entry in the \code{\link{search}} path.
}
#ifdef windows
\note{
  \code{file} can be a UTF-8-encoded filepath that cannot be translated to
  the current locale.
}
#endif
\seealso{
  \code{\link{save}}, \code{\link{download.file}}; further
  \code{\link{attach}} as wrapper for \code{load()}.

  For other interfaces to the underlying serialization format, see
  \code{\link{unserialize}} and \code{\link{readRDS}}.
}
\examples{
\dontshow{oldwd <- setwd(tempdir())}

## save all data
xx <- pi # to ensure there is some data
save(list = ls(all = TRUE), file= "all.rda")
rm(xx)

## restore the saved values to the current environment
local({
   load("all.rda")
   ls()
})

xx <- exp(1:3)
## restore the saved values to the user's workspace
load("all.rda") ## which is here *equivalent* to
## load("all.rda", .GlobalEnv)
## This however annihilates all objects in .GlobalEnv with the same names !
xx # no longer exp(1:3)
rm(xx)
attach("all.rda") # safer and will warn about masked objects w/ same name in .GlobalEnv
ls(pos = 2)
##  also typically need to cleanup the search path:
detach("file:all.rda")

## clean up (the example):
unlink("all.rda")
\dontshow{setwd(oldwd)}

\dontrun{
con <- url("http://some.where.net/R/data/example.rda")
## print the value to see what objects were created.
print(load(con))
close(con) # url() always opens the connection
}}
\keyword{file}