Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 1 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 2 | :mod:`fractions` --- Rational numbers |
Christian Heimes | 0bd4e11 | 2008-02-12 22:59:25 +0000 | [diff] [blame^] | 3 | ===================================== |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 4 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 5 | .. module:: fractions |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 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 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 12 | The :mod:`fractions` module defines an immutable, infinite-precision |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 13 | Rational number class. |
| 14 | |
| 15 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 16 | .. class:: Fraction(numerator=0, denominator=1) |
| 17 | Fraction(other_fraction) |
| 18 | Fraction(string) |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 19 | |
| 20 | The first version requires that *numerator* and *denominator* are |
| 21 | instances of :class:`numbers.Integral` and returns a new |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 22 | ``Fraction`` representing ``numerator/denominator``. If |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 23 | *denominator* is :const:`0`, raises a :exc:`ZeroDivisionError`. The |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 24 | second version requires that *other_fraction* is an instance of |
| 25 | :class:`numbers.Fraction` and returns an instance of |
Christian Heimes | 587c2bf | 2008-01-19 16:21:02 +0000 | [diff] [blame] | 26 | :class:`Rational` with the same value. The third version expects a |
| 27 | string of the form ``[-+]?[0-9]+(/[0-9]+)?``, optionally surrounded |
| 28 | by spaces. |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 29 | |
| 30 | Implements all of the methods and operations from |
Christian Heimes | 587c2bf | 2008-01-19 16:21:02 +0000 | [diff] [blame] | 31 | :class:`numbers.Rational` and is immutable and hashable. |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 32 | |
| 33 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 34 | .. method:: Fraction.from_float(flt) |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 35 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 36 | This classmethod constructs a :class:`Fraction` representing the |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 37 | exact value of *flt*, which must be a :class:`float`. Beware that |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 38 | ``Fraction.from_float(0.3)`` is not the same value as ``Rational(3, |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 39 | 10)`` |
| 40 | |
| 41 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 42 | .. method:: Fraction.from_decimal(dec) |
Christian Heimes | 587c2bf | 2008-01-19 16:21:02 +0000 | [diff] [blame] | 43 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 44 | This classmethod constructs a :class:`Fraction` representing the |
Christian Heimes | 587c2bf | 2008-01-19 16:21:02 +0000 | [diff] [blame] | 45 | exact value of *dec*, which must be a |
| 46 | :class:`decimal.Decimal`. |
| 47 | |
| 48 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 49 | .. method:: Fraction.__floor__() |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 50 | |
| 51 | Returns the greatest :class:`int` ``<= self``. Will be accessible |
| 52 | through :func:`math.floor` in Py3k. |
| 53 | |
| 54 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 55 | .. method:: Fraction.__ceil__() |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 56 | |
| 57 | Returns the least :class:`int` ``>= self``. Will be accessible |
| 58 | through :func:`math.ceil` in Py3k. |
| 59 | |
| 60 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 61 | .. method:: Fraction.__round__() |
| 62 | Fraction.__round__(ndigits) |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 63 | |
| 64 | The first version returns the nearest :class:`int` to ``self``, |
| 65 | rounding half to even. The second version rounds ``self`` to the |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 66 | nearest multiple of ``Fraction(1, 10**ndigits)`` (logically, if |
Guido van Rossum | 7736b5b | 2008-01-15 21:44:53 +0000 | [diff] [blame] | 67 | ``ndigits`` is negative), again rounding half toward even. Will be |
| 68 | accessible through :func:`round` in Py3k. |
| 69 | |
| 70 | |
| 71 | .. seealso:: |
| 72 | |
| 73 | Module :mod:`numbers` |
| 74 | The abstract base classes making up the numeric tower. |
| 75 | |