/ 
Test2-Tools-Numeric-0.01_01
River stage zero No dependents
/ Test2::Tools::Numeric

NAME

Test2::Tools::Numeric - Test functions for common numeric tests

VERSION

Version 0.01_01

SYNOPSIS

use Test2::Tools::Numeric;

my @array = get_widgets();
is_even( scalar @a, '@array must have an even number of widgets' );

WHY TEST2::TOOLS::NUMERIC?

Test2::Tools::Numeric is designed to make your code more readable, based on the idea that reading English is easier and less prone to misinterpretation than reading Perl, and less prone to error by reducing common cut & paste tasks.

Conside either of these two tests:

ok( $x % 2 == 0 );
is( $x % 2, 0 );

What are they doing? They're testing that $x is an even number. It's a common expression that most programmers can easily identify. Most any programmer will see that and think "Aha, it's testing to see if it's an even number."

Better still to make it explicitly clear, in English, what you're trying to accomplish:

is_even( $x );

Test2::Tools::Numeric also does more stringent checking than the common quick tests that we put in. These tests will all pass. You probably don't want them to.

for my $x ( undef, 'foo', {}, [] ) {
    ok( $x % 2 == 0 );
}

Here's another one that will pass, albeit with warnings, even though it's undoubtedly a mistake:

my %hash = ( foo => 1, bar => 2, bat => 3 );
cmp_ok( %hash, '>', 0 );

Why does it pass? Because the stringification of that hash is "3/8" and in a numeric context that becomes 3.

Test2::Tools::Numeric is based on the idea that the reader should be able to tell as much from English as possible without having to decipher code, and to have extra safety checks that you might not consider.

EXPORT

All functions in this module are exported by default.

NUMERIC SUBROUTINES

is_number( $n [, $name ] )

Tests that $n is what Perl considers to be a number.

is_integer( $n [, $name ] )

Tests if $n is an integer.

The following are integers:

1
-1
+1
0E0
9E14
-9E14

The following are not:

string representations of integers
1.
1.0
'abc'
''
undef
Any reference

cmp_integer_ok( $got, $op, $expected [, $name ] )

Tests that both $got and $expected are valid integers, and match the comparator $op.

This is a strengthened version of cmp_ok. With normal cmp_ok, you can get back unexpected values that still match, such as:

cmp_ok( '',    '==', 0 );       # Passes
cmp_ok( undef, '==', 0 );       # Passes
cmp_ok( 'abc', '==', 0 );       # Passes
cmp_ok( 'abc', '==', 'xyz' );   # Passes

These will all throw various warnings if the warnings pragma is on, but the tests will still pass.

cmp_integer_ok is more stringent and will catch accidental passes.

cmp_integer_ok( '',    '==', 0 );   # Fails
cmp_integer_ok( undef, '==', 0 );   # Fails

It also checks that your comparator is valid.

cmp_integer_ok( 0,     'eq', 0 );   # Fails because 'eq' isn't valid for integers

is_positive_integer( $n [, $name ] )

Verifies that $n is an integer, and greater than zero.

is_nonnegative_integer( $n [, $name ] )

Verifies that $n is an integer, and greater than or equal to zero.

is_even( $n [, $name ] )

Checks whether the number $n is an integer and is divisible by two.

is_odd( $n [, $name ] )

Checks whether the number $n is an integer and is not divisible by two.

AUTHOR

Andy Lester, <andy at petdance.com>

BUGS

Please report any bugs or feature requests to bug-test2-tools-numeric at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test2-Tools-Numeric. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

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

perldoc Test2::Tools::Numeric

You can also look for information at:

ACKNOWLEDGEMENTS

None yet.

LICENSE AND COPYRIGHT

Copyright 2016 Andy Lester.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0).