Number::Bytes::Human(3pm)

1Human(3)              User Contributed Perl Documentation             Human(3)
2
3
4

NAME

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

SYNOPSIS

9         use Number::Bytes::Human qw(format_bytes parse_bytes);
10         $size = format_bytes(0); # '0'
11         $size = format_bytes(2*1024); # '2.0K'
12
13         $size = format_bytes(1_234_890, bs => 1000); # '1.3M'
14         $size = format_bytes(1E9, bs => 1000); # '1.0G'
15
16         my $bytes = parse_bytes('1.0K');   # 1024
17         my $bytes = parse_bytes('1.0KB');  # 1000, SI unit
18         my $bytes = parse_bytes('1.0KiB'); # 1024, SI unit
19
20         # the OO way
21         $human = Number::Bytes::Human->new(bs => 1000, si => 1);
22         $size = $human->format(1E7); # '10MB'
23
24         $bytes = $human->parse('10MB');   # 10*1000*1000
25         $bytes = $human->parse('10MiB');  # 10*1024*1024
26         $bytes = $human->parse('10M');    # Error, no SI unit
27
28         $human->set_options(zero => '-');
29         $size = $human->format(0);    # '-'
30         $bytes = $human->parse('-');  # 0
31
32         $human = Number::Bytes::Human->new(bs => 1000, round_style => 'round', precision => 2);
33         $size = $human->format(10240000); # '10.24MB'
34

DESCRIPTION

