/Doc/library/fractions.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 114 lines · 81 code · 33 blank · 0 comment · 0 complexity · f27c65c81f22850a667c6fe1d5cdc138 MD5 · raw file

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