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

\name{object.size}
\alias{object.size}
\alias{format.object_size}
\alias{print.object_size}
\title{Report the Space Allocated for an Object}
\description{
  Provides an estimate of the memory that is being used to store an \R object.
}
\usage{
object.size(x)

\method{format}{object_size}(x, units = "b", standard = "auto", digits = 1L, \dots)
\method{print}{object_size}(x, quote = FALSE, units = "b", standard = "auto",
      digits = 1L, \dots)
}
\arguments{
  \item{x}{an \R object.}
  \item{quote}{logical, indicating whether or not the result should be
    printed with surrounding quotes.}
  \item{units}{the units to be used in formatting and printing the size.
    Allowed values for the different \code{standard}s are
    \describe{
      \item{\code{standard = "legacy"}:}{
	\code{"b"}, \code{"Kb"}, \code{"Mb"}, \code{"Gb"}, \code{"Tb"}, \code{"Pb"},
	\code{"B"}, \code{"KB"}, \code{"MB"}, \code{"GB"}, \code{"TB"} and \code{"PB"}.}
      \item{\code{standard = "IEC"}:}{
	\code{"B"}, \code{"KiB"}, \code{"MiB"}, \code{"GiB"},
	\code{"TiB"}, \code{"PiB"}, \code{"EiB"}, \code{"ZiB"} and \code{"YiB"}.}
      \item{\code{standard = "SI"}:}{
	\code{"B"}, \code{"kB"}, \code{"MB"}, \code{"GB"}, \code{"TB"},
	\code{"PB"}, \code{"EB"}, \code{"ZB"} and \code{"YB"}.}
    }
    For all standards, \code{unit = "auto"} is also allowed.
    If \code{standard = "auto"}, any of the "legacy" and \acronym{IEC}
    units are allowed.
    See \sQuote{Formatting and printing object sizes} for details.}
  \item{standard}{the byte-size unit standard to be used.  A character
    string, possibly abbreviated from \code{"legacy"}, \code{"IEC"},
    \code{"SI"} and \code{"auto"}.  See \sQuote{Formatting and printing
      object sizes} for details.}
  \item{digits}{the number of digits after the decimal point, passed to
    \code{\link{round}}.}
  \item{\dots}{arguments to be passed to or from other methods.}
}
\details{
  Exactly which parts of the memory allocation should be attributed to
  which object is not clear-cut.  This function merely provides a rough
  indication: it should be reasonably accurate for atomic vectors, but
  does not detect if elements of a list are shared, for example.
  (Sharing amongst elements of a character vector is taken into account,
  but not that between character vectors in a single object.)

  The calculation is of the size of the object, and excludes the space
  needed to store its name in the symbol table.

  Associated space (e.g., the environment of a function and what the
  pointer in a \code{EXTPTRSXP} points to) is not included in the
  calculation.

  Object sizes are larger on 64-bit builds than 32-bit ones, but will
  very likely be the same on different platforms with the same word
  length and pointer size.

  Sizes of objects using a compact internal representation may be
  over-estimated.
}

\section{Formatting and printing object sizes}{
  Object sizes can be formatted using byte-size units from \R's legacy
  standard, the \acronym{IEC} standard, or the \acronym{SI} standard.
  As illustrated by below tables, the legacy and \acronym{IEC} standards use
  \emph{binary} units (multiples of 1024), whereas the SI standard uses
  \emph{decimal} units (multiples of 1000).

  For methods \code{format} and \code{print}, argument \code{standard}
  specifies which standard to use and argument \code{units} specifies
  which byte-size unit to use.  \code{units = "auto"} chooses the largest
  units in which the result is one or more (before rounding).
  Byte sizes are rounded to \code{digits} decimal places.
  \code{standard = "auto"} chooses the standard based on \code{units},
  if possible, otherwise, the legacy standard is used.

  Summary of \R's legacy and \acronym{IEC} units:
  \tabular{lll}{
   \bold{object size} \tab\bold{legacy} \tab\bold{IEC}\cr
     1                \tab  1 bytes     \tab  1 B    \cr
     1024             \tab  1 Kb        \tab  1 KiB  \cr
     1024^2           \tab  1 Mb        \tab  1 MiB  \cr
     1024^3           \tab  1 Gb        \tab  1 GiB  \cr
     1024^4           \tab  1 Tb        \tab  1 TiB  \cr
     1024^5           \tab  1 Pb        \tab  1 PiB  \cr
     1024^6           \tab              \tab  1 EiB  \cr
     1024^7           \tab              \tab  1 ZiB  \cr
     1024^8           \tab              \tab  1 YiB  \cr
  }

  Summary of \acronym{SI} units:
  \tabular{ll}{
   \bold{object size} \tab \bold{SI} \cr
     1       \tab  1 B   \cr
     1000    \tab  1 kB  \cr
     1000^2  \tab  1 MB  \cr
     1000^3  \tab  1 GB  \cr
     1000^4  \tab  1 TB  \cr
     1000^5  \tab  1 PB  \cr
     1000^6  \tab  1 EB  \cr
     1000^7  \tab  1 ZB  \cr
     1000^8  \tab  1 YB  \cr
  }
}
\value{
  An object of class \code{"object_size"} with a length-one double value,
  an estimate of the memory allocation attributable to the object in bytes.
}
\author{R Core; Henrik Bengtsson for the non-legacy \code{standard}s.}
\seealso{
  \code{\link{Memory-limits}} for the design limitations on object size.
}
\references{
  The wikipedia page, \url{https://en.wikipedia.org/wiki/Binary_prefix},
  is extensive on the different standards, usages and their history.
}
\examples{
object.size(letters)
object.size(ls)
format(object.size(library), units = "auto")

sl <- object.size(rep(letters, 1000))

print(sl)                                    ## 209288 bytes
print(sl, units = "auto")                    ## 204.4 Kb
print(sl, units = "auto", standard = "IEC")  ## 204.4 KiB
print(sl, units = "auto", standard = "SI")   ## 209.3 kB

(fsl <- sapply(c("Kb", "KB", "KiB"),
               function(u) format(sl, units = u)))
stopifnot(identical( ## assert that all three are the same :
             unique(substr(as.vector(fsl), 1,5)),
             format(round(as.vector(sl)/1024, 1))))

## find the 10 largest objects in the base package
z <- sapply(ls("package:base"), function(x)
            object.size(get(x, envir = baseenv())))
if(interactive()) {
as.matrix(rev(sort(z))[1:10])
} else # (more constant over time):
    names(rev(sort(z))[1:10])
}
\keyword{utilities}