README
1NAME
2
3 Number::Misc - handy utilities for numbers
4
5SYNOPSIS
6
7 use Number::Misc ':all';
8
9 is_numeric('x'); # false
10 to_number('3,000'); # 3000
11 commafie('3000'); # 3,000
12 zero_pad(2, 10); # 0000000002
13 rand_in_range(3, 10); # a random number from 3 to 10, inclusive
14 is_even(3) # true
15 is_odd(4); # true
16
17DESCRIPTION
18
19 Number::Misc provides some miscellaneous handy utilities for handling
20 numbers. These utilities handle processing numbers as strings,
21 determining basic properties of numbers, or selecting a random number
22 from a range.
23
24INSTALLATION
25
26 Number::Misc can be installed with the usual routine:
27
28 perl Makefile.PL
29 make
30 make test
31 make install
32
33FUNCTIONS
34
35 is_numeric
36
37 Returns true if the given scalar is a number. An undefined value
38 returns false. A "number" is defined as consisting solely of numerals
39 (i.e. the characters 0-9), with at most one decimal, and at most a
40 single leading minus or plus sign.
41
42 is_numeric('3'); # true
43 is_numeric('-3'); # true
44 is_numeric('+3'); # true
45 is_numeric('0003'); # true
46 is_numeric('0.003'); # true
47 is_numeric('0.00.3'); # false
48 is_numeric('3,003'); # false
49 is_numeric(' 3'); # false
50 is_numeric(undef); # false
51
52 option: convertible
53
54 If you want to test if the string could be a number if it were run
55 through to_number() then use the convertible option.
56
57 is_numeric('3,003', convertible=>1); # true
58 is_numeric(' 3', convertible=>1); # true
59 is_numeric('0.00.3', convertible=>1); # false
60
61 to_number
62
63 Converts a string to a number by removing commas and spaces. If the
64 string can't be converted, returns undef. Some examples:
65
66 to_number(' 3 '); # returns 3
67 to_number(' 3,000 '); # returns 3000
68 to_number('whatever'); # returns undef
69
70 option: always_number
71
72 If the string cannot be converted to a number, return 0 instead of
73 undef. For example, this call:
74
75 to_number('whatever', always_number=>1)
76
77 returns 0.
78
79 commafie
80
81 Converts a number to a string representing the same number but with
82 commas
83
84 commafie(2000); # 2,000
85 commafie(-2000); # -1,000
86 commafie(2000.33); # 2,000.33
87 commafie(100); # 100
88
89 option: sep
90
91 The sep option lets you set what to use as a separator instead of a
92 comma. For example, if you want to : instead of , you would do that
93 like this:
94
95 commafie('2000', sep=>':');
96
97 which would give you this:
98
99 2:000
100
101 zero_pad
102
103 Prepends zeroes to the number to make it a specified length. The first
104 param is the number, the second is the target length. If the length of
105 the number is equal to or longer than the given length then nothing is
106 changed.
107
108 zero_pad(2, 3); # 002
109 zero_pad(2, 10); # 0000000002
110 zero_pad(444, 2); # 444
111
112 rand_in_range
113
114 Given lower and upper bounds, returns a random number greater than or
115 equal to the lower bound and less than or equal to the upper. Works
116 only on integers.
117
118 rand_in_range(3, 10); # a random number from 3 to 10, inclusive
119 rand_in_range(-1, 10); # a random number from -1 to 10, inclusive
120
121 is_even / is_odd
122
123 is_even returns true if the number is even. is_odd returns true if the
124 number is odd. Nonnumbers and decimals return undef.
125
126Other modules
127
128 Here are a few other modules available on CPAN that do many of the same
129 things as Number::Misc:
130
131 Number::Format <http://search.cpan.org/~wrw/Number-Format/>
132
133 Test::Numeric <http://search.cpan.org/~evdb/Test-Numeric/>
134
135 Math::Random <http://search.cpan.org/~grommel/Math-Random/>
136
137TERMS AND CONDITIONS
138
139 Copyright (c) 2012 by Miko O'Sullivan. All rights reserved. This
140 program is free software; you can redistribute it and/or modify it
141 under the same terms as Perl itself. This software comes with NO
142 WARRANTY of any kind.
143
144AUTHOR
145
146 Miko O'Sullivan miko@idocs.com
147
148VERSION
149
150 Version 1.0 July, 2012
151
152 Initial release.
153
154 Version 1.1 April 25, 2014
155
156 Fixed problem in META.yml.
157
158 Version 1.2 January 2, 2015
159
160 Fixed issues in tests. Added 'sep' option to commafie.
161
162