.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Number::Misc 3"
.TH Number::Misc 3 2025-12-14 "perl v5.42.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Number::Misc \- handy utilities for numbers
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& use Number::Misc \*(Aq:all\*(Aq;
\&
\& is_numeric(\*(Aqx\*(Aq); # false
\& to_number(\*(Aq3,000\*(Aq); # 3000
\& commafie(\*(Aq3000\*(Aq); # 3,000
\& zero_pad(2, 10); # 0000000002
\& rand_in_range(3, 10); # a random number from 3 to 10, inclusive
\& is_even(3) # true
\& is_odd(4); # true
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Number::Misc provides some miscellaneous handy utilities for handling numbers.
These utilities handle processing numbers as strings, determining basic properties
of numbers, or selecting a random number from a range.
.SH INSTALLATION
.IX Header "INSTALLATION"
Number::Misc can be installed with the usual routine:
.PP
.Vb 4
\& perl Makefile.PL
\& make
\& make test
\& make install
.Ve
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS is_numeric
.IX Subsection "is_numeric"
Returns true if the given scalar is a number. An undefined value returns false.
A "number" is defined as consisting solely of numerals (i.e. the characters 0\-9),
with at most one decimal, and at most a single leading minus or plus sign.
.PP
.Vb 9
\& is_numeric(\*(Aq3\*(Aq); # true
\& is_numeric(\*(Aq\-3\*(Aq); # true
\& is_numeric(\*(Aq+3\*(Aq); # true
\& is_numeric(\*(Aq0003\*(Aq); # true
\& is_numeric(\*(Aq0.003\*(Aq); # true
\& is_numeric(\*(Aq0.00.3\*(Aq); # false
\& is_numeric(\*(Aq3,003\*(Aq); # false
\& is_numeric(\*(Aq 3\*(Aq); # false
\& is_numeric(undef); # false
.Ve
.IP "option: convertible" 4
.IX Item "option: convertible"
If you want to test if the string \fBcould\fR be a number if it were run through
\&\fBto_number()\fR then use the convertible option.
.Sp
.Vb 3
\& is_numeric(\*(Aq3,003\*(Aq, convertible=>1); # true
\& is_numeric(\*(Aq 3\*(Aq, convertible=>1); # true
\& is_numeric(\*(Aq0.00.3\*(Aq, convertible=>1); # false
.Ve
.SS to_number
.IX Subsection "to_number"
Converts a string to a number by removing commas and spaces. If the string
can\*(Aqt be converted, returns undef. Some examples:
.PP
.Vb 3
\& to_number(\*(Aq 3 \*(Aq); # returns 3
\& to_number(\*(Aq 3,000 \*(Aq); # returns 3000
\& to_number(\*(Aqwhatever\*(Aq); # returns undef
.Ve
.IP "option: always_number" 4
.IX Item "option: always_number"
If the string cannot be converted to a number, return 0 instead of undef.
For example, this call:
.Sp
.Vb 1
\& to_number(\*(Aqwhatever\*(Aq, always_number=>1)
.Ve
.Sp
returns 0.
.SS commafie
.IX Subsection "commafie"
Converts a number to a string representing the same number but with commas
.PP
.Vb 4
\& commafie(2000); # 2,000
\& commafie(\-2000); # \-1,000
\& commafie(2000.33); # 2,000.33
\& commafie(100); # 100
.Ve
.PP
\&\fBoption: sep\fR
.PP
The \f(CW\*(C`sep\*(C'\fR option lets you set what to use as a separator instead of a comma.
For example, if you want to \f(CW\*(C`:\*(C'\fR instead of \f(CW\*(C`,\*(C'\fR you would do that like this:
.PP
.Vb 1
\& commafie(\*(Aq2000\*(Aq, sep=>\*(Aq:\*(Aq);
.Ve
.PP
which would give you this:
.PP
.Vb 1
\& 2:000
.Ve
.SS zero_pad
.IX Subsection "zero_pad"
Prepends zeroes to the number to make it a specified length. The first param is
the number, the second is the target length. If the length of the number is
equal to or longer than the given length then nothing is changed.
.PP
.Vb 3
\& zero_pad(2, 3); # 002
\& zero_pad(2, 10); # 0000000002
\& zero_pad(444, 2); # 444
.Ve
.SS rand_in_range
.IX Subsection "rand_in_range"
Given lower and upper bounds, returns a random number greater than
or equal to the lower bound and less than or equal to the upper.
Works only on integers.
.PP
.Vb 2
\& rand_in_range(3, 10); # a random number from 3 to 10, inclusive
\& rand_in_range(\-1, 10); # a random number from \-1 to 10, inclusive
.Ve
.SS "is_even / is_odd"
.IX Subsection "is_even / is_odd"
\&\f(CW\*(C`is_even\*(C'\fR returns true if the number is even.
\&\f(CW\*(C`is_odd\*(C'\fR returns true if the number is odd.
Nonnumbers and decimals return undef.
.SH "Other modules"
.IX Header "Other modules"
Here are a few other modules available on CPAN that do many of the same things
as Number::Misc:
.PP
Number::Format
.PP
Test::Numeric
.PP
Math::Random
.SH "TERMS AND CONDITIONS"
.IX Header "TERMS AND CONDITIONS"
Copyright (c) 2012 by Miko O\*(AqSullivan. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the same terms
as Perl itself. This software comes with \fBNO WARRANTY\fR of any kind.
.SH AUTHOR
.IX Header "AUTHOR"
Miko O\*(AqSullivan
\&\fImiko@idocs.com\fR
.SH VERSION
.IX Header "VERSION"
.IP "Version 1.0 July, 2012" 4
.IX Item "Version 1.0 July, 2012"
Initial release.
.IP "Version 1.1 April 25, 2014" 4
.IX Item "Version 1.1 April 25, 2014"
Fixed problem in META.yml.
.IP "Version 1.2 January 2, 2015" 4
.IX Item "Version 1.2 January 2, 2015"
Fixed issues in tests. Added \*(Aqsep\*(Aq option to commafie.