1Round(3) User Contributed Perl Documentation Round(3)
2
6 Math::Round - Perl extension for rounding numbers
7
9 use Math::Round qw(...those desired... or :all);
10 $rounded = round($scalar);
12 @rounded = round(LIST...);
13 $rounded = nearest($target, $scalar);
14 @rounded = nearest($target, LIST...);
15 # and other functions as described below
17
19 Math::Round supplies functions that will round numbers in different
20 ways. The functions round and nearest are exported by default; others
21 are available as described below. "use ... qw(:all)" exports all
22 functions.
23
25 round LIST
26 Rounds the number(s) to the nearest integer. In scalar context,
27 returns a single value; in list context, returns a list of values.
28 Numbers that are halfway between two integers are rounded "to
29 infinity"; i.e., positive values are rounded up (e.g., 2.5 becomes 3)
30 and negative values down (e.g., -2.5 becomes -3).
31 Starting in Perl 5.22, the POSIX module by default exports all
33 functions, including one named "round". If you use both POSIX and
34 this module, exercise due caution.
35 round_even LIST
37 Rounds the number(s) to the nearest integer. In scalar context,
38 returns a single value; in list context, returns a list of values.
39 Numbers that are halfway between two integers are rounded to the
40 nearest even number; e.g., 2.5 becomes 2, 3.5 becomes 4, and -2.5
41 becomes -2.
42 round_odd LIST
44 Rounds the number(s) to the nearest integer. In scalar context,
45 returns a single value; in list context, returns a list of values.
46 Numbers that are halfway between two integers are rounded to the
47 nearest odd number; e.g., 3.5 becomes 3, 4.5 becomes 5, and -3.5
48 becomes -3.
49 round_rand LIST
51 Rounds the number(s) to the nearest integer. In scalar context,
52 returns a single value; in list context, returns a list of values.
53 Numbers that are halfway between two integers are rounded up or down
54 in a random fashion. For example, in a large number of trials, 2.5
55 will become 2 half the time and 3 half the time.
56 nearest TARGET, LIST
58 Rounds the number(s) to the nearest multiple of the target value.
59 TARGET must be positive. In scalar context, returns a single value;
60 in list context, returns a list of values. Numbers that are halfway
61 between two multiples of the target will be rounded to infinity. For
62 example:
63 nearest(10, 44) yields 40
65 nearest(10, 46) 50
66 nearest(10, 45) 50
67 nearest(25, 328) 325
68 nearest(.1, 4.567) 4.6
69 nearest(10, -45) -50
70 nearest_ceil TARGET, LIST
72 Rounds the number(s) to the nearest multiple of the target value.
73 TARGET must be positive. In scalar context, returns a single value;
74 in list context, returns a list of values. Numbers that are halfway
75 between two multiples of the target will be rounded to the ceiling,
76 i.e. the next algebraically higher multiple. For example:
77 nearest_ceil(10, 44) yields 40
79 nearest_ceil(10, 45) 50
80 nearest_ceil(10, -45) -40
81 nearest_floor TARGET, LIST
83 Rounds the number(s) to the nearest multiple of the target value.
84 TARGET must be positive. In scalar context, returns a single value;
85 in list context, returns a list of values. Numbers that are halfway
86 between two multiples of the target will be rounded to the floor,
87 i.e. the next algebraically lower multiple. For example:
88 nearest_floor(10, 44) yields 40
90 nearest_floor(10, 45) 40
91 nearest_floor(10, -45) -50
92 nearest_rand TARGET, LIST
94 Rounds the number(s) to the nearest multiple of the target value.
95 TARGET must be positive. In scalar context, returns a single value;
96 in list context, returns a list of values. Numbers that are halfway
97 between two multiples of the target will be rounded up or down in a
98 random fashion. For example, in a large number of trials,
99 "nearest(10, 45)" will yield 40 half the time and 50 half the time.
100 nlowmult TARGET, LIST
102 Returns the next lower multiple of the number(s) in LIST. TARGET
103 must be positive. In scalar context, returns a single value; in list
104 context, returns a list of values. Numbers that are between two
105 multiples of the target will be adjusted to the nearest multiples of
106 LIST that are algebraically lower. For example:
107 nlowmult(10, 44) yields 40
109 nlowmult(10, 46) 40
110 nlowmult(25, 328) 325
111 nlowmult(.1, 4.567) 4.5
112 nlowmult(10, -41) -50
113 nhimult TARGET, LIST
115 Returns the next higher multiple of the number(s) in LIST. TARGET
116 must be positive. In scalar context, returns a single value; in list
117 context, returns a list of values. Numbers that are between two
118 multiples of the target will be adjusted to the nearest multiples of
119 LIST that are algebraically higher. For example:
120 nhimult(10, 44) yields 50
122 nhimult(10, 46) 50
123 nhimult(25, 328) 350
124 nhimult(.1, 4.512) 4.6
125 nhimult(10, -49) -40
126
128 The variable $Math::Round::half is used by most routines in this
129 module. Its value is very slightly larger than 0.5, for reasons
130 explained below. If you find that your application does not deliver the
131 expected results, you may reset this variable at will.
132
134 Floating-point numbers are, of course, a rational subset of the real
135 numbers, so calculations with them are not always exact. Numbers that
136 are supposed to be halfway between two others may surprise you; for
137 instance, 0.85 may not be exactly halfway between 0.8 and 0.9, and
138 (0.75 - 0.7) may not be the same as (0.85 - 0.8).
139 In order to give more predictable results, these routines use a value
141 for one-half that is slightly larger than 0.5. Nevertheless, if the
142 numbers to be rounded are stored as floating-point, they will be
143 subject as usual to the mercies of your hardware, your C compiler, etc.
144
146 Math::Round was written by Geoffrey Rommel <GROMMEL@cpan.org> in
147 October 2000.
148perl v5.36.0 2023-01-20 Round(3)