36       THIS IS ALPHA SOFTWARE: THE DOCUMENTATION AND THE CODE WILL SUFFER
37       CHANGES SOME DAY (THANKS, GOD!).
38
39       This module provides a formatter which turns byte counts to usual
40       readable format, like '2.0K', '3.1G', '100B'.  It was inspired in the
41       "-h" option of Unix utilities like "du", "df" and "ls" for "human-
42       readable" output.
43
44       From the FreeBSD man page of "df":
45       http://www.freebsd.org/cgi/man.cgi?query=df
46
47         "Human-readable" output.  Use unit suffixes: Byte, Kilobyte,
48         Megabyte, Gigabyte, Terabyte and Petabyte in order to reduce the
49         number of digits to four or fewer using base 2 for sizes.
50
51         byte      B
52         kilobyte  K = 2**10 B = 1024 B
53         megabyte  M = 2**20 B = 1024 * 1024 B
54         gigabyte  G = 2**30 B = 1024 * 1024 * 1024 B
55         terabyte  T = 2**40 B = 1024 * 1024 * 1024 * 1024 B
56
57         petabyte  P = 2**50 B = 1024 * 1024 * 1024 * 1024 * 1024 B
58         exabyte   E = 2**60 B = 1024 * 1024 * 1024 * 1024 * 1024 * 1024 B
59         zettabyte Z = 2**70 B = 1024 * 1024 * 1024 * 1024 * 1024 * 1024 * 1024 B
60         yottabyte Y = 2**80 B = 1024 * 1024 * 1024 * 1024 * 1024 * 1024 * 1024 * 1024 B
61
62       I have found this link to be quite useful:
63
64         http://www.t1shopper.com/tools/calculate/
65
66       If you feel like a hard-drive manufacturer, you can start counting
67       bytes by powers of 1000 (instead of the generous 1024).  Just use "bs
68       => 1000".
69
70       But if you are a floppy disk manufacturer and want to start counting in
71       units of 1024000 (for your "1.44 MB" disks)?  Then use "bs =>
72       1_024_000".
73
74       If you feel like a purist academic, you can force the use of metric
75       prefixes according to the Dec 1998 standard by the IEC. Never mind the
76       units for base 1000 are "('B', 'kB', 'MB', 'GB', 'TB', 'PB', 'EB',
77       'ZB', 'YB')" and, even worse, the ones for base 1024 are "('B', 'KiB',
78       'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB')" with the horrible
79       names: bytes, kibibytes, mebibytes, etc.  All you have to do is to use
80       "si => 1". Ain't that beautiful the SI system? Read about it:
81
82         http://physics.nist.gov/cuu/Units/binary.html
83
84       You can try a pure Perl "ls -lh"-inspired command with the one-liner,
85       er, two-liner:
86
87         $ perl -MNumber::Bytes::Human=format_bytes \
88                -e 'printf "%5s %s\n", format_bytes(-s), $_ for @ARGV' *
89
90       Why to write such a module? Because if people can write such things in
91       C, it can be written much easier in Perl and then reused, refactored,
92       abused. And then, when it is much improved, some brave soul can port it
93       back to C (if only for the warm feeling of painful programming).
94
95       It is also possible to parse human readable formatted bytes. The
96       automatic format detection recognizes SI units with the blocksizes of
97       1000 and 1024 respectively and additionally the customary K / M / G
98       etc. with blocksize 1024. When si => 1 is added to the options only SI
99       units are recognized. Explicitly specifying a blocksize changes it for
100       all detected units.
101
102   OBJECTS
103       An alternative to the functional style of this module is the OO
104       fashion. This is useful for avoiding the unnecessary parsing of the
105       arguments over and over if you have to format lots of numbers
106
107         for (@sizes) {
108           my $fmt_size = format_bytes($_, @args);
109           ...
110         }
111
112       versus
113
114         my $human = Number::Format::Bytes->new(@args);
115         for (@sizes) {
116           my $fmt_size = $human->format($_);
117           ...
118         }
119
120       for TODO [TODO] MAKE IT JUST A MATTER OF STYLE: memoize _parse_args()
121       $seed == undef
122
123   FUNCTIONS
124       format_bytes
125             $h_size = format_bytes($size, @options);
126
127           Turns a byte count (like 1230) to a readable format like '1.3K'.
128           You have a bunch of options to play with. See the section "OPTIONS"
129           to know the details.
130
131       parse_bytes
132             $size = parse_bytes($h_size, @options);
133
134           Turns a human readable byte count into a number of the equivalent
135           bytes.
136
137   METHODS
138       new
139             $h = Number::Bytes::Human->new(@options);
140
141           The constructor. For details on the arguments, see the section
142           "OPTIONS".
143
144       format
145             $h_size = $h->format($size);
146
147           Turns a byte count (like 1230) to a readable format like '1.3K'.
148           The statements
149
150             $h = Number::Bytes::Human->new(@options);
151             $h_size = $h->format($size);
152
153           are equivalent to "$h_size = format_bytes($size, @options)", with
154           only one pass for the option arguments.
155
156       parse
157             $size = $h->parse($h_size)
158
159           Turns a human readable byte count into the number of bytes.  The
160           statements
161
162             $h = Number::Bytes::Human->new(@options);
163             $size = $h->format($h_size);
164
165           are equivalent to "$size = parse_bytes($h_size, @options)", with
166           only one pass for the option arguments.
167
168       set_options
169             $h->set_options(@options);
170
171           To alter the options of a "Number::Bytes::Human" object.  See
172           "OPTIONS".
173
174   OPTIONS
175       BASE
176             block | base | block_size | bs => 1000 | 1024 | 1024000
177             base_1024 | block_1024 | 1024 => 1
178             base_1000 | block_1000 | 1000 => 1
179
180           The base to be used: 1024 (default), 1000 or 1024000.
181
182           Any other value throws an exception.
183
184       SUFFIXES
185             suffixes => 1000 | 1024 | 1024000 | si_1000 | si_1024 | $arrayref
186
187           By default, the used suffixes stand for '', 'K', 'M', ...  for base
188           1024 and '', 'k', 'M', ... for base 1000 (which are indeed the
189           usual metric prefixes with implied unit as bytes, 'B'). For the
190           weird 1024000 base, suffixes are '', 'M', 'T', etc.
191
192       ZERO
193             zero => string | undef
194
195           The string 0 maps to ('0' by default). If "undef", the general case
196           is used.  The string may contain '%S' in which case the suffix for
197           byte is used.
198
199             format_bytes(0, zero => '-') => '-'
200
201       METRIC SYSTEM
202             si => 1
203
204       ROUND
205             round_function => $coderef
206             round_style => 'ceil' | 'floor' | 'round' | 'trunc'
207
208       TO_S
209       QUIET
210             quiet => 1
211
212           Suppresses the warnings emitted. Currently, the only case is when
213           the number is large than "$base**(@suffixes+1)".
214
215       PRECISION
216             precision => <integer>
217
218           default = 1 sets the precicion of digits, only apropreacte for
219           round_style 'round' or if you want to accept it in as the second
220           parameter to your custome round_function.
221
222       PRECISION_CUTOFF
223             precision_cutoff => <integer>
224
225           default = 1 when the number of digits exceeds this number causes
226           the precision to be cutoff (was default behaviour in 0.07 and
227           below)
228
229   EXPORT
230       It is alright to import "format_bytes" and "parse_bytes", but nothing
231       is exported by default.
232

DIAGNOSTICS

234         "unknown round style '$style'";
235
236         "invalid base: $block (should be 1024, 1000 or 1024000)";
237
238         "round function ($args{round_function}) should be a code ref";
239
240         "suffixes ($args{suffixes}) should be 1000, 1024, 1024000 or an array ref";
241
242         "negative numbers are not allowed" (??)
243

BUGS

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

AUTHOR

254       Adriano R. Ferreira, <ferreira@cpan.org>
255
256       Dagobert Michelsen, <dagobert@cpan.org>
257

COPYRIGHT AND LICENSE

259       Copyright (C) 2005-2017 by Adriano R. Ferreira
260
261       This library is free software; you can redistribute it and/or modify it
262       under the same terms as Perl itself.
263
264
265
266perl v5.32.0                      2020-07-28                          Human(3)