Round(3pm)						User Contributed Perl Documentation						Round(3pm)

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.  Num-
	 bers that are halfway between two integers are rounded "to infinity"; i.e., positive values are rounded up (e.g., 2.5 becomes 3) and neg-
	 ative 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.  Num-
	 bers 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.  Num-
	 bers 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.  Num-
	 bers 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 num-
       bers 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.

perl v5.8.8							    2006-12-02								Round(3pm)