[Python-checkins] python/nondist/sandbox/decimal Decimal.py, 1.33,
1.34
rhettinger at users.sourceforge.net
rhettinger at users.sourceforge.net
Wed Jun 30 15:11:42 EDT 2004
Update of /cvsroot/python/python/nondist/sandbox/decimal
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv30998
Modified Files:
Decimal.py
Log Message:
Part IV: docstrings and doctests
Index: Decimal.py
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/decimal/Decimal.py,v
retrieving revision 1.33
retrieving revision 1.34
diff -C2 -d -r1.33 -r1.34
*** Decimal.py 30 Jun 2004 18:49:07 -0000 1.33
--- Decimal.py 30 Jun 2004 19:11:40 -0000 1.34
***************
*** 212,216 ****
class Clamped(DecimalException):
! """Exponent of a 0 changed to fit bounds"""
--- 212,225 ----
class Clamped(DecimalException):
! """Exponent of a 0 changed to fit bounds.
!
! This occurs and signals clamped if the exponent of a result has been
! altered in order to fit the constraints of a specific concrete
! representation. This may occur when the exponent of a zero result would
! be outside the bounds of a representation, or when a large normal
! number would have an encoded exponent that cannot be represented. In
! this latter case, the exponent is reduced to fit and the corresponding
! number of zero digits are appended to the coefficient ("fold-down").
! """
***************
*** 240,244 ****
class ConversionSyntax(InvalidOperation):
! """Trying to convert badly formed string."""
def handle(self, context, *args):
--- 249,258 ----
class ConversionSyntax(InvalidOperation):
! """Trying to convert badly formed string.
!
! This occurs and signals invalid-operation if an string is being
! converted to a number and it does not conform to the numeric string
! syntax. The result is [0,qNaN].
! """
def handle(self, context, *args):
***************
*** 248,256 ****
"""Division by 0.
! x / 0
! Different from ZeroDivisionError because if the trap is disabled,
! (+-) INF is returned.
! Pass in the sign, and another argument will return a 2-tuple
! (for divmod) instead of the single number.
"""
--- 262,273 ----
"""Division by 0.
! This occurs and signals division-by-zero if division of a finite number
! by zero was attempted (during a divide-integer or divide operation, or a
! power operation with negative right-hand operand), and the dividend was
! not zero.
!
! The result of the operation is [sign,inf], where sign is the exclusive
! or of the signs of the operands for divide, or is 1 for an odd power of
! â0, for power.
"""
***************
*** 263,268 ****
"""Cannot perform the division adequately.
! Result of a divide-integer or remainder option longer than precision
! Not actually raised.
"""
--- 280,286 ----
"""Cannot perform the division adequately.
! This occurs and signals invalid-operation if the integer result of a
! divide-integer or remainder operation had too many digits (would be
! longer than precision). The result is [0,qNaN].
"""
***************
*** 273,283 ****
"""Undefined result of division.
! 0 / 0
! Not a ZeroDivisionError, because it isn't infinity,
! but can be anything.
! If the trap is disabled, returns NaN.
!
! If arguments are passed, it returns a 2-tuple (for divmod) as opposed
! to a single tuple.
"""
--- 291,297 ----
"""Undefined result of division.
! This occurs and signals invalid-operation if division by zero was
! attempted (during a divide-integer, divide, or remainder operation), and
! the dividend is also zero. The result is [0,qNaN].
"""
***************
*** 288,296 ****
class Inexact(DecimalException):
! """Had to round, losing information."""
default = 0
class InvalidContext(InvalidOperation):
! """Invalid context. Unknown rounding, for example."""
def handle(self, context, *args):
--- 302,327 ----
class Inexact(DecimalException):
! """Had to round, losing information.
!
! This occurs and signals inexact whenever the result of an operation is
! not exact (that is, it needed to be rounded and any discarded digits
! were non-zero), or if an overflow or underflow condition occurs. The
! result in all cases is unchanged.
!
! The inexact signal may be tested (or trapped) to determine if a given
! operation (or sequence of operations) was inexact.
! """
default = 0
class InvalidContext(InvalidOperation):
! """Invalid context. Unknown rounding, for example.
!
! This occurs and signals invalid-operation if an invalid context was
! detected during an operation. This can occur if contexts are not checked
! on creation and either the precision exceeds the capability of the
! underlying concrete representation or an unknown or unsupported rounding
! was specified. These aspects of the context need only be checked when
! the values are required to be used. The result is [0,qNaN].
! """
def handle(self, context, *args):
***************
*** 298,325 ****
class Rounded(DecimalException):
! """Number got rounded (not necessarily changed during rounding)"""
default = 0
class Subnormal(DecimalException):
! """Exponent < Emin before rounding"""
pass
class Overflow(Inexact, Rounded):
! """Number overflows
! Rescale with coefficient becoming greater than prec long
! Adjusted exponent greater than Emax
! Power's adjusted exponent above ABSOLUTE_EMAX
! Pass in the sign, and the result is:
! rounding in (half-up, half-even, half-down, up) => signed INF
! Otherwise, if the sign is negative:
! If rounding is floor, return -INF
! otherwise (rounding in (ceiling, down)) return negative number
! with highest absolute value possible (9.999999...eEmin)
! Sign positive:
! rounding = ceiling => INF
! rounding in (floor, down) => maximum finite number (9.9999...eEmax)
! """
def handle(self, context, sign, *args):
--- 329,377 ----
class Rounded(DecimalException):
! """Number got rounded (not necessarily changed during rounding).
!
! This occurs and signals rounded whenever the result of an operation is
! rounded (that is, some zero or non-zero digits were discarded from the
! coefficient), or if an overflow or underflow condition occurs. The
! result in all cases is unchanged.
!
! The rounded signal may be tested (or trapped) to determine if a given
! operation (or sequence of operations) caused a loss of precision.
! """
default = 0
class Subnormal(DecimalException):
! """Exponent < Emin before rounding.
!
! This occurs and signals subnormal whenever the result of a conversion or
! operation is subnormal (that is, its adjusted exponent is less than
! Emin, before any rounding). The result in all cases is unchanged.
!
! The subnormal signal may be tested (or trapped) to determine if a given
! or operation (or sequence of operations) yielded a subnormal result.
! """
pass
class Overflow(Inexact, Rounded):
! """Numerical overflow.
! This occurs and signals overflow if the adjusted exponent of a result
! (from a conversion or from an operation that is not an attempt to divide
! by zero), after rounding, would be greater than the largest value that
! can be handled by the implementation (the value Emax).
! The result depends on the rounding mode:
!
! For round-half-up and round-half-even (and for round-half-down and
! round-up, if implemented), the result of the operation is [sign,inf],
! where sign is the sign of the intermediate result. For round-down, the
! result is the largest finite number that can be represented in the
! current precision, with the sign of the intermediate result. For
! round-ceiling, the result is the same as for round-down if the sign of
! the intermediate result is 1, or is [0,inf] otherwise. For round-floor,
! the result is the same as for round-down if the sign of the intermediate
! result is 0, or is [1,inf] otherwise. In all cases, Inexact and Rounded
! will also be raised.
! """
def handle(self, context, sign, *args):
***************
*** 340,344 ****
class Underflow(Inexact, Rounded, Subnormal):
! """Number too small, got rounded to 0"""
--- 392,408 ----
class Underflow(Inexact, Rounded, Subnormal):
! """Numerical underflow with result rounded to 0.
!
! This occurs and signals underflow if a result is inexact and the
! adjusted exponent of the result would be smaller (more negative) than
! the smallest value that can be handled by the implementation (the value
! Emin). That is, the result is both inexact and subnormal.
!
! The result after an underflow will be a subnormal number rounded, if
! necessary, so that its exponent is not less than Etiny. This may result
! in 0 with the sign of the intermediate result and an exponent of Etiny.
!
! In all cases, Inexact, Rounded, and Subnormal will also be raised.
! """
***************
*** 2412,2415 ****
--- 2476,2525 ----
def power(self, a, b, modulo=None):
+ """Raises a to the power of b, to modulo if given.
+
+ The right-hand operand must be a whole number whose integer part (after
+ any exponent has been applied) has no more than 9 digits and whose
+ fractional part (if any) is all zeros before any rounding. The operand
+ may be positive, negative, or zero; if negative, the absolute value of
+ the power is used, and the left-hand operand is inverted (divided into
+ 1) before use.
+
+ If the increased precision needed for the intermediate calculations
+ exceeds the capabilities of the implementation then an Invalid operation
+ condition is raised.
+
+ If, when raising to a negative power, an underflow occurs during the
+ division into 1, the operation is not halted at that point but
+ continues.
+
+ >>> Context(prec=9).power(Decimal('2'), Decimal('3'))
+ Decimal("8")
+ >>> Context(prec=9).power(Decimal('2'), Decimal('-3'))
+ Decimal("0.125")
+ >>> Context(prec=9).power(Decimal('1.7'), Decimal('8'))
+ Decimal("69.7575744")
+ >>> Context(prec=9).power(Decimal('Infinity'), Decimal('-2'))
+ Decimal("0")
+ >>> Context(prec=9).power(Decimal('Infinity'), Decimal('-1'))
+ Decimal("0")
+ >>> Context(prec=9).power(Decimal('Infinity'), Decimal('0'))
+ Decimal("1")
+ >>> Context(prec=9).power(Decimal('Infinity'), Decimal('1'))
+ Decimal("Infinity")
+ >>> Context(prec=9).power(Decimal('Infinity'), Decimal('2'))
+ Decimal("Infinity")
+ >>> Context(prec=9).power(Decimal('-Infinity'), Decimal('-2'))
+ Decimal("0")
+ >>> Context(prec=9).power(Decimal('-Infinity'), Decimal('-1'))
+ Decimal("-0")
+ >>> Context(prec=9).power(Decimal('-Infinity'), Decimal('0'))
+ Decimal("1")
+ >>> Context(prec=9).power(Decimal('-Infinity'), Decimal('1'))
+ Decimal("-Infinity")
+ >>> Context(prec=9).power(Decimal('-Infinity'), Decimal('2'))
+ Decimal("Infinity")
+ >>> Context(prec=9).power(Decimal('0'), Decimal('0'))
+ Decimal("NaN")
+ """
return a.__pow__(b, modulo, context=self)
***************
*** 2576,2582 ****
--- 2686,2700 ----
def to_eng_string(self, a):
+ """Converts a number to a string, using scientific notation.
+
+ The operation is not affected by the context.
+ """
return a.to_eng_string(context=self)
def to_sci_string(self, a):
+ """Converts a number to a string, using scientific notation.
+
+ The operation is not affected by the context.
+ """
return a.__str__(context=self)
More information about the Python-checkins
mailing list