NAME
    Math::TriangularNumbers - Perl extension for Triangular numbers.

    Version 0.03

SYNOPSIS
      use Math::TriangularNumbers qw(T Ti is_T);
  
      ##### prints Triangular numbers "1, 3, 6, 10, 15, 21"
      print STDERR join(", ",T(1),T(2),T(3),T(4),T(5),T(6)), "\n";

      ##### prints right Triangular indices "1, 2, 2, 3, 3, 3":
      print STDERR join(", ",Ti(1),Ti(2),Ti(3),Ti(4),Ti(5),Ti(6)), "\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
        T(5) = 15
        T(6) = 21
        etc.

    These are 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
            1       6      15      20      15       6       1
        1       7      21      35      35      21       7       1

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

    This module implements the function T(n), given by the above equation,
    and it's "right inverse", T'(N), given by:

            T'(N) = int( (1 + sqrt(1 + 8*(N-1))) / 2 )

    E.g. Given an integer N which is not necessarily a Triangular Number,
    find n such that T(n-1) < N <= T(n).

    I have extended the definition of a Triangular number to include zero
    and negative indices and integers.

  EXPORT
    None by default.

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

   Ti($N)
    Returns right Triangular index of $N. Croaks if passed a non-integer
    argument. Note that Ti(0) = 0, and Ti(-$T) = -Ti($T).

   is_T($N)
    Returns true if $N is a Triangular number, if $N is zero, or if -$N is 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.