NAME

Format::FileSize - Perl extension for formating file sizes

SYNOPSIS

  use Format::FileSize;
  my $size= formatted_size( -s $ARG[0]);
  print "$ARG[0] $size\n";

ABSTRACT

  Format::FileSize exports one function: formatted_size, which takes a size and
  returns a nicely formated number.

  It can also be configured to format other types of data.

DESCRIPTION

The number is formated so that it looks like n.nn U or n U where U is one of '', K, M, G, T, P.

EXPORT

formatted_size <$size>

formatted_size takes a file size and returns it nicely formatted.

You can probably stop reading here.

By default the number is given as a number of units. Units are '' (empty), K, M, G, T, P. The number is formatted with 2 decimals if < 10, with 1 if < 100 and with no decimals if > 100.

You should definitely stop reading HERE!

You can add (named) options after the size.

Options are:

precision => <$nb>

$nb must be an integer from 0 to 4.

Numbers are always formatted with this number of digits after the dot.

nb_dec => <$hasref_trigger2precision>

$hasref_trigger2precision is a hashref that controls how many digits are displayed, depending on the integer part of the number.

The default is

   nb_dec => { 0 => 2, 10 => 1, 100 => 0 }

Which means that numbers between 0 and 10 are displayed with 2 digits after the dot, numbers 10 and 100 with one digit after the dot, and only the integer part is displayed for numbers above 100

You cannot use both precision and nb_dec.

symbols => <$arrayref_list_of_symbols>

Maybe you don't like the default units. No problem, you can change them by passing a list to formatted_size

  symbols => [ '', ' Kb', ' Mb', ' Gb', ' Tb', ' Waouh!' ]

A few notes:

- don't forget the initial empty string if you don't want sizes under 1 Kb to get a unit

- the space between the number and the unit is part of the unit string, don't forget it

factor

By default formatted_size assumes a factor of 1024 between 2 units, but of course hard disk manufacturers use this strange (at least for computer geeks) system where a Kb is really 1000 bytes, and a Mb is 1000 Kb. The factor option changes this:

  factor => 1000

keep_size => <left|right>

It can be convenient, when processing an output that's already formatted for example, to have the formatted string be the same size as the original string.

Use keep_size to force the string to keep the same size. The code will try as hard as possible, even if means loosing precision.

AUTHOR

Michel Rodriguez, <mirod@cpan.org<gt>

COPYRIGHT AND LICENSE

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