Number::Misc - handy utilities for numbers

- NAME
- SYNOPSIS
- DESCRIPTION
- INSTALLATION
- FUNCTIONS
  - is_numeric
  - to_number
  - commafie
  - zero_pad
  - rand_in_range
  - is_even / is_odd
- Other modules
- TERMS AND CONDITIONS
- AUTHOR
- VERSION

# 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

Test::Numeric

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.

Number::Misc - handy utilities for numbers