Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(39)

## Side by Side Diff: Lib/_pydecimal.py

Issue 27779: Sync-up docstrings in C version of the the decimal module
Patch Set: Created 3 years, 1 month ago
 Left: Base Patch Set 1: None Patch Set 2: None Right: Patch Set 1: None Patch Set 2: None
« no previous file with comments | « no previous file | Modules/_decimal/docstrings.h » ('j') | no next file with comments »
OLDNEW
1 # Copyright (c) 2004 Python Software Foundation. 1 # Copyright (c) 2004 Python Software Foundation.
3 3
4 # Written by Eric Price <eprice at tjhsst.edu> 4 # Written by Eric Price <eprice at tjhsst.edu>
5 # and Facundo Batista <facundo at taniquetil.com.ar> 5 # and Facundo Batista <facundo at taniquetil.com.ar>
6 # and Raymond Hettinger <python at rcn.com> 6 # and Raymond Hettinger <python at rcn.com>
7 # and Aahz <aahz at pobox.com> 7 # and Aahz <aahz at pobox.com>
8 # and Tim Peters 8 # and Tim Peters
9 9
10 # This module should be kept in sync with the latest updates of the 10 # This module should be kept in sync with the latest updates of the
(...skipping 506 matching lines...)
517 ctx.prec += 2 517 ctx.prec += 2
518 # Rest of sin calculation algorithm 518 # Rest of sin calculation algorithm
519 # uses a precision 2 greater than normal 519 # uses a precision 2 greater than normal
520 return +s # Convert result to normal precision 520 return +s # Convert result to normal precision
521 521
522 def sin(x): 522 def sin(x):
523 with localcontext(ExtendedContext): 523 with localcontext(ExtendedContext):
524 # Rest of sin calculation algorithm 524 # Rest of sin calculation algorithm
525 # uses the Extended Context from the 525 # uses the Extended Context from the
526 # General Decimal Arithmetic Specification 526 # General Decimal Arithmetic Specification
527 return +s # Convert result to normal context
528
529 >>> setcontext(DefaultContext)
530 >>> print(getcontext().prec) # Return a context manager for a copy of the su pplied context
531
532 Uses a copy of the current context if no context is specified
533 The returned context manager creates a local decimal context
534 in a with statement:
535 def sin(x):
536 with localcontext() as ctx:
537 ctx.prec += 2
538 # Rest of sin calculation algorithm
539 # uses a precision 2 greater than normal
540 return +s # Convert result to normal precision
541
542 def sin(x):
543 with localcontext(ExtendedContext):
544 # Rest of sin calculation algorithm
545 # uses the Extended Context from the
546 # General Decimal Arithmetic Specification
527 return +s # Convert result to normal context 547 return +s # Convert result to normal context
528 548
529 >>> setcontext(DefaultContext) 549 >>> setcontext(DefaultContext)
530 >>> print(getcontext().prec) 550 >>> print(getcontext().prec)
531 28 551 28
532 >>> with localcontext(): 552 >>> with localcontext():
533 ... ctx = getcontext() 553 ... ctx = getcontext()
534 ... ctx.prec += 2 554 ... ctx.prec += 2
535 ... print(ctx.prec) 555 ... print(ctx.prec)
536 ... 556 ...
537 30 557 30
538 >>> with localcontext(ExtendedContext): 558 >>> with localcontext(ExtendedContext):
539 ... print(getcontext().prec) 559 ... print(getcontext().prec)
540 ... 560 ...
561 9
562 >>> print(getcontext().prec)
563 28
564 28
565 >>> with localcontext():
566 ... ctx = getcontext()
567 ... ctx.prec += 2
568 ... print(ctx.prec)
569 ...
570 30
571 >>> with localcontext(ExtendedContext):
572 ... print(getcontext().prec)
573 ...
541 9 574 9
542 >>> print(getcontext().prec) 575 >>> print(getcontext().prec)
543 28 576 28
544 """ 577 """
545 if ctx is None: ctx = getcontext() 578 if ctx is None: ctx = getcontext()
546 return _ContextManager(ctx) 579 return _ContextManager(ctx)
547 580
548 581
549 ##### Decimal class ####################################################### 582 ##### Decimal class #######################################################
550 583
(...skipping 14 matching lines...) Expand all
565 """Create a decimal point instance. 598 """Create a decimal point instance.
566 599
567 >>> Decimal('3.14') # string input 600 >>> Decimal('3.14') # string input
568 Decimal('3.14') 601 Decimal('3.14')
569 >>> Decimal((0, (3, 1, 4), -2)) # tuple (sign, digit_tuple, exponent) 602 >>> Decimal((0, (3, 1, 4), -2)) # tuple (sign, digit_tuple, exponent)
570 Decimal('3.14') 603 Decimal('3.14')
571 >>> Decimal(314) # int 604 >>> Decimal(314) # int
572 Decimal('314') 605 Decimal('314')
573 >>> Decimal(Decimal(314)) # another decimal instance 606 >>> Decimal(Decimal(314)) # another decimal instance
574 Decimal('314') 607 Decimal('314')
575 >>> Decimal(' 3.14 \\n') # leading and trailing whitespace okay 608 >>> Decimal(' 3.14 \\n') # leading and trailing whitespace okay
576 Decimal('3.14') 609 Decimal('3.14')
577 """ 610 """
578 611
579 # Note that the coefficient, self._int, is actually stored as 612 # Note that the coefficient, self._int, is actually stored as
580 # a string rather than as a tuple of digits. This speeds up 613 # a string rather than as a tuple of digits. This speeds up
581 # the "digits to integer" and "integer to digits" conversions 614 # the "digits to integer" and "integer to digits" conversions
582 # that are used in almost every arithmetic operation on 615 # that are used in almost every arithmetic operation on
583 # Decimals. This is an internal detail: the as_tuple function 616 # Decimals. This is an internal detail: the as_tuple function
584 # and the Decimal constructor still deal with tuples of 617 # and the Decimal constructor still deal with tuples of
585 # digits. 618 # digits.
(...skipping 411 matching lines...)
997 1030
998 if self._exp >= 0: 1031 if self._exp >= 0:
999 exp_hash = pow(10, self._exp, _PyHASH_MODULUS) 1032 exp_hash = pow(10, self._exp, _PyHASH_MODULUS)
1000 else: 1033 else:
1001 exp_hash = pow(_PyHASH_10INV, -self._exp, _PyHASH_MODULUS) 1034 exp_hash = pow(_PyHASH_10INV, -self._exp, _PyHASH_MODULUS)
1002 hash_ = int(self._int) * exp_hash % _PyHASH_MODULUS 1035 hash_ = int(self._int) * exp_hash % _PyHASH_MODULUS
1003 ans = hash_ if self >= 0 else -hash_ 1036 ans = hash_ if self >= 0 else -hash_
1004 return -2 if ans == -1 else ans 1037 return -2 if ans == -1 else ans
1005 1038
1006 def as_tuple(self): 1039 def as_tuple(self):
1007 """Represents the number as a triple tuple. 1040 """Represents the number as a triple tuple, to show the internals
1008 1041 exactly as they are.
1009 To show the internals exactly as they are.
1010 """ 1042 """
1011 return DecimalTuple(self._sign, tuple(map(int, self._int)), self._exp) 1043 return DecimalTuple(self._sign, tuple(map(int, self._int)), self._exp)
1012 1044
1013 def as_integer_ratio(self): 1045 def as_integer_ratio(self):
1014 """Express a finite Decimal instance in the form n / d. 1046 """Express a finite Decimal instance in the form n / d.
1015 1047
1016 Returns a pair (n, d) of integers. When called on an infinity 1048 Return a pair (n, d) of integers, whose ratio is exactly equal to the
1017 or NaN, raises OverflowError or ValueError respectively. 1049 original Decimal and with a positive denominator. The ratio is in
1050 lowest terms. Raise OverflowError on infinities and a ValueError
1051 on NaNs.
1018 1052
1019 >>> Decimal('3.14').as_integer_ratio() 1053 >>> Decimal('3.14').as_integer_ratio()
1020 (157, 50) 1054 (157, 50)
1021 >>> Decimal('-123e5').as_integer_ratio() 1055 >>> Decimal('-123e5').as_integer_ratio()
1022 (-12300000, 1) 1056 (-12300000, 1)
1023 >>> Decimal('0.00').as_integer_ratio() 1057 >>> Decimal('0.00').as_integer_ratio()
1024 (0, 1) 1058 (0, 1)
1025 1059
1026 """ 1060 """
1027 if self._is_special: 1061 if self._is_special:
(...skipping 1907 matching lines...)
2935 rest = self._int[self._exp:] 2969 rest = self._int[self._exp:]
2936 return rest == '0'*len(rest) 2970 return rest == '0'*len(rest)
2937 2971
2938 def _iseven(self): 2972 def _iseven(self):
2939 """Returns True if self is even. Assumes self is an integer.""" 2973 """Returns True if self is even. Assumes self is an integer."""
2940 if not self or self._exp > 0: 2974 if not self or self._exp > 0:
2941 return True 2975 return True
2942 return self._int[-1+self._exp] in '02468' 2976 return self._int[-1+self._exp] in '02468'
2943 2977
2945 """Return the adjusted exponent of self""" 2979 """Return the adjusted exponent of self.
2980
2981 Defined as exp + digits - 1.
2982 """
2946 try: 2983 try:
2947 return self._exp + len(self._int) - 1 2984 return self._exp + len(self._int) - 1
2948 # If NaN or Infinity, self._exp is string 2985 # If NaN or Infinity, self._exp is string
2949 except TypeError: 2986 except TypeError:
2950 return 0 2987 return 0
2951 2988
2952 def canonical(self): 2989 def canonical(self):
2953 """Returns the same Decimal object. 2990 """Return the canonical encoding of the argument.
2954 2991
2955 As we do not have different encodings for the same number, the 2992 Currently, the encoding of a Decimal instance is always canonical,
2956 received object already is in its canonical form. 2993 so this operation returns its argument unchanged.
2957 """ 2994 """
2958 return self 2995 return self
2959 2996
2960 def compare_signal(self, other, context=None): 2997 def compare_signal(self, other, context=None):
2961 """Compares self to the other operand numerically. 2998 """Compares self to the other operand numerically.
2962 2999
2963 It's pretty much like compare(), but all NaNs signal, with signaling 3000 It's pretty much like compare(), but all NaNs signal, with signaling
2964 NaNs taking precedence over quiet NaNs. 3001 NaNs taking precedence over quiet NaNs.
2965 """ 3002 """
2966 other = _convert_other(other, raiseit = True) 3003 other = _convert_other(other, raiseit = True)
(...skipping 120 matching lines...)
3087 3124
3088 # exp(0) = 1 3125 # exp(0) = 1
3089 if not self: 3126 if not self:
3090 return _One 3127 return _One
3091 3128
3092 # exp(Infinity) = Infinity 3129 # exp(Infinity) = Infinity
3093 if self._isinfinity() == 1: 3130 if self._isinfinity() == 1:
3094 return Decimal(self) 3131 return Decimal(self)
3095 3132
3096 # the result is now guaranteed to be inexact (the true 3133 # the result is now guaranteed to be inexact (the true
3097 # mathematical result is transcendental). There's no need to 3134 # mathematical is transcendental). There's no need to
3098 # raise Rounded and Inexact here---they'll always be raised as 3135 # raise Rounded and Inexact here---they'll always be raised as
3099 # a result of the call to _fix. 3136 # a result of the call to _fix.
3100 p = context.prec 3137 p = context.prec
3102 3139
3103 # we only need to do any computation for quite a small range 3140 # we only need to do any computation for quite a small range
3104 # of adjusted exponents---for example, -29 <= adj <= 10 for 3141 # of adjusted exponents---for example, -29 <= adj <= 10 for
3105 # the default context. For smaller exponent the result is 3142 # the default context. For smaller exponent the result is
3106 # indistinguishable from 1 at the given precision, while for 3143 # indistinguishable from 1 at the given precision, while for
3107 # larger exponent the result either overflows or underflows. 3144 # larger exponent the result either overflows or underflows.
(...skipping 1119 matching lines...)
4227 If the signs of the operands differ, a value representing each operand 4264 If the signs of the operands differ, a value representing each operand
4228 ('-1' if the operand is less than zero, '0' if the operand is zero or 4265 ('-1' if the operand is less than zero, '0' if the operand is zero or
4229 negative zero, or '1' if the operand is greater than zero) is used in 4266 negative zero, or '1' if the operand is greater than zero) is used in
4230 place of that operand for the comparison instead of the actual 4267 place of that operand for the comparison instead of the actual
4231 operand. 4268 operand.
4232 4269
4233 The comparison is then effected by subtracting the second operand from 4270 The comparison is then effected by subtracting the second operand from
4234 the first and then returning a value according to the result of the 4271 the first and then returning a value according to the result of the
4235 subtraction: '-1' if the result is less than zero, '0' if the result is 4272 subtraction: '-1' if the result is less than zero, '0' if the result is
4236 zero or negative zero, or '1' if the result is greater than zero. 4273 zero or negative zero, or '1' if the result is greater than zero.
4274
4275 a or b is a NaN ==> Decimal('NaN')
4276 a < b ==> Decimal('-1')
4277 a == b ==> Decimal('0')
4278 a > b ==> Decimal('1')
4237 4279
4238 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('3')) 4280 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('3'))
4239 Decimal('-1') 4281 Decimal('-1')
4240 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1')) 4282 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1'))
4241 Decimal('0') 4283 Decimal('0')
4242 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.10')) 4284 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.10'))
4243 Decimal('0') 4285 Decimal('0')
4244 >>> ExtendedContext.compare(Decimal('3'), Decimal('2.1')) 4286 >>> ExtendedContext.compare(Decimal('3'), Decimal('2.1'))
4245 Decimal('1') 4287 Decimal('1')
4246 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('-3')) 4288 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('-3'))
4247 Decimal('1') 4289 Decimal('1')
4248 >>> ExtendedContext.compare(Decimal('-3'), Decimal('2.1')) 4290 >>> ExtendedContext.compare(Decimal('-3'), Decimal('2.1'))
4249 Decimal('-1') 4291 Decimal('-1')
4250 >>> ExtendedContext.compare(1, 2) 4292 >>> ExtendedContext.compare(1, 2)
4251 Decimal('-1') 4293 Decimal('-1')
4252 >>> ExtendedContext.compare(Decimal(1), 2) 4294 >>> ExtendedContext.compare(Decimal(1), 2)
4253 Decimal('-1') 4295 Decimal('-1')
4254 >>> ExtendedContext.compare(1, Decimal(2)) 4296 >>> ExtendedContext.compare(1, Decimal(2))
4255 Decimal('-1') 4297 Decimal('-1')
4298 >>> ExtendedContext.compare(Decimal('2'), Decimal('NaN'))
4299 Decimal('NaN')
4256 """ 4300 """
4257 a = _convert_other(a, raiseit=True) 4301 a = _convert_other(a, raiseit=True)
4258 return a.compare(b, context=self) 4302 return a.compare(b, context=self)
4259 4303
4260 def compare_signal(self, a, b): 4304 def compare_signal(self, a, b):
4261 """Compares the values of the two operands numerically. 4305 """Compares the values of the two operands numerically.
4262 4306
4263 It's pretty much like compare(), but all NaNs signal, with signaling 4307 It's pretty much like compare(), but all NaNs signal, with signaling
4264 NaNs taking precedence over quiet NaNs. 4308 NaNs taking precedence over quiet NaNs.
4265 4309
4266 >>> c = ExtendedContext 4310 >>> ExtendedContext.compare_signal(Decimal('2.1'), Decimal('3'))
4267 >>> c.compare_signal(Decimal('2.1'), Decimal('3'))
4268 Decimal('-1') 4311 Decimal('-1')
4269 >>> c.compare_signal(Decimal('2.1'), Decimal('2.1')) 4312 >>> ExtendedContext.compare_signal(Decimal('2.1'), Decimal('2.1'))
4270 Decimal('0') 4313 Decimal('0')
4271 >>> c.flags[InvalidOperation] = 0 4314 >>> ExtendedContext.flags[InvalidOperation] = 0
4272 >>> print(c.flags[InvalidOperation]) 4315 >>> print(ExtendedContext.flags[InvalidOperation])
4273 0 4316 0
4274 >>> c.compare_signal(Decimal('NaN'), Decimal('2.1')) 4317 >>> ExtendedContext.compare_signal(Decimal('NaN'), Decimal('2.1'))
4275 Decimal('NaN') 4318 Decimal('NaN')
4276 >>> print(c.flags[InvalidOperation]) 4319 >>> print(ExtendedContext.flags[InvalidOperation])
4277 1 4320 1
4278 >>> c.flags[InvalidOperation] = 0 4321 >>> ExtendedContext.flags[InvalidOperation] = 0
4279 >>> print(c.flags[InvalidOperation]) 4322 >>> print(ExtendedContext.flags[InvalidOperation])
4280 0 4323 0
4281 >>> c.compare_signal(Decimal('sNaN'), Decimal('2.1')) 4324 >>> ExtendedContext.compare_signal(Decimal('sNaN'), Decimal('2.1'))
4282 Decimal('NaN') 4325 Decimal('NaN')
4283 >>> print(c.flags[InvalidOperation]) 4326 >>> print(ExtendedContext.flags[InvalidOperation])
4284 1 4327 1
4285 >>> c.compare_signal(-1, 2) 4328 >>> ExtendedContext.compare_signal(-1, 2)
4286 Decimal('-1') 4329 Decimal('-1')
4287 >>> c.compare_signal(Decimal(-1), 2) 4330 >>> ExtendedContext.compare_signal(Decimal(-1), 2)
4288 Decimal('-1') 4331 Decimal('-1')
4289 >>> c.compare_signal(-1, Decimal(2)) 4332 >>> ExtendedContext.compare_signal(-1, Decimal(2))
4290 Decimal('-1') 4333 Decimal('-1')
4291 """ 4334 """
4292 a = _convert_other(a, raiseit=True) 4335 a = _convert_other(a, raiseit=True)
4293 return a.compare_signal(b, context=self) 4336 return a.compare_signal(b, context=self)
4294 4337
4295 def compare_total(self, a, b): 4338 def compare_total(self, a, b):
4296 """Compares two operands using their abstract representation. 4339 """Compares two operands using their abstract representation rather
4340 than their numerical value.
4297 4341
4298 This is not like the standard compare, which use their numerical 4342 Similar to the compare() method, but the result gives a total ordering
4299 value. Note that a total ordering is defined for all possible abstract 4343 on Decimal instances.
4300 representations. 4344
4345 Quiet and signaling NaNs are also included in the total ordering.
4346 The result of this function is Decimal('0') if both operands have the
4347 same representation, Decimal('-1') if the first operand is lower in
4348 the total order than the second, and Decimal('1') if the first
4349 operand is higher in the total order than the second operand. See
4350 the specification for details of the total order.
4351
4352 This operation is unaffected by context and is quiet: no flags are
4353 changed and no rounding is performed.
4301 4354
4302 >>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9')) 4355 >>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9'))
4303 Decimal('-1') 4356 Decimal('-1')
4304 >>> ExtendedContext.compare_total(Decimal('-127'), Decimal('12')) 4357 >>> ExtendedContext.compare_total(Decimal('-127'), Decimal('12'))
4305 Decimal('-1') 4358 Decimal('-1')
4306 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.3')) 4359 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.3'))
4307 Decimal('-1') 4360 Decimal('-1')
4308 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.30')) 4361 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.30'))
4309 Decimal('0') 4362 Decimal('0')
4310 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('12.300')) 4363 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('12.300'))
4311 Decimal('1') 4364 Decimal('1')
4312 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('NaN')) 4365 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('NaN'))
4313 Decimal('-1') 4366 Decimal('-1')
4314 >>> ExtendedContext.compare_total(1, 2) 4367 >>> ExtendedContext.compare_total(1, 2)
4315 Decimal('-1') 4368 Decimal('-1')
4316 >>> ExtendedContext.compare_total(Decimal(1), 2) 4369 >>> ExtendedContext.compare_total(Decimal(1), 2)
4317 Decimal('-1') 4370 Decimal('-1')
4318 >>> ExtendedContext.compare_total(1, Decimal(2)) 4371 >>> ExtendedContext.compare_total(1, Decimal(2))
4319 Decimal('-1') 4372 Decimal('-1')
4320 """ 4373 """
4321 a = _convert_other(a, raiseit=True) 4374 a = _convert_other(a, raiseit=True)
4322 return a.compare_total(b) 4375 return a.compare_total(b)
4323 4376
4324 def compare_total_mag(self, a, b): 4377 def compare_total_mag(self, a, b):
4325 """Compares two operands using their abstract representation ignoring si gn. 4378 """Compares two operands using their abstract representation rather
4379 than their numerical value and with their sign ignored.
4326 4380
4327 Like compare_total, but with operand's sign ignored and assumed to be 0. 4381 Like compare_total, but with operand's sign ignored and assumed to be
4382 0.
4383
4384 x.compare_total_mag(y) is equivalent to x.copy_abs().compare_total(y.co py_abs())
4385 This operation is unaffected by context and is quiet: no flags are
4386 changed and no rounding is performed.
4328 """ 4387 """
4329 a = _convert_other(a, raiseit=True) 4388 a = _convert_other(a, raiseit=True)
4330 return a.compare_total_mag(b) 4389 return a.compare_total_mag(b)
4331 4390
4332 def copy_abs(self, a): 4391 def copy_abs(self, a):
4333 """Returns a copy of the operand with the sign set to 0. 4392 """Returns a copy of the operand with the sign set to 0.
4334 4393
4335 >>> ExtendedContext.copy_abs(Decimal('2.1')) 4394 >>> ExtendedContext.copy_abs(Decimal('2.1'))
4336 Decimal('2.1') 4395 Decimal('2.1')
4337 >>> ExtendedContext.copy_abs(Decimal('-100')) 4396 >>> ExtendedContext.copy_abs(Decimal('-100'))
(...skipping 24 matching lines...) Expand all
4362 Decimal('-101.5') 4421 Decimal('-101.5')
4363 >>> ExtendedContext.copy_negate(Decimal('-101.5')) 4422 >>> ExtendedContext.copy_negate(Decimal('-101.5'))
4364 Decimal('101.5') 4423 Decimal('101.5')
4365 >>> ExtendedContext.copy_negate(1) 4424 >>> ExtendedContext.copy_negate(1)
4366 Decimal('-1') 4425 Decimal('-1')
4367 """ 4426 """
4368 a = _convert_other(a, raiseit=True) 4427 a = _convert_other(a, raiseit=True)
4369 return a.copy_negate() 4428 return a.copy_negate()
4370 4429
4371 def copy_sign(self, a, b): 4430 def copy_sign(self, a, b):
4372 """Copies the second operand's sign to the first one. 4431 """Returns a copy of the first operand with the sign equal to the second
4373 4432 operand.
4374 In detail, it returns a copy of the first operand with the sign
4375 equal to the sign of the second operand.
4376 4433
4377 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33')) 4434 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33'))
4378 Decimal('1.50') 4435 Decimal('1.50')
4379 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('7.33')) 4436 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('7.33'))
4380 Decimal('1.50') 4437 Decimal('1.50')
4381 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('-7.33')) 4438 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('-7.33'))
4382 Decimal('-1.50') 4439 Decimal('-1.50')
4383 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('-7.33')) 4440 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('-7.33'))
4384 Decimal('-1.50') 4441 Decimal('-1.50')
4385 >>> ExtendedContext.copy_sign(1, -2) 4442 >>> ExtendedContext.copy_sign(1, -2)
4386 Decimal('-1') 4443 Decimal('-1')
4387 >>> ExtendedContext.copy_sign(Decimal(1), -2) 4444 >>> ExtendedContext.copy_sign(Decimal(1), -2)
4388 Decimal('-1') 4445 Decimal('-1')
4389 >>> ExtendedContext.copy_sign(1, Decimal(-2)) 4446 >>> ExtendedContext.copy_sign(1, Decimal(-2))
4390 Decimal('-1') 4447 Decimal('-1')
4448
4449 This operation is unaffected by context and is quiet: no flags are
4450 changed and no rounding is performed.
4391 """ 4451 """
4392 a = _convert_other(a, raiseit=True) 4452 a = _convert_other(a, raiseit=True)
4393 return a.copy_sign(b) 4453 return a.copy_sign(b)
4394 4454
4395 def divide(self, a, b): 4455 def divide(self, a, b):
4396 """Decimal division in a specified context. 4456 """Decimal division in a specified context.
4397 4457
4398 >>> ExtendedContext.divide(Decimal('1'), Decimal('3')) 4458 >>> ExtendedContext.divide(Decimal('1'), Decimal('3'))
4399 Decimal('0.333333333') 4459 Decimal('0.333333333')
4400 >>> ExtendedContext.divide(Decimal('2'), Decimal('3')) 4460 >>> ExtendedContext.divide(Decimal('2'), Decimal('3'))
(...skipping 66 matching lines...)
4467 (Decimal('2'), Decimal('0')) 4527 (Decimal('2'), Decimal('0'))
4468 """ 4528 """
4469 a = _convert_other(a, raiseit=True) 4529 a = _convert_other(a, raiseit=True)
4470 r = a.__divmod__(b, context=self) 4530 r = a.__divmod__(b, context=self)
4471 if r is NotImplemented: 4531 if r is NotImplemented:
4472 raise TypeError("Unable to convert %s to Decimal" % b) 4532 raise TypeError("Unable to convert %s to Decimal" % b)
4473 else: 4533 else:
4474 return r 4534 return r
4475 4535
4476 def exp(self, a): 4536 def exp(self, a):
4477 """Returns e ** a. 4537 """Return the value of the (natural) exponential function e ** a.
4538 The function always uses the ROUND_HALF_EVEN mode and the result
4539 is correctly rounded.
4478 4540
4479 >>> c = ExtendedContext.copy() 4541 >>> c = ExtendedContext.copy()
4480 >>> c.Emin = -999 4542 >>> c.Emin = -999
4481 >>> c.Emax = 999 4543 >>> c.Emax = 999
4482 >>> c.exp(Decimal('-Infinity')) 4544 >>> c.exp(Decimal('-Infinity'))
4483 Decimal('0') 4545 Decimal('0')
4484 >>> c.exp(Decimal('-1')) 4546 >>> c.exp(Decimal('-1'))
4485 Decimal('0.367879441') 4547 Decimal('0.367879441')
4486 >>> c.exp(Decimal('0')) 4548 >>> c.exp(Decimal('0'))
4487 Decimal('1') 4549 Decimal('1')
4488 >>> c.exp(Decimal('1')) 4550 >>> c.exp(Decimal('1'))
4489 Decimal('2.71828183') 4551 Decimal('2.71828183')
4490 >>> c.exp(Decimal('0.693147181')) 4552 >>> c.exp(Decimal('0.693147181'))
4491 Decimal('2.00000000') 4553 Decimal('2.00000000')
4492 >>> c.exp(Decimal('+Infinity')) 4554 >>> c.exp(Decimal('+Infinity'))
4493 Decimal('Infinity') 4555 Decimal('Infinity')
4494 >>> c.exp(10) 4556 >>> c.exp(10)
4495 Decimal('22026.4658') 4557 Decimal('22026.4658')
4496 """ 4558 """
4497 a =_convert_other(a, raiseit=True) 4559 a =_convert_other(a, raiseit=True)
4498 return a.exp(context=self) 4560 return a.exp(context=self)
4499 4561
4500 def fma(self, a, b, c): 4562 def fma(self, a, b, c):
4501 """Returns a multiplied by b, plus c. 4563 """Returns a multiplied by b, plus c.
4502 4564
4503 The first two operands are multiplied together, using multiply, 4565 Fused multiple-add. The first two operands are multiplied together,
4504 the third operand is then added to the result of that 4566 using multiply, the third operand is then added to the result of that
4505 multiplication, using add, all with only one final rounding. 4567 multiplication, using add, all with only one final rounding.
4506 4568
4507 >>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7')) 4569 >>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7'))
4508 Decimal('22') 4570 Decimal('22')
4509 >>> ExtendedContext.fma(Decimal('3'), Decimal('-5'), Decimal('7')) 4571 >>> ExtendedContext.fma(Decimal('3'), Decimal('-5'), Decimal('7'))
4510 Decimal('-8') 4572 Decimal('-8')
4511 >>> ExtendedContext.fma(Decimal('888565290'), Decimal('1557.96930'), Dec imal('-86087.7578')) 4573 >>> ExtendedContext.fma(Decimal('888565290'), Decimal('1557.96930'), Dec imal('-86087.7578'))
4512 Decimal('1.38435736E+12') 4574 Decimal('1.38435736E+12')
4513 >>> ExtendedContext.fma(1, 3, 4) 4575 >>> ExtendedContext.fma(1, 3, 4)
4514 Decimal('7') 4576 Decimal('7')
(...skipping 49 matching lines...)
4564 True 4626 True
4565 >>> ExtendedContext.is_infinite(Decimal('NaN')) 4627 >>> ExtendedContext.is_infinite(Decimal('NaN'))
4566 False 4628 False
4567 >>> ExtendedContext.is_infinite(1) 4629 >>> ExtendedContext.is_infinite(1)
4568 False 4630 False
4569 """ 4631 """
4570 a = _convert_other(a, raiseit=True) 4632 a = _convert_other(a, raiseit=True)
4571 return a.is_infinite() 4633 return a.is_infinite()
4572 4634
4573 def is_nan(self, a): 4635 def is_nan(self, a):
4574 """Return True if the operand is a qNaN or sNaN; 4636 """Return True if the operand is a (quiet or signaling) NaN or NaN;
4575 otherwise return False. 4637 otherwise return False.
4576 4638
4577 >>> ExtendedContext.is_nan(Decimal('2.50')) 4639 >>> ExtendedContext.is_nan(Decimal('2.50'))
4578 False 4640 False
4579 >>> ExtendedContext.is_nan(Decimal('NaN')) 4641 >>> ExtendedContext.is_nan(Decimal('NaN'))
4580 True 4642 True
4581 >>> ExtendedContext.is_nan(Decimal('-sNaN')) 4643 >>> ExtendedContext.is_nan(Decimal('-sNaN'))
4582 True 4644 True
4583 >>> ExtendedContext.is_nan(1) 4645 >>> ExtendedContext.is_nan(1)
4584 False 4646 False
(...skipping 34 matching lines...)
4619 >>> ExtendedContext.is_qnan(Decimal('sNaN')) 4681 >>> ExtendedContext.is_qnan(Decimal('sNaN'))
4620 False 4682 False
4621 >>> ExtendedContext.is_qnan(1) 4683 >>> ExtendedContext.is_qnan(1)
4622 False 4684 False
4623 """ 4685 """
4624 a = _convert_other(a, raiseit=True) 4686 a = _convert_other(a, raiseit=True)
4625 return a.is_qnan() 4687 return a.is_qnan()
4626 4688
4627 def is_signed(self, a): 4689 def is_signed(self, a):
4628 """Return True if the operand is negative; otherwise return False. 4690 """Return True if the operand is negative; otherwise return False.
4691
4692 Note that both zeros and NaNs can carry signs.
4629 4693
4630 >>> ExtendedContext.is_signed(Decimal('2.50')) 4694 >>> ExtendedContext.is_signed(Decimal('2.50'))
4631 False 4695 False
4632 >>> ExtendedContext.is_signed(Decimal('-12')) 4696 >>> ExtendedContext.is_signed(Decimal('-12'))
4633 True 4697 True
4634 >>> ExtendedContext.is_signed(Decimal('-0')) 4698 >>> ExtendedContext.is_signed(Decimal('-0'))
4635 True 4699 True
4636 >>> ExtendedContext.is_signed(8) 4700 >>> ExtendedContext.is_signed(8)
4637 False 4701 False
4638 >>> ExtendedContext.is_signed(-8) 4702 >>> ExtendedContext.is_signed(-8)
(...skipping 13 matching lines...) Expand all
4652 >>> ExtendedContext.is_snan(Decimal('sNaN')) 4716 >>> ExtendedContext.is_snan(Decimal('sNaN'))
4653 True 4717 True
4654 >>> ExtendedContext.is_snan(1) 4718 >>> ExtendedContext.is_snan(1)
4655 False 4719 False
4656 """ 4720 """
4657 a = _convert_other(a, raiseit=True) 4721 a = _convert_other(a, raiseit=True)
4658 return a.is_snan() 4722 return a.is_snan()
4659 4723
4660 def is_subnormal(self, a): 4724 def is_subnormal(self, a):
4661 """Return True if the operand is subnormal; otherwise return False. 4725 """Return True if the operand is subnormal; otherwise return False.
4726
4727 A number is subnormal if it is non-zero, finite, and has an adjusted
4728 exponent less than Emin.
4662 4729
4663 >>> c = ExtendedContext.copy() 4730 >>> c = ExtendedContext.copy()
4664 >>> c.Emin = -999 4731 >>> c.Emin = -999
4665 >>> c.Emax = 999 4732 >>> c.Emax = 999
4666 >>> c.is_subnormal(Decimal('2.50')) 4733 >>> c.is_subnormal(Decimal('2.50'))
4667 False 4734 False
4668 >>> c.is_subnormal(Decimal('0.1E-999')) 4735 >>> c.is_subnormal(Decimal('0.1E-999'))
4669 True 4736 True
4670 >>> c.is_subnormal(Decimal('0.00')) 4737 >>> c.is_subnormal(Decimal('0.00'))
4671 False 4738 False
(...skipping 19 matching lines...) Expand all
4691 >>> ExtendedContext.is_zero(1) 4758 >>> ExtendedContext.is_zero(1)
4692 False 4759 False
4693 >>> ExtendedContext.is_zero(0) 4760 >>> ExtendedContext.is_zero(0)
4694 True 4761 True
4695 """ 4762 """
4696 a = _convert_other(a, raiseit=True) 4763 a = _convert_other(a, raiseit=True)
4697 return a.is_zero() 4764 return a.is_zero()
4698 4765
4699 def ln(self, a): 4766 def ln(self, a):
4700 """Returns the natural (base e) logarithm of the operand. 4767 """Returns the natural (base e) logarithm of the operand.
4768
4769 The function always uses the ROUND_HALF_EVEN mode and the result is
4770 correctly rounded.
4701 4771
4702 >>> c = ExtendedContext.copy() 4772 >>> c = ExtendedContext.copy()
4703 >>> c.Emin = -999 4773 >>> c.Emin = -999
4704 >>> c.Emax = 999 4774 >>> c.Emax = 999
4705 >>> c.ln(Decimal('0')) 4775 >>> c.ln(Decimal('0'))
4706 Decimal('-Infinity') 4776 Decimal('-Infinity')
4707 >>> c.ln(Decimal('1.000')) 4777 >>> c.ln(Decimal('1.000'))
4708 Decimal('0') 4778 Decimal('0')
4709 >>> c.ln(Decimal('2.71828183')) 4779 >>> c.ln(Decimal('2.71828183'))
4710 Decimal('1.00000000') 4780 Decimal('1.00000000')
4711 >>> c.ln(Decimal('10')) 4781 >>> c.ln(Decimal('10'))
4712 Decimal('2.30258509') 4782 Decimal('2.30258509')
4713 >>> c.ln(Decimal('+Infinity')) 4783 >>> c.ln(Decimal('+Infinity'))
4714 Decimal('Infinity') 4784 Decimal('Infinity')
4715 >>> c.ln(1) 4785 >>> c.ln(1)
4716 Decimal('0') 4786 Decimal('0')
4717 """ 4787 """
4718 a = _convert_other(a, raiseit=True) 4788 a = _convert_other(a, raiseit=True)
4719 return a.ln(context=self) 4789 return a.ln(context=self)
4720 4790
4721 def log10(self, a): 4791 def log10(self, a):
4722 """Returns the base 10 logarithm of the operand. 4792 """Returns the base 10 logarithm of the operand.
4793
4794 The function always uses the ROUND_HALF_EVEN mode and the result
4795 is correctly rounded.
4723 4796
4724 >>> c = ExtendedContext.copy() 4797 >>> c = ExtendedContext.copy()
4725 >>> c.Emin = -999 4798 >>> c.Emin = -999
4726 >>> c.Emax = 999 4799 >>> c.Emax = 999
4727 >>> c.log10(Decimal('0')) 4800 >>> c.log10(Decimal('0'))
4728 Decimal('-Infinity') 4801 Decimal('-Infinity')
4729 >>> c.log10(Decimal('0.001')) 4802 >>> c.log10(Decimal('0.001'))
4730 Decimal('-3') 4803 Decimal('-3')
4731 >>> c.log10(Decimal('1.000')) 4804 >>> c.log10(Decimal('1.000'))
4732 Decimal('0') 4805 Decimal('0')
4733 >>> c.log10(Decimal('2')) 4806 >>> c.log10(Decimal('2'))
4734 Decimal('0.301029996') 4807 Decimal('0.301029996')
4735 >>> c.log10(Decimal('10')) 4808 >>> c.log10(Decimal('10'))
4736 Decimal('1') 4809 Decimal('1')
4737 >>> c.log10(Decimal('70')) 4810 >>> c.log10(Decimal('70'))
4738 Decimal('1.84509804') 4811 Decimal('1.84509804')
4739 >>> c.log10(Decimal('+Infinity')) 4812 >>> c.log10(Decimal('+Infinity'))
4740 Decimal('Infinity') 4813 Decimal('Infinity')
4741 >>> c.log10(0) 4814 >>> c.log10(0)
4742 Decimal('-Infinity') 4815 Decimal('-Infinity')
4743 >>> c.log10(1) 4816 >>> c.log10(1)
4744 Decimal('0') 4817 Decimal('0')
4745 """ 4818 """
4746 a = _convert_other(a, raiseit=True) 4819 a = _convert_other(a, raiseit=True)
4747 return a.log10(context=self) 4820 return a.log10(context=self)
4748 4821
4749 def logb(self, a): 4822 def logb(self, a):
4750 """ Returns the exponent of the magnitude of the operand's MSD. 4823 """Returns the exponent of the magnitude of the operand's MSD.
4751 4824
4752 The result is the integer which is the exponent of the magnitude 4825 The result is the integer which is the exponent of the magnitude
4753 of the most significant digit of the operand (as though the 4826 of the most significant digit of the operand (as though the
4754 operand were truncated to a single digit while maintaining the 4827 operand were truncated to a single digit while maintaining the
4755 value of that digit and without limiting the resulting exponent). 4828 value of that digit and without limiting the resulting exponent).
4756 4829
4757 >>> ExtendedContext.logb(Decimal('250')) 4830 >>> ExtendedContext.logb(Decimal('250'))
4758 Decimal('2') 4831 Decimal('2')
4759 >>> ExtendedContext.logb(Decimal('2.50')) 4832 >>> ExtendedContext.logb(Decimal('2.50'))
4760 Decimal('0') 4833 Decimal('0')
(...skipping 546 matching lines...)
5307 Decimal('1') 5380 Decimal('1')
5308 >>> ExtendedContext.quantize(Decimal(1), 2) 5381 >>> ExtendedContext.quantize(Decimal(1), 2)
5309 Decimal('1') 5382 Decimal('1')
5310 >>> ExtendedContext.quantize(1, Decimal(2)) 5383 >>> ExtendedContext.quantize(1, Decimal(2))
5311 Decimal('1') 5384 Decimal('1')
5312 """ 5385 """
5313 a = _convert_other(a, raiseit=True) 5386 a = _convert_other(a, raiseit=True)
5314 return a.quantize(b, context=self) 5387 return a.quantize(b, context=self)
5315 5388
5317 """Just returns 10, as this is Decimal, :) 5390 """Return Decimal(10), the radix (base) in which the Decimal class does
5391 all its arithmetic. Included for compatibility with the specification .
5318 5392
5320 Decimal('10') 5394 Decimal('10')
5321 """ 5395 """
5322 return Decimal(10) 5396 return Decimal(10)
5323 5397
5324 def remainder(self, a, b): 5398 def remainder(self, a, b):
5325 """Returns the remainder from integer division. 5399 """Returns the remainder from integer division.
5326 5400
5327 The result is the residue of the dividend after the operation of 5401 The result is the residue of the dividend after the operation of
(...skipping 1112 matching lines...)
6440 # Constants related to the hash implementation; hash(x) is based 6514 # Constants related to the hash implementation; hash(x) is based
6441 # on the reduction of x modulo _PyHASH_MODULUS 6515 # on the reduction of x modulo _PyHASH_MODULUS
6442 _PyHASH_MODULUS = sys.hash_info.modulus 6516 _PyHASH_MODULUS = sys.hash_info.modulus
6443 # hash values to use for positive and negative infinities, and nans 6517 # hash values to use for positive and negative infinities, and nans
6444 _PyHASH_INF = sys.hash_info.inf 6518 _PyHASH_INF = sys.hash_info.inf
6445 _PyHASH_NAN = sys.hash_info.nan 6519 _PyHASH_NAN = sys.hash_info.nan
6446 6520
6447 # _PyHASH_10INV is the inverse of 10 modulo the prime _PyHASH_MODULUS 6521 # _PyHASH_10INV is the inverse of 10 modulo the prime _PyHASH_MODULUS
6448 _PyHASH_10INV = pow(10, _PyHASH_MODULUS - 2, _PyHASH_MODULUS) 6522 _PyHASH_10INV = pow(10, _PyHASH_MODULUS - 2, _PyHASH_MODULUS)
6449 del sys 6523 del sys
OLDNEW
« no previous file with comments | « no previous file | Modules/_decimal/docstrings.h » ('j') | no next file with comments »

This is Rietveld 894c83f36cb7+