| Current File : //usr/local/share/man/man3/Math::Calc::Units.3pm |
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. 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 "Units 3"
.TH Units 3 "2009-08-04" "perl v5.26.3" "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"
Math::Calc::Units \- Human\-readable unit\-aware calculator
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Math::Calc::Units qw(calc readable convert equal);
\&
\& print "It will take ".calc("10MB/(384Kbps)")." to download\en";
\&
\& my @alternative_descriptions = readable("10MB/(384Kbps)");
\&
\& print "A week is ".convert("1 week", "seconds")." long\en";
\&
\& if (equal("$rate bytes / sec", "1 MB/sec")) { ... };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Math::Calc::Units\*(C'\fR is a simple calculator that keeps track of units. It
currently handles combinations of byte sizes and duration only,
although adding any other multiplicative types is easy. Any unknown
type is treated as a unique user type (with some effort to map English
plurals to their singular forms).
.PP
The primary intended use is via the \f(CW\*(C`ucalc\*(C'\fR script that prints out
all of the \*(L"readable\*(R" variants of a value. For example, \f(CW"3 bytes"\fR
will only produce \f(CW"3 byte"\fR, but \f(CW"3 byte / sec"\fR produces the
original along with \f(CW"180 byte / minute"\fR, \f(CW"10.55 kilobyte / hour"\fR,
etc.
.PP
The \f(CW\*(C`Math::Calc::Units\*(C'\fR interface only provides for string-based
computations, which could result in a large loss of precision for some
applications. If you need the exact result, you may pass in an extra
parameter \f(CW\*(Aqexact\*(Aq\fR to \f(CW\*(C`calc\*(C'\fR or \f(CW\*(C`convert\*(C'\fR, causing them to return a
2\-element list containing the numerical result and a string describing
the units of that result:
.PP
.Vb 1
\& my ($value, $units) = convert("10MB/sec", "GB/day");
.Ve
.PP
(In scalar context, they just return the numeric value.)
.SS "Examples of use"
.IX Subsection "Examples of use"
.IP "\(bu" 4
Estimate transmission rates (e.g., 10MB at 384 kilobit/sec)
.IP "\(bu" 4
Estimate performance characteristics (e.g., disk I/O rates)
.IP "\(bu" 4
Figure out how long something will take to complete
.PP
I tend to work on performance-sensitive code that involves a lot of
network and disk traffic, so I wrote this tool after I became very
sick of constantly converting KB/sec to GB/day when trying to figure
out how long a run is going to take, or what the theoretical maximum
performance would be if we were 100% disk bound. Now I can't live
without it.
.SS "Contraindications"
.IX Subsection "Contraindications"
If you are just trying to convert from one unit to another, you'll
probably be better off with \f(CW\*(C`Math::Units\*(C'\fR or \f(CW\*(C`Convert::Units\*(C'\fR. This
module really only makes sense when you're converting to and from
human-readable values.
.SH "AUTHOR"
.IX Header "AUTHOR"
Steve Fink <sfink@cpan.org>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
ucalc, Math::Units, Convert::Units.