Math::Round (3)

Leading comments

Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/Math::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. 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.