1package Format::Human::Bytes;
2
3use warnings;
4use strict;
5
6=head1 NAME
7
8Format::Human::Bytes - Format a bytecount and make it human readable
9
10=head1 VERSION
11
12Version 0.06
13
14=cut
15
16our $VERSION = '0.06';
17
18=head1 SYNOPSIS
19
20Ever showed 12345678 bytes to the user instead of just saying 11MB?
21This module returns you a printable string which is more readable by
22humans than a simple bytecount.
23
24    use Format::Human::Bytes;
25
26    $readable = Format::Human::Bytes::base2($bytecount[,$decimals]);
27    $readable = Format::Human::Bytes::base10($bytecount[,$decimals]);
28
29    $readable = Format::Human::Bytes->base2($bytecount[,$decimals]);
30    $readable = Format::Human::Bytes->base10($bytecount[,$decimals]);
31
32    my $fhb = Format::Human::Bytes->new();
33    $readable = $fhb->base2($bytecount[,$decimals]);
34    $readable = $fhb->base10($bytecount[,$decimals]);
35
36All functions do "intelligent" switching to the next unit, for example:
37
38    1000 => 1000B
39    [...]
40    8000 => 8000B
41    9000 => 9kB
42
43The difference between 1000 bytes and 1500 bytes is usually bigger (for
44example because of a slow link) than between 95kB and 95,5kB. The same
45applies to 8000kB vs. 9 MB and for the other units.
46
47Depending on your usage, you may want to specify how many decimals should
48be shown (defaults to no decimals).
49
50=head1 FUNCTIONS / METHODS
51
52=head2 new
53
54    my $fhb = Format::Human::Bytes->new();
55
56Creates and returns a Format::Human::Bytes - object.
57
58=cut
59
60sub new {    # URL
61
62    my $class = shift;
63    my $Scalar;
64    my $self = bless \$Scalar, $class;
65
66    return $self;
67}
68
69=head2 base2
70
71Callable as a function:
72
73    $readable = Format::Human::Bytes::base2($bytecount[,$decimals]);
74
75Callable as a class method:
76
77    $readable = Format::Human::Bytes->base2($bytecount[,$decimals]);
78
79Callable as a object method:
80
81    $readable = $fhb->base2($bytecount[,$decimals]);
82
83Returns the correct readable form of the given bytecount.
84
85Correct in this case means that 1kB are 1024 Bytes which is
86how computers see the world.
87
88If you specify a decimal parameter, the result number will have the
89number of decimal numbers you specified.
90
91=cut
92
93sub base2 {
94    shift if ref( $_[0] ) ne '';    # Use me as a method if you like
95    shift
96      if defined( $_[0] )
97          and ( $_[0] eq 'Format::Human::Bytes' )
98    ;                               # Use me as a method if you like
99
100    my $Bytes = $_[0] || 0;
101    defined($Bytes) or $Bytes = 0;
102
103    my $Decimal = $_[1] || 0;
104
105    if ( $Bytes > 8192000000000 ) {
106        return sprintf( '%0.' . $Decimal . 'f', $Bytes / 1099511627776 ) . "TB";
107    }
108    elsif ( $Bytes > 8192000000 ) {
109        return sprintf( '%0.' . $Decimal . 'f', $Bytes / 1073741824 ) . "GB";
110    }
111    elsif ( $Bytes > 8192000 ) {
112        return sprintf( '%0.' . $Decimal . 'f', $Bytes / 1048576 ) . "MB";
113    }
114    elsif ( $Bytes > 8192 ) {
115        return sprintf( '%0.' . $Decimal . 'f', $Bytes / 1024 ) . "kB";
116    }
117    elsif ( $Bytes == 0 ) { return sprintf( '%0.' . $Decimal . 'f', 0 ); }
118    else { return sprintf( '%0.' . $Decimal . 'f', $Bytes ) . "B"; }
119}
120
121=head2 base10
122
123Callable as a function:
124
125    $readable = Format::Human::Bytes::base10($bytecount[,$decimals]);
126
127Callable as a class method:
128
129    $readable = Format::Human::Bytes->base10($bytecount[,$decimals]);
130
131Callable as a object method:
132
133    $readable = $fhb->base10($bytecount[,$decimals]);
134
135Returns the incorrect readable form of the given bytecount.
136
137Incorrect in this case means that 1kB is 1000 Bytes and 1 MB is
1381000000 bytes which is how some (many) people see the world, but
139it's wrong for computers.
140
141If you specify a decimal parameter, the result number will have the
142number of decimal numbers you specified.
143
144=cut
145
146sub base10 {
147    shift if ref( $_[0] ) ne '';    # Use me as a method if you like
148    shift
149      if defined( $_[0] )
150          and ( $_[0] eq 'Format::Human::Bytes' )
151    ;                               # Use me as a method if you like
152
153    my $Bytes = $_[0] || 0;
154    defined($Bytes) or $Bytes = 0;
155
156    my $Decimal = $_[1] || 0;
157
158    if ( $Bytes > 8192000000000 ) {
159        return sprintf( '%0.' . $Decimal . 'f', $Bytes / 1000000000000 ) . "TB";
160    }
161    elsif ( $Bytes > 8192000000 ) {
162        return sprintf( '%0.' . $Decimal . 'f', $Bytes / 1000000000 ) . "GB";
163    }
164    elsif ( $Bytes > 8192000 ) {
165        return sprintf( '%0.' . $Decimal . 'f', $Bytes / 1000000 ) . "MB";
166    }
167    elsif ( $Bytes > 8192 ) {
168        return sprintf( '%0.' . $Decimal . 'f', $Bytes / 1000 ) . "kB";
169    }
170    elsif ( $Bytes == 0 ) { return sprintf( '%0.' . $Decimal . 'f', 0 ); }
171    else { return sprintf( '%0.' . $Decimal . 'f', $Bytes ) . "B"; }
172}
173
174=head1 AUTHOR
175
176Sebastian Willing, C<< <sewi at cpan.org> >>
177
178=head1 BUGS
179
180Please report any bugs or feature requests to C<bug-format-human-bytes at rt.cpan.org>, or through
181the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Format-Human-Bytes>.  I will be notified, and then you'll
182automatically be notified of progress on your bug as I make changes.
183
184
185=head1 SUPPORT
186
187You can find documentation for this module with the perldoc command.
188
189    perldoc Format::Human::Bytes
190
191
192You can also look for information at:
193
194=over 4
195
196=item * RT: CPAN's request tracker
197
198L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Format-Human-Bytes>
199
200=item * AnnoCPAN: Annotated CPAN documentation
201
202L<http://annocpan.org/dist/Format-Human-Bytes>
203
204=item * CPAN Ratings
205
206L<http://cpanratings.perl.org/d/Format-Human-Bytes>
207
208=item * Search CPAN
209
210L<http://search.cpan.org/dist/Format-Human-Bytes/>
211
212=back
213
214
215=head1 HISTORY
216
217The functions are in use since late 2003 or early 2004 but I didn't pack them
218for CPAN before 2009.
219
220
221=head1 LICENSE
222
223This program is free software; you can redistribute it and/or
224modify it under the same terms as Perl 5 itself.
225
226
227=cut
228
2291;    # End of Format::Human::Bytes
230