1Number::Misc(3)       User Contributed Perl Documentation      Number::Misc(3)
2
3
4

NAME

6       Number::Misc - handy utilities for numbers
7

SYNOPSIS

9        use Number::Misc ':all';
10
11        is_numeric('x');        # false
12        to_number('3,000');     # 3000
13        commafie('3000');       # 3,000
14        zero_pad(2, 10);        # 0000000002
15        rand_in_range(3, 10);   # a random number from 3 to 10, inclusive
16        is_even(3)              # true
17        is_odd(4);              # true
18

DESCRIPTION

20       Number::Misc provides some miscellaneous handy utilities for handling
21       numbers.  These utilities handle processing numbers as strings,
22       determining basic properties of numbers, or selecting a random number
23       from a range.
24

INSTALLATION

26       Number::Misc can be installed with the usual routine:
27
28        perl Makefile.PL
29        make
30        make test
31        make install
32

FUNCTIONS

34   is_numeric
35       Returns true if the given scalar is a number.  An undefined value
36       returns false.  A "number" is defined as consisting solely of numerals
37       (i.e. the characters 0-9), with at most one decimal, and at most a
38       single leading minus or plus sign.
39
40        is_numeric('3');       # true
41        is_numeric('-3');      # true
42        is_numeric('+3');      # true
43        is_numeric('0003');    # true
44        is_numeric('0.003');   # true
45        is_numeric('0.00.3');  # false
46        is_numeric('3,003');   # false
47        is_numeric('  3');     # false
48        is_numeric(undef);     # false
49
50       option: convertible
51           If you want to test if the string could be a number if it were run
52           through to_number() then use the convertible option.
53
54            is_numeric('3,003',  convertible=>1);  # true
55            is_numeric('  3',    convertible=>1);  # true
56            is_numeric('0.00.3', convertible=>1);  # false
57
58   to_number
59       Converts a string to a number by removing commas and spaces.  If the
60       string can't be converted, returns undef. Some examples:
61
62        to_number(' 3 ');       # returns 3
63        to_number(' 3,000 ');   # returns 3000
64        to_number('whatever');  # returns undef
65
66       option: always_number
67           If the string cannot be converted to a number, return 0 instead of
68           undef.  For example, this call:
69
70            to_number('whatever', always_number=>1)
71
72           returns 0.
73
74   commafie
75       Converts a number to a string representing the same number but with
76       commas
77
78        commafie(2000);     #  2,000
79        commafie(-2000);    # -1,000
80        commafie(2000.33);  #  2,000.33
81        commafie(100);      #    100
82
83       option: sep
84
85       The "sep" option lets you set what to use as a separator instead of a
86       comma.  For example, if you want to ":" instead of "," you would do
87       that like this:
88
89        commafie('2000', sep=>':');
90
91       which would give you this:
92
93        2:000
94
95   zero_pad
96       Prepends zeroes to the number to make it a specified length.  The first
97       param is the  number, the second is the target length.  If the length
98       of the number is equal to or longer than the given length then nothing
99       is changed.
100
101        zero_pad(2, 3);   # 002
102        zero_pad(2, 10);  # 0000000002
103        zero_pad(444, 2); # 444
104
105   rand_in_range
106       Given lower and upper bounds, returns a random number greater than or
107       equal to the lower bound and less than or equal to the upper.  Works
108       only on integers.
109
110        rand_in_range(3, 10);   # a random number from 3 to 10, inclusive
111        rand_in_range(-1, 10);  # a random number from -1 to 10, inclusive
112
113   is_even / is_odd
114       "is_even" returns true if the number is even.  "is_odd" returns true if
115       the number is odd.  Nonnumbers and decimals return undef.
116

Other modules

118       Here are a few other modules available on CPAN that do many of the same
119       things as Number::Misc:
120
121       Number::Format <http://search.cpan.org/~wrw/Number-Format/>
122
123       Test::Numeric <http://search.cpan.org/~evdb/Test-Numeric/>
124
125       Math::Random <http://search.cpan.org/~grommel/Math-Random/>
126

TERMS AND CONDITIONS

128       Copyright (c) 2012 by Miko O'Sullivan.  All rights reserved.  This
129       program is free software; you can redistribute it and/or modify it
130       under the same terms as Perl itself. This software comes with NO
131       WARRANTY of any kind.
132

AUTHOR

134       Miko O'Sullivan miko@idocs.com
135

VERSION

137       Version 1.0    July, 2012
138           Initial release.
139
140       Version 1.1  April 25, 2014
141           Fixed problem in META.yml.
142
143       Version 1.2 January 2, 2015
144           Fixed issues in tests.  Added 'sep' option to commafie.
145
146
147
148perl v5.34.0                      2022-01-21                   Number::Misc(3)
Impressum