Author: mark.dickinson Date: Fri Jun 27 18:49:27 2008 New Revision: 64561 Log: Issue #3197: rework documentation for fractions module. Modified: python/trunk/Doc/library/fractions.rst Modified: python/trunk/Doc/library/fractions.rst ============================================================================== --- python/trunk/Doc/library/fractions.rst (original) +++ python/trunk/Doc/library/fractions.rst Fri Jun 27 18:49:27 2008 @@ -9,38 +9,74 @@ .. versionadded:: 2.6 -The :mod:`fractions` module defines an immutable, infinite-precision -Fraction number class. +The :mod:`fractions` module provides support for rational number arithmetic. +A Fraction instance can be constructed from a pair of integers, from +another rational number, or from a string. + .. class:: Fraction(numerator=0, denominator=1) Fraction(other_fraction) Fraction(string) The first version requires that *numerator* and *denominator* are instances of :class:`numbers.Integral` and returns a new - ``Fraction`` representing ``numerator/denominator``. If - *denominator* is :const:`0`, raises a :exc:`ZeroDivisionError`. The - second version requires that *other_fraction* is an instance of - :class:`numbers.Rational` and returns an instance of - :class:`Fraction` with the same value. The third version expects a - string of the form ``[-+]?[0-9]+(/[0-9]+)?``, optionally surrounded - by spaces. - - Implements all of the methods and operations from - :class:`numbers.Rational` and is immutable and hashable. + :class:`Fraction` instance with value ``numerator/denominator``. If + *denominator* is :const:`0`, it raises a + :exc:`ZeroDivisionError`. The second version requires that + *other_fraction* is an instance of :class:`numbers.Rational` and + returns an :class:`Fraction` instance with the same value. The + last version of the constructor expects a string or unicode + instance in one of two possible forms. The first form is:: + + [sign] numerator ['/' denominator] + + where the optional ``sign`` may be either '+' or '-' and + ``numerator`` and ``denominator`` (if present) are strings of + decimal digits. The second permitted form is that of a number + containing a decimal point:: + + [sign] integer '.' [fraction] | [sign] '.' fraction + + where ``integer`` and ``fraction`` are strings of digits. In + either form the input string may also have leading and/or trailing + whitespace. Here are some examples:: + + >>> from fractions import Fraction + >>> Fraction(16, -10) + Fraction(-8, 5) + >>> Fraction(123) + Fraction(123, 1) + >>> Fraction() + Fraction(0, 1) + >>> Fraction('3/7') + Fraction(3, 7) + [40794 refs] + >>> Fraction(' -3/7 ') + Fraction(-3, 7) + >>> Fraction('1.414213 \t\n') + Fraction(1414213, 1000000) + >>> Fraction('-.125') + Fraction(-1, 8) + + + The :class:`Fraction` class inherits from the abstract base class + :class:`numbers.Rational`, and implements all of the methods and + operations from that class. :class:`Fraction` instances are hashable, + and should be treated as immutable. In addition, + :class:`Fraction` has the following methods: .. method:: from_float(flt) - This classmethod constructs a :class:`Fraction` representing the exact + This class method constructs a :class:`Fraction` representing the exact value of *flt*, which must be a :class:`float`. Beware that ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)`` .. method:: from_decimal(dec) - This classmethod constructs a :class:`Fraction` representing the exact + This class method constructs a :class:`Fraction` representing the exact value of *dec*, which must be a :class:`decimal.Decimal`. @@ -52,34 +88,24 @@ >>> from fractions import Fraction >>> Fraction('3.1415926535897932').limit_denominator(1000) - Fraction(355L, 113L) + Fraction(355, 113) or for recovering a rational number that's represented as a float: >>> from math import pi, cos >>> Fraction.from_float(cos(pi/3)) - Fraction(4503599627370497L, 9007199254740992L) + Fraction(4503599627370497, 9007199254740992) >>> Fraction.from_float(cos(pi/3)).limit_denominator() - Fraction(1L, 2L) - - - .. method:: __floor__() - - Returns the greatest :class:`int` ``<= self``. - - - .. method:: __ceil__() - - Returns the least :class:`int` ``>= self``. + Fraction(1, 2) - .. method:: __round__() - __round__(ndigits) +.. function:: gcd(a, b) - The first version returns the nearest :class:`int` to ``self``, rounding - half to even. The second version rounds ``self`` to the nearest multiple - of ``Fraction(1, 10**ndigits)`` (logically, if ``ndigits`` is negative), - again rounding half toward even. + Return the greatest common divisor of the integers `a` and `b`. If + either `a` or `b` is nonzero, then the absolute value of `gcd(a, + b)` is the largest integer that divides both `a` and `b`. `gcd(a,b)` + has the same sign as `b` if `b` is nonzero; otherwise it takes the sign + of `a`. `gcd(0, 0)` returns `0`. .. seealso::