File: //usr/local/ssl/local/share/man/man3/Math::Round.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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. | will give a
.\" real vertical bar. \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.\"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Round 3"
.TH Round 3 "2006-11-21" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Math::Round \- Perl extension for rounding numbers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Math::Round qw(...those desired... or :all);
.Ve
.PP
.Vb 4
\& $rounded = round($scalar);
\& @rounded = round(LIST...);
\& $rounded = nearest($target, $scalar);
\& @rounded = nearest($target, LIST...);
.Ve
.PP
.Vb 1
\& # and other functions as described below
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBMath::Round\fR supplies functions that will round numbers in different
ways. The functions \fBround\fR and \fBnearest\fR are exported by
default; others are available as described below. \*(L"use ... qw(:all)\*(R"
exports all functions.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "\fBround\fR \s-1LIST\s0" 2
.IX Item "round LIST"
Rounds the number(s) to the nearest integer. In scalar context,
returns a single value; in list context, returns a list of values.
Numbers that are halfway between two integers are rounded
\&\*(L"to infinity\*(R"; i.e., positive values are rounded up (e.g., 2.5
becomes 3) and negative values down (e.g., \-2.5 becomes \-3).
.IP "\fBround_even\fR \s-1LIST\s0" 2
.IX Item "round_even LIST"
Rounds the number(s) to the nearest integer. In scalar context,
returns a single value; in list context, returns a list of values.
Numbers that are halfway between two integers are rounded to the
nearest even number; e.g., 2.5 becomes 2, 3.5 becomes 4, and \-2.5
becomes \-2.
.IP "\fBround_odd\fR \s-1LIST\s0" 2
.IX Item "round_odd LIST"
Rounds the number(s) to the nearest integer. In scalar context,
returns a single value; in list context, returns a list of values.
Numbers that are halfway between two integers are rounded to the
nearest odd number; e.g., 3.5 becomes 3, 4.5 becomes 5, and \-3.5
becomes \-3.
.IP "\fBround_rand\fR \s-1LIST\s0" 2
.IX Item "round_rand LIST"
Rounds the number(s) to the nearest integer. In scalar context,
returns a single value; in list context, returns a list of values.
Numbers that are halfway between two integers are rounded up or
down in a random fashion. For example, in a large number of trials,
2.5 will become 2 half the time and 3 half the time.
.IP "\fBnearest\fR \s-1TARGET\s0, \s-1LIST\s0" 2
.IX Item "nearest TARGET, LIST"
Rounds the number(s) to the nearest multiple of the target value.
\&\s-1TARGET\s0 must be positive.
In scalar context, returns a single value; in list context, returns
a list of values. Numbers that are halfway between two multiples
of the target will be rounded to infinity. For example:
.Sp
.Vb 6
\& nearest(10, 44) yields 40
\& nearest(10, 46) 50
\& nearest(10, 45) 50
\& nearest(25, 328) 325
\& nearest(.1, 4.567) 4.6
\& nearest(10, -45) -50
.Ve
.IP "\fBnearest_ceil\fR \s-1TARGET\s0, \s-1LIST\s0" 2
.IX Item "nearest_ceil TARGET, LIST"
Rounds the number(s) to the nearest multiple of the target value.
\&\s-1TARGET\s0 must be positive.
In scalar context, returns a single value; in list context, returns
a list of values. Numbers that are halfway between two multiples
of the target will be rounded to the ceiling, i.e. the next
algebraically higher multiple. For example:
.Sp
.Vb 3
\& nearest_ceil(10, 44) yields 40
\& nearest_ceil(10, 45) 50
\& nearest_ceil(10, -45) -40
.Ve
.IP "\fBnearest_floor\fR \s-1TARGET\s0, \s-1LIST\s0" 2
.IX Item "nearest_floor TARGET, LIST"
Rounds the number(s) to the nearest multiple of the target value.
\&\s-1TARGET\s0 must be positive.
In scalar context, returns a single value; in list context, returns
a list of values. Numbers that are halfway between two multiples
of the target will be rounded to the floor, i.e. the next
algebraically lower multiple. For example:
.Sp
.Vb 3
\& nearest_floor(10, 44) yields 40
\& nearest_floor(10, 45) 40
\& nearest_floor(10, -45) -50
.Ve
.IP "\fBnearest_rand\fR \s-1TARGET\s0, \s-1LIST\s0" 2
.IX Item "nearest_rand TARGET, LIST"
Rounds the number(s) to the nearest multiple of the target value.
\&\s-1TARGET\s0 must be positive.
In scalar context, returns a single value; in list context, returns
a list of values. Numbers that are halfway between two multiples
of the target will be rounded up or down in a random fashion.
For example, in a large number of trials, \f(CW\*(C`nearest(10, 45)\*(C'\fR will
yield 40 half the time and 50 half the time.
.IP "\fBnlowmult\fR \s-1TARGET\s0, \s-1LIST\s0" 2
.IX Item "nlowmult TARGET, LIST"
Returns the next lower multiple of the number(s) in \s-1LIST\s0.
\&\s-1TARGET\s0 must be positive.
In scalar context, returns a single value; in list context, returns
a list of values. Numbers that are between two multiples of the
target will be adjusted to the nearest multiples of \s-1LIST\s0 that are
algebraically lower. For example:
.Sp
.Vb 5
\& nlowmult(10, 44) yields 40
\& nlowmult(10, 46) 40
\& nlowmult(25, 328) 325
\& nlowmult(.1, 4.567) 4.5
\& nlowmult(10, -41) -50
.Ve
.IP "\fBnhimult\fR \s-1TARGET\s0, \s-1LIST\s0" 2
.IX Item "nhimult TARGET, LIST"
Returns the next higher multiple of the number(s) in \s-1LIST\s0.
\&\s-1TARGET\s0 must be positive.
In scalar context, returns a single value; in list context, returns
a list of values. Numbers that are between two multiples of the
target will be adjusted to the nearest multiples of \s-1LIST\s0 that are
algebraically higher. For example:
.Sp
.Vb 5
\& nhimult(10, 44) yields 50
\& nhimult(10, 46) 50
\& nhimult(25, 328) 350
\& nhimult(.1, 4.512) 4.6
\& nhimult(10, -49) -40
.Ve
.SH "VARIABLE"
.IX Header "VARIABLE"
The variable \fB$Math::Round::half\fR is used by most routines in this
module. Its value is very slightly larger than 0.5, for reasons
explained below. If you find that your application does not deliver
the expected results, you may reset this variable at will.
.SH "STANDARD FLOATING-POINT DISCLAIMER"
.IX Header "STANDARD FLOATING-POINT DISCLAIMER"
Floating-point numbers are, of course, a rational subset of the real
numbers, so calculations with them are not always exact.
Numbers that are supposed to be halfway between
two others may surprise you; for instance, 0.85 may not be exactly
halfway between 0.8 and 0.9, and (0.75 \- 0.7) may not be the same as
(0.85 \- 0.8).
.PP
In order to give more predictable results,
these routines use a value for
one-half that is slightly larger than 0.5. Nevertheless,
if the numbers to be rounded are stored as floating\-point, they will
be subject, as usual, to the mercies of your hardware, your C
compiler, etc.
.SH "AUTHOR"
.IX Header "AUTHOR"
Math::Round was written by Geoffrey Rommel <GROMMEL@cpan.org>
in October 2000.