NAME

    Number::Misc - handy utilities for numbers

SYNOPSIS

     use Number::Misc ':all';
    
     is_numeric('x');        # false
     to_number('3,000');     # 3000
     commafie('3000');       # 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

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.

INSTALLATION

    Number::Misc can be installed with the usual routine:

     perl Makefile.PL
     make
     make test
     make install

FUNCTIONS

 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.

     is_numeric('3');       # true
     is_numeric('-3');      # true
     is_numeric('+3');      # true
     is_numeric('0003');    # true
     is_numeric('0.003');   # true
     is_numeric('0.00.3');  # false
     is_numeric('3,003');   # false
     is_numeric('  3');     # false
     is_numeric(undef);     # false

    option: convertible

      If you want to test if the string could be a number if it were run
      through to_number() then use the convertible option.

       is_numeric('3,003',  convertible=>1);  # true
       is_numeric('  3',    convertible=>1);  # true
       is_numeric('0.00.3', convertible=>1);  # false

 to_number

    Converts a string to a number by removing commas and spaces. If the
    string can't be converted, returns undef. Some examples:

     to_number(' 3 ');       # returns 3
     to_number(' 3,000 ');   # returns 3000
     to_number('whatever');  # returns undef

    option: always_number

      If the string cannot be converted to a number, return 0 instead of
      undef. For example, this call:

       to_number('whatever', always_number=>1)

      returns 0.

 commafie

    Converts a number to a string representing the same number but with
    commas

     commafie(2000);     #  2,000
     commafie(-2000);    # -1,000
     commafie(2000.33);  #  2,000.33
     commafie(100);      #    100

    option: sep

    The sep option lets you set what to use as a separator instead of a
    comma. For example, if you want to : instead of , you would do that
    like this:

     commafie('2000', sep=>':');

    which would give you this:

     2:000

 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.

     zero_pad(2, 3);   # 002
     zero_pad(2, 10);  # 0000000002
     zero_pad(444, 2); # 444

 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.

     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

 is_even / is_odd

    is_even returns true if the number is even. is_odd returns true if the
    number is odd. Nonnumbers and decimals return undef.

Other modules

    Here are a few other modules available on CPAN that do many of the same
    things as Number::Misc:

    Number::Format <http://search.cpan.org/~wrw/Number-Format/>

    Test::Numeric <http://search.cpan.org/~evdb/Test-Numeric/>

    Math::Random <http://search.cpan.org/~grommel/Math-Random/>

TERMS AND CONDITIONS

    Copyright (c) 2012 by Miko O'Sullivan. 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 NO
    WARRANTY of any kind.

AUTHOR

    Miko O'Sullivan miko@idocs.com

VERSION

    Version 1.0 July, 2012

      Initial release.

    Version 1.1 April 25, 2014

      Fixed problem in META.yml.

    Version 1.2 January 2, 2015

      Fixed issues in tests. Added 'sep' option to commafie.