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

## Side by Side Diff: Modules/_decimal/docstrings.h

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 | « Lib/_pydecimal.py ('k') | no next file » | no next file with comments »
OLDNEW
1 /* 1 /*
3 * Modified and extended by Stefan Krah. 3 * Modified and extended by Stefan Krah.
4 */ 4 */
5 5
6 6
7 #ifndef DOCSTRINGS_H 7 #ifndef DOCSTRINGS_H
8 #define DOCSTRINGS_H 8 #define DOCSTRINGS_H
9 9
10 10
11 #include "pymacro.h" 11 #include "pymacro.h"
12 12
13 13
14 /******************************************************************************/ 14 /******************************************************************************/
15 /* Module */ 15 /* Module */
16 /******************************************************************************/ 16 /******************************************************************************/
17 17
18 18
19 PyDoc_STRVAR(doc__decimal, 19 PyDoc_STRVAR(doc__decimal,
20 "C decimal arithmetic module"); 20 "This is an implementation of decimal floating point arithmetic based on\n\
21 the General Decimal Arithmetic Specification:\n\
22 \n\
23 http://speleotrove.com/decimal/decarith.html\n\
24 \n\
25 and IEEE standard 854-1987:\n\
26 \n\
27 http://en.wikipedia.org/wiki/IEEE_854-1987\n\
28 \n\
29 Decimal floating point has finite precision with arbitrarily large bounds.\n\
30 \n\
31 The purpose of this module is to support arithmetic using familiar\n\
32 \"schoolhouse\" rules and to avoid some of the tricky representation\n\
33 issues associated with binary floating point. The package is especially\n\
34 useful for financial applications or for contexts where users have\n\
35 expectations that are at odds with binary floating point (for instance,\n\
36 in binary floating point, 1.00 % 0.1 gives 0.09999999999999995 instead\n\
37 of 0.0; Decimal('1.00') % Decimal('0.1') returns the expected\n\
38 Decimal('0.00')).\n\
39 \n\
40 Here are some examples of using the decimal module:\n\
41 \n\
42 >>> from decimal import *\n\
43 >>> setcontext(ExtendedContext)\n\
44 >>> Decimal(0)\n\
45 Decimal('0')\n\
46 >>> Decimal('1')\n\
47 Decimal('1')\n\
48 >>> Decimal('-.0123')\n\
49 Decimal('-0.0123')\n\
50 >>> Decimal(123456)\n\
51 Decimal('123456')\n\
52 >>> Decimal('123.45e12345678')\n\
53 Decimal('1.2345E+12345680')\n\
54 >>> Decimal('1.33') + Decimal('1.27')\n\
55 Decimal('2.60')\n\
56 >>> Decimal('12.34') + Decimal('3.87') - Decimal('18.41')\n\
57 Decimal('-2.20')\n\
58 >>> dig = Decimal(1)\n\
59 >>> print(dig / Decimal(3))\n\
60 0.333333333\n\
61 >>> getcontext().prec = 18\n\
62 >>> print(dig / Decimal(3))\n\
63 0.333333333333333333\n\
64 >>> print(dig.sqrt())\n\
65 1\n\
66 >>> print(Decimal(3).sqrt())\n\
67 1.73205080756887729\n\
68 >>> print(Decimal(3) ** 123)\n\
69 4.85192780976896427E+58\n\
70 >>> inf = Decimal(1) / Decimal(0)\n\
71 >>> print(inf)\n\
72 Infinity\n\
73 >>> neginf = Decimal(-1) / Decimal(0)\n\
74 >>> print(neginf)\n\
75 -Infinity\n\
76 >>> print(neginf + inf)\n\
77 NaN\n\
78 >>> print(neginf * inf)\n\
79 -Infinity\n\
80 >>> print(dig / 0)\n\
81 Infinity\n\
82 >>> getcontext().traps[DivisionByZero] = 1\n\
83 >>> print(dig / 0)\n\
84 Traceback (most recent call last):\n\
85 ...\n\
86 ...\n\
87 ...\n\
88 decimal.DivisionByZero: x / 0\n\
89 >>> c = Context()\n\
90 >>> c.traps[InvalidOperation] = 0\n\
91 >>> print(c.flags[InvalidOperation])\n\
92 0\n\
93 >>> c.divide(Decimal(0), Decimal(0))\n\
94 Decimal('NaN')\n\
95 >>> c.traps[InvalidOperation] = 1\n\
96 >>> print(c.flags[InvalidOperation])\n\
97 1\n\
98 >>> c.flags[InvalidOperation] = 0\n\
99 >>> print(c.flags[InvalidOperation])\n\
100 0\n\
101 >>> print(c.divide(Decimal(0), Decimal(0)))\n\
102 Traceback (most recent call last):\n\
103 ...\n\
104 ...\n\
105 ...\n\
106 decimal.InvalidOperation: 0 / 0\n\
107 >>> print(c.flags[InvalidOperation])\n\
108 1\n\
109 >>> c.flags[InvalidOperation] = 0\n\
110 >>> c.traps[InvalidOperation] = 0\n\
111 >>> print(c.divide(Decimal(0), Decimal(0)))\n\
112 NaN\n\
113 >>> print(c.flags[InvalidOperation])\n\
114 1\n\
115 >>>\n\
116 \n");
21 117
22 PyDoc_STRVAR(doc_getcontext, 118 PyDoc_STRVAR(doc_getcontext,
23 "getcontext(\$module, /)\n--\n\n\ 119 "getcontext(\$module, /)\n--\n\n\
24 Get the current default context.\n\ 120 Returns this thread's context.\n\
121 \n\
122 If this thread does not yet have a context, returns\n\
123 a new context and sets this thread's context.\n\
124 New contexts are copies of DefaultContext.\n\
25 \n"); 125 \n");
26 126
127 /*This seems clearer than the python version*/
27 PyDoc_STRVAR(doc_setcontext, 128 PyDoc_STRVAR(doc_setcontext,
28 "setcontext(\$module, context, /)\n--\n\n\ 129 "setcontext(\$module, context, /)\n--\n\n\
29 Set a new default context.\n\ 130 Set a new default context.\n\
30 \n"); 131 \n");
31 132
32 PyDoc_STRVAR(doc_localcontext, 133 PyDoc_STRVAR(doc_localcontext,
33 "localcontext(\$module, /, ctx=None)\n--\n\n\ 134 "localcontext(\$module, /, ctx=None)\n--\n\n\
34 Return a context manager that will set the default context to a copy of ctx\n\ 135 Return a context manager that will set the default context to a copy of ctx\n\
35 on entry to the with-statement and restore the previous default context when\n\ 136 on entry to the with-statement and restore the previous default context when\n\
36 exiting the with-statement. If no context is specified, a copy of the current\n\ 137 exiting the with-statement. If no context is specified, a copy of the current\n\
37 default context is used.\n\ 138 default context is used.\n\
139 The returned context manager creates a local decimal context\n\
140 in a with statement:\n\
141 def sin(x):\n\
142 with localcontext() as ctx:\n\
143 ctx.prec += 2\n\
144 # Rest of sin calculation algorithm\n\
145 # uses a precision 2 greater than normal\n\
146 return +s # Convert result to normal precision\n\
147 \n\
148 def sin(x):\n\
149 with localcontext(ExtendedContext):\n\
150 # Rest of sin calculation algorithm\n\
151 # uses the Extended Context from the\n\
152 # General Decimal Arithmetic Specification\n\
153 return +s # Convert result to normal context\n\
154 \n\
155 >>> setcontext(DefaultContext)\n\
156 >>> print(getcontext().prec) # Return a context manager for a copy of the su pplied context\n\
157 \n\
158 Uses a copy of the current context if no context is specified.\n\
159 The returned context manager creates a local decimal context\n\
160 in a with statement:\n\
161 def sin(x):\n\
162 with localcontext() as ctx:\n\
163 ctx.prec += 2\n\
164 # Rest of sin calculation algorithm\n\
165 # uses a precision 2 greater than normal\n\
166 return +s # Convert result to normal precision\n\
167 \n\
168 def sin(x):\n\
169 with localcontext(ExtendedContext):\n\
170 # Rest of sin calculation algorithm\n\
171 # uses the Extended Context from the\n\
172 # General Decimal Arithmetic Specification\n\
173 return +s # Convert result to normal context\n\
174 \n\
175 >>> setcontext(DefaultContext)\n\
176 >>> print(getcontext().prec)\n\
177 28\n\
178 >>> with localcontext():\n\
179 ... ctx = getcontext()\n\
180 ... ctx.prec += 2\n\
181 ... print(ctx.prec)\n\
182 ...\n\
183 30\n\
184 >>> with localcontext(ExtendedContext):\n\
185 ... print(getcontext().prec)\n\
186 ...\n\
187 9\n\
188 >>> print(getcontext().prec)\n\
189 28\n\
190 28\n\
191 >>> with localcontext():\n\
192 ... ctx = getcontext()\n\
193 ... ctx.prec += 2\n\
194 ... print(ctx.prec)\n\
195 ...\n\
196 30\n\
197 >>> with localcontext(ExtendedContext):\n\
198 ... print(getcontext().prec)\n\
199 ...\n\
200 9\n\
201 >>> print(getcontext().prec)\n\
202 28\n\
38 \n"); 203 \n");
39 204
40 #ifdef EXTRA_FUNCTIONALITY 205 #ifdef EXTRA_FUNCTIONALITY
41 PyDoc_STRVAR(doc_ieee_context, 206 PyDoc_STRVAR(doc_ieee_context,
42 "IEEEContext(\$module, bits, /)\n--\n\n\ 207 "IEEEContext(\$module, bits, /)\n--\n\n\
43 Return a context object initialized to the proper values for one of the\n\ 208 Return a context object initialized to the proper values for one of the\n\
44 IEEE interchange formats. The argument must be a multiple of 32 and less\n\ 209 IEEE interchange formats. The argument must be a multiple of 32 and less\n\
45 than IEEE_CONTEXT_MAX_BITS. For the most common values, the constants\n\ 210 than IEEE_CONTEXT_MAX_BITS. For the most common values, the constants\n\
46 DECIMAL32, DECIMAL64 and DECIMAL128 are provided.\n\ 211 DECIMAL32, DECIMAL64 and DECIMAL128 are provided.\n\
47 \n"); 212 \n");
48 #endif 213 #endif
49 214
50 215
51 /******************************************************************************/ 216 /******************************************************************************/
52 /* Decimal Object and Methods */ 217 /* Decimal Object and Methods */
53 /******************************************************************************/ 218 /******************************************************************************/
54 219
55 PyDoc_STRVAR(doc_decimal, 220 PyDoc_STRVAR(doc_decimal,
56 "Decimal(value=\"0\", context=None)\n--\n\n\ 221 "Decimal(value=\"0\", context=None)\n--\n\n\
57 Construct a new Decimal object. 'value' can be an integer, string, tuple,\n\ 222 Construct a new Decimal object. 'value' can be an integer, string, tuple,\n\
58 or another Decimal object. If no value is given, return Decimal('0'). The\n\ 223 or another Decimal object. If no value is given, return Decimal('0'). The\n\
59 context does not affect the conversion and is only passed to determine if\n\ 224 context does not affect the conversion and is only passed to determine if\n\
60 the InvalidOperation trap is active.\n\ 225 the InvalidOperation trap is active.\n\
226 \n\
227 >>> Decimal('3.14') # string input\n\
228 Decimal('3.14')\n\
229 >>> Decimal((0, (3, 1, 4), -2)) # tuple (sign, digit_tuple, exponent)\n\
230 Decimal('3.14')\n\
231 >>> Decimal(314) # int\n\
232 Decimal('314')\n\
233 >>> Decimal(Decimal(314)) # another decimal instance\n\
234 Decimal('314')\n\
235 >>> Decimal(' 3.14 \\\\n') # leading and trailing whitespace okay\n\
236 Decimal('3.14')\n\
61 \n"); 237 \n");
62 238
65 Return the adjusted exponent of the number. Defined as exp + digits - 1.\n\ 241 Return the adjusted exponent of the number. Defined as exp + digits - 1.\n\
66 \n"); 242 \n");
67 243
68 PyDoc_STRVAR(doc_as_tuple, 244 PyDoc_STRVAR(doc_as_tuple,
69 "as_tuple(\$self, /)\n--\n\n\ 245 "as_tuple(\$self, /)\n--\n\n\
70 Return a tuple representation of the number.\n\ 246 Represents the number as a triple tuple, to show the internals exactly as\n\
247 they are.\n\
71 \n"); 248 \n");
72 249
73 PyDoc_STRVAR(doc_as_integer_ratio, 250 PyDoc_STRVAR(doc_as_integer_ratio,
74 "as_integer_ratio(\$self, /)\n--\n\n\ 251 "as_integer_ratio(\$self, /)\n--\n\n\
75 Decimal.as_integer_ratio() -> (int, int)\n\ 252 Express a finite Decimal instance in the form n / d.\n\
76 \n\ 253 Return a pair (n, d) of integers, whose ratio is exactly equal to the original\n \
77 Return a pair of integers, whose ratio is exactly equal to the original\n\
78 Decimal and with a positive denominator. The ratio is in lowest terms.\n\ 254 Decimal and with a positive denominator. The ratio is in lowest terms.\n\
79 Raise OverflowError on infinities and a ValueError on NaNs.\n\ 255 Raise OverflowError on infinities and a ValueError on NaNs.\n\
256 \n\
257 >>> Decimal('3.14').as_integer_ratio()\n\
258 (157, 50)\n\
259 >>> Decimal('-123e5').as_integer_ratio()\n\
260 (-12300000, 1)\n\
261 >>> Decimal('0.00').as_integer_ratio()\n\
262 (0, 1)\n\
80 \n"); 263 \n");
81 264
82 PyDoc_STRVAR(doc_canonical, 265 PyDoc_STRVAR(doc_canonical,
83 "canonical(\$self, /)\n--\n\n\ 266 "canonical(\$self, /)\n--\n\n\
84 Return the canonical encoding of the argument. Currently, the encoding\n\ 267 Returns the same Decimal object.\n\
85 of a Decimal instance is always canonical, so this operation returns its\n\ 268 As we do not have different encodings for the same number, the received\n\
86 argument unchanged.\n\ 269 object already is in its canonical form.\n\
270 \n\
271 >>> ExtendedContext.canonical(Decimal('2.50'))\n\
272 Decimal('2.50')\n\
87 \n"); 273 \n");
88 274
89 PyDoc_STRVAR(doc_compare, 275 PyDoc_STRVAR(doc_compare,
90 "compare(\$self, /, other, context=None)\n--\n\n\ 276 "compare(\$self, /, other, context=None)\n--\n\n\
91 Compare self to other. Return a decimal value:\n\ 277 Compare values numerically.\n\
92 \n\ 278 \n\
93 a or b is a NaN ==> Decimal('NaN')\n\ 279 If the signs of the operands differ, a value representing each operand\n\
94 a < b ==> Decimal('-1')\n\ 280 ('-1' if the operand is less than zero, '0' if the operand is zero or\n\
95 a == b ==> Decimal('0')\n\ 281 negative zero, or '1' if the operand is greater than zero) is used in\n\
96 a > b ==> Decimal('1')\n\ 282 place of that operand for the comparison instead of the actual\n\
283 operand.\n\
284 \n\
285 The comparison is then effected by subtracting the second operand from\n\
286 the first and then returning a value according to the result of the\n\
287 subtraction: '-1' if the result is less than zero, '0' if the result is\n\
288 zero or negative zero, or '1' if the result is greater than zero.\n\
289 \n\
290 a or b is a NaN ==> Decimal('NaN')\n\
291 a < b ==> Decimal('-1')\n\
292 a == b ==> Decimal('0')\n\
293 a > b ==> Decimal('1')\n\
294 \n\
295 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('3'))\n\
296 Decimal('-1')\n\
297 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1'))\n\
298 Decimal('0')\n\
299 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.10'))\n\
300 Decimal('0')\n\
301 >>> ExtendedContext.compare(Decimal('3'), Decimal('2.1'))\n\
302 Decimal('1')\n\
303 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('-3'))\n\
304 Decimal('1')\n\
305 >>> ExtendedContext.compare(Decimal('-3'), Decimal('2.1'))\n\
306 Decimal('-1')\n\
307 >>> ExtendedContext.compare(1, 2)\n\
308 Decimal('-1')\n\
309 >>> ExtendedContext.compare(Decimal(1), 2)\n\
310 Decimal('-1')\n\
311 >>> ExtendedContext.compare(1, Decimal(2))\n\
312 Decimal('-1')\n\
313 >>> ExtendedContext.compare(Decimal('2'), Decimal('NaN'))\n\
314 Decimal('NaN')\n\
97 \n"); 315 \n");
98 316
99 PyDoc_STRVAR(doc_compare_signal, 317 PyDoc_STRVAR(doc_compare_signal,
100 "compare_signal(\$self, /, other, context=None)\n--\n\n\ 318 "compare_signal(\$self, /, other, context=None)\n--\n\n\
101 Identical to compare, except that all NaNs signal.\n\ 319 Compare the values of the two operands numerically.\n\
320 \n\
321 It's pretty much like compare(), but all NaNs signal, with signaling\n\
322 NaNs taking precedence over quiet NaNs.\n\
323 \n\
324 >>> ExtendedContext.compare_signal(Decimal('2.1'), Decimal('3'))\n\
325 Decimal('-1')\n\
326 >>> ExtendedContext.compare_signal(Decimal('2.1'), Decimal('2.1'))\n\
327 Decimal('0')\n\
328 >>> ExtendedContext.flags[InvalidOperation] = 0\n\
329 >>> print(ExtendedContext.flags[InvalidOperation])\n\
330 0\n\
331 >>> ExtendedContext.compare_signal(Decimal('NaN'), Decimal('2.1'))\n\
332 Decimal('NaN')\n\
333 >>> print(ExtendedContext.flags[InvalidOperation])\n\
334 1\n\
335 >>> ExtendedContext.flags[InvalidOperation] = 0\n\
336 >>> print(ExtendedContext.flags[InvalidOperation])\n\
337 0\n\
338 >>> ExtendedContext.compare_signal(Decimal('sNaN'), Decimal('2.1'))\n\
339 Decimal('NaN')\n\
340 >>> print(ExtendedContext.flags[InvalidOperation])\n\
341 1\n\
342 >>> ExtendedContext.compare_signal(-1, 2)\n\
343 Decimal('-1')\n\
344 >>> ExtendedContext.compare_signal(Decimal(-1), 2)\n\
345 Decimal('-1')\n\
346 >>> ExtendedContext.compare_signal(-1, Decimal(2))\n\
347 Decimal('-1')\n\
102 \n"); 348 \n");
103 349
104 PyDoc_STRVAR(doc_compare_total, 350 PyDoc_STRVAR(doc_compare_total,
105 "compare_total(\$self, /, other, context=None)\n--\n\n\ 351 "compare_total(\$self, /, other, context=None)\n--\n\n\
106 Compare two operands using their abstract representation rather than\n\ 352 Compare two operands using their abstract representation rather than\n\
107 their numerical value. Similar to the compare() method, but the result\n\ 353 their numerical value. Similar to the compare() method, but the result\n\
108 gives a total ordering on Decimal instances. Two Decimal instances with\n\ 354 gives a total ordering on Decimal instances. Two Decimal instances with\n\
109 the same numeric value but different representations compare unequal\n\ 355 the same numeric value but different representations compare unequal\n\
110 in this ordering:\n\ 356 in this ordering:\n\
111 \n\ 357 \n\
112 >>> Decimal('12.0').compare_total(Decimal('12'))\n\ 358 >>> Decimal('12.0').compare_total(Decimal('12'))\n\
113 Decimal('-1')\n\ 359 Decimal('-1')\n\
114 \n\ 360 \n\
115 Quiet and signaling NaNs are also included in the total ordering. The result\n\ 361 Quiet and signaling NaNs are also included in the total ordering. The result\n\
116 of this function is Decimal('0') if both operands have the same representation,\ n\ 362 of this function is Decimal('0') if both operands have the same representation,\ n\
117 Decimal('-1') if the first operand is lower in the total order than the second,\ n\ 363 Decimal('-1') if the first operand is lower in the total order than the second,\ n\
118 and Decimal('1') if the first operand is higher in the total order than the\n\ 364 and Decimal('1') if the first operand is higher in the total order than the\n\
119 second operand. See the specification for details of the total order.\n\ 365 second operand. See the specification for details of the total order.\n\
120 \n\ 366 \n\
121 This operation is unaffected by context and is quiet: no flags are changed\n\ 367 This operation is unaffected by context and is quiet: no flags are changed\n\
122 and no rounding is performed. As an exception, the C version may raise\n\ 368 and no rounding is performed. As an exception, the C version may raise\n\
123 InvalidOperation if the second operand cannot be converted exactly.\n\ 369 InvalidOperation if the second operand cannot be converted exactly.\n\
370 \n\
371 >>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9'))\n\
372 Decimal('-1')\n\
373 >>> ExtendedContext.compare_total(Decimal('-127'), Decimal('12'))\n\
374 Decimal('-1')\n\
375 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.3'))\n\
376 Decimal('-1')\n\
377 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.30'))\n\
378 Decimal('0')\n\
379 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('12.300'))\n\
380 Decimal('1')\n\
381 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('NaN'))\n\
382 Decimal('-1')\n\
383 >>> ExtendedContext.compare_total(1, 2)\n\
384 Decimal('-1')\n\
385 >>> ExtendedContext.compare_total(Decimal(1), 2)\n\
386 Decimal('-1')\n\
387 >>> ExtendedContext.compare_total(1, Decimal(2))\n\
388 Decimal('-1')\n\
124 \n"); 389 \n");
125 390
126 PyDoc_STRVAR(doc_compare_total_mag, 391 PyDoc_STRVAR(doc_compare_total_mag,
127 "compare_total_mag(\$self, /, other, context=None)\n--\n\n\ 392 "compare_total_mag(\$self, /, other, context=None)\n--\n\n\
128 Compare two operands using their abstract representation rather than their\n\ 393 Compare two operands using their abstract representation rather than their\n\
129 value as in compare_total(), but ignoring the sign of each operand.\n\ 394 numerical value and with their sign ignored. Like compare_total, but with\n\
395 operand's sign ignored and assumed to be 0.\n\
130 \n\ 396 \n\
131 x.compare_total_mag(y) is equivalent to x.copy_abs().compare_total(y.copy_abs()) .\n\ 397 x.compare_total_mag(y) is equivalent to x.copy_abs().compare_total(y.copy_abs()) .\n\
132 \n\ 398 \n\
133 This operation is unaffected by context and is quiet: no flags are changed\n\ 399 This operation is unaffected by context and is quiet: no flags are changed\n\
134 and no rounding is performed. As an exception, the C version may raise\n\ 400 and no rounding is performed. As an exception, the C version may raise\n\
135 InvalidOperation if the second operand cannot be converted exactly.\n\ 401 InvalidOperation if the second operand cannot be converted exactly.\n\
136 \n"); 402 \n");
137 403
138 PyDoc_STRVAR(doc_conjugate, 404 PyDoc_STRVAR(doc_conjugate,
139 "conjugate(\$self, /)\n--\n\n\ 405 "conjugate(\$self, /)\n--\n\n\
140 Return self.\n\ 406 Returns self.\n\
141 \n"); 407 \n");
142 408
143 PyDoc_STRVAR(doc_copy_abs, 409 PyDoc_STRVAR(doc_copy_abs,
144 "copy_abs(\$self, /)\n--\n\n\ 410 "copy_abs(\$self, /)\n--\n\n\
145 Return the absolute value of the argument. This operation is unaffected by\n\ 411 Returns the absolute value of the argument. This operation is unaffected by\n\
146 context and is quiet: no flags are changed and no rounding is performed.\n\ 412 context and is quiet: no flags are changed and no rounding is performed.\n\
413 \n\
414 >>> ExtendedContext.copy_abs(Decimal('2.1'))\n\
415 Decimal('2.1')\n\
416 >>> ExtendedContext.copy_abs(Decimal('-100'))\n\
417 Decimal('100')\n\
418 >>> ExtendedContext.copy_abs(-1)\n\
419 Decimal('1')\n\
147 \n"); 420 \n");
148 421
149 PyDoc_STRVAR(doc_copy_negate, 422 PyDoc_STRVAR(doc_copy_negate,
150 "copy_negate(\$self, /)\n--\n\n\ 423 "copy_negate(\$self, /)\n--\n\n\
151 Return the negation of the argument. This operation is unaffected by context\n\ 424 Returns a copy of the operand with the sign inverted. This operation is\n\
152 and is quiet: no flags are changed and no rounding is performed.\n\ 425 unaffected by context and is quiet: no flags are changed and no rounding\n\
426 is performed.\n\
427 \n\
428 >>> ExtendedContext.copy_negate(Decimal('101.5'))\n\
429 Decimal('-101.5')\n\
430 >>> ExtendedContext.copy_negate(Decimal('-101.5'))\n\
431 Decimal('101.5')\n\
432 >>> ExtendedContext.copy_negate(1)\n\
433 Decimal('-1')\n\
153 \n"); 434 \n");
154 435
155 PyDoc_STRVAR(doc_copy_sign, 436 PyDoc_STRVAR(doc_copy_sign,
156 "copy_sign(\$self, /, other, context=None)\n--\n\n\ 437 "copy_sign(\$self, /, other, context=None)\n--\n\n\
157 Return a copy of the first operand with the sign set to be the same as the\n\ 438 Returns a copy of the first operand with the sign equal to the second operand.\n \
158 sign of the second operand. For example:\n\
159 \n\ 439 \n\
160 >>> Decimal('2.3').copy_sign(Decimal('-1.5'))\n\ 440 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33'))\n\
161 Decimal('-2.3')\n\ 441 Decimal('1.50')\n\
442 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('7.33'))\n\
443 Decimal('1.50')\n\
444 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('-7.33'))\n\
445 Decimal('-1.50')\n\
446 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('-7.33'))\n\
447 Decimal('-1.50')\n\
448 >>> ExtendedContext.copy_sign(1, -2)\n\
449 Decimal('-1')\n\
450 >>> ExtendedContext.copy_sign(Decimal(1), -2)\n\
451 Decimal('-1')\n\
452 >>> ExtendedContext.copy_sign(1, Decimal(-2))\n\
453 Decimal('-1')\n\
162 \n\ 454 \n\
163 This operation is unaffected by context and is quiet: no flags are changed\n\ 455 This operation is unaffected by context and is quiet: no flags are changed\n\
164 and no rounding is performed. As an exception, the C version may raise\n\ 456 and no rounding is performed. As an exception, the C version may raise\n\
165 InvalidOperation if the second operand cannot be converted exactly.\n\ 457 InvalidOperation if the second operand cannot be converted exactly.\n\
166 \n"); 458 \n");
167 459
168 PyDoc_STRVAR(doc_exp, 460 PyDoc_STRVAR(doc_exp,
169 "exp(\$self, /, context=None)\n--\n\n\ 461 "exp(\$self, /, context=None)\n--\n\n\
170 Return the value of the (natural) exponential function e**x at the given\n\ 462 Return the value of the (natural) exponential function e ** a. The function alwa ys uses the ROUND_HALF_EVEN mode and the result\n\
171 number. The function always uses the ROUND_HALF_EVEN mode and the result\n\
172 is correctly rounded.\n\ 463 is correctly rounded.\n\
464 \n\
465 >>> c = ExtendedContext.copy()\n\
466 >>> c.Emin = -999\n\
467 >>> c.Emax = 999\n\
468 >>> c.exp(Decimal('-Infinity'))\n\
469 Decimal('0')\n\
470 >>> c.exp(Decimal('-1'))\n\
471 Decimal('0.367879441')\n\
472 >>> c.exp(Decimal('0'))\n\
473 Decimal('1')\n\
474 >>> c.exp(Decimal('1'))\n\
475 Decimal('2.71828183')\n\
476 >>> c.exp(Decimal('0.693147181'))\n\
477 Decimal('2.00000000')\n\
478 >>> c.exp(Decimal('+Infinity'))\n\
479 Decimal('Infinity')\n\
480 >>> c.exp(10)\n\
481 Decimal('22026.4658')\n\
173 \n"); 482 \n");
174 483
175 PyDoc_STRVAR(doc_from_float, 484 PyDoc_STRVAR(doc_from_float,
176 "from_float(\$type, f, /)\n--\n\n\ 485 "from_float(\$type, f, /)\n--\n\n\
177 Class method that converts a float to a decimal number, exactly.\n\ 486 Class method that converts a float to a decimal number, exactly.\n\
178 Since 0.1 is not exactly representable in binary floating point,\n\ 487 Since 0.1 is not exactly representable in binary floating point,\n\
179 Decimal.from_float(0.1) is not the same as Decimal('0.1').\n\ 488 Decimal.from_float(0.1) is not the same as Decimal('0.1').\n\
180 \n\ 489 \n\
181 >>> Decimal.from_float(0.1)\n\ 490 >>> Decimal.from_float(0.1)\n\
182 Decimal('0.1000000000000000055511151231257827021181583404541015625')\n\ 491 Decimal('0.1000000000000000055511151231257827021181583404541015625')\n\
183 >>> Decimal.from_float(float('nan'))\n\ 492 >>> Decimal.from_float(float('nan'))\n\
184 Decimal('NaN')\n\ 493 Decimal('NaN')\n\
185 >>> Decimal.from_float(float('inf'))\n\ 494 >>> Decimal.from_float(float('inf'))\n\
186 Decimal('Infinity')\n\ 495 Decimal('Infinity')\n\
187 >>> Decimal.from_float(float('-inf'))\n\ 496 >>> Decimal.from_float(float('-inf'))\n\
188 Decimal('-Infinity')\n\ 497 Decimal('-Infinity')\n\
189 \n\ 498 \n\
190 \n"); 499 \n");
191 500
192 PyDoc_STRVAR(doc_fma, 501 PyDoc_STRVAR(doc_fma,
193 "fma(\$self, /, other, third, context=None)\n--\n\n\ 502 "fma(\$self, /, other, third, context=None)\n--\n\n\
194 Fused multiply-add. Return self*other+third with no rounding of the\n\ 503 Returns a multiplied by b, plus c.\n\
195 intermediate product self*other.\n\ 504 \n\
196 \n\ 505 Fused multiply-add. The first two operands are multiplied together,\n\
197 >>> Decimal(2).fma(3, 5)\n\ 506 using multiply, the third operand is then added to the result of that\n\
198 Decimal('11')\n\ 507 multiplication, using add, all with only one final rounding.\n\
199 \n\ 508 \n\
509 >>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7'))\n\
510 Decimal('22')\n\
511 >>> ExtendedContext.fma(Decimal('3'), Decimal('-5'), Decimal('7'))\n\
512 Decimal('-8')\n\
513 >>> ExtendedContext.fma(Decimal('888565290'), Decimal('1557.96930'), Decimal ('-86087.7578'))\n\
514 Decimal('1.38435736E+12')\n\
515 >>> ExtendedContext.fma(1, 3, 4)\n\
516 Decimal('7')\n\
517 >>> ExtendedContext.fma(1, Decimal(3), 4)\n\
518 Decimal('7')\n\
519 >>> ExtendedContext.fma(1, 3, Decimal(4))\n\
520 Decimal('7')\n\
200 \n"); 521 \n");
201 522
202 PyDoc_STRVAR(doc_is_canonical, 523 PyDoc_STRVAR(doc_is_canonical,
203 "is_canonical(\$self, /)\n--\n\n\ 524 "is_canonical(\$self, /)\n--\n\n\
204 Return True if the argument is canonical and False otherwise. Currently,\n\ 525 Return True if the operand is canonical; otherwise return False.\n\
205 a Decimal instance is always canonical, so this operation always returns\n\ 526 Currently, the encoding of a Decimal instance is always\n\
206 True.\n\ 527 canonical, so this method returns True for any Decimal.\n\
528 \n\
529 >>> ExtendedContext.is_canonical(Decimal('2.50'))\n\
530 True\n\
207 \n"); 531 \n");
208 532
209 PyDoc_STRVAR(doc_is_finite, 533 PyDoc_STRVAR(doc_is_finite,
210 "is_finite(\$self, /)\n--\n\n\ 534 "is_finite(\$self, /)\n--\n\n\
211 Return True if the argument is a finite number, and False if the argument\n\ 535 Return True if the operand is finite; otherwise return False.\n\
212 is infinite or a NaN.\n\ 536 A Decimal instance is considered finite if it is neither infinite nor a\n\
537 NaN.\n\
538 \n\
539 >>> ExtendedContext.is_finite(Decimal('2.50'))\n\
540 True\n\
541 >>> ExtendedContext.is_finite(Decimal('-0.3'))\n\
542 True\n\
543 >>> ExtendedContext.is_finite(Decimal('0'))\n\
544 True\n\
545 >>> ExtendedContext.is_finite(Decimal('Inf'))\n\
546 False\n\
547 >>> ExtendedContext.is_finite(Decimal('NaN'))\n\
548 False\n\
549 >>> ExtendedContext.is_finite(1)\n\
550 True\n\
213 \n"); 551 \n");
214 552
215 PyDoc_STRVAR(doc_is_infinite, 553 PyDoc_STRVAR(doc_is_infinite,
216 "is_infinite(\$self, /)\n--\n\n\ 554 "is_infinite(\$self, /)\n--\n\n\
217 Return True if the argument is either positive or negative infinity and\n\ 555 Return True if the operand is infinite; otherwise return False.\n\
218 False otherwise.\n\ 556 \n\
557 >>> ExtendedContext.is_infinite(Decimal('2.50'))\n\
558 False\n\
559 >>> ExtendedContext.is_infinite(Decimal('-Inf'))\n\
560 True\n\
561 >>> ExtendedContext.is_infinite(Decimal('NaN'))\n\
562 False\n\
563 >>> ExtendedContext.is_infinite(1)\n\
564 False\n\
219 \n"); 565 \n");
220 566
221 PyDoc_STRVAR(doc_is_nan, 567 PyDoc_STRVAR(doc_is_nan,
222 "is_nan(\$self, /)\n--\n\n\ 568 "is_nan(\$self, /)\n--\n\n\
223 Return True if the argument is a (quiet or signaling) NaN and False\n\ 569 Return True if the operand is a (quiet or signaling) NaN or NaN;\n\
224 otherwise.\n\ 570 otherwise return False.\n\
571 \n\
572 >>> ExtendedContext.is_nan(Decimal('2.50'))\n\
573 False\n\
574 >>> ExtendedContext.is_nan(Decimal('NaN'))\n\
575 True\n\
576 >>> ExtendedContext.is_nan(Decimal('-sNaN'))\n\
577 True\n\
578 >>> ExtendedContext.is_nan(1)\n\
579 False\n\
225 \n"); 580 \n");
226 581
227 PyDoc_STRVAR(doc_is_normal, 582 PyDoc_STRVAR(doc_is_normal,
228 "is_normal(\$self, /, context=None)\n--\n\n\ 583 "is_normal(\$self, /, context=None)\n--\n\n\
229 Return True if the argument is a normal finite non-zero number with an\n\ 584 Return True if the operand is a normal number; otherwise return False.\n\
230 adjusted exponent greater than or equal to Emin. Return False if the\n\ 585 \n\
231 argument is zero, subnormal, infinite or a NaN.\n\ 586 >>> c = ExtendedContext.copy()\n\
587 >>> c.Emin = -999\n\
588 >>> c.Emax = 999\n\
589 >>> c.is_normal(Decimal('2.50'))\n\
590 True\n\
591 >>> c.is_normal(Decimal('0.1E-999'))\n\
592 False\n\
593 >>> c.is_normal(Decimal('0.00'))\n\
594 False\n\
595 >>> c.is_normal(Decimal('-Inf'))\n\
596 False\n\
597 >>> c.is_normal(Decimal('NaN'))\n\
598 False\n\
599 >>> c.is_normal(1)\n\
600 True\n\
232 \n"); 601 \n");
233 602
234 PyDoc_STRVAR(doc_is_qnan, 603 PyDoc_STRVAR(doc_is_qnan,
235 "is_qnan(\$self, /)\n--\n\n\ 604 "is_qnan(\$self, /)\n--\n\n\
236 Return True if the argument is a quiet NaN, and False otherwise.\n\ 605 Return True if the argument is a quiet NaN; otherwise return False.\n\
606 \n\
607 >>> ExtendedContext.is_qnan(Decimal('2.50'))\n\
608 False\n\
609 >>> ExtendedContext.is_qnan(Decimal('NaN'))\n\
610 True\n\
611 >>> ExtendedContext.is_qnan(Decimal('sNaN'))\n\
612 False\n\
613 >>> ExtendedContext.is_qnan(1)\n\
614 False\n\
237 \n"); 615 \n");
238 616
239 PyDoc_STRVAR(doc_is_signed, 617 PyDoc_STRVAR(doc_is_signed,
240 "is_signed(\$self, /)\n--\n\n\ 618 "is_signed(\$self, /)\n--\n\n\
241 Return True if the argument has a negative sign and False otherwise.\n\ 619 Return True if the argument has a negative sign and False otherwise.\n\
242 Note that both zeros and NaNs can carry signs.\n\ 620 Note that both zeros and NaNs can carry signs.\n\
621 \n\
622 >>> ExtendedContext.is_signed(Decimal('2.50'))\n\
623 False\n\
624 >>> ExtendedContext.is_signed(Decimal('-12'))\n\
625 True\n\
626 >>> ExtendedContext.is_signed(Decimal('-0'))\n\
627 True\n\
628 >>> ExtendedContext.is_signed(8)\n\
629 False\n\
630 >>> ExtendedContext.is_signed(-8)\n\
631 True\n\
243 \n"); 632 \n");
244 633
245 PyDoc_STRVAR(doc_is_snan, 634 PyDoc_STRVAR(doc_is_snan,
246 "is_snan(\$self, /)\n--\n\n\ 635 "is_snan(\$self, /)\n--\n\n\
247 Return True if the argument is a signaling NaN and False otherwise.\n\ 636 Return True if the operand is a signaling NaN; otherwise return False.\n\
637 \n\
638 >>> ExtendedContext.is_snan(Decimal('2.50'))\n\
639 False\n\
640 >>> ExtendedContext.is_snan(Decimal('NaN'))\n\
641 False\n\
642 >>> ExtendedContext.is_snan(Decimal('sNaN'))\n\
643 True\n\
644 >>> ExtendedContext.is_snan(1)\n\
645 False\n\
248 \n"); 646 \n");
249 647
250 PyDoc_STRVAR(doc_is_subnormal, 648 PyDoc_STRVAR(doc_is_subnormal,
251 "is_subnormal(\$self, /, context=None)\n--\n\n\ 649 "is_subnormal(\$self, /, context=None)\n--\n\n\
252 Return True if the argument is subnormal, and False otherwise. A number is\n\ 650 Return True if the argument is subnormal; otherwise return False. A number\n\
253 subnormal if it is non-zero, finite, and has an adjusted exponent less\n\ 651 is subnormal if it is non-zero, finite, and has an adjusted exponent less\n\
254 than Emin.\n\ 652 than Emin.\n\
653 \n\
654 >>> c = ExtendedContext.copy()\n\
655 >>> c.Emin = -999\n\
656 >>> c.Emax = 999\n\
657 >>> c.is_subnormal(Decimal('2.50'))\n\
658 False\n\
659 >>> c.is_subnormal(Decimal('0.1E-999'))\n\
660 True\n\
661 >>> c.is_subnormal(Decimal('0.00'))\n\
662 False\n\
663 >>> c.is_subnormal(Decimal('-Inf'))\n\
664 False\n\
665 >>> c.is_subnormal(Decimal('NaN'))\n\
666 False\n\
667 >>> c.is_subnormal(1)\n\
668 False\n\
255 \n"); 669 \n");
256 670
257 PyDoc_STRVAR(doc_is_zero, 671 PyDoc_STRVAR(doc_is_zero,
258 "is_zero(\$self, /)\n--\n\n\ 672 "is_zero(\$self, /)\n--\n\n\
259 Return True if the argument is a (positive or negative) zero and False\n\ 673 Return True if the operand is a zero; otherwise return False.\n\
260 otherwise.\n\ 674 \n\
675 >>> ExtendedContext.is_zero(Decimal('0'))\n\
676 True\n\
677 >>> ExtendedContext.is_zero(Decimal('2.50'))\n\
678 False\n\
679 >>> ExtendedContext.is_zero(Decimal('-0E+2'))\n\
680 True\n\
681 >>> ExtendedContext.is_zero(1)\n\
682 False\n\
683 >>> ExtendedContext.is_zero(0)\n\
684 True\n\
261 \n"); 685 \n");
262 686
263 PyDoc_STRVAR(doc_ln, 687 PyDoc_STRVAR(doc_ln,
264 "ln(\$self, /, context=None)\n--\n\n\ 688 "ln(\$self, /, context=None)\n--\n\n\
265 Return the natural (base e) logarithm of the operand. The function always\n\ 689 Return the natural (base e) logarithm of the operand. The function always\n\
266 uses the ROUND_HALF_EVEN mode and the result is correctly rounded.\n\ 690 uses the ROUND_HALF_EVEN mode and the result is correctly rounded.\n\
691 \n\
692 >>> c = ExtendedContext.copy()\n\
693 >>> c.Emin = -999\n\
694 >>> c.Emax = 999\n\
695 >>> c.ln(Decimal('0'))\n\
696 Decimal('-Infinity')\n\
697 >>> c.ln(Decimal('1.000'))\n\
698 Decimal('0')\n\
699 >>> c.ln(Decimal('2.71828183'))\n\
700 Decimal('1.00000000')\n\
701 >>> c.ln(Decimal('10'))\n\
702 Decimal('2.30258509')\n\
703 >>> c.ln(Decimal('+Infinity'))\n\
704 Decimal('Infinity')\n\
705 >>> c.ln(1)\n\
706 Decimal('0')\n\
267 \n"); 707 \n");
268 708
269 PyDoc_STRVAR(doc_log10, 709 PyDoc_STRVAR(doc_log10,
270 "log10(\$self, /, context=None)\n--\n\n\ 710 "log10(\$self, /, context=None)\n--\n\n\
271 Return the base ten logarithm of the operand. The function always uses the\n\ 711 Return the base 10 logarithm of the operand. The function always uses the\n\
272 ROUND_HALF_EVEN mode and the result is correctly rounded.\n\ 712 ROUND_HALF_EVEN mode and the result is correctly rounded.\n\
713 \n\
714 >>> c = ExtendedContext.copy()\n\
715 >>> c.Emin = -999\n\
716 >>> c.Emax = 999\n\
717 >>> c.log10(Decimal('0'))\n\
718 Decimal('-Infinity')\n\
719 >>> c.log10(Decimal('0.001'))\n\
720 Decimal('-3')\n\
721 >>> c.log10(Decimal('1.000'))\n\
722 Decimal('0')\n\
723 >>> c.log10(Decimal('2'))\n\
724 Decimal('0.301029996')\n\
725 >>> c.log10(Decimal('10'))\n\
726 Decimal('1')\n\
727 >>> c.log10(Decimal('70'))\n\
728 Decimal('1.84509804')\n\
729 >>> c.log10(Decimal('+Infinity'))\n\
730 Decimal('Infinity')\n\
731 >>> c.log10(0)\n\
732 Decimal('-Infinity')\n\
733 >>> c.log10(1)\n\
734 Decimal('0')\n\
273 \n"); 735 \n");
274 736
275 PyDoc_STRVAR(doc_logb, 737 PyDoc_STRVAR(doc_logb,
276 "logb(\$self, /, context=None)\n--\n\n\ 738 "logb(\$self, /, context=None)\n--\n\n\
277 For a non-zero number, return the adjusted exponent of the operand as a\n\ 739 Returns the exponent of the magnitude of the operand's MSD.\n\
278 Decimal instance. If the operand is a zero, then Decimal('-Infinity') is\n\ 740 The result is the integer which is the exponent of the magnitude\n\
279 returned and the DivisionByZero condition is raised. If the operand is\n\ 741 of the most significant digit of the operand (as though the\n\
280 an infinity then Decimal('Infinity') is returned.\n\ 742 operand were truncated to a single digit while maintaining the\n\
743 value of that digit and without limiting the resulting exponent).\n\
744 \n\
745 >>> ExtendedContext.logb(Decimal('250'))\n\
746 Decimal('2')\n\
747 >>> ExtendedContext.logb(Decimal('2.50'))\n\
748 Decimal('0')\n\
749 >>> ExtendedContext.logb(Decimal('0.03'))\n\
750 Decimal('-2')\n\
751 >>> ExtendedContext.logb(Decimal('0'))\n\
752 Decimal('-Infinity')\n\
753 >>> ExtendedContext.logb(1)\n\
754 Decimal('0')\n\
755 >>> ExtendedContext.logb(10)\n\
756 Decimal('1')\n\
757 >>> ExtendedContext.logb(100)\n\
758 Decimal('2')\n\
281 \n"); 759 \n");
282 760
283 PyDoc_STRVAR(doc_logical_and, 761 PyDoc_STRVAR(doc_logical_and,
284 "logical_and(\$self, /, other, context=None)\n--\n\n\ 762 "logical_and(\$self, /, other, context=None)\n--\n\n\
285 Return the digit-wise 'and' of the two (logical) operands.\n\ 763 Applies the logical operation 'and' between each operand's digits.\n\
764 The operands must be both logical numbers.\n\
765 \n\
766 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('0'))\n\
767 Decimal('0')\n\
768 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('1'))\n\
769 Decimal('0')\n\
770 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('0'))\n\
771 Decimal('0')\n\
772 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('1'))\n\
773 Decimal('1')\n\
774 >>> ExtendedContext.logical_and(Decimal('1100'), Decimal('1010'))\n\
775 Decimal('1000')\n\
776 >>> ExtendedContext.logical_and(Decimal('1111'), Decimal('10'))\n\
777 Decimal('10')\n\
778 >>> ExtendedContext.logical_and(110, 1101)\n\
779 Decimal('100')\n\
780 >>> ExtendedContext.logical_and(Decimal(110), 1101)\n\
781 Decimal('100')\n\
782 >>> ExtendedContext.logical_and(110, Decimal(1101))\n\
783 Decimal('100')\n\
286 \n"); 784 \n");
287 785
288 PyDoc_STRVAR(doc_logical_invert, 786 PyDoc_STRVAR(doc_logical_invert,
289 "logical_invert(\$self, /, context=None)\n--\n\n\ 787 "logical_invert(\$self, /, context=None)\n--\n\n\
290 Return the digit-wise inversion of the (logical) operand.\n\ 788 Invert all the digits in the operand.\n\
789 The operand must be a logical number.\n\
790 \n\
791 >>> ExtendedContext.logical_invert(Decimal('0'))\n\
792 Decimal('111111111')\n\
793 >>> ExtendedContext.logical_invert(Decimal('1'))\n\
794 Decimal('111111110')\n\
795 >>> ExtendedContext.logical_invert(Decimal('111111111'))\n\
796 Decimal('0')\n\
797 >>> ExtendedContext.logical_invert(Decimal('101010101'))\n\
798 Decimal('10101010')\n\
799 >>> ExtendedContext.logical_invert(1101)\n\
800 Decimal('111110010')\n\
291 \n"); 801 \n");
292 802
293 PyDoc_STRVAR(doc_logical_or, 803 PyDoc_STRVAR(doc_logical_or,
294 "logical_or(\$self, /, other, context=None)\n--\n\n\ 804 "logical_or(\$self, /, other, context=None)\n--\n\n\
295 Return the digit-wise 'or' of the two (logical) operands.\n\ 805 Applies the logical operation 'or' between each operand's digits.\n\
806 The operands must be both logical numbers.\n\
807 \n\
808 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('0'))\n\
809 Decimal('0')\n\
810 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('1'))\n\
811 Decimal('1')\n\
812 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('0'))\n\
813 Decimal('1')\n\
814 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('1'))\n\
815 Decimal('1')\n\
816 >>> ExtendedContext.logical_or(Decimal('1100'), Decimal('1010'))\n\
817 Decimal('1110')\n\
818 >>> ExtendedContext.logical_or(Decimal('1110'), Decimal('10'))\n\
819 Decimal('1110')\n\
820 >>> ExtendedContext.logical_or(110, 1101)\n\
821 Decimal('1111')\n\
822 >>> ExtendedContext.logical_or(Decimal(110), 1101)\n\
823 Decimal('1111')\n\
824 >>> ExtendedContext.logical_or(110, Decimal(1101))\n\
825 Decimal('1111')\n\
296 \n"); 826 \n");
297 827
298 PyDoc_STRVAR(doc_logical_xor, 828 PyDoc_STRVAR(doc_logical_xor,
299 "logical_xor(\$self, /, other, context=None)\n--\n\n\ 829 "logical_xor(\$self, /, other, context=None)\n--\n\n\
300 Return the digit-wise 'exclusive or' of the two (logical) operands.\n\ 830 Applies the logical operation 'xor' between each operand's digits.\n\
831 The operands must be both logical numbers.\n\
832 \n\
833 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('0'))\n\
834 Decimal('0')\n\
835 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('1'))\n\
836 Decimal('1')\n\
837 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('0'))\n\
838 Decimal('1')\n\
839 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('1'))\n\
840 Decimal('0')\n\
841 >>> ExtendedContext.logical_xor(Decimal('1100'), Decimal('1010'))\n\
842 Decimal('110')\n\
843 >>> ExtendedContext.logical_xor(Decimal('1111'), Decimal('10'))\n\
844 Decimal('1101')\n\
845 >>> ExtendedContext.logical_xor(110, 1101)\n\
846 Decimal('1011')\n\
847 >>> ExtendedContext.logical_xor(Decimal(110), 1101)\n\
848 Decimal('1011')\n\
849 >>> ExtendedContext.logical_xor(110, Decimal(1101))\n\
850 Decimal('1011')\n\
301 \n"); 851 \n");
302 852
303 PyDoc_STRVAR(doc_max, 853 PyDoc_STRVAR(doc_max,
304 "max(\$self, /, other, context=None)\n--\n\n\ 854 "max(\$self, /, other, context=None)\n--\n\n\
305 Maximum of self and other. If one operand is a quiet NaN and the other is\n\ 855 max compares two values numerically and returns the maximum.\n\
306 numeric, the numeric operand is returned.\n\ 856 \n\
857 If either operand is a NaN then the general rules apply.\n\
858 Otherwise, the operands are compared as though by the compare\n\
859 operation. If they are numerically equal then the left-hand operand\n\
860 is chosen as the result. Otherwise the maximum (closer to positive\n\
861 infinity) of the two operands is chosen as the result.\n\
862 \n\
863 >>> ExtendedContext.max(Decimal('3'), Decimal('2'))\n\
864 Decimal('3')\n\
865 >>> ExtendedContext.max(Decimal('-10'), Decimal('3'))\n\
866 Decimal('3')\n\
867 >>> ExtendedContext.max(Decimal('1.0'), Decimal('1'))\n\
868 Decimal('1')\n\
869 >>> ExtendedContext.max(Decimal('7'), Decimal('NaN'))\n\
870 Decimal('7')\n\
871 >>> ExtendedContext.max(1, 2)\n\
872 Decimal('2')\n\
873 >>> ExtendedContext.max(Decimal(1), 2)\n\
874 Decimal('2')\n\
875 >>> ExtendedContext.max(1, Decimal(2))\n\
876 Decimal('2')\n\
307 \n"); 877 \n");
308 878
309 PyDoc_STRVAR(doc_max_mag, 879 PyDoc_STRVAR(doc_max_mag,
310 "max_mag(\$self, /, other, context=None)\n--\n\n\ 880 "max_mag(\$self, /, other, context=None)\n--\n\n\
311 Similar to the max() method, but the comparison is done using the absolute\n\ 881 Compare the values numerically with their sign ignored.\n\
312 values of the operands.\n\ 882 \n\
883 >>> ExtendedContext.max_mag(Decimal('7'), Decimal('NaN'))\n\
884 Decimal('7')\n\
885 >>> ExtendedContext.max_mag(Decimal('7'), Decimal('-10'))
886 Decimal('-10')\n\
887 >>> ExtendedContext.max_mag(1, -2)\n\
888 Decimal('-2')\n\
889 >>> ExtendedContext.max_mag(Decimal(1), -2)\n\
890 Decimal('-2')\n\
891 >>> ExtendedContext.max_mag(1, Decimal(-2))\n\
892 Decimal('-2')\n\
313 \n"); 893 \n");
314 894
315 PyDoc_STRVAR(doc_min, 895 PyDoc_STRVAR(doc_min,
316 "min(\$self, /, other, context=None)\n--\n\n\ 896 "min(\$self, /, other, context=None)\n--\n\n\
317 Minimum of self and other. If one operand is a quiet NaN and the other is\n\ 897 min compares two values numerically and returns the minimum.\n\
318 numeric, the numeric operand is returned.\n\ 898 \n\
899 If either operand is a NaN then the general rules apply.\n\
900 Otherwise, the operands are compared as though by the compare\n\
901 operation. If they are numerically equal then the left-hand operand\n\
902 is chosen as the result. Otherwise the minimum (closer to negative\n\
903 infinity) of the two operands is chosen as the result.\n\
904 \n\
905 >>> ExtendedContext.min(Decimal('3'), Decimal('2'))\n\
906 Decimal('2')\n\
907 >>> ExtendedContext.min(Decimal('-10'), Decimal('3'))\n\
908 Decimal('-10')\n\
909 >>> ExtendedContext.min(Decimal('1.0'), Decimal('1'))\n\
910 Decimal('1.0')\n\
911 >>> ExtendedContext.min(Decimal('7'), Decimal('NaN'))\n\
912 Decimal('7')\n\
913 >>> ExtendedContext.min(1, 2)\n\
914 Decimal('1')\n\
915 >>> ExtendedContext.min(Decimal(1), 2)\n\
916 Decimal('1')\n\
917 >>> ExtendedContext.min(1, Decimal(29))\n\
918 Decimal('1')\n\
319 \n"); 919 \n");
320 920
321 PyDoc_STRVAR(doc_min_mag, 921 PyDoc_STRVAR(doc_min_mag,
322 "min_mag(\$self, /, other, context=None)\n--\n\n\ 922 "min_mag(\$self, /, other, context=None)\n--\n\n\
323 Similar to the min() method, but the comparison is done using the absolute\n\ 923 Compare the values numerically with their sign ignored.\n\
324 values of the operands.\n\ 924 \n\
925 >>> ExtendedContext.min_mag(Decimal('3'), Decimal('-2'))\n\
926 Decimal('-2')\n\
927 >>> ExtendedContext.min_mag(Decimal('-3'), Decimal('NaN'))\n\
928 Decimal('-3')\n\
929 >>> ExtendedContext.min_mag(1, -2)\n\
930 Decimal('1')\n\
931 >>> ExtendedContext.min_mag(Decimal(1), -2)\n\
932 Decimal('1')\n\
933 >>> ExtendedContext.min_mag(1, Decimal(-2))\n\
934 Decimal('1')\n\
325 \n"); 935 \n");
326 936
327 PyDoc_STRVAR(doc_next_minus, 937 PyDoc_STRVAR(doc_next_minus,
328 "next_minus(\$self, /, context=None)\n--\n\n\ 938 "next_minus(\$self, /, context=None)\n--\n\n\
329 Return the largest number representable in the given context (or in the\n\ 939 Returns the largest representable number smaller than a.\n\
330 current default context if no context is given) that is smaller than the\n\ 940 \n\
331 given operand.\n\ 941 >>> c = ExtendedContext.copy()\n\
942 >>> c.Emin = -999\n\
943 >>> c.Emax = 999\n\
944 >>> ExtendedContext.next_minus(Decimal('1'))\n\
945 Decimal('0.999999999')\n\
946 >>> c.next_minus(Decimal('1E-1007'))\n\
947 Decimal('0E-1007')\n\
948 >>> ExtendedContext.next_minus(Decimal('-1.00000003'))\n\
949 Decimal('-1.00000004')\n\
950 >>> c.next_minus(Decimal('Infinity'))\n\
951 Decimal('9.99999999E+999')\n\
952 >>> c.next_minus(1)\n\
953 Decimal('0.999999999')\n\
332 \n"); 954 \n");
333 955
334 PyDoc_STRVAR(doc_next_plus, 956 PyDoc_STRVAR(doc_next_plus,
335 "next_plus(\$self, /, context=None)\n--\n\n\ 957 "next_plus(\$self, /, context=None)\n--\n\n\
336 Return the smallest number representable in the given context (or in the\n\ 958 Returns the smallest representable number larger than a.\n\
337 current default context if no context is given) that is larger than the\n\ 959 \n\
338 given operand.\n\ 960 >>> c = ExtendedContext.copy()\n\
961 >>> c.Emin = -999\n\
962 >>> c.Emax = 999\n\
963 >>> ExtendedContext.next_plus(Decimal('1'))\n\
964 Decimal('1.00000001')\n\
965 >>> c.next_plus(Decimal('-1E-1007'))\n\
966 Decimal('-0E-1007')\n\
967 >>> ExtendedContext.next_plus(Decimal('-1.00000003'))\n\
968 Decimal('-1.00000002')\n\
969 >>> c.next_plus(Decimal('-Infinity'))\n\
970 Decimal('-9.99999999E+999')\n\
971 >>> c.next_plus(1)\n\
972 Decimal('1.00000001')\n\
339 \n"); 973 \n");
340 974
341 PyDoc_STRVAR(doc_next_toward, 975 PyDoc_STRVAR(doc_next_toward,
342 "next_toward(\$self, /, other, context=None)\n--\n\n\ 976 "next_toward(\$self, /, other, context=None)\n--\n\n\
343 If the two operands are unequal, return the number closest to the first\n\ 977 Returns the number closest to a, in direction towards b.\n\
344 operand in the direction of the second operand. If both operands are\n\ 978 \n\
345 numerically equal, return a copy of the first operand with the sign set\n\ 979 The result is the closest representable number from the first\n\
346 to be the same as the sign of the second operand.\n\ 980 operand (but not the first operand) that is in the direction\n\
981 towards the second operand, unless the operands have the same\n\
982 value.\n\
983 \n\
984 >>> c = ExtendedContext.copy()\n\
985 >>> c.Emin = -999\n\
986 >>> c.Emax = 999\n\
987 >>> c.next_toward(Decimal('1'), Decimal('2'))\n\
988 Decimal('1.00000001')\n\
989 >>> c.next_toward(Decimal('-1E-1007'), Decimal('1'))\n\
990 Decimal('-0E-1007')\n\
991 >>> c.next_toward(Decimal('-1.00000003'), Decimal('0'))\n\
992 Decimal('-1.00000002')\n\
993 >>> c.next_toward(Decimal('1'), Decimal('0'))\n\
994 Decimal('0.999999999')\n\
995 >>> c.next_toward(Decimal('1E-1007'), Decimal('-100'))\n\
996 Decimal('0E-1007')\n\
997 >>> c.next_toward(Decimal('-1.00000003'), Decimal('-10'))\n\
998 Decimal('-1.00000004')\n\
999 >>> c.next_toward(Decimal('0.00'), Decimal('-0.0000'))\n\
1000 Decimal('-0.00')\n\
1001 >>> c.next_toward(0, 1)\n\
1002 Decimal('1E-1007')\n\
1003 >>> c.next_toward(Decimal(0), 1)\n\
1004 Decimal('1E-1007')\n\
1005 >>> c.next_toward(0, Decimal(1))\n\
1006 Decimal('1E-1007')\n\
347 \n"); 1007 \n");
348 1008
349 PyDoc_STRVAR(doc_normalize, 1009 PyDoc_STRVAR(doc_normalize,
350 "normalize(\$self, /, context=None)\n--\n\n\ 1010 "normalize(\$self, /, context=None)\n--\n\n\
351 Normalize the number by stripping the rightmost trailing zeros and\n\ 1011 normalize reduces an operand to its simplest form.\n\
352 converting any result equal to Decimal('0') to Decimal('0e0'). Used\n\ 1012 \n\
353 for producing canonical values for members of an equivalence class.\n\ 1013 Essentially a plus operation with all trailing zeros removed from the\n\
354 For example, Decimal('32.100') and Decimal('0.321000e+2') both normalize\n\ 1014 result.\n\
355 to the equivalent value Decimal('32.1').\n\ 1015 \n\
1016 >>> ExtendedContext.normalize(Decimal('2.1'))\n\
1017 Decimal('2.1')\n\
1018 >>> ExtendedContext.normalize(Decimal('-2.0'))\n\
1019 Decimal('-2')\n\
1020 >>> ExtendedContext.normalize(Decimal('1.200'))\n\
1021 Decimal('1.2')\n\
1022 >>> ExtendedContext.normalize(Decimal('-120'))\n\
1023 Decimal('-1.2E+2')\n\
1024 >>> ExtendedContext.normalize(Decimal('120.00'))\n\
1025 Decimal('1.2E+2')\n\
1026 >>> ExtendedContext.normalize(Decimal('0.00'))\n\
1027 Decimal('0')\n\
1028 >>> ExtendedContext.normalize(6)\n\
1029 Decimal('6')\n\
356 \n"); 1030 \n");
357 1031
358 PyDoc_STRVAR(doc_number_class, 1032 PyDoc_STRVAR(doc_number_class,
359 "number_class(\$self, /, context=None)\n--\n\n\ 1033 "number_class(\$self, /, context=None)\n--\n\n\
360 Return a string describing the class of the operand. The returned value\n\ 1034 Returns an indication of the class of the operand.\n\
361 is one of the following ten strings:\n\ 1035 \n\
1036 The class is one of the following strings:\n\
362 \n\ 1037 \n\
363 * '-Infinity', indicating that the operand is negative infinity.\n\ 1038 * '-Infinity', indicating that the operand is negative infinity.\n\
364 * '-Normal', indicating that the operand is a negative normal number.\n\ 1039 * '-Normal', indicating that the operand is a negative normal number.\n\
365 * '-Subnormal', indicating that the operand is negative and subnormal.\n\ 1040 * '-Subnormal', indicating that the operand is negative and subnormal.\n\
366 * '-Zero', indicating that the operand is a negative zero.\n\ 1041 * '-Zero', indicating that the operand is a negative zero.\n\
367 * '+Zero', indicating that the operand is a positive zero.\n\ 1042 * '+Zero', indicating that the operand is a positive zero.\n\
368 * '+Subnormal', indicating that the operand is positive and subnormal.\n\ 1043 * '+Subnormal', indicating that the operand is positive and subnormal.\n\
369 * '+Normal', indicating that the operand is a positive normal number.\n\ 1044 * '+Normal', indicating that the operand is a positive normal number.\n\
370 * '+Infinity', indicating that the operand is positive infinity.\n\ 1045 * '+Infinity', indicating that the operand is positive infinity.\n\
371 * 'NaN', indicating that the operand is a quiet NaN (Not a Number).\n\ 1046 * 'NaN', indicating that the operand is a quiet NaN (Not a Number).\n\
372 * 'sNaN', indicating that the operand is a signaling NaN.\n\ 1047 * 'sNaN', indicating that the operand is a signaling NaN.\n\
373 \n\ 1048 \n\
1049 >>> c = ExtendedContext.copy()\n\
1050 >>> c.Emin = -999\n\
1051 >>> c.Emax = 999\n\
1052 >>> c.number_class(Decimal('Infinity'))\n\
1053 '+Infinity'\n\
1054 >>> c.number_class(Decimal('1E-10'))\n\
1055 '+Normal'\n\
1056 >>> c.number_class(Decimal('2.50'))\n\
1057 '+Normal'\n\
1058 >>> c.number_class(Decimal('0.1E-999'))\n\
1059 '+Subnormal'\n\
1060 >>> c.number_class(Decimal('0'))\n\
1061 '+Zero'\n\
1062 >>> c.number_class(Decimal('-0'))\n\
1063 '-Zero'\n\
1064 >>> c.number_class(Decimal('-0.1E-999'))\n\
1065 '-Subnormal'\n\
1066 >>> c.number_class(Decimal('-1E-10'))\n\
1067 '-Normal'\n\
1068 >>> c.number_class(Decimal('-2.50'))\n\
1069 '-Normal'\n\
1070 >>> c.number_class(Decimal('-Infinity'))\n\
1071 '-Infinity'\n\
1072 >>> c.number_class(Decimal('NaN'))\n\
1073 'NaN'\n\
1074 >>> c.number_class(Decimal('-NaN'))\n\
1075 'NaN'\n\
1076 >>> c.number_class(Decimal('sNaN'))\n\
1077 'sNaN'\n\
1078 >>> c.number_class(123)\n\
1079 '+Normal'\n\
374 \n"); 1080 \n");
375 1081
376 PyDoc_STRVAR(doc_quantize, 1082 PyDoc_STRVAR(doc_quantize,
377 "quantize(\$self, /, exp, rounding=None, context=None)\n--\n\n\ 1083 "quantize(\$self, /, exp, rounding=None, context=None)\n--\n\n\
378 Return a value equal to the first operand after rounding and having the\n\ 1084 Returns a value equal to 'a' (rounded), having the exponent of 'b'.\n\
379 exponent of the second operand.\n\ 1085 \n\
380 \n\ 1086 The coefficient of the result is derived from that of the left-hand\n\
381 >>> Decimal('1.41421356').quantize(Decimal('1.000'))\n\ 1087 operand. It may be rounded using the current rounding setting (if the\n\
382 Decimal('1.414')\n\ 1088 exponent is being increased), multiplied by a positive power of ten (if\n\
383 \n\ 1089 the exponent is being decreased), or is unchanged (if the exponent is\n\
384 Unlike other operations, if the length of the coefficient after the quantize\n\ 1090 already equal to that of the right-hand operand).\n\
385 operation would be greater than precision, then an InvalidOperation is signaled. \n\ 1091 \n\
386 This guarantees that, unless there is an error condition, the quantized exponent \n\ 1092 Unlike other operations, if the length of the coefficient after the\n\
387 is always equal to that of the right-hand operand.\n\ 1093 quantize operation would be greater than precision then an Invalid\n\
388 \n\ 1094 operation condition is raised. This guarantees that, unless there is\n\
389 Also unlike other operations, quantize never signals Underflow, even if the\n\ 1095 an error condition, the exponent of the result of a quantize is always\n\
390 result is subnormal and inexact.\n\ 1096 equal to that of the right-hand operand.\n\
391 \n\ 1097 Also unlike other operations, quantize will never raise Underflow, even\n\
392 If the exponent of the second operand is larger than that of the first, then\n\ 1098 if the result is subnormal and inexact.\n\
393 rounding may be necessary. In this case, the rounding mode is determined by the\ n\ 1099 \n\
394 rounding argument if given, else by the given context argument; if neither\n\ 1100 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.001'))\n\
395 argument is given, the rounding mode of the current thread's context is used.\n\ 1101 Decimal('2.170')\n\
1102 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.01'))\n\
1103 Decimal('2.17')\n\
1104 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.1'))\n\
1105 Decimal('2.2')\n\
1106 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+0'))\n\
1107 Decimal('2')\n\
1108 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+1'))\n\
1109 Decimal('0E+1')\n\
1110 >>> ExtendedContext.quantize(Decimal('-Inf'), Decimal('Infinity'))\n\
1111 Decimal('-Infinity')\n\
1112 >>> ExtendedContext.quantize(Decimal('2'), Decimal('Infinity'))\n\
1113 Decimal('NaN')\n\
1114 >>> ExtendedContext.quantize(Decimal('-0.1'), Decimal('1'))\n\
1115 Decimal('-0')\n\
1116 >>> ExtendedContext.quantize(Decimal('-0'), Decimal('1e+5'))\n\
1117 Decimal('-0E+5')\n\
1118 >>> ExtendedContext.quantize(Decimal('+35236450.6'), Decimal('1e-2'))\n\
1119 Decimal('NaN')\n\
1120 >>> ExtendedContext.quantize(Decimal('-35236450.6'), Decimal('1e-2'))\n\
1121 Decimal('NaN')
1122 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-1'))\n\
1123 Decimal('217.0')\n\
1124 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-0'))\n\
1125 Decimal('217')\n\
1126 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+1'))\n\
1127 Decimal('2.2E+2')\n\
1128 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+2'))\n\
1129 Decimal('2E+2')\n\
1130 >>> ExtendedContext.quantize(1, 2)\n\
1131 Decimal('1')\n\
1132 >>> ExtendedContext.quantize(Decimal(1), 2)\n\
1133 Decimal('1')\n\
1134 >>> ExtendedContext.quantize(1, Decimal(2))\n\
1135 Decimal('1')\n\
396 \n"); 1136 \n");
397 1137
400 Return Decimal(10), the radix (base) in which the Decimal class does\n\ 1140 Return Decimal(10), the radix (base) in which the Decimal class does\n\
401 all its arithmetic. Included for compatibility with the specification.\n\ 1141 all its arithmetic. Included for compatibility with the specification.\n\
1142 \n\
1144 Decimal('10')\n\
402 \n"); 1145 \n");
403 1146
404 PyDoc_STRVAR(doc_remainder_near, 1147 PyDoc_STRVAR(doc_remainder_near,
405 "remainder_near(\$self, /, other, context=None)\n--\n\n\ 1148 "remainder_near(\$self, /, other, context=None)\n--\n\n\
406 Return the remainder from dividing self by other. This differs from\n\ 1149 Returns to be \"a - b * n\", where n is the integer nearest the exact\n\
407 self % other in that the sign of the remainder is chosen so as to minimize\n\ 1150 value of \"x / b\" (if two integers are equally near then the even one\n\
408 its absolute value. More precisely, the return value is self - n * other\n\ 1151 is chosen). If the result is equal to 0 then its sign will be the\n\
409 where n is the integer nearest to the exact value of self / other, and\n\ 1152 sign of a.\n\
410 if two integers are equally near then the even one is chosen.\n\ 1153 \n\
411 \n\ 1154 This operation will fail under the same conditions as integer division\n\
412 If the result is zero then its sign will be the sign of self.\n\ 1155 (that is, if integer division on the same two operands would fail, the\n\
1156 remainder cannot be calculated).\n\
1157 \n\
1158 >>> ExtendedContext.remainder_near(Decimal('2.1'), Decimal('3'))\n\
1159 Decimal('-0.9')\n\
1160 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('6'))\n\
1161 Decimal('-2')\n\
1162 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('3'))\n\
1163 Decimal('1')\n\
1164 >>> ExtendedContext.remainder_near(Decimal('-10'), Decimal('3'))\n\
1165 Decimal('-1')\n\
1166 >>> ExtendedContext.remainder_near(Decimal('10.2'), Decimal('1'))\n\
1167 Decimal('0.2')\n\
1168 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('0.3'))\n\
1169 Decimal('0.1')
1170 >>> ExtendedContext.remainder_near(Decimal('3.6'), Decimal('1.3'))\n\
1171 Decimal('-0.3')\n\
1172 >>> ExtendedContext.remainder_near(3, 11)\n\
1173 Decimal('3')\n\
1174 >>> ExtendedContext.remainder_near(Decimal(3), 11)\n\
1175 Decimal('3')\n\
1176 >>> ExtendedContext.remainder_near(3, Decimal(11))\n\
1177 Decimal('3')\n\
413 \n"); 1178 \n");
414 1179
415 PyDoc_STRVAR(doc_rotate, 1180 PyDoc_STRVAR(doc_rotate,
416 "rotate(\$self, /, other, context=None)\n--\n\n\ 1181 "rotate(\$self, /, other, context=None)\n--\n\n\
417 Return the result of rotating the digits of the first operand by an amount\n\ 1182 Returns a rotated copy of a, b times.\n\
418 specified by the second operand. The second operand must be an integer in\n\ 1183 \n\
419 the range -precision through precision. The absolute value of the second\n\ 1184 The coefficient of the result is a rotated copy of the digits in\n\
420 operand gives the number of places to rotate. If the second operand is\n\ 1185 the coefficient of the first operand. The number of places of\n\
421 positive then rotation is to the left; otherwise rotation is to the right.\n\ 1186 rotation is taken from the absolute value of the second operand,\n\
422 The coefficient of the first operand is padded on the left with zeros to\n\ 1187 with the rotation being to the left if the second operand is\n\
423 length precision if necessary. The sign and exponent of the first operand are\n\ 1188 positive or to the right otherwise.\n\
424 unchanged.\n\ 1189 \n\
1190 >>> ExtendedContext.rotate(Decimal('34'), Decimal('8'))\n\
1191 Decimal('400000003')\n\
1192 >>> ExtendedContext.rotate(Decimal('12'), Decimal('9'))\n\
1193 Decimal('12')\n\
1194 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('-2'))\n\
1195 Decimal('891234567')\n\
1196 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('0'))\n\
1197 Decimal('123456789')\n\
1198 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('+2'))\n\
1199 Decimal('345678912')\n\
1200 >>> ExtendedContext.rotate(1333333, 1)\n\
1201 Decimal('13333330')\n\
1202 >>> ExtendedContext.rotate(Decimal(1333333), 1)\n\
1203 Decimal('13333330')\n\
1204 >>> ExtendedContext.rotate(1333333, Decimal(1))\n\
1205 Decimal('13333330')\n\
425 \n"); 1206 \n");
426 1207
427 PyDoc_STRVAR(doc_same_quantum, 1208 PyDoc_STRVAR(doc_same_quantum,
428 "same_quantum(\$self, /, other, context=None)\n--\n\n\ 1209 "same_quantum(\$self, /, other, context=None)\n--\n\n\
429 Test whether self and other have the same exponent or whether both are NaN.\n\ 1210 Returns True if the two operands have the same exponent.\n\
430 \n\ 1211 \n\
431 This operation is unaffected by context and is quiet: no flags are changed\n\ 1212 The result is never affected by either the sign or the coefficient of\n\
432 and no rounding is performed. As an exception, the C version may raise\n\ 1213 either operand.\n\
433 InvalidOperation if the second operand cannot be converted exactly.\n\ 1214 \n\
1215 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.001'))\n\
1216 False\n\
1217 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.01'))\n\
1218 True\n\
1219 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('1'))\n\
1220 False\n\
1221 >>> ExtendedContext.same_quantum(Decimal('Inf'), Decimal('-Inf'))
1222 True\n\
1223 >>> ExtendedContext.same_quantum(10000, -1)\n\
1224 True\n\
1225 >>> ExtendedContext.same_quantum(Decimal(10000), -1)\n\
1226 True\n\
1227 >>> ExtendedContext.same_quantum(10000, Decimal(-1))\n\
1228 True\n\
434 \n"); 1229 \n");
435 1230
436 PyDoc_STRVAR(doc_scaleb, 1231 PyDoc_STRVAR(doc_scaleb,
437 "scaleb(\$self, /, other, context=None)\n--\n\n\ 1232 "scaleb(\$self, /, other, context=None)\n--\n\n\
438 Return the first operand with the exponent adjusted the second. Equivalently,\n \ 1233 Returns the first operand after adding the second value its exp.\n\
439 return the first operand multiplied by 10**other. The second operand must be\n\ 1234 \n\
440 an integer.\n\ 1235 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('-2'))
1236 Decimal('0.0750')\n\
1237 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('0'))\n\
1238 Decimal('7.50')\n\
1239 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('3'))\n\
1240 Decimal('7.50E+3')\n\
1241 >>> ExtendedContext.scaleb(1, 4)\n\
1242 Decimal('1E+4')\n\
1243 >>> ExtendedContext.scaleb(Decimal(1), 4)\n\
1244 Decimal('1E+4')\n\
1245 >>> ExtendedContext.scaleb(1, Decimal(4))\n\
1246 Decimal('1E+4')\n\
441 \n"); 1247 \n");
442 1248
443 PyDoc_STRVAR(doc_shift, 1249 PyDoc_STRVAR(doc_shift,
444 "shift(\$self, /, other, context=None)\n--\n\n\ 1250 "shift(\$self, /, other, context=None)\n--\n\n\
445 Return the result of shifting the digits of the first operand by an amount\n\ 1251 Returns a shifted copy of a, b times.\n\
446 specified by the second operand. The second operand must be an integer in\n\ 1252 \n\
447 the range -precision through precision. The absolute value of the second\n\ 1253 The coefficient of the result is a shifted copy of the digits\n\
448 operand gives the number of places to shift. If the second operand is\n\ 1254 in the coefficient of the first operand. The number of places\n\
449 positive, then the shift is to the left; otherwise the shift is to the\n\ 1255 to shift is taken from the absolute value of the second operand,\n\
450 right. Digits shifted into the coefficient are zeros. The sign and exponent\n\ 1256 with the shift being to the left if the second operand is\n\
451 of the first operand are unchanged.\n\ 1257 positive or to the right otherwise. Digits shifted into the\n\
1258 coefficient are zeros.\n\
1259 \n\
1260 >>> ExtendedContext.shift(Decimal('34'), Decimal('8'))\n\
1261 Decimal('400000000')\n\
1262 >>> ExtendedContext.shift(Decimal('12'), Decimal('9'))\n\
1263 Decimal('0')\n\
1264 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('-2'))\n\
1265 Decimal('1234567')\n\
1266 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('0'))\n\
1267 Decimal('123456789')\n\
1268 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('+2'))\n\
1269 Decimal('345678900')\n\
1270 >>> ExtendedContext.shift(88888888, 2)\n\
1271 Decimal('888888800')\n\
1272 >>> ExtendedContext.shift(Decimal(88888888), 2)\n\
1273 Decimal('888888800')\n\
1274 >>> ExtendedContext.shift(88888888, Decimal(2))\n\
1275 Decimal('888888800')\n\
452 \n"); 1276 \n");
453 1277
454 PyDoc_STRVAR(doc_sqrt, 1278 PyDoc_STRVAR(doc_sqrt,
455 "sqrt(\$self, /, context=None)\n--\n\n\ 1279 "sqrt(\$self, /, context=None)\n--\n\n\
456 Return the square root of the argument to full precision. The result is\n\ 1280 Square root of a non-negative number to context precision.\n\
457 correctly rounded using the ROUND_HALF_EVEN rounding mode.\n\ 1281 \n\
1282 If the result must be inexact, it is rounded using the round-half-even\n\
1283 algorithm.\n\
1284 \n\
1285 >>> ExtendedContext.sqrt(Decimal('0'))\n\
1286 Decimal('0')\n\
1287 >>> ExtendedContext.sqrt(Decimal('-0'))\n\
1288 Decimal('-0')\n\
1289 >>> ExtendedContext.sqrt(Decimal('0.39'))\n\
1290 Decimal('0.624499800')\n\
1291 >>> ExtendedContext.sqrt(Decimal('100'))\n\
1292 Decimal('10')\n\
1293 >>> ExtendedContext.sqrt(Decimal('1'))\n\
1294 Decimal('1')\n\
1295 >>> ExtendedContext.sqrt(Decimal('1.0'))\n\
1296 Decimal('1.0')\n\
1297 >>> ExtendedContext.sqrt(Decimal('1.00'))\n\
1298 Decimal('1.0')\n\
1299 >>> ExtendedContext.sqrt(Decimal('7'))\n\
1300 Decimal('2.64575131')\n\
1301 >>> ExtendedContext.sqrt(Decimal('10'))\n\
1302 Decimal('3.16227766')\n\
1303 >>> ExtendedContext.sqrt(2)\n\
1304 Decimal('1.41421356')\n\
1305 >>> ExtendedContext.prec\n\
1306 9\n\
458 \n"); 1307 \n");
459 1308
460 PyDoc_STRVAR(doc_to_eng_string, 1309 PyDoc_STRVAR(doc_to_eng_string,
461 "to_eng_string(\$self, /, context=None)\n--\n\n\ 1310 "to_eng_string(\$self, /, context=None)\n--\n\n\
462 Convert to an engineering-type string. Engineering notation has an exponent\n\ 1311 Convert to a string, using engineering notation if an exponent is needed.\n\
463 which is a multiple of 3, so there are up to 3 digits left of the decimal\n\ 1312 \n\
464 place. For example, Decimal('123E+1') is converted to Decimal('1.23E+3').\n\ 1313 Engineering notation has an exponent which is a multiple of 3. This\n\
465 \n\ 1314 can leave up to 3 digits to the left of the decimal place and may\n\
1315 require the addition of either one or two trailing zeros.\n\
1316
466 The value of context.capitals determines whether the exponent sign is lower\n\ 1317 The value of context.capitals determines whether the exponent sign is lower\n\
467 or upper case. Otherwise, the context does not affect the operation.\n\ 1318 or upper case. Otherwise, the context does not affect the operation.\n\
1319 \n\
1320 >>> ExtendedContext.to_eng_string(Decimal('123E+1'))\n\
1321 '1.23E+3'\n\
1322 >>> ExtendedContext.to_eng_string(Decimal('123E+3'))\n\
1323 '123E+3'\n\
1324 >>> ExtendedContext.to_eng_string(Decimal('123E-10'))\n\
1325 '12.3E-9'\n\
1326 >>> ExtendedContext.to_eng_string(Decimal('-123E-12'))\n\
1327 '-123E-12'\n\
1328 >>> ExtendedContext.to_eng_string(Decimal('7E-7'))\n\
1329 '700E-9'\n\
1330 >>> ExtendedContext.to_eng_string(Decimal('7E+1'))\n\
1331 '70'\n\
1332 >>> ExtendedContext.to_eng_string(Decimal('0E+1'))\n\
1333 '0.00E+3'\n\
468 \n"); 1334 \n");
469 1335
470 PyDoc_STRVAR(doc_to_integral, 1336 PyDoc_STRVAR(doc_to_integral,
471 "to_integral(\$self, /, rounding=None, context=None)\n--\n\n\ 1337 "to_integral(\$self, /, rounding=None, context=None)\n--\n\n\
472 Identical to the to_integral_value() method. The to_integral() name has been\n\ 1338 Identical to the to_integral_value() method. The to_integral() name has been\n\
473 kept for compatibility with older versions.\n\ 1339 kept for compatibility with older versions.\n\
474 \n"); 1340 \n");
475 1341
476 PyDoc_STRVAR(doc_to_integral_exact, 1342 PyDoc_STRVAR(doc_to_integral_exact,
477 "to_integral_exact(\$self, /, rounding=None, context=None)\n--\n\n\ 1343 "to_integral_exact(\$self, /, rounding=None, context=None)\n--\n\n\
478 Round to the nearest integer, signaling Inexact or Rounded as appropriate if\n\ 1344 Rounds to an integer.
479 rounding occurs. The rounding mode is determined by the rounding parameter\n\ 1345 \n\
480 if given, else by the given context. If neither parameter is given, then the\n\ 1346 When the operand has a negative exponent, the result is the same\n\
481 rounding mode of the current default context is used.\n\ 1347 as using the quantize() operation using the given operand as the\n\
1348 left-hand-operand, 1E+0 as the right-hand-operand, and the precision\n\
1349 of the operand as the precision setting; Inexact and Rounded flags\n\
1350 are allowed in this operation. The rounding mode is taken from the\n\
1351 context.\n\
1352 \n\
1353 >>> ExtendedContext.to_integral_exact(Decimal('2.1'))\n\
1354 Decimal('2')\n\
1355 >>> ExtendedContext.to_integral_exact(Decimal('100'))\n\
1356 Decimal('100')\n\
1357 >>> ExtendedContext.to_integral_exact(Decimal('100.0'))\n\
1358 Decimal('100')\n\
1359 >>> ExtendedContext.to_integral_exact(Decimal('101.5'))\n\
1360 Decimal('102')\n\
1361 >>> ExtendedContext.to_integral_exact(Decimal('-101.5'))\n\
1362 Decimal('-102')\n\
1363 >>> ExtendedContext.to_integral_exact(Decimal('10E+5'))\n\
1364 Decimal('1.0E+6')\n\
1365 >>> ExtendedContext.to_integral_exact(Decimal('7.89E+77'))\n\
1366 Decimal('7.89E+77')\n\
1367 >>> ExtendedContext.to_integral_exact(Decimal('-Inf'))\n\
1368 Decimal('-Infinity')\n\
482 \n"); 1369 \n");
483 1370
484 PyDoc_STRVAR(doc_to_integral_value, 1371 PyDoc_STRVAR(doc_to_integral_value,
485 "to_integral_value(\$self, /, rounding=None, context=None)\n--\n\n\ 1372 "to_integral_value(\$self, /, rounding=None, context=None)\n--\n\n\
486 Round to the nearest integer without signaling Inexact or Rounded. The\n\ 1373 Rounds to an integer.\n\
487 rounding mode is determined by the rounding parameter if given, else by\n\ 1374 \n\
488 the given context. If neither parameter is given, then the rounding mode\n\ 1375 When the operand has a negative exponent, the result is the same\n\
489 of the current default context is used.\n\ 1376 as using the quantize() operation using the given operand as the\n\
1377 left-hand-operand, 1E+0 as the right-hand-operand, and the precision\n\
1378 of the operand as the precision setting, except that no flags will\n\
1379 be set. The rounding mode is taken from the context.\n\
1380 \n\
1381 >>> ExtendedContext.to_integral_value(Decimal('2.1'))\n\
1382 Decimal('2')\n\
1383 >>> ExtendedContext.to_integral_value(Decimal('100'))\n\
1384 Decimal('100')\n\
1385 >>> ExtendedContext.to_integral_value(Decimal('100.0'))\n\
1386 Decimal('100')\n\
1387 >>> ExtendedContext.to_integral_value(Decimal('101.5'))\n\
1388 Decimal('102')\n\
1389 >>> ExtendedContext.to_integral_value(Decimal('-101.5'))\n\
1390 Decimal('-102')\n\
1391 >>> ExtendedContext.to_integral_value(Decimal('10E+5'))\n\
1392 Decimal('1.0E+6')\n\
1393 >>> ExtendedContext.to_integral_value(Decimal('7.89E+77'))\n\
1394 Decimal('7.89E+77')\n\
1395 >>> ExtendedContext.to_integral_value(Decimal('-Inf'))\n\
1396 Decimal('-Infinity')\n\
490 \n"); 1397 \n");
491 1398
492 1399
493 /******************************************************************************/ 1400 /******************************************************************************/
494 /* Context Object and Methods */ 1401 /* Context Object and Methods */
495 /******************************************************************************/ 1402 /******************************************************************************/
496 1403
497 PyDoc_STRVAR(doc_context, 1404 PyDoc_STRVAR(doc_context,
498 "Context(prec=None, rounding=None, Emin=None, Emax=None, capitals=None, clamp=No ne, flags=None, traps=None)\n--\n\n\ 1405 "Context(prec=None, rounding=None, Emin=None, Emax=None, capitals=None, clamp=No ne, flags=None, traps=None)\n--\n\n\
499 The context affects almost all operations and controls rounding,\n\ 1406 The context affects almost all operations and controls rounding,\n\
(...skipping 372 matching lines...)
872 Round to an integer.\n\ 1779 Round to an integer.\n\
873 \n"); 1780 \n");
874 1781
875 PyDoc_STRVAR(doc_ctx_to_sci_string, 1782 PyDoc_STRVAR(doc_ctx_to_sci_string,
876 "to_sci_string(\$self, x, /)\n--\n\n\ 1783 "to_sci_string(\$self, x, /)\n--\n\n\
877 Convert a number to a string using scientific notation.\n\ 1784 Convert a number to a string using scientific notation.\n\
878 \n"); 1785 \n");
879 1786
880 1787
881 #endif /* DOCSTRINGS_H */ 1788 #endif /* DOCSTRINGS_H */
882
883
884
OLDNEW
« no previous file with comments | « Lib/_pydecimal.py ('k') | no next file » | no next file with comments »

This is Rietveld 894c83f36cb7+