mirror of
https://github.com/python/cpython.git
synced 2025-10-31 13:41:24 +00:00
36ab1ef8ee
svn+ssh://pythondev@svn.python.org/python/trunk ........ r68219 | georg.brandl | 2009-01-03 21:47:01 +0100 (Sat, 03 Jan 2009) | 2 lines Fix uses of the default role. ........
139 lines
4.7 KiB
ReStructuredText
139 lines
4.7 KiB
ReStructuredText
|
|
:mod:`fractions` --- Rational numbers
|
|
=====================================
|
|
|
|
.. module:: fractions
|
|
:synopsis: Rational numbers.
|
|
.. moduleauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
|
|
.. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
|
|
|
|
|
|
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
|
|
: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
|
|
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 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 class method constructs a :class:`Fraction` representing the exact
|
|
value of *dec*, which must be a :class:`decimal.Decimal` instance.
|
|
|
|
|
|
.. method:: limit_denominator(max_denominator=1000000)
|
|
|
|
Finds and returns the closest :class:`Fraction` to ``self`` that has
|
|
denominator at most max_denominator. This method is useful for finding
|
|
rational approximations to a given floating-point number:
|
|
|
|
>>> from fractions import Fraction
|
|
>>> Fraction('3.1415926535897932').limit_denominator(1000)
|
|
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(4503599627370497, 9007199254740992)
|
|
>>> Fraction.from_float(cos(pi/3)).limit_denominator()
|
|
Fraction(1, 2)
|
|
|
|
|
|
.. method:: __floor__()
|
|
|
|
Returns the greatest :class:`int` ``<= self``. This method can
|
|
also be accessed through the :func:`math.floor` function:
|
|
|
|
>>> from math import floor
|
|
>>> floor(Fraction(355, 113))
|
|
3
|
|
|
|
|
|
.. method:: __ceil__()
|
|
|
|
Returns the least :class:`int` ``>= self``. This method can
|
|
also be accessed through the :func:`math.ceil` function.
|
|
|
|
|
|
.. method:: __round__()
|
|
__round__(ndigits)
|
|
|
|
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. This
|
|
method can also be accessed through the :func:`round` function.
|
|
|
|
|
|
.. function:: gcd(a, b)
|
|
|
|
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::
|
|
|
|
Module :mod:`numbers`
|
|
The abstract base classes making up the numeric tower.
|