/ 
Math-Pandigital-0.01
River stage zero No dependents
/ Math::Pandigital

NAME

Math::Pandigital - Pandigital number detection.

SYNOPSIS

use Math::Pandigital;

my $p = Math::Pandigital->new;
my $test = 1234567890;
if( $p->is_pandigital( $test ) ) {
  print "$test is pandigital.\n";
}
else {
  print $test is not pandigital.\n";
}

my $p = Math::Pandigital->new( base => 8, zero => 0, unique => 1 );
print "012345567 is pandigital\n" if $p->is_pandigital('012345567'); # No.
print "1234567 is pandigital\n" if $p->is_pandigital('1234567');     # Yes.

DESCRIPTION

A Pandigital number is an integer that contains at least one of each digit in its base system. For example, a base-2 pandigital number must contain both 0 and 1. A base-10 pandigital number must contain 0, 1, 2, 3, 4, 5, 6, 7, 8, and 9.

Pandigital numbers usually include zero. However, zeroless pandigital numbers, containing (in base-10), 1 .. 9, and not 0 are sometimes permitted.

Additionally, some uses of pandigital numbers require that there be no repeated digits. In such a case, the base-2 number 01 would be pandigital, whereas 101 would not.

Math::Pandigital provides a class that can be instantiated in any base, from 1 through 10, or 16 (hex), and can be used to detect pandigital numbers. It may also be configured to accept repeated digits, or to reject them, and to require the 'zero' digit, or to reject it.

EXPORTS

No exports.

SUBROUTINES AND METHODS

new

my $p = Math::Pandigital->new;

Constructs a Math::Pandigital test object. If no parameters are passed, the tests will assume base ten, requiring a "zero", and permitting repeated digits.

Optional constructor parameters

Any (or all) of the following parameters may optionally be used to configure the test object.

base

my $p = Math::Pandigital->new( base => 16 );

Set's the base to any value from 1 to 10, or 16. If the goal is to detect pandigitality of a binary number, select base = 2>, for example. If not specified, the default is base ten. Common options are 2 (binary), 8 (octal), 10 (decimal), and 16 (hex), though 1 is permitted (unary), as is any value between one and ten, inclusive.

For base-16 tests, the digits A .. F will be tested case-insensitively.

unique

my $p = Math::Pandigital->new( unique => 1 );

A Boolean flag used to set whether or not the pandigital number may contain repeated digits. For example, in base 2, with unique set, there are only two pandigital numbers: 01, and 10. With unique unset (the default), any binary number of any length is permitted so long as it has at least one zero, and one one. The default is the traditional definition of a pandigital number: repeated digits allowed.

zero

my $p = Math::Pandigital->new( zero => 1 );

A Boolean flag. The default is true. When set (or the default accepted), the pandigital number must include a zero. When unset, the pandigital number may not include a zero.

my $p = Math::Pandigital->new( base => 4, zero => 0, unique => 1 );

The preceeding test would allow the following numbers to match: 123, 231, 213, 321, 312, and 132. It would reject any number with a zero, or more (or less) than three digits.

is_pandigital

$p->is_pandigital($n);

$n may be any string. If the string contains only numeric digits that match the criteria set forth when the test object is constructed, true is returned. If the string contains any digits that aren't part of the base, or if it fails to contain all necessary digits, or if it violates the uniqueness setting (if set), it will return false.

Beware the possible traps and pitfalls. Perl sees 0123456789 as 123456789, which may not be what you were expecting. If there's a possibility of a significant leadign zero, be sure to pass a string of digits rather than a number. is_pandigital will silently stringify its target before testing, but if an integer with a leading '0' is passed as a parameter, the damage is done before is_pandigital gets a chance to stringify it.

Another issue to consider: Pass hex as a string of hex digits, not as its native 0xNNNNNNNNNNNNNNNN representation. This is for two reasons. First, a 16-digit hex number corresponds to 1.84467440737E+19, which loses significant digits if passed numerically. Second, we're simply not doing any conversions; internally the string of digits is treated just as that, a string of digits.

This is true of any base system. It just works out better that way.

Remember that hex will be treated case-insensitively.

CAVEATS & WARNINGS

While any length of string of digits is permitted, there is no silver bullet; the computational complexity of the is_pandigital() test is linear in the worst case. In the best case, because length tests are carried out first, any digit strings that violate the length requirements will be rejected in constant time, without falling through to subsequent linear-time tests.

Math::Pandigital's test suite is currently at 99.0% coverage.

CONFIGURATION AND ENVIRONMENT

No special considerations.

DEPENDENCIES

Perl 5.6.2, and Any::Moose are required. Any::Moose will utilize either Mouse, or Moose depending on your system and application's configuration.

INCOMPATIBILITIES

No known incompatibilities.

SEE ALSO

http://en.wikipedia.org/wiki/Pandigital_number

AUTHOR

David Oswald <davido at cpan dot org>

DIAGNOSTICS

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Math::Pandigital

This module is maintained in a public repo at Github. You may look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2012 David Oswald.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.