src/library/utils/man/object.size.Rd - R - Git at Google

 % 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}
	% 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}