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

\name{try}
\alias{try}
\title{Try an Expression Allowing Error Recovery}
\description{
  \code{try} is a wrapper to run an expression that might fail and allow
  the user's code to handle error-recovery.
}
\usage{
try(expr, silent = FALSE,
    outFile = getOption("try.outFile", default = stderr()))
}
\arguments{
  \item{expr}{an \R expression to try.}
  \item{silent}{logical: should the report of error messages be
     suppressed?}
  \item{outFile}{a \link{connection}, or a character string naming the
    file to print to (via \code{\link{cat}(*, file = outFile)});
    used only if \code{silent} is false, as by default.}
}
\details{
  \code{try} evaluates an expression and traps any errors that occur
  during the evaluation.  If an error occurs then the error
  message is printed to the \code{\link{stderr}} connection unless
  \code{options("show.error.messages")} is false or
  the call includes \code{silent = TRUE}.  The error message is also
  stored in a buffer where it can be retrieved by
  \code{geterrmessage}. (This should not be needed as the value returned
  in case of an error contains the error message.)

  \code{try} is implemented using \code{\link{tryCatch}}; for
  programming, instead of \code{try(expr, silent = TRUE)}, something like
  \code{tryCatch(expr, error = function(e) e)} (or other simple
  error handler functions) may be more efficient and flexible.

  It may be useful to set the default for \code{outFile} to
  \code{\link{stdout}()}, i.e., \preformatted{  options(try.outFile = stdout()) }
  instead of the default \code{\link{stderr}()},
  notably when \code{try()} is used inside a \code{\link{Sweave}} code
  chunk and the error message should appear in the resulting document.
}
\value{
  The value of the expression if \code{expr} is evaluated without error:
  otherwise an invisible object inheriting from class \code{"try-error"}
  containing the error message with the error condition as the
  \code{"condition"} attribute.
}
\section{Warning}{
  Do not test\preformatted{
    if (class(res) == "try-error"))
}
  as if there is no error, the result might (now or in future) have a
  class of length > 1. Use \code{if(\link{inherits}(res, "try-error"))}
  instead.
}
\seealso{
  \code{\link{options}} for setting error handlers and suppressing the
  printing of error messages;
  \code{\link{geterrmessage}} for retrieving the last error message.
  The underlying \code{\link{tryCatch}} provides more flexible means of
  catching and handling errors.

  \code{\link{assertCondition}} in package \pkg{tools} is related and
  useful for testing.
}
\examples{
## this example will not work correctly in example(try), but
## it does work correctly if pasted in
options(show.error.messages = FALSE)
try(log("a"))
print(.Last.value)
options(show.error.messages = TRUE)

## alternatively,
print(try(log("a"), TRUE))

## run a simulation, keep only the results that worked.
set.seed(123)
x <- stats::rnorm(50)
doit <- function(x)
{
    x <- sample(x, replace = TRUE)
    if(length(unique(x)) > 30) mean(x)
    else stop("too few unique points")
}
## alternative 1
res <- lapply(1:100, function(i) try(doit(x), TRUE))
## alternative 2
\dontrun{res <- vector("list", 100)
for(i in 1:100) res[[i]] <- try(doit(x), TRUE)}
unlist(res[sapply(res, function(x) !inherits(x, "try-error"))])
}
\keyword{programming}