Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Human(3)	      User Contributed Perl Documentation	      Human(3)

NAME
       Number::Bytes::Human - Convert byte count to human readable format

SYNOPSIS
	 use Number::Bytes::Human qw(format_bytes parse_bytes);
	 $size = format_bytes(0); # '0'
	 $size = format_bytes(2*1024); # '2.0K'

	 $size = format_bytes(1_234_890, bs => 1000); #	'1.3M'
	 $size = format_bytes(1E9, bs => 1000);	# '1.0G'

	 my $bytes = parse_bytes('1.0K');   # 1024
	 my $bytes = parse_bytes('1.0KB');  # 1000, SI unit
	 my $bytes = parse_bytes('1.0KiB'); # 1024, SI unit

	 # the OO way
	 $human	= Number::Bytes::Human->new(bs => 1000,	si => 1);
	 $size = $human->format(1E7); #	'10MB'

	 $bytes	= $human->parse('10MB');   # 10*1000*1000
	 $bytes	= $human->parse('10MiB');  # 10*1024*1024
	 $bytes	= $human->parse('10M');	   # Error, no SI unit

	 $human->set_options(zero => '-');
	 $size = $human->format(0);    # '-'
	 $bytes	= $human->parse('-');  # 0

	 $human	= Number::Bytes::Human->new(bs => 1000,	round_style => 'round',	precision => 2);
	 $size = $human->format(10240000); # '10.24MB'

DESCRIPTION
       THIS IS ALPHA SOFTWARE: THE DOCUMENTATION AND THE CODE WILL SUFFER
       CHANGES SOME DAY	(THANKS, GOD!).

       This module provides a formatter	which turns byte counts	to usual
       readable	format,	like '2.0K', '3.1G', '100B'.  It was inspired in the
       "-h" option of Unix utilities like "du",	"df" and "ls" for "human-
       readable" output.

       From the	FreeBSD	man page of "df":
       http://www.freebsd.org/cgi/man.cgi?query=df

	 "Human-readable" output.  Use unit suffixes: Byte, Kilobyte,
	 Megabyte, Gigabyte, Terabyte and Petabyte in order to reduce the
	 number	of digits to four or fewer using base 2	for sizes.

	 byte	   B
	 kilobyte  K = 2**10 B = 1024 B
	 megabyte  M = 2**20 B = 1024 *	1024 B
	 gigabyte  G = 2**30 B = 1024 *	1024 * 1024 B
	 terabyte  T = 2**40 B = 1024 *	1024 * 1024 * 1024 B

	 petabyte  P = 2**50 B = 1024 *	1024 * 1024 * 1024 * 1024 B
	 exabyte   E = 2**60 B = 1024 *	1024 * 1024 * 1024 * 1024 * 1024 B
	 zettabyte Z = 2**70 B = 1024 *	1024 * 1024 * 1024 * 1024 * 1024 * 1024	B
	 yottabyte Y = 2**80 B = 1024 *	1024 * 1024 * 1024 * 1024 * 1024 * 1024	* 1024 B

       I have found this link to be quite useful:

	 http://www.t1shopper.com/tools/calculate/

       If you feel like	a hard-drive manufacturer, you can start counting
       bytes by	powers of 1000 (instead	of the generous	1024).	Just use "bs
       => 1000".

       But if you are a	floppy disk manufacturer and want to start counting in
       units of	1024000	(for your "1.44	MB" disks)?  Then use "bs =>
       1_024_000".

       If you feel like	a purist academic, you can force the use of metric
       prefixes	according to the Dec 1998 standard by the IEC. Never mind the
       units for base 1000 are "('B', 'kB', 'MB', 'GB',	'TB', 'PB', 'EB',
       'ZB', 'YB')" and, even worse, the ones for base 1024 are	"('B', 'KiB',
       'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB')" with the horrible
       names: bytes, kibibytes,	mebibytes, etc.	 All you have to do is to use
       "si => 1". Ain't	that beautiful the SI system? Read about it:

	 http://physics.nist.gov/cuu/Units/binary.html

       You can try a pure Perl "ls -lh"-inspired command with the one-liner,
       er, two-liner:

	 $ perl	-MNumber::Bytes::Human=format_bytes \
		-e 'printf "%5s	%s\n", format_bytes(-s), $_ for	@ARGV' *

       Why to write such a module? Because if people can write such things in
       C, it can be written much easier	in Perl	and then reused, refactored,
       abused. And then, when it is much improved, some	brave soul can port it
       back to C (if only for the warm feeling of painful programming).

       It is also possible to parse human readable formatted bytes. The
       automatic format	detection recognizes SI	units with the blocksizes of
       1000 and	1024 respectively and additionally the customary K / M / G
       etc. with blocksize 1024. When si => 1 is added to the options only SI
       units are recognized. Explicitly	specifying a blocksize changes it for
       all detected units.

   OBJECTS
       An alternative to the functional	style of this module is	the OO
       fashion.	This is	useful for avoiding the	unnecessary parsing of the
       arguments over and over if you have to format lots of numbers

	 for (@sizes) {
	   my $fmt_size	= format_bytes($_, @args);
	   ...
	 }

       versus

	 my $human = Number::Format::Bytes->new(@args);
	 for (@sizes) {
	   my $fmt_size	= $human->format($_);
	   ...
	 }

       for TODO	[TODO] MAKE IT JUST A MATTER OF	STYLE: memoize _parse_args()
       $seed ==	undef

   FUNCTIONS
       format_bytes
	     $h_size = format_bytes($size, @options);

	   Turns a byte	count (like 1230) to a readable	format like '1.3K'.
	   You have a bunch of options to play with. See the section "OPTIONS"
	   to know the details.

       parse_bytes
	     $size = parse_bytes($h_size, @options);

	   Turns a human readable byte count into a number of the equivalent
	   bytes.

   METHODS
       new
	     $h	= Number::Bytes::Human->new(@options);

	   The constructor. For	details	on the arguments, see the section
	   "OPTIONS".

       format
	     $h_size = $h->format($size);

	   Turns a byte	count (like 1230) to a readable	format like '1.3K'.
	   The statements

	     $h	= Number::Bytes::Human->new(@options);
	     $h_size = $h->format($size);

	   are equivalent to "$h_size =	format_bytes($size, @options)",	with
	   only	one pass for the option	arguments.

       parse
	     $size = $h->parse($h_size)

	   Turns a human readable byte count into the number of	bytes.	The
	   statements

	     $h	= Number::Bytes::Human->new(@options);
	     $size = $h->format($h_size);

	   are equivalent to "$size = parse_bytes($h_size, @options)", with
	   only	one pass for the option	arguments.

       set_options
	     $h->set_options(@options);

	   To alter the	options	of a "Number::Bytes::Human" object.  See
	   "OPTIONS".

   OPTIONS
       BASE
	     block | base | block_size | bs => 1000 | 1024 | 1024000
	     base_1024 | block_1024 | 1024 => 1
	     base_1000 | block_1000 | 1000 => 1

	   The base to be used:	1024 (default),	1000 or	1024000.

	   Any other value throws an exception.

       SUFFIXES
	     suffixes => 1000 |	1024 | 1024000 | si_1000 | si_1024 | $arrayref

	   By default, the used	suffixes stand for '', 'K', 'M', ...  for base
	   1024	and '',	'k', 'M', ... for base 1000 (which are indeed the
	   usual metric	prefixes with implied unit as bytes, 'B'). For the
	   weird 1024000 base, suffixes	are '',	'M', 'T', etc.

       ZERO
	     zero => string | undef

	   The string 0	maps to	('0' by	default). If "undef", the general case
	   is used.  The string	may contain '%S' in which case the suffix for
	   byte	is used.

	     format_bytes(0, zero => '-') => '-'

       METRIC SYSTEM
	     si	=> 1

       ROUND
	     round_function => $coderef
	     round_style => 'ceil' | 'floor' | 'round' | 'trunc'

       TO_S
       QUIET
	     quiet => 1

	   Suppresses the warnings emitted. Currently, the only	case is	when
	   the number is large than "$base**(@suffixes+1)".

       PRECISION
	     precision => <integer>

	   default = 1 sets the	precicion of digits, only apropreacte for
	   round_style 'round' or if you want to accept	it in as the second
	   parameter to	your custome round_function.

       PRECISION_CUTOFF
	     precision_cutoff => <integer>

	   default = 1 when the	number of digits exceeds this number causes
	   the precision to be cutoff (was default behaviour in	0.07 and
	   below)

   EXPORT
       It is alright to	import "format_bytes" and "parse_bytes", but nothing
       is exported by default.

DIAGNOSTICS
	 "unknown round	style '$style'";

	 "invalid base:	$block (should be 1024,	1000 or	1024000)";

	 "round	function ($args{round_function}) should	be a code ref";

	 "suffixes ($args{suffixes}) should be 1000, 1024, 1024000 or an array ref";

	 "negative numbers are not allowed" (??)

SEE ALSO
       lib/human.c and lib/human.h in GNU coreutils.

       The "_convert()"	solution by COG	in Filesys::DiskUsage.

BUGS
       Please report bugs via Github
       <https://github.com/aferreira/cpan-Number-Bytes-Human/issues>.

AUTHOR
       Adriano R. Ferreira, <ferreira@cpan.org>

       Dagobert	Michelsen, <dagobert@cpan.org>

COPYRIGHT AND LICENSE
       Copyright (C) 2005-2017 by Adriano R. Ferreira

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.1			  2017-01-09			      Human(3)

NAME | SYNOPSIS | DESCRIPTION | DIAGNOSTICS | SEE ALSO | BUGS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Number::Bytes::Human&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help