1% File src/library/utils/man/object.size.Rd 2% Part of the R package, https://www.R-project.org 3% Copyright 1995-2017 R Core Team 4% Distributed under GPL 2 or later 5 6\name{object.size} 7\alias{object.size} 8\alias{format.object_size} 9\alias{print.object_size} 10\title{Report the Space Allocated for an Object} 11\description{ 12 Provides an estimate of the memory that is being used to store an \R object. 13} 14\usage{ 15object.size(x) 16 17\method{format}{object_size}(x, units = "b", standard = "auto", digits = 1L, \dots) 18\method{print}{object_size}(x, quote = FALSE, units = "b", standard = "auto", 19 digits = 1L, \dots) 20} 21\arguments{ 22 \item{x}{an \R object.} 23 \item{quote}{logical, indicating whether or not the result should be 24 printed with surrounding quotes.} 25 \item{units}{the units to be used in formatting and printing the size. 26 Allowed values for the different \code{standard}s are 27 \describe{ 28 \item{\code{standard = "legacy"}:}{ 29 \code{"b"}, \code{"Kb"}, \code{"Mb"}, \code{"Gb"}, \code{"Tb"}, \code{"Pb"}, 30 \code{"B"}, \code{"KB"}, \code{"MB"}, \code{"GB"}, \code{"TB"} and \code{"PB"}.} 31 \item{\code{standard = "IEC"}:}{ 32 \code{"B"}, \code{"KiB"}, \code{"MiB"}, \code{"GiB"}, 33 \code{"TiB"}, \code{"PiB"}, \code{"EiB"}, \code{"ZiB"} and \code{"YiB"}.} 34 \item{\code{standard = "SI"}:}{ 35 \code{"B"}, \code{"kB"}, \code{"MB"}, \code{"GB"}, \code{"TB"}, 36 \code{"PB"}, \code{"EB"}, \code{"ZB"} and \code{"YB"}.} 37 } 38 For all standards, \code{unit = "auto"} is also allowed. 39 If \code{standard = "auto"}, any of the "legacy" and \acronym{IEC} 40 units are allowed. 41 See \sQuote{Formatting and printing object sizes} for details.} 42 \item{standard}{the byte-size unit standard to be used. A character 43 string, possibly abbreviated from \code{"legacy"}, \code{"IEC"}, 44 \code{"SI"} and \code{"auto"}. See \sQuote{Formatting and printing 45 object sizes} for details.} 46 \item{digits}{the number of digits after the decimal point, passed to 47 \code{\link{round}}.} 48 \item{\dots}{arguments to be passed to or from other methods.} 49} 50\details{ 51 Exactly which parts of the memory allocation should be attributed to 52 which object is not clear-cut. This function merely provides a rough 53 indication: it should be reasonably accurate for atomic vectors, but 54 does not detect if elements of a list are shared, for example. 55 (Sharing amongst elements of a character vector is taken into account, 56 but not that between character vectors in a single object.) 57 58 The calculation is of the size of the object, and excludes the space 59 needed to store its name in the symbol table. 60 61 Associated space (e.g., the environment of a function and what the 62 pointer in a \code{EXTPTRSXP} points to) is not included in the 63 calculation. 64 65 Object sizes are larger on 64-bit builds than 32-bit ones, but will 66 very likely be the same on different platforms with the same word 67 length and pointer size. 68 69 Sizes of objects using a compact internal representation may be 70 over-estimated. 71} 72 73\section{Formatting and printing object sizes}{ 74 Object sizes can be formatted using byte-size units from \R's legacy 75 standard, the \acronym{IEC} standard, or the \acronym{SI} standard. 76 As illustrated by below tables, the legacy and \acronym{IEC} standards use 77 \emph{binary} units (multiples of 1024), whereas the SI standard uses 78 \emph{decimal} units (multiples of 1000). 79 80 For methods \code{format} and \code{print}, argument \code{standard} 81 specifies which standard to use and argument \code{units} specifies 82 which byte-size unit to use. \code{units = "auto"} chooses the largest 83 units in which the result is one or more (before rounding). 84 Byte sizes are rounded to \code{digits} decimal places. 85 \code{standard = "auto"} chooses the standard based on \code{units}, 86 if possible, otherwise, the legacy standard is used. 87 88 Summary of \R's legacy and \acronym{IEC} units: 89 \tabular{lll}{ 90 \bold{object size} \tab\bold{legacy} \tab\bold{IEC}\cr 91 1 \tab 1 bytes \tab 1 B \cr 92 1024 \tab 1 Kb \tab 1 KiB \cr 93 1024^2 \tab 1 Mb \tab 1 MiB \cr 94 1024^3 \tab 1 Gb \tab 1 GiB \cr 95 1024^4 \tab 1 Tb \tab 1 TiB \cr 96 1024^5 \tab 1 Pb \tab 1 PiB \cr 97 1024^6 \tab \tab 1 EiB \cr 98 1024^7 \tab \tab 1 ZiB \cr 99 1024^8 \tab \tab 1 YiB \cr 100 } 101 102 Summary of \acronym{SI} units: 103 \tabular{ll}{ 104 \bold{object size} \tab \bold{SI} \cr 105 1 \tab 1 B \cr 106 1000 \tab 1 kB \cr 107 1000^2 \tab 1 MB \cr 108 1000^3 \tab 1 GB \cr 109 1000^4 \tab 1 TB \cr 110 1000^5 \tab 1 PB \cr 111 1000^6 \tab 1 EB \cr 112 1000^7 \tab 1 ZB \cr 113 1000^8 \tab 1 YB \cr 114 } 115} 116\value{ 117 An object of class \code{"object_size"} with a length-one double value, 118 an estimate of the memory allocation attributable to the object in bytes. 119} 120\author{R Core; Henrik Bengtsson for the non-legacy \code{standard}s.} 121\seealso{ 122 \code{\link{Memory-limits}} for the design limitations on object size. 123} 124\references{ 125 The wikipedia page, \url{https://en.wikipedia.org/wiki/Binary_prefix}, 126 is extensive on the different standards, usages and their history. 127} 128\examples{ 129object.size(letters) 130object.size(ls) 131format(object.size(library), units = "auto") 132 133sl <- object.size(rep(letters, 1000)) 134 135print(sl) ## 209288 bytes 136print(sl, units = "auto") ## 204.4 Kb 137print(sl, units = "auto", standard = "IEC") ## 204.4 KiB 138print(sl, units = "auto", standard = "SI") ## 209.3 kB 139 140(fsl <- sapply(c("Kb", "KB", "KiB"), 141 function(u) format(sl, units = u))) 142stopifnot(identical( ## assert that all three are the same : 143 unique(substr(as.vector(fsl), 1,5)), 144 format(round(as.vector(sl)/1024, 1)))) 145 146## find the 10 largest objects in the base package 147z <- sapply(ls("package:base"), function(x) 148 object.size(get(x, envir = baseenv()))) 149if(interactive()) { 150as.matrix(rev(sort(z))[1:10]) 151} else # (more constant over time): 152 names(rev(sort(z))[1:10]) 153} 154\keyword{utilities} 155