The R Project SVN R

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

\name{log}
\alias{log}
\alias{logb}
\alias{log10}
\alias{log2}
\alias{log1p}
\alias{exp}
\alias{expm1}
\title{Logarithms and Exponentials}
\usage{
log(x, base = exp(1))
logb(x, base = exp(1))
log10(x)
log2(x)

log1p(x)

exp(x)
expm1(x)
}
\arguments{
  \item{x}{a numeric or complex vector.}
  \item{base}{a positive or complex number: the base with respect to which
    logarithms are computed.  Defaults to \eqn{e}=\code{exp(1)}.}
  }
\description{
  \code{log} computes logarithms, by default natural logarithms,
  \code{log10} computes common (i.e., base 10) logarithms, and
  \code{log2} computes binary (i.e., base 2) logarithms.
  The general form \code{log(x, base)} computes logarithms with base
  \code{base}.

  \code{log1p(x)} computes \eqn{\log(1+x)}{log(1+x)} accurately also for
  \eqn{|x| \ll 1}{|x| << 1}.

  \code{exp} computes the exponential function.

  \code{expm1(x)} computes \eqn{\exp(x) - 1}{exp(x) - 1} accurately also for
  \eqn{|x| \ll 1}{|x| << 1}.
}
\value{
  A vector of the same length as \code{x} containing the transformed
  values.  \code{log(0)} gives \code{-Inf}, and \code{log(x)} for
  negative values of \code{x} is \code{NaN}.  \code{exp(-Inf)} is \code{0}.

  For complex inputs to the log functions, the value is a complex number
  with imaginary part in the range \eqn{[-\pi, \pi]}{[-pi, pi]}: which
  end of the range is used might be platform-specific.
}
\details{
  All except \code{logb} are generic functions: methods can be defined
  for them individually or via the \code{\link[=S3groupGeneric]{Math}}
  group generic.

  \code{log10} and \code{log2} are only convenience wrappers, but logs
  to bases 10 and 2 (whether computed \emph{via} \code{log} or the wrappers)
  will be computed more efficiently and accurately where supported by the OS.
  Methods can be set for them individually (and otherwise methods for
  \code{log} will be used).

  \code{logb} is a wrapper for \code{log} for compatibility with S.  If
  (S3 or S4) methods are set for \code{log} they will be dispatched.
  Do not set S4 methods on \code{logb} itself.

  All except \code{log} are \link{primitive} functions.
}
\section{S4 methods}{
  \code{exp}, \code{expm1}, \code{log}, \code{log10}, \code{log2} and
  \code{log1p} are S4 generic and are members of the
  \code{\link[=S4groupGeneric]{Math}} group generic.

  Note that this means that the S4 generic for \code{log} has a
  signature with only one argument, \code{x}, but that \code{base} can
  be passed to methods (but will not be used for method selection).  On
  the other hand, if you only set a method for the \code{Math} group
  generic then \code{base} argument of \code{log} will be ignored for
  your class.
}
\source{
  \code{log1p} and \code{expm1} may be taken from the operating system,
  but if not available there then they are based on the Fortran subroutine
  \code{dlnrel} by W. Fullerton of Los Alamos Scientific Laboratory (see
  \url{https://netlib.org/slatec/fnlib/dlnrel.f}) and (for small x) a
  single Newton step for the solution of \code{log1p(y) = x}
  respectively.
}
\references{
  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
  \emph{The New S Language}.
  Wadsworth & Brooks/Cole.
  (for \code{log}, \code{log10} and \code{exp}.)

  Chambers, J. M. (1998)
  \emph{Programming with Data.  A Guide to the S Language}.
  Springer. (for \code{logb}.)
}
\seealso{
  \code{\link{Trig}},
  \code{\link{sqrt}},
  \code{\link{Arithmetic}}.
}
\examples{
log(exp(3))
log10(1e7) # = 7

x <- 10^-(1+2*1:9)
cbind(deparse.level=2, # to get nice column names
      x, log(1+x), log1p(x), exp(x)-1, expm1(x))
}
\keyword{math}