gdata (version 2.18.0)

humanReadable: Print Byte Size in Human Readable Format

Description

humanReadable converts integer byte sizes to a human readable units such as kB, MB, GB, etc.

Usage

humanReadable(x, units="auto", standard=c("IEC", "SI", "Unix"),
              digits=1, width=NULL, sep=" ", justify=c("right", "left") )

Arguments

x

integer, byte size

standard

character, "IEC" for powers of 1024 ('MiB'), "SI" for powers of 1000 ('MB'), or "Unix" for powers of 1024 ('M'). See details.

units

character, unit to use for all values (optional), one of "auto", "bytes", or an appropriate unit corresponding to standard.

digits

integer, number of digits after decimal point

width

integer, width of number string

sep

character, separator between number and unit

justify

two-element vector specifiy the alignment for the number and unit components of the size. Each element should be one of "none", "left", "right", or "center"

Value

Byte size in human readable format as character with proper unit symbols added at the end of the string.

Details

The basic unit used to store information in computers is a bit. Bits are represented as zeroes and ones - binary number system. Although, the binary number system is not the same as the decimal number system, decimal prefixes for binary multiples such as kilo and mega are often used. In the decimal system kilo represent 1000, which is close to \(1024 = 2^{10}\) in the binary system. This sometimes causes problems as it is not clear which powers (2 or 10) are used in a notation like 1 kB. To overcome this problem International Electrotechnical Commission (IEC) has provided the following solution to this problem:

Name	System	Symbol	Size	Conversion
byte	binary	B	\(2^3\)	8 bits
kilobyte	decimal	kB	\(10^3\)	1000 bytes
kibibyte	binary	KiB	\(2^{10}\)	1024 bytes
megabyte	decimal	MB	\((10^3)^2\)	1000 kilobytes
mebibyte	binary	MiB	\((2^{10})^2\)	1024 kibibytes
gigabyte	decimal	GB	\((10^3)^3\)	1000 megabytes
gibibyte	binary	GiB	\((2^{10})^3\)	1024 mebibytes
terabyte	decimal	TB	\((10^3)^4\)	1000 gigabytes
tebibyte	binary	TiB	\((2^{10})^4\)	1024 gibibytes
petabyte	decimal	PB	\((10^3)^5\)	1000 terabytes
pebibyte	binary	PiB	\((2^{10})^5\)	1024 tebibytes
exabyte	decimal	EB	\((10^3)^6\)	1000 petabytes
exbibyte	binary	EiB	\((2^{10})^6\)	1024 pebibytes
zettabyte	decimal	ZB	\((10^3)^7\)	1000 exabytes
zebibyte	binary	ZiB	\((2^{10})^7\)	1024 exbibytes
yottabyte	decimal	YB	\((10^3)^8\)	1000 zettabytes
yebibyte	binary	YiB	\((2^{10})^8\)	1024 zebibytes

where Zi and Yi are GNU extensions to IEC. To get the output in the decimal system (powers of 1000) use standard="SI". To obtain IEC standard (powers of 1024) use standard="IEC".

In addition, single-character units are provided that follow (and extend) the Unix pattern (use standard="Unix"):

Name	System	Symbol	Size	Conversion
byte	binary	B	\(2^3\)	8 bits
kibibyte	binary	K	\(2^{10}\)	1024 bytes
mebibyte	binary	M	\((2^{10})^2\)	1024 kibibytes
gibibyte	binary	G	\((2^{10})^3\)	1024 mebibytes
tebibyte	binary	T	\((2^{10})^4\)	1024 gibibytes
pebibyte	binary	P	\((2^{10})^5\)	1024 tebibytes
exbibyte	binary	E	\((2^{10})^6\)	1024 pebibytes
zebibyte	binary	Z	\((2^{10})^7\)	1024 exbibytes
yottabyte	binary	Y	\((2^{10})^8\)	1024 zebibytes

For printout both digits and width can be specified. If width is NULL, all values have given number of digits. If width is not NULL, output is rounded to a given width and formated similar to human readable format of the Unix ls, df or du shell commands.

References

Wikipedia: http://en.wikipedia.org/wiki/Byte http://en.wikipedia.org/wiki/SI_prefix http://en.wikipedia.org/wiki/Binary_prefix

GNU manual for coreutils: http://www.gnu.org/software/coreutils/manual/html_node/Block-size.html#Block-size

See Also

object.size in package 'gdata', object.size in package 'utils', ll

Examples

# NOT RUN {
# Simple example: maximum addressible size of 32 bit pointer
humanReadable(2^32-1)
humanReadable(2^32-1, standard="IEC")
humanReadable(2^32-1, standard="SI")
humanReadable(2^32-1, standard="Unix")

humanReadable(2^32-1, unit="MiB")
humanReadable(2^32-1, standard="IEC",  unit="MiB")
humanReadable(2^32-1, standard="SI",   unit="MB")
humanReadable(2^32-1, standard="Unix", unit="M")

# Vector of sizes
matrix(humanReadable(c(60810, 124141, 124, 13412513), width=4))
matrix(humanReadable(c(60810, 124141, 124, 13412513), width=4, unit="KiB"))

# Specify digits rather than width
matrix(humanReadable(c(60810, 124141, 124, 13412513), width=NULL, digits=2))

# Change the justification
matrix(humanReadable(c(60810, 124141, 124, 13412513), width=NULL,
                    justify=c("right", "right") ))

# }