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_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.

STANDARD FLOATING-POINT DISCLAIMER

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@sears.com> in October 2000.