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.

SEE ALSO
    http://mathforum.org/dr.math/faq/faq.pascal.triangle.html

    http://mathworld.wolfram.com/TriangularNumber.html

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

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
    Copyright 2005 by David Christensen <dpchrist@holgerdanske.com>

    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.