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)