#!/usr/bin/python -tt
#=======================================================================
#                        General Documentation

"""Single-function module.

   See function docstring for description.
"""

#-----------------------------------------------------------------------
#                       Additional Documentation
#
# RCS Revision Code:
#   $Id: lindgen.py,v 1.1 2004/03/17 00:51:34 jlin Exp $
#
# Modification History:
# - 16 Mar 2004:  Original by Johnny Lin, Computation Institute,
#   University of Chicago.  Passed passably reasonable tests.
#
# Notes:
# - Written for Python 2.2.2.
# - Module docstrings can be tested using the doctest module.  To
#   test, execute "python lindgen.py".
# - See import statements throughout for packages/modules required.
#
# Copyright (c) 2004 by Johnny Lin.  For licensing, distribution 
# conditions, contact information, and additional documentation see
# the URL http://www.johnny-lin.com/py_pkgs/gemath/doc/.
#=======================================================================




#----------------------- Overall Module Imports ------------------------

#- Set module information to package information, as applicable:

import gemath_version
__version__ = gemath_version.version
__author__  = gemath_version.author
__date__    = gemath_version.date
__credits__ = gemath_version.credits
del gemath_version




#--------------------------- General Function --------------------------

def lindgen(shape):
    """Create an Int array of shape filled with 1-D indices.

    Output is a long integer Numeric array with shape given by 
    argument shape, where the elements of the array are filled with 
    the values of the 1-D indices that would be given in a Numeric.
    ravel()ed version of the array.  This function is similar in 
    purpose to the IDL LINDGEN function.
    
    Positional Input Argument:
    * shape:   If is 1-D tuple of integers, argument specifies the 
      shape of the output array.  If argument shape is a scalar, the
      output array is a 1-D vector with argument shape number of
      elements.

    Examples:
    >>> from lindgen import lindgen
    >>> array = lindgen(5)
    >>> ['%.2g' % array[i] for i in range(len(array))]
    ['0', '1', '2', '3', '4']
    >>> array.shape
    (5,)
    >>> array.typecode()
    'l'

    >>> array = lindgen((3,4))
    >>> ['%.2g' % array[0,i] for i in range(4)]
    ['0', '1', '2', '3']
    >>> ['%.2g' % array[1,i] for i in range(4)]
    ['4', '5', '6', '7']
    >>> ['%.2g' % array[2,i] for i in range(4)]
    ['8', '9', '10', '11']
    >>> array.shape
    (3, 4)
    """
    import Numeric as N

    if type(shape) != type(()):  shape_use = (shape,)
    else:  shape_use = shape

    tot_nelem = N.product(N.array(shape_use))
    tmp = N.arange(tot_nelem, typecode=N.Int)
    
    return N.reshape(tmp, shape_use)




#-------------------------- Main:  Test Module -------------------------

#- Define additional examples for doctest to use:

__test__ = { 'Additional Examples':
    """
    >>> from lindgen import lindgen
    >>> array = lindgen(5,4)
    Traceback (most recent call last):
        ...
    TypeError: lindgen() takes exactly 1 argument (2 given)

    >>> import Numeric as N
    >>> array = lindgen((3,4,2))
    >>> print N.sum(N.ravel(array) == N.arange(24))
    24
    """ }


#- Execute doctest if module is run from command line:

if __name__ == "__main__":
    """Test the module.

    Tests the examples in all the module documentation 
    strings, plus __test__.

    Note:  To help ensure that module testing of this file works, the
    parent directory to the current directory is added to sys.path.
    """
    import doctest, sys, os
    sys.path.append(os.pardir)
    doctest.testmod(sys.modules[__name__])




# ===== end file =====