Provided by: libmath-round-perl_0.08-1_all 
NAME
Math::Round - Perl extension for rounding numbers
SYNOPSIS
use Math::Round qw(...those desired... or :all);
$rounded = round($scalar);
@rounded = round(LIST...);
$rounded = nearest($target, $scalar);
@rounded = nearest($target, LIST...);
# and other functions as described below
DESCRIPTION
Math::Round supplies functions that will round numbers in different ways. The functions round and
nearest are exported by default; others are available as described below. "use ... qw(:all)" exports all
functions.
FUNCTIONS
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 "to
infinity"; i.e., positive values are rounded up (e.g., 2.5 becomes 3) and negative values down (e.g.,
-2.5 becomes -3).
Starting in Perl 5.22, the POSIX module by default exports all functions, including one named "round".
If you use both POSIX and this module, exercise due caution.
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.
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.
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.
nearest TARGET, LIST
Rounds the number(s) to the nearest multiple of the target value. TARGET 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:
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
nearest_ceil TARGET, LIST
Rounds the number(s) to the nearest multiple of the target value. TARGET 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:
nearest_ceil(10, 44) yields 40
nearest_ceil(10, 45) 50
nearest_ceil(10, -45) -40
nearest_floor TARGET, LIST
Rounds the number(s) to the nearest multiple of the target value. TARGET 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:
nearest_floor(10, 44) yields 40
nearest_floor(10, 45) 40
nearest_floor(10, -45) -50
nearest_rand TARGET, LIST
Rounds the number(s) to the nearest multiple of the target value. TARGET 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, "nearest(10, 45)" will yield 40 half the time and 50 half the time.
nlowmult TARGET, LIST
Returns the next lower multiple of the number(s) in LIST. TARGET 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 LIST that are algebraically lower.
For example:
nlowmult(10, 44) yields 40
nlowmult(10, 46) 40
nlowmult(25, 328) 325
nlowmult(.1, 4.567) 4.5
nlowmult(10, -41) -50
nhimult TARGET, LIST
Returns the next higher multiple of the number(s) in LIST. TARGET 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 LIST that are algebraically
higher. For example:
nhimult(10, 44) yields 50
nhimult(10, 46) 50
nhimult(25, 328) 350
nhimult(.1, 4.512) 4.6
nhimult(10, -49) -40
VARIABLE
The variable $Math::Round::half 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.
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).
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.
AUTHOR
Math::Round was written by Geoffrey Rommel <GROMMEL@cpan.org> in October 2000.
COPYRIGHT AND LICENSE
This software is copyright (c) 2000 by Geoffrey Rommel <grommel@cpan.org>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5
programming language system itself.