← Back to branch summary

~malept/ubuntu/lucid/python2.6/dev-dependency-fix

« back to all changes in this revision

Viewing changes to Doc/library/fractions.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-02-13 12:51:00 UTC
  • Revision ID: james.westby@ubuntu.com-20090213125100-uufgcb9yeqzujpqw
Tags: upstream-2.6.1
Import upstream version 2.6.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/fractions.rst
 
1
 
 
2
:mod:`fractions` --- Rational numbers
 
3
=====================================
 
4
 
 
5
.. module:: fractions
 
6
   :synopsis: Rational numbers.
 
7
.. moduleauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
 
8
.. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
 
9
.. versionadded:: 2.6
 
10
 
 
11
 
 
12
The :mod:`fractions` module provides support for rational number arithmetic.
 
13
 
 
14
 
 
15
A Fraction instance can be constructed from a pair of integers, from
 
16
another rational number, or from a string.
 
17
 
 
18
.. class:: Fraction(numerator=0, denominator=1)
 
19
           Fraction(other_fraction)
 
20
           Fraction(string)
 
21
 
 
22
   The first version requires that *numerator* and *denominator* are
 
23
   instances of :class:`numbers.Integral` and returns a new
 
24
   :class:`Fraction` instance with value ``numerator/denominator``. If
 
25
   *denominator* is :const:`0`, it raises a
 
26
   :exc:`ZeroDivisionError`. The second version requires that
 
27
   *other_fraction* is an instance of :class:`numbers.Rational` and
 
28
   returns an :class:`Fraction` instance with the same value.  The
 
29
   last version of the constructor expects a string or unicode
 
30
   instance in one of two possible forms.  The first form is::
 
31
 
 
32
      [sign] numerator ['/' denominator]
 
33
 
 
34
   where the optional ``sign`` may be either '+' or '-' and
 
35
   ``numerator`` and ``denominator`` (if present) are strings of
 
36
   decimal digits.  The second permitted form is that of a number
 
37
   containing a decimal point::
 
38
 
 
39
      [sign] integer '.' [fraction] | [sign] '.' fraction
 
40
 
 
41
   where ``integer`` and ``fraction`` are strings of digits.  In
 
42
   either form the input string may also have leading and/or trailing
 
43
   whitespace.  Here are some examples::
 
44
 
 
45
      >>> from fractions import Fraction
 
46
      >>> Fraction(16, -10)
 
47
      Fraction(-8, 5)
 
48
      >>> Fraction(123)
 
49
      Fraction(123, 1)
 
50
      >>> Fraction()
 
51
      Fraction(0, 1)
 
52
      >>> Fraction('3/7')
 
53
      Fraction(3, 7)
 
54
      [40794 refs]
 
55
      >>> Fraction(' -3/7 ')
 
56
      Fraction(-3, 7)
 
57
      >>> Fraction('1.414213 \t\n')
 
58
      Fraction(1414213, 1000000)
 
59
      >>> Fraction('-.125')
 
60
      Fraction(-1, 8)
 
61
 
 
62
 
 
63
   The :class:`Fraction` class inherits from the abstract base class
 
64
   :class:`numbers.Rational`, and implements all of the methods and
 
65
   operations from that class.  :class:`Fraction` instances are hashable,
 
66
   and should be treated as immutable.  In addition,
 
67
   :class:`Fraction` has the following methods:
 
68
 
 
69
 
 
70
   .. method:: from_float(flt)
 
71
 
 
72
      This class method constructs a :class:`Fraction` representing the exact
 
73
      value of *flt*, which must be a :class:`float`. Beware that
 
74
      ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``
 
75
 
 
76
 
 
77
   .. method:: from_decimal(dec)
 
78
 
 
79
      This class method constructs a :class:`Fraction` representing the exact
 
80
      value of *dec*, which must be a :class:`decimal.Decimal`.
 
81
 
 
82
 
 
83
   .. method:: limit_denominator(max_denominator=1000000)
 
84
 
 
85
      Finds and returns the closest :class:`Fraction` to ``self`` that has
 
86
      denominator at most max_denominator.  This method is useful for finding
 
87
      rational approximations to a given floating-point number:
 
88
 
 
89
         >>> from fractions import Fraction
 
90
         >>> Fraction('3.1415926535897932').limit_denominator(1000)
 
91
         Fraction(355, 113)
 
92
 
 
93
      or for recovering a rational number that's represented as a float:
 
94
 
 
95
         >>> from math import pi, cos
 
96
         >>> Fraction.from_float(cos(pi/3))
 
97
         Fraction(4503599627370497, 9007199254740992)
 
98
         >>> Fraction.from_float(cos(pi/3)).limit_denominator()
 
99
         Fraction(1, 2)
 
100
 
 
101
 
 
102
.. function:: gcd(a, b)
 
103
 
 
104
   Return the greatest common divisor of the integers `a` and `b`.  If
 
105
   either `a` or `b` is nonzero, then the absolute value of `gcd(a,
 
106
   b)` is the largest integer that divides both `a` and `b`.  `gcd(a,b)`
 
107
   has the same sign as `b` if `b` is nonzero; otherwise it takes the sign
 
108
   of `a`.  `gcd(0, 0)` returns `0`.
 
109
 
 
110
 
 
111
.. seealso::
 
112
 
 
113
   Module :mod:`numbers`
 
114
      The abstract base classes making up the numeric tower.