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).
- 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
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. In order to avoid surprises
because of this, these routines use a value for one-half that is very 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. Thus, numbers that are supposed to be halfway
between two others may be stored in a slightly different way and thus behave
surprisingly.
AUTHOR¶
Math::Round was written by Geoffrey Rommel <GROMMEL@cpan.org> in October
2000.