2.3 Headings of Sage Library Code Files

r"""
<Very short 1-line summary>

<Paragraph description>
...

AUTHORS: 
    -- YOUR NAME (2005-01-03): initial version
    -- person (date in ISO year-month-day format): short desc
     ... 
    -- person (date in ISO year-month-day format): short desc

 ...

Lots and lots of examples.
"""

#*****************************************************************************
#       Copyright (C) 2008 YOUR NAME <your email>
#
#  Distributed under the terms of the GNU General Public License (GPL)
#                  http://www.gnu.org/licenses/
#*****************************************************************************

r"""
Elements of the ring $\Z$ of integers

AUTHORS:
    -- William Stein (2005): initial version
    -- Gonzalo Tornaria (2006-03-02): vastly improved python/GMP
                                   conversion; hashing
    -- Didier Deshommes <dfdeshom@gmail.com> (2006-03-06): numerous
                                   examples and docstrings
    -- William Stein (2006-03-31): changes to reflect GMP bug fixes
    -- William Stein (2006-04-14): added GMP factorial method (since it's
                                   now very fast).
    -- David Harvey (2006-09-15): added nth_root, exact_log
    -- David Harvey (2006-09-16): attempt to optimise Integer constructor
    -- Rishikesh (2007-02-25): changed quo_rem so that the rem is positive
    -- David Harvey, Martin Albrecht, Robert Bradshaw (2007-03-01):
                                   optimized Integer constructor and
                                   pool
    -- Pablo De Napoli (2007-04-01): multiplicative_order should
                                   return +infinity for non zero
                                   numbers
    -- Robert Bradshaw (2007-04-12): is_perfect_power, Jacobi symbol
                                   (with Kronecker extension). Convert
                                   some methods to use GMP directly
                                   rather than pari, Integer() ->
                                   PY_NEW(Integer)
    -- David Roe (2007-03-21): sped up valuation and is_square, added
                                   val_unit, is_power, is_power_of and
                                   divide_knowing_divisible_by
    -- Robert Bradshaw (2008-03-26): gamma function, multifactorials

EXAMPLES:
   Add 2 integers:
       sage: a = Integer(3) ; b = Integer(4)
       sage: a + b == 7
       True

   Add an integer and a real number:
       sage: a + 4.0
       7.00000000000000

   Add an integer and a rational number:
       sage: a + Rational(2)/5
       17/5

   Add an integer and a complex number:
       sage: b = ComplexField().0 + 1.5
       sage: loads((a+b).dumps()) == a+b
       True

   sage: z = 32
   sage: -z
   -32
   sage: z = 0; -z
   0
   sage: z = -0; -z
   0
   sage: z = -1; -z
   1

Multiplication:
    sage: a = Integer(3) ; b = Integer(4)
    sage: a * b == 12
    True
    sage: loads((a * 4.0).dumps()) == a*b
    True
    sage: a * Rational(2)/5
    6/5

    sage: list([2,3]) * 4
    [2, 3, 2, 3, 2, 3, 2, 3]

    sage: 'sage'*Integer(3)
    'sagesagesage'

COERCIONS:
    Returns version of this integer in the multi-precision floating
    real field R.

    sage: n = 9390823
    sage: RR = RealField(200)
    sage: RR(n)
    9.3908230000000000000000000000000000000000000000000000000000e6

"""
#*****************************************************************************
#       Copyright (C) 2004,2006 William Stein <wstein@gmail.com>
#       Copyright (C) 2006 Gonzalo Tornaria <tornaria@math.utexas.edu>
#       Copyright (C) 2006 Didier Deshommes <dfdeshom@gmail.com>
#       Copyright (C) 2007 David Harvey <dmharvey@math.harvard.edu>
#       Copyright (C) 2007 Martin Albrecht <malb@informatik.uni-bremen.de>
#       Copyright (C) 2007,2008 Robert Bradshaw <robertwb@math.washington.edu>
#       Copyright (C) 2007 David Roe <roed314@gmail.com>
#
#  Distributed under the terms of the GNU General Public License (GPL)
#                  http://www.gnu.org/licenses/
#*****************************************************************************