NAME

Math::TriangularNumbers - Perl extension for Triangular numbers.

Version 0.02

SYNOPSIS

  use Math::TriangularNumbers qw(T Ti is_T);


  ##### prints the first four Triangular numbers "1, 3, 6, 10"
  print STDERR join(", ", T(1), T(2), T(3), T(4)), "\n";

  ##### prints their indices "1, 2, 3, 4":
  print STDERR join(", ", Ti(1), Ti(3), Ti(6), Ti(10)), "\n";


  ##### determines if the number 666 is triangular (it is):
  print STDERR is_T(666) ? "yes\n" : "no\n";

DESCRIPTION

I was using the following function for games:

    T($n) = 1 + 2 + ... + ($n-1) + $n

         = $n * ($n+1) / 2

For example:

    T(1) = 1
    T(2) = 3
    T(3) = 6
    T(4) = 10

I suspected that there must be proper math terminology for the above. So when I wanted to implement it as a Perl module for posting on CPAN, I did some research. Sure enough they're called Triangular numbers, after Pascal's Triangle:

                            1
                        1       1
                    1       2       1
                1       3       3       1
            1       4       6       4       1
        1       5       10      10      5       1

Observe the diagonal numbers starting at the third row: 1, 3, 6, 10.

This module implements the function T(), given by the above equation, and it's inverse, Ti(), given by:

        Ti($T) = $n = (-1 + sqrt(1 + 8*$T)) / 2

Furthermore, I have extended the definition of a Triangular number so that the functions include zero and negative arguments.

EXPORT

None by default.

FUNCTIONS

`T($n)`

Function that returns the $n-th Triangular number. Croaks if passed a non-integer argument. Note that T(0) = 0, and T(-$n) = -T($n).

`Ti($T)`

Function that returns index of the Triangular number equal to or less than $T. Croaks if passed a non-integer argument. Note that Ti(0) = 0, and Ti(-$T) = -Ti($T).

`is_T($x)`

Function that returns true if $x is a Triangular number, if $x is zero, or if $x is the negative of a Triangular number. Otherwise, returns false. Croaks if passed a non-integer argument.

INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

DEPENDENCIES

None.

TO DO

Everything is currently implemented using standard Perl scalars, so large arguments are likely to result in errors due to floating-point limitations.

AUTHOR

David Christensen, <dpchrist@holgerdanske.com>

CREDITS

Rob ``Sisyphus'', for helping me find the correct term ``index'' and for suggesting a function to test if a number is triangular.

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.

Math::TriangularNumbers - Perl extension for Triangular numbers.