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

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.