Number::Bytes::Human man page on Kali

Man page or keyword search:  
man Server   9211 pages
apropos Keyword Search (all sections)
Output format
Kali logo
[printable version]

Human(3pm)	      User Contributed Perl Documentation	    Human(3pm)

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.24.1			  2017-01-09			    Human(3pm)
[top]

List of man pages available for Kali

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net