.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Human 3"
.TH Human 3 2023-07-26 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Number::Bytes::Human \- Convert byte count to human readable format
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&  use Number::Bytes::Human qw(format_bytes parse_bytes);
\&  $size = format_bytes(0); # \*(Aq0\*(Aq
\&  $size = format_bytes(2*1024); # \*(Aq2.0K\*(Aq
\&
\&  $size = format_bytes(1_234_890, bs => 1000); # \*(Aq1.3M\*(Aq
\&  $size = format_bytes(1E9, bs => 1000); # \*(Aq1.0G\*(Aq
\&
\&  my $bytes = parse_bytes(\*(Aq1.0K\*(Aq);   # 1024
\&  my $bytes = parse_bytes(\*(Aq1.0KB\*(Aq);  # 1000, SI unit
\&  my $bytes = parse_bytes(\*(Aq1.0KiB\*(Aq); # 1024, SI unit
\&
\&  # the OO way
\&  $human = Number::Bytes::Human\->new(bs => 1000, si => 1);
\&  $size = $human\->format(1E7); # \*(Aq10MB\*(Aq
\&
\&  $bytes = $human\->parse(\*(Aq10MB\*(Aq);   # 10*1000*1000
\&  $bytes = $human\->parse(\*(Aq10MiB\*(Aq);  # 10*1024*1024
\&  $bytes = $human\->parse(\*(Aq10M\*(Aq);    # Error, no SI unit
\&
\&  $human\->set_options(zero => \*(Aq\-\*(Aq);
\&  $size = $human\->format(0);    # \*(Aq\-\*(Aq
\&  $bytes = $human\->parse(\*(Aq\-\*(Aq);  # 0
\&
\&  $human = Number::Bytes::Human\->new(bs => 1000, round_style => \*(Aqround\*(Aq, precision => 2);
\&  $size = $human\->format(10240000); # \*(Aq10.24MB\*(Aq
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
THIS IS ALPHA SOFTWARE: THE DOCUMENTATION AND THE CODE WILL SUFFER
CHANGES SOME DAY (THANKS, GOD!).
.PP
This module provides a formatter which turns byte counts
to usual readable format, like '2.0K', '3.1G', '100B'.
It was inspired in the \f(CW\*(C`\-h\*(C'\fR option of Unix
utilities like \f(CW\*(C`du\*(C'\fR, \f(CW\*(C`df\*(C'\fR and \f(CW\*(C`ls\*(C'\fR for "human-readable" output.
.PP
From the FreeBSD man page of \f(CW\*(C`df\*(C'\fR: http://www.freebsd.org/cgi/man.cgi?query=df
.PP
.Vb 3
\&  "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
.Ve
.PP
I have found this link to be quite useful:
.PP
.Vb 1
\&  http://www.t1shopper.com/tools/calculate/
.Ve
.PP
If you feel like a hard-drive manufacturer, you can start
counting bytes by powers of 1000 (instead of the generous 1024).
Just use \f(CW\*(C`bs => 1000\*(C'\fR.
.PP
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 \f(CW\*(C`bs => 1_024_000\*(C'\fR.
.PP
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 \f(CW\*(C`(\*(AqB\*(Aq, \*(AqkB\*(Aq, \*(AqMB\*(Aq, \*(AqGB\*(Aq, \*(AqTB\*(Aq, \*(AqPB\*(Aq, \*(AqEB\*(Aq, \*(AqZB\*(Aq, \*(AqYB\*(Aq)\*(C'\fR and,
even worse, the ones for base 1024 are
\&\f(CW\*(C`(\*(AqB\*(Aq, \*(AqKiB\*(Aq, \*(AqMiB\*(Aq, \*(AqGiB\*(Aq, \*(AqTiB\*(Aq, \*(AqPiB\*(Aq, \*(AqEiB\*(Aq, \*(AqZiB\*(Aq, \*(AqYiB\*(Aq)\*(C'\fR
with the horrible names: bytes, kibibytes, mebibytes, etc.
All you have to do is to use \f(CW\*(C`si => 1\*(C'\fR. Ain't that beautiful
the SI system? Read about it:
.PP
.Vb 1
\&  http://physics.nist.gov/cuu/Units/binary.html
.Ve
.PP
You can try a pure Perl \f(CW"ls \-lh"\fR\-inspired command with the one-liner, er, two-liner:
.PP
.Vb 2
\&  $ perl \-MNumber::Bytes::Human=format_bytes \e
\&         \-e \*(Aqprintf "%5s %s\en", format_bytes(\-s), $_ for @ARGV\*(Aq *
.Ve
.PP
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).
.PP
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.
.SS OBJECTS
.IX Subsection "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
.PP
.Vb 4
\&  for (@sizes) {
\&    my $fmt_size = format_bytes($_, @args);
\&    ...
\&  }
.Ve
.PP
versus
.PP
.Vb 5
\&  my $human = Number::Format::Bytes\->new(@args);
\&  for (@sizes) {
\&    my $fmt_size = $human\->format($_);
\&    ...
\&  }
.Ve
.PP
for TODO
[TODO] MAKE IT JUST A MATTER OF STYLE: memoize \fB_parse_args()\fR
\&\f(CW$seed\fR == undef
.SS FUNCTIONS
.IX Subsection "FUNCTIONS"
.IP \fBformat_bytes\fR 4
.IX Item "format_bytes"
.Vb 1
\&  $h_size = format_bytes($size, @options);
.Ve
.Sp
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.
.IP \fBparse_bytes\fR 4
.IX Item "parse_bytes"
.Vb 1
\&  $size = parse_bytes($h_size, @options);
.Ve
.Sp
Turns a human readable byte count into a number of the equivalent bytes.
.SS METHODS
.IX Subsection "METHODS"
.IP \fBnew\fR 4
.IX Item "new"
.Vb 1
\&  $h = Number::Bytes::Human\->new(@options);
.Ve
.Sp
The constructor. For details on the arguments, see the section
"OPTIONS".
.IP \fBformat\fR 4
.IX Item "format"
.Vb 1
\&  $h_size = $h\->format($size);
.Ve
.Sp
Turns a byte count (like 1230) to a readable format like '1.3K'.
The statements
.Sp
.Vb 2
\&  $h = Number::Bytes::Human\->new(@options);
\&  $h_size = $h\->format($size);
.Ve
.Sp
are equivalent to \f(CW\*(C`$h_size = format_bytes($size, @options)\*(C'\fR,
with only one pass for the option arguments.
.IP \fBparse\fR 4
.IX Item "parse"
.Vb 1
\&  $size = $h\->parse($h_size)
.Ve
.Sp
Turns a human readable byte count into the number of bytes.
The statements
.Sp
.Vb 2
\&  $h = Number::Bytes::Human\->new(@options);
\&  $size = $h\->format($h_size);
.Ve
.Sp
are equivalent to \f(CW\*(C`$size = parse_bytes($h_size, @options)\*(C'\fR,
with only one pass for the option arguments.
.IP \fBset_options\fR 4
.IX Item "set_options"
.Vb 1
\&  $h\->set_options(@options);
.Ve
.Sp
To alter the options of a \f(CW\*(C`Number::Bytes::Human\*(C'\fR object.
See "OPTIONS".
.SS OPTIONS
.IX Subsection "OPTIONS"
.IP BASE 4
.IX Item "BASE"
.Vb 3
\&  block | base | block_size | bs => 1000 | 1024 | 1024000
\&  base_1024 | block_1024 | 1024 => 1
\&  base_1000 | block_1000 | 1000 => 1
.Ve
.Sp
The base to be used: 1024 (default), 1000 or 1024000.
.Sp
Any other value throws an exception.
.IP SUFFIXES 4
.IX Item "SUFFIXES"
.Vb 1
\&  suffixes => 1000 | 1024 | 1024000 | si_1000 | si_1024 | $arrayref
.Ve
.Sp
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.
.IP ZERO 4
.IX Item "ZERO"
.Vb 1
\&  zero => string | undef
.Ve
.Sp
The string \f(CW0\fR maps to ('0' by default). If \f(CW\*(C`undef\*(C'\fR, the general case is used.
The string may contain '%S' in which case the suffix for byte is used.
.Sp
.Vb 1
\&  format_bytes(0, zero => \*(Aq\-\*(Aq) => \*(Aq\-\*(Aq
.Ve
.IP "METRIC SYSTEM" 4
.IX Item "METRIC SYSTEM"
.Vb 1
\&  si => 1
.Ve
.IP ROUND 4
.IX Item "ROUND"
.Vb 2
\&  round_function => $coderef
\&  round_style => \*(Aqceil\*(Aq | \*(Aqfloor\*(Aq | \*(Aqround\*(Aq | \*(Aqtrunc\*(Aq
.Ve
.IP TO_S 4
.IX Item "TO_S"
.PD 0
.IP QUIET 4
.IX Item "QUIET"
.PD
.Vb 1
\&  quiet => 1
.Ve
.Sp
Suppresses the warnings emitted. Currently, the only case is
when the number is large than \f(CW\*(C`$base**(@suffixes+1)\*(C'\fR.
.IP PRECISION 4
.IX Item "PRECISION"
.Vb 1
\&  precision => <integer>
.Ve
.Sp
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.
.IP PRECISION_CUTOFF 4
.IX Item "PRECISION_CUTOFF"
.Vb 1
\&  precision_cutoff => <integer>
.Ve
.Sp
default = 1
when the number of digits exceeds this number causes the precision to be cutoff
(was default behaviour in 0.07 and below)
.SS EXPORT
.IX Subsection "EXPORT"
It is alright to import \f(CW\*(C`format_bytes\*(C'\fR and \f(CW\*(C`parse_bytes\*(C'\fR, but nothing is exported by default.
.SH DIAGNOSTICS
.IX Header "DIAGNOSTICS"
.Vb 1
\&  "unknown round style \*(Aq$style\*(Aq";
\&
\&  "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" (??)
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIlib/human.c\fR and \fIlib/human.h\fR in GNU coreutils.
.PP
The \f(CW_convert()\fR solution by COG in Filesys::DiskUsage.
.SH BUGS
.IX Header "BUGS"
Please report bugs via Github <https://github.com/aferreira/cpan\-Number\-Bytes\-Human/issues>.
.SH AUTHOR
.IX Header "AUTHOR"
Adriano R. Ferreira, <ferreira@cpan.org>
.PP
Dagobert Michelsen, <dagobert@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2005\-2017 by Adriano R. Ferreira
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.