Debian Codegraph @

Modules/_decimal/docstrings.h

raw
1 /*
2 * Copyright (c) 2001 Python Software Foundation. All Rights Reserved.
3 * Modified and extended by Stefan Krah.
4 */
5
6
7 #ifndef DOCSTRINGS_H
8 #define DOCSTRINGS_H
9
10
11 #include "pymacro.h"
12
13
14 /******************************************************************************/
15 /* Module */
16 /******************************************************************************/
17
18
19 PyDoc_STRVAR(doc__decimal,
20 "C decimal arithmetic module");
21
22 PyDoc_STRVAR(doc_getcontext,
23 "getcontext($module, /)\n--\n\n\
24 Get the current default context.\n\
25 \n");
26
27 PyDoc_STRVAR(doc_setcontext,
28 "setcontext($module, context, /)\n--\n\n\
29 Set a new default context.\n\
30 \n");
31
32 PyDoc_STRVAR(doc_localcontext,
33 "localcontext($module, /, ctx=None, **kwargs)\n--\n\n\
34 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\
36 exiting the with-statement. If no context is specified, a copy of the current\n\
37 default context is used.\n\
38 \n");
39
40 PyDoc_STRVAR(doc_ieee_context,
41 "IEEEContext($module, bits, /)\n--\n\n\
42 Return a context object initialized to the proper values for one of the\n\
43 IEEE interchange formats. The argument must be a multiple of 32 and less\n\
44 than IEEE_CONTEXT_MAX_BITS.\n\
45 \n");
46
47
48 /******************************************************************************/
49 /* Decimal Object and Methods */
50 /******************************************************************************/
51
52 PyDoc_STRVAR(doc_decimal,
53 "Decimal(value=\"0\", context=None)\n--\n\n\
54 Construct a new Decimal object. 'value' can be an integer, string, tuple,\n\
55 or another Decimal object. If no value is given, return Decimal('0'). The\n\
56 context does not affect the conversion and is only passed to determine if\n\
57 the InvalidOperation trap is active.\n\
58 \n");
59
60 PyDoc_STRVAR(doc_adjusted,
61 "adjusted($self, /)\n--\n\n\
62 Return the adjusted exponent of the number. Defined as exp + digits - 1.\n\
63 \n");
64
65 PyDoc_STRVAR(doc_as_tuple,
66 "as_tuple($self, /)\n--\n\n\
67 Return a tuple representation of the number.\n\
68 \n");
69
70 PyDoc_STRVAR(doc_as_integer_ratio,
71 "as_integer_ratio($self, /)\n--\n\n\
72 Decimal.as_integer_ratio() -> (int, int)\n\
73 \n\
74 Return a pair of integers, whose ratio is exactly equal to the original\n\
75 Decimal and with a positive denominator. The ratio is in lowest terms.\n\
76 Raise OverflowError on infinities and a ValueError on NaNs.\n\
77 \n");
78
79 PyDoc_STRVAR(doc_canonical,
80 "canonical($self, /)\n--\n\n\
81 Return the canonical encoding of the argument. Currently, the encoding\n\
82 of a Decimal instance is always canonical, so this operation returns its\n\
83 argument unchanged.\n\
84 \n");
85
86 PyDoc_STRVAR(doc_compare,
87 "compare($self, /, other, context=None)\n--\n\n\
88 Compare self to other. Return a decimal value:\n\
89 \n\
90 a or b is a NaN ==> Decimal('NaN')\n\
91 a < b ==> Decimal('-1')\n\
92 a == b ==> Decimal('0')\n\
93 a > b ==> Decimal('1')\n\
94 \n");
95
96 PyDoc_STRVAR(doc_compare_signal,
97 "compare_signal($self, /, other, context=None)\n--\n\n\
98 Identical to compare, except that all NaNs signal.\n\
99 \n");
100
101 PyDoc_STRVAR(doc_compare_total,
102 "compare_total($self, /, other, context=None)\n--\n\n\
103 Compare two operands using their abstract representation rather than\n\
104 their numerical value. Similar to the compare() method, but the result\n\
105 gives a total ordering on Decimal instances. Two Decimal instances with\n\
106 the same numeric value but different representations compare unequal\n\
107 in this ordering:\n\
108 \n\
109 >>> Decimal('12.0').compare_total(Decimal('12'))\n\
110 Decimal('-1')\n\
111 \n\
112 Quiet and signaling NaNs are also included in the total ordering. The result\n\
113 of this function is Decimal('0') if both operands have the same representation,\n\
114 Decimal('-1') if the first operand is lower in the total order than the second,\n\
115 and Decimal('1') if the first operand is higher in the total order than the\n\
116 second operand. See the specification for details of the total order.\n\
117 \n\
118 This operation is unaffected by context and is quiet: no flags are changed\n\
119 and no rounding is performed. As an exception, the C version may raise\n\
120 InvalidOperation if the second operand cannot be converted exactly.\n\
121 \n");
122
123 PyDoc_STRVAR(doc_compare_total_mag,
124 "compare_total_mag($self, /, other, context=None)\n--\n\n\
125 Compare two operands using their abstract representation rather than their\n\
126 value as in compare_total(), but ignoring the sign of each operand.\n\
127 \n\
128 x.compare_total_mag(y) is equivalent to x.copy_abs().compare_total(y.copy_abs()).\n\
129 \n\
130 This operation is unaffected by context and is quiet: no flags are changed\n\
131 and no rounding is performed. As an exception, the C version may raise\n\
132 InvalidOperation if the second operand cannot be converted exactly.\n\
133 \n");
134
135 PyDoc_STRVAR(doc_conjugate,
136 "conjugate($self, /)\n--\n\n\
137 Return self.\n\
138 \n");
139
140 PyDoc_STRVAR(doc_copy_abs,
141 "copy_abs($self, /)\n--\n\n\
142 Return the absolute value of the argument. This operation is unaffected by\n\
143 context and is quiet: no flags are changed and no rounding is performed.\n\
144 \n");
145
146 PyDoc_STRVAR(doc_copy_negate,
147 "copy_negate($self, /)\n--\n\n\
148 Return the negation of the argument. This operation is unaffected by context\n\
149 and is quiet: no flags are changed and no rounding is performed.\n\
150 \n");
151
152 PyDoc_STRVAR(doc_copy_sign,
153 "copy_sign($self, /, other, context=None)\n--\n\n\
154 Return a copy of the first operand with the sign set to be the same as the\n\
155 sign of the second operand. For example:\n\
156 \n\
157 >>> Decimal('2.3').copy_sign(Decimal('-1.5'))\n\
158 Decimal('-2.3')\n\
159 \n\
160 This operation is unaffected by context and is quiet: no flags are changed\n\
161 and no rounding is performed. As an exception, the C version may raise\n\
162 InvalidOperation if the second operand cannot be converted exactly.\n\
163 \n");
164
165 PyDoc_STRVAR(doc_exp,
166 "exp($self, /, context=None)\n--\n\n\
167 Return the value of the (natural) exponential function e**x at the given\n\
168 number. The function always uses the ROUND_HALF_EVEN mode and the result\n\
169 is correctly rounded.\n\
170 \n");
171
172 PyDoc_STRVAR(doc_from_float,
173 "from_float($type, f, /)\n--\n\n\
174 Class method that converts a float to a decimal number, exactly.\n\
175 Since 0.1 is not exactly representable in binary floating point,\n\
176 Decimal.from_float(0.1) is not the same as Decimal('0.1').\n\
177 \n\
178 >>> Decimal.from_float(0.1)\n\
179 Decimal('0.1000000000000000055511151231257827021181583404541015625')\n\
180 >>> Decimal.from_float(float('nan'))\n\
181 Decimal('NaN')\n\
182 >>> Decimal.from_float(float('inf'))\n\
183 Decimal('Infinity')\n\
184 >>> Decimal.from_float(float('-inf'))\n\
185 Decimal('-Infinity')\n\
186 \n\
187 \n");
188
189 PyDoc_STRVAR(doc_from_number,
190 "from_number($type, number, /)\n--\n\n\
191 Class method that converts a real number to a decimal number, exactly.\n\
192 \n\
193 >>> Decimal.from_number(314) # int\n\
194 Decimal('314')\n\
195 >>> Decimal.from_number(0.1) # float\n\
196 Decimal('0.1000000000000000055511151231257827021181583404541015625')\n\
197 >>> Decimal.from_number(Decimal('3.14')) # another decimal instance\n\
198 Decimal('3.14')\n\
199 \n\
200 \n");
201
202 PyDoc_STRVAR(doc_fma,
203 "fma($self, /, other, third, context=None)\n--\n\n\
204 Fused multiply-add. Return self*other+third with no rounding of the\n\
205 intermediate product self*other.\n\
206 \n\
207 >>> Decimal(2).fma(3, 5)\n\
208 Decimal('11')\n\
209 \n\
210 \n");
211
212 PyDoc_STRVAR(doc_is_canonical,
213 "is_canonical($self, /)\n--\n\n\
214 Return True if the argument is canonical and False otherwise. Currently,\n\
215 a Decimal instance is always canonical, so this operation always returns\n\
216 True.\n\
217 \n");
218
219 PyDoc_STRVAR(doc_is_finite,
220 "is_finite($self, /)\n--\n\n\
221 Return True if the argument is a finite number, and False if the argument\n\
222 is infinite or a NaN.\n\
223 \n");
224
225 PyDoc_STRVAR(doc_is_infinite,
226 "is_infinite($self, /)\n--\n\n\
227 Return True if the argument is either positive or negative infinity and\n\
228 False otherwise.\n\
229 \n");
230
231 PyDoc_STRVAR(doc_is_nan,
232 "is_nan($self, /)\n--\n\n\
233 Return True if the argument is a (quiet or signaling) NaN and False\n\
234 otherwise.\n\
235 \n");
236
237 PyDoc_STRVAR(doc_is_normal,
238 "is_normal($self, /, context=None)\n--\n\n\
239 Return True if the argument is a normal finite non-zero number with an\n\
240 adjusted exponent greater than or equal to Emin. Return False if the\n\
241 argument is zero, subnormal, infinite or a NaN.\n\
242 \n");
243
244 PyDoc_STRVAR(doc_is_qnan,
245 "is_qnan($self, /)\n--\n\n\
246 Return True if the argument is a quiet NaN, and False otherwise.\n\
247 \n");
248
249 PyDoc_STRVAR(doc_is_signed,
250 "is_signed($self, /)\n--\n\n\
251 Return True if the argument has a negative sign and False otherwise.\n\
252 Note that both zeros and NaNs can carry signs.\n\
253 \n");
254
255 PyDoc_STRVAR(doc_is_snan,
256 "is_snan($self, /)\n--\n\n\
257 Return True if the argument is a signaling NaN and False otherwise.\n\
258 \n");
259
260 PyDoc_STRVAR(doc_is_subnormal,
261 "is_subnormal($self, /, context=None)\n--\n\n\
262 Return True if the argument is subnormal, and False otherwise. A number is\n\
263 subnormal if it is non-zero, finite, and has an adjusted exponent less\n\
264 than Emin.\n\
265 \n");
266
267 PyDoc_STRVAR(doc_is_zero,
268 "is_zero($self, /)\n--\n\n\
269 Return True if the argument is a (positive or negative) zero and False\n\
270 otherwise.\n\
271 \n");
272
273 PyDoc_STRVAR(doc_ln,
274 "ln($self, /, context=None)\n--\n\n\
275 Return the natural (base e) logarithm of the operand. The function always\n\
276 uses the ROUND_HALF_EVEN mode and the result is correctly rounded.\n\
277 \n");
278
279 PyDoc_STRVAR(doc_log10,
280 "log10($self, /, context=None)\n--\n\n\
281 Return the base ten logarithm of the operand. The function always uses the\n\
282 ROUND_HALF_EVEN mode and the result is correctly rounded.\n\
283 \n");
284
285 PyDoc_STRVAR(doc_logb,
286 "logb($self, /, context=None)\n--\n\n\
287 For a non-zero number, return the adjusted exponent of the operand as a\n\
288 Decimal instance. If the operand is a zero, then Decimal('-Infinity') is\n\
289 returned and the DivisionByZero condition is raised. If the operand is\n\
290 an infinity then Decimal('Infinity') is returned.\n\
291 \n");
292
293 PyDoc_STRVAR(doc_logical_and,
294 "logical_and($self, /, other, context=None)\n--\n\n\
295 Applies an 'and' operation between self and other's digits.\n\n\
296 Both self and other must be logical numbers.\n\
297 \n");
298
299 PyDoc_STRVAR(doc_logical_invert,
300 "logical_invert($self, /, context=None)\n--\n\n\
301 Invert all its digits.\n\n\
302 The self must be logical number.\n\
303 \n");
304
305 PyDoc_STRVAR(doc_logical_or,
306 "logical_or($self, /, other, context=None)\n--\n\n\
307 Applies an 'or' operation between self and other's digits.\n\n\
308 Both self and other must be logical numbers. \n\
309 \n");
310
311 PyDoc_STRVAR(doc_logical_xor,
312 "logical_xor($self, /, other, context=None)\n--\n\n\
313 Applies an 'xor' operation between self and other's digits.\n\n\
314 Both self and other must be logical numbers.\n\
315 \n");
316
317 PyDoc_STRVAR(doc_max,
318 "max($self, /, other, context=None)\n--\n\n\
319 Maximum of self and other. If one operand is a quiet NaN and the other is\n\
320 numeric, the numeric operand is returned.\n\
321 \n");
322
323 PyDoc_STRVAR(doc_max_mag,
324 "max_mag($self, /, other, context=None)\n--\n\n\
325 Similar to the max() method, but the comparison is done using the absolute\n\
326 values of the operands.\n\
327 \n");
328
329 PyDoc_STRVAR(doc_min,
330 "min($self, /, other, context=None)\n--\n\n\
331 Minimum of self and other. If one operand is a quiet NaN and the other is\n\
332 numeric, the numeric operand is returned.\n\
333 \n");
334
335 PyDoc_STRVAR(doc_min_mag,
336 "min_mag($self, /, other, context=None)\n--\n\n\
337 Similar to the min() method, but the comparison is done using the absolute\n\
338 values of the operands.\n\
339 \n");
340
341 PyDoc_STRVAR(doc_next_minus,
342 "next_minus($self, /, context=None)\n--\n\n\
343 Return the largest number representable in the given context (or in the\n\
344 current default context if no context is given) that is smaller than the\n\
345 given operand.\n\
346 \n");
347
348 PyDoc_STRVAR(doc_next_plus,
349 "next_plus($self, /, context=None)\n--\n\n\
350 Return the smallest number representable in the given context (or in the\n\
351 current default context if no context is given) that is larger than the\n\
352 given operand.\n\
353 \n");
354
355 PyDoc_STRVAR(doc_next_toward,
356 "next_toward($self, /, other, context=None)\n--\n\n\
357 If the two operands are unequal, return the number closest to the first\n\
358 operand in the direction of the second operand. If both operands are\n\
359 numerically equal, return a copy of the first operand with the sign set\n\
360 to be the same as the sign of the second operand.\n\
361 \n");
362
363 PyDoc_STRVAR(doc_normalize,
364 "normalize($self, /, context=None)\n--\n\n\
365 Normalize the number by stripping the rightmost trailing zeros and\n\
366 converting any result equal to Decimal('0') to Decimal('0e0'). Used\n\
367 for producing canonical values for members of an equivalence class.\n\
368 For example, Decimal('32.100') and Decimal('0.321000e+2') both normalize\n\
369 to the equivalent value Decimal('32.1').\n\
370 \n");
371
372 PyDoc_STRVAR(doc_number_class,
373 "number_class($self, /, context=None)\n--\n\n\
374 Return a string describing the class of the operand. The returned value\n\
375 is one of the following ten strings:\n\
376 \n\
377 * '-Infinity', indicating that the operand is negative infinity.\n\
378 * '-Normal', indicating that the operand is a negative normal number.\n\
379 * '-Subnormal', indicating that the operand is negative and subnormal.\n\
380 * '-Zero', indicating that the operand is a negative zero.\n\
381 * '+Zero', indicating that the operand is a positive zero.\n\
382 * '+Subnormal', indicating that the operand is positive and subnormal.\n\
383 * '+Normal', indicating that the operand is a positive normal number.\n\
384 * '+Infinity', indicating that the operand is positive infinity.\n\
385 * 'NaN', indicating that the operand is a quiet NaN (Not a Number).\n\
386 * 'sNaN', indicating that the operand is a signaling NaN.\n\
387 \n\
388 \n");
389
390 PyDoc_STRVAR(doc_quantize,
391 "quantize($self, /, exp, rounding=None, context=None)\n--\n\n\
392 Return a value equal to the first operand after rounding and having the\n\
393 exponent of the second operand.\n\
394 \n\
395 >>> Decimal('1.41421356').quantize(Decimal('1.000'))\n\
396 Decimal('1.414')\n\
397 \n\
398 Unlike other operations, if the length of the coefficient after the quantize\n\
399 operation would be greater than precision, then an InvalidOperation is signaled.\n\
400 This guarantees that, unless there is an error condition, the quantized exponent\n\
401 is always equal to that of the right-hand operand.\n\
402 \n\
403 Also unlike other operations, quantize never signals Underflow, even if the\n\
404 result is subnormal and inexact.\n\
405 \n\
406 If the exponent of the second operand is larger than that of the first, then\n\
407 rounding may be necessary. In this case, the rounding mode is determined by the\n\
408 rounding argument if given, else by the given context argument; if neither\n\
409 argument is given, the rounding mode of the current thread's context is used.\n\
410 \n");
411
412 PyDoc_STRVAR(doc_radix,
413 "radix($self, /)\n--\n\n\
414 Return Decimal(10), the radix (base) in which the Decimal class does\n\
415 all its arithmetic. Included for compatibility with the specification.\n\
416 \n");
417
418 PyDoc_STRVAR(doc_remainder_near,
419 "remainder_near($self, /, other, context=None)\n--\n\n\
420 Return the remainder from dividing self by other. This differs from\n\
421 self % other in that the sign of the remainder is chosen so as to minimize\n\
422 its absolute value. More precisely, the return value is self - n * other\n\
423 where n is the integer nearest to the exact value of self / other, and\n\
424 if two integers are equally near then the even one is chosen.\n\
425 \n\
426 If the result is zero then its sign will be the sign of self.\n\
427 \n");
428
429 PyDoc_STRVAR(doc_rotate,
430 "rotate($self, /, other, context=None)\n--\n\n\
431 Return the result of rotating the digits of the first operand by an amount\n\
432 specified by the second operand. The second operand must be an integer in\n\
433 the range -precision through precision. The absolute value of the second\n\
434 operand gives the number of places to rotate. If the second operand is\n\
435 positive then rotation is to the left; otherwise rotation is to the right.\n\
436 The coefficient of the first operand is padded on the left with zeros to\n\
437 length precision if necessary. The sign and exponent of the first operand are\n\
438 unchanged.\n\
439 \n");
440
441 PyDoc_STRVAR(doc_same_quantum,
442 "same_quantum($self, /, other, context=None)\n--\n\n\
443 Test whether self and other have the same exponent or whether both are NaN.\n\
444 \n\
445 This operation is unaffected by context and is quiet: no flags are changed\n\
446 and no rounding is performed. As an exception, the C version may raise\n\
447 InvalidOperation if the second operand cannot be converted exactly.\n\
448 \n");
449
450 PyDoc_STRVAR(doc_scaleb,
451 "scaleb($self, /, other, context=None)\n--\n\n\
452 Return the first operand with the exponent adjusted the second. Equivalently,\n\
453 return the first operand multiplied by 10**other. The second operand must be\n\
454 an integer.\n\
455 \n");
456
457 PyDoc_STRVAR(doc_shift,
458 "shift($self, /, other, context=None)\n--\n\n\
459 Return the result of shifting the digits of the first operand by an amount\n\
460 specified by the second operand. The second operand must be an integer in\n\
461 the range -precision through precision. The absolute value of the second\n\
462 operand gives the number of places to shift. If the second operand is\n\
463 positive, then the shift is to the left; otherwise the shift is to the\n\
464 right. Digits shifted into the coefficient are zeros. The sign and exponent\n\
465 of the first operand are unchanged.\n\
466 \n");
467
468 PyDoc_STRVAR(doc_sqrt,
469 "sqrt($self, /, context=None)\n--\n\n\
470 Return the square root of the argument to full precision. The result is\n\
471 correctly rounded using the ROUND_HALF_EVEN rounding mode.\n\
472 \n");
473
474 PyDoc_STRVAR(doc_to_eng_string,
475 "to_eng_string($self, /, context=None)\n--\n\n\
476 Convert to an engineering-type string. Engineering notation has an exponent\n\
477 which is a multiple of 3, so there are up to 3 digits left of the decimal\n\
478 place. For example, Decimal('123E+1') is converted to Decimal('1.23E+3').\n\
479 \n\
480 The value of context.capitals determines whether the exponent sign is lower\n\
481 or upper case. Otherwise, the context does not affect the operation.\n\
482 \n");
483
484 PyDoc_STRVAR(doc_to_integral,
485 "to_integral($self, /, rounding=None, context=None)\n--\n\n\
486 Identical to the to_integral_value() method. The to_integral() name has been\n\
487 kept for compatibility with older versions.\n\
488 \n");
489
490 PyDoc_STRVAR(doc_to_integral_exact,
491 "to_integral_exact($self, /, rounding=None, context=None)\n--\n\n\
492 Round to the nearest integer, signaling Inexact or Rounded as appropriate if\n\
493 rounding occurs. The rounding mode is determined by the rounding parameter\n\
494 if given, else by the given context. If neither parameter is given, then the\n\
495 rounding mode of the current default context is used.\n\
496 \n");
497
498 PyDoc_STRVAR(doc_to_integral_value,
499 "to_integral_value($self, /, rounding=None, context=None)\n--\n\n\
500 Round to the nearest integer without signaling Inexact or Rounded. The\n\
501 rounding mode is determined by the rounding parameter if given, else by\n\
502 the given context. If neither parameter is given, then the rounding mode\n\
503 of the current default context is used.\n\
504 \n");
505
506
507 /******************************************************************************/
508 /* Context Object and Methods */
509 /******************************************************************************/
510
511 PyDoc_STRVAR(doc_context,
512 "Context(prec=None, rounding=None, Emin=None, Emax=None, capitals=None, clamp=None, flags=None, traps=None)\n--\n\n\
513 The context affects almost all operations and controls rounding,\n\
514 Over/Underflow, raising of exceptions and much more. A new context\n\
515 can be constructed as follows:\n\
516 \n\
517 >>> c = Context(prec=28, Emin=-425000000, Emax=425000000,\n\
518 ... rounding=ROUND_HALF_EVEN, capitals=1, clamp=1,\n\
519 ... traps=[InvalidOperation, DivisionByZero, Overflow],\n\
520 ... flags=[])\n\
521 >>>\n\
522 \n\
523 \n");
524
525 #ifdef EXTRA_FUNCTIONALITY
526 PyDoc_STRVAR(doc_ctx_apply,
527 "apply($self, x, /)\n--\n\n\
528 Apply self to Decimal x.\n\
529 \n");
530 #endif
531
532 PyDoc_STRVAR(doc_ctx_clear_flags,
533 "clear_flags($self, /)\n--\n\n\
534 Reset all flags to False.\n\
535 \n");
536
537 PyDoc_STRVAR(doc_ctx_clear_traps,
538 "clear_traps($self, /)\n--\n\n\
539 Set all traps to False.\n\
540 \n");
541
542 PyDoc_STRVAR(doc_ctx_copy,
543 "copy($self, /)\n--\n\n\
544 Return a duplicate of the context with all flags cleared.\n\
545 \n");
546
547 PyDoc_STRVAR(doc_ctx_copy_decimal,
548 "copy_decimal($self, x, /)\n--\n\n\
549 Return a copy of Decimal x.\n\
550 \n");
551
552 PyDoc_STRVAR(doc_ctx_create_decimal,
553 "create_decimal($self, num=\"0\", /)\n--\n\n\
554 Create a new Decimal instance from num, using self as the context. Unlike the\n\
555 Decimal constructor, this function observes the context limits.\n\
556 \n");
557
558 PyDoc_STRVAR(doc_ctx_create_decimal_from_float,
559 "create_decimal_from_float($self, f, /)\n--\n\n\
560 Create a new Decimal instance from float f. Unlike the Decimal.from_float()\n\
561 class method, this function observes the context limits.\n\
562 \n");
563
564 PyDoc_STRVAR(doc_ctx_Etiny,
565 "Etiny($self, /)\n--\n\n\
566 Return a value equal to Emin - prec + 1, which is the minimum exponent value\n\
567 for subnormal results. When underflow occurs, the exponent is set to Etiny.\n\
568 \n");
569
570 PyDoc_STRVAR(doc_ctx_Etop,
571 "Etop($self, /)\n--\n\n\
572 Return a value equal to Emax - prec + 1. This is the maximum exponent\n\
573 if the _clamp field of the context is set to 1 (IEEE clamp mode). Etop()\n\
574 must not be negative.\n\
575 \n");
576
577 PyDoc_STRVAR(doc_ctx_abs,
578 "abs($self, x, /)\n--\n\n\
579 Return the absolute value of x.\n\
580 \n");
581
582 PyDoc_STRVAR(doc_ctx_add,
583 "add($self, x, y, /)\n--\n\n\
584 Return the sum of x and y.\n\
585 \n");
586
587 PyDoc_STRVAR(doc_ctx_canonical,
588 "canonical($self, x, /)\n--\n\n\
589 Return a new instance of x.\n\
590 \n");
591
592 PyDoc_STRVAR(doc_ctx_compare,
593 "compare($self, x, y, /)\n--\n\n\
594 Compare x and y numerically.\n\
595 \n");
596
597 PyDoc_STRVAR(doc_ctx_compare_signal,
598 "compare_signal($self, x, y, /)\n--\n\n\
599 Compare x and y numerically. All NaNs signal.\n\
600 \n");
601
602 PyDoc_STRVAR(doc_ctx_compare_total,
603 "compare_total($self, x, y, /)\n--\n\n\
604 Compare x and y using their abstract representation.\n\
605 \n");
606
607 PyDoc_STRVAR(doc_ctx_compare_total_mag,
608 "compare_total_mag($self, x, y, /)\n--\n\n\
609 Compare x and y using their abstract representation, ignoring sign.\n\
610 \n");
611
612 PyDoc_STRVAR(doc_ctx_copy_abs,
613 "copy_abs($self, x, /)\n--\n\n\
614 Return a copy of x with the sign set to 0.\n\
615 \n");
616
617 PyDoc_STRVAR(doc_ctx_copy_negate,
618 "copy_negate($self, x, /)\n--\n\n\
619 Return a copy of x with the sign inverted.\n\
620 \n");
621
622 PyDoc_STRVAR(doc_ctx_copy_sign,
623 "copy_sign($self, x, y, /)\n--\n\n\
624 Copy the sign from y to x.\n\
625 \n");
626
627 PyDoc_STRVAR(doc_ctx_divide,
628 "divide($self, x, y, /)\n--\n\n\
629 Return x divided by y.\n\
630 \n");
631
632 PyDoc_STRVAR(doc_ctx_divide_int,
633 "divide_int($self, x, y, /)\n--\n\n\
634 Return x divided by y, truncated to an integer.\n\
635 \n");
636
637 PyDoc_STRVAR(doc_ctx_divmod,
638 "divmod($self, x, y, /)\n--\n\n\
639 Return quotient and remainder of the division x / y.\n\
640 \n");
641
642 PyDoc_STRVAR(doc_ctx_exp,
643 "exp($self, x, /)\n--\n\n\
644 Return e ** x.\n\
645 \n");
646
647 PyDoc_STRVAR(doc_ctx_fma,
648 "fma($self, x, y, z, /)\n--\n\n\
649 Return x multiplied by y, plus z.\n\
650 \n");
651
652 PyDoc_STRVAR(doc_ctx_is_canonical,
653 "is_canonical($self, x, /)\n--\n\n\
654 Return True if x is canonical, False otherwise.\n\
655 \n");
656
657 PyDoc_STRVAR(doc_ctx_is_finite,
658 "is_finite($self, x, /)\n--\n\n\
659 Return True if x is finite, False otherwise.\n\
660 \n");
661
662 PyDoc_STRVAR(doc_ctx_is_infinite,
663 "is_infinite($self, x, /)\n--\n\n\
664 Return True if x is infinite, False otherwise.\n\
665 \n");
666
667 PyDoc_STRVAR(doc_ctx_is_nan,
668 "is_nan($self, x, /)\n--\n\n\
669 Return True if x is a qNaN or sNaN, False otherwise.\n\
670 \n");
671
672 PyDoc_STRVAR(doc_ctx_is_normal,
673 "is_normal($self, x, /)\n--\n\n\
674 Return True if x is a normal number, False otherwise.\n\
675 \n");
676
677 PyDoc_STRVAR(doc_ctx_is_qnan,
678 "is_qnan($self, x, /)\n--\n\n\
679 Return True if x is a quiet NaN, False otherwise.\n\
680 \n");
681
682 PyDoc_STRVAR(doc_ctx_is_signed,
683 "is_signed($self, x, /)\n--\n\n\
684 Return True if x is negative, False otherwise.\n\
685 \n");
686
687 PyDoc_STRVAR(doc_ctx_is_snan,
688 "is_snan($self, x, /)\n--\n\n\
689 Return True if x is a signaling NaN, False otherwise.\n\
690 \n");
691
692 PyDoc_STRVAR(doc_ctx_is_subnormal,
693 "is_subnormal($self, x, /)\n--\n\n\
694 Return True if x is subnormal, False otherwise.\n\
695 \n");
696
697 PyDoc_STRVAR(doc_ctx_is_zero,
698 "is_zero($self, x, /)\n--\n\n\
699 Return True if x is a zero, False otherwise.\n\
700 \n");
701
702 PyDoc_STRVAR(doc_ctx_ln,
703 "ln($self, x, /)\n--\n\n\
704 Return the natural (base e) logarithm of x.\n\
705 \n");
706
707 PyDoc_STRVAR(doc_ctx_log10,
708 "log10($self, x, /)\n--\n\n\
709 Return the base 10 logarithm of x.\n\
710 \n");
711
712 PyDoc_STRVAR(doc_ctx_logb,
713 "logb($self, x, /)\n--\n\n\
714 Return the exponent of the magnitude of the operand's MSD.\n\
715 \n");
716
717 PyDoc_STRVAR(doc_ctx_logical_and,
718 "logical_and($self, x, y, /)\n--\n\n\
719 Applies the logical operation 'and' between each operand's digits.\n\n\
720 The operands must be both logical numbers.\n\n\
721 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('0'))\n\
722 Decimal('0')\n\
723 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('1'))\n\
724 Decimal('0')\n\
725 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('0'))\n\
726 Decimal('0')\n\
727 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('1'))\n\
728 Decimal('1')\n\
729 >>> ExtendedContext.logical_and(Decimal('1100'), Decimal('1010'))\n\
730 Decimal('1000')\n\
731 >>> ExtendedContext.logical_and(Decimal('1111'), Decimal('10'))\n\
732 Decimal('10')\n\
733 >>> ExtendedContext.logical_and(110, 1101)\n\
734 Decimal('100')\n\
735 >>> ExtendedContext.logical_and(Decimal(110), 1101)\n\
736 Decimal('100')\n\
737 >>> ExtendedContext.logical_and(110, Decimal(1101))\n\
738 Decimal('100')\n\
739 \n");
740
741 PyDoc_STRVAR(doc_ctx_logical_invert,
742 "logical_invert($self, x, /)\n--\n\n\
743 Invert all the digits in the operand.\n\n\
744 The operand must be a logical number.\n\n\
745 >>> ExtendedContext.logical_invert(Decimal('0'))\n\
746 Decimal('111111111')\n\
747 >>> ExtendedContext.logical_invert(Decimal('1'))\n\
748 Decimal('111111110')\n\
749 >>> ExtendedContext.logical_invert(Decimal('111111111'))\n\
750 Decimal('0')\n\
751 >>> ExtendedContext.logical_invert(Decimal('101010101'))\n\
752 Decimal('10101010')\n\
753 >>> ExtendedContext.logical_invert(1101)\n\
754 Decimal('111110010')\n\
755 \n");
756
757 PyDoc_STRVAR(doc_ctx_logical_or,
758 "logical_or($self, x, y, /)\n--\n\n\
759 Applies the logical operation 'or' between each operand's digits.\n\n\
760 The operands must be both logical numbers.\n\n\
761 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('0'))\n\
762 Decimal('0')\n\
763 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('1'))\n\
764 Decimal('1')\n\
765 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('0'))\n\
766 Decimal('1')\n\
767 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('1'))\n\
768 Decimal('1')\n\
769 >>> ExtendedContext.logical_or(Decimal('1100'), Decimal('1010'))\n\
770 Decimal('1110')\n\
771 >>> ExtendedContext.logical_or(Decimal('1110'), Decimal('10'))\n\
772 Decimal('1110')\n\
773 >>> ExtendedContext.logical_or(110, 1101)\n\
774 Decimal('1111')\n\
775 >>> ExtendedContext.logical_or(Decimal(110), 1101)\n\
776 Decimal('1111')\n\
777 >>> ExtendedContext.logical_or(110, Decimal(1101))\n\
778 Decimal('1111')\n\
779 \n");
780
781 PyDoc_STRVAR(doc_ctx_logical_xor,
782 "logical_xor($self, x, y, /)\n--\n\n\
783 Applies the logical operation 'xor' between each operand's digits.\n\n\
784 The operands must be both logical numbers.\n\n\
785 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('0'))\n\
786 Decimal('0')\n\
787 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('1'))\n\
788 Decimal('1')\n\
789 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('0'))\n\
790 Decimal('1')\n\
791 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('1'))\n\
792 Decimal('0')\n\
793 >>> ExtendedContext.logical_xor(Decimal('1100'), Decimal('1010'))\n\
794 Decimal('110')\n\
795 >>> ExtendedContext.logical_xor(Decimal('1111'), Decimal('10'))\n\
796 Decimal('1101')\n\
797 >>> ExtendedContext.logical_xor(110, 1101)\n\
798 Decimal('1011')\n\
799 >>> ExtendedContext.logical_xor(Decimal(110), 1101)\n\
800 Decimal('1011')\n\
801 >>> ExtendedContext.logical_xor(110, Decimal(1101))\n\
802 Decimal('1011')\n\
803 \n");
804
805 PyDoc_STRVAR(doc_ctx_max,
806 "max($self, x, y, /)\n--\n\n\
807 Compare the values numerically and return the maximum.\n\
808 \n");
809
810 PyDoc_STRVAR(doc_ctx_max_mag,
811 "max_mag($self, x, y, /)\n--\n\n\
812 Compare the values numerically with their sign ignored.\n\
813 \n");
814
815 PyDoc_STRVAR(doc_ctx_min,
816 "min($self, x, y, /)\n--\n\n\
817 Compare the values numerically and return the minimum.\n\
818 \n");
819
820 PyDoc_STRVAR(doc_ctx_min_mag,
821 "min_mag($self, x, y, /)\n--\n\n\
822 Compare the values numerically with their sign ignored.\n\
823 \n");
824
825 PyDoc_STRVAR(doc_ctx_minus,
826 "minus($self, x, /)\n--\n\n\
827 Minus corresponds to the unary prefix minus operator in Python, but applies\n\
828 the context to the result.\n\
829 \n");
830
831 PyDoc_STRVAR(doc_ctx_multiply,
832 "multiply($self, x, y, /)\n--\n\n\
833 Return the product of x and y.\n\
834 \n");
835
836 PyDoc_STRVAR(doc_ctx_next_minus,
837 "next_minus($self, x, /)\n--\n\n\
838 Return the largest representable number smaller than x.\n\
839 \n");
840
841 PyDoc_STRVAR(doc_ctx_next_plus,
842 "next_plus($self, x, /)\n--\n\n\
843 Return the smallest representable number larger than x.\n\
844 \n");
845
846 PyDoc_STRVAR(doc_ctx_next_toward,
847 "next_toward($self, x, y, /)\n--\n\n\
848 Return the number closest to x, in the direction towards y.\n\
849 \n");
850
851 PyDoc_STRVAR(doc_ctx_normalize,
852 "normalize($self, x, /)\n--\n\n\
853 Reduce x to its simplest form. Alias for reduce(x).\n\
854 \n");
855
856 PyDoc_STRVAR(doc_ctx_number_class,
857 "number_class($self, x, /)\n--\n\n\
858 Return an indication of the class of x.\n\
859 \n");
860
861 PyDoc_STRVAR(doc_ctx_plus,
862 "plus($self, x, /)\n--\n\n\
863 Plus corresponds to the unary prefix plus operator in Python, but applies\n\
864 the context to the result.\n\
865 \n");
866
867 PyDoc_STRVAR(doc_ctx_power,
868 "power($self, /, a, b, modulo=None)\n--\n\n\
869 Compute a**b. If 'a' is negative, then 'b' must be integral. The result\n\
870 will be inexact unless 'a' is integral and the result is finite and can\n\
871 be expressed exactly in 'precision' digits. In the Python version the\n\
872 result is always correctly rounded, in the C version the result is almost\n\
873 always correctly rounded.\n\
874 \n\
875 If modulo is given, compute (a**b) % modulo. The following restrictions\n\
876 hold:\n\
877 \n\
878 * all three arguments must be integral\n\
879 * 'b' must be nonnegative\n\
880 * at least one of 'a' or 'b' must be nonzero\n\
881 * modulo must be nonzero and less than 10**prec in absolute value\n\
882 \n\
883 \n");
884
885 PyDoc_STRVAR(doc_ctx_quantize,
886 "quantize($self, x, y, /)\n--\n\n\
887 Return a value equal to x (rounded), having the exponent of y.\n\
888 \n");
889
890 PyDoc_STRVAR(doc_ctx_radix,
891 "radix($self, /)\n--\n\n\
892 Return 10.\n\
893 \n");
894
895 PyDoc_STRVAR(doc_ctx_remainder,
896 "remainder($self, x, y, /)\n--\n\n\
897 Return the remainder from integer division. The sign of the result,\n\
898 if non-zero, is the same as that of the original dividend.\n\
899 \n");
900
901 PyDoc_STRVAR(doc_ctx_remainder_near,
902 "remainder_near($self, x, y, /)\n--\n\n\
903 Return x - y * n, where n is the integer nearest the exact value of x / y\n\
904 (if the result is 0 then its sign will be the sign of x).\n\
905 \n");
906
907 PyDoc_STRVAR(doc_ctx_rotate,
908 "rotate($self, x, y, /)\n--\n\n\
909 Return a copy of x, rotated by y places.\n\
910 \n");
911
912 PyDoc_STRVAR(doc_ctx_same_quantum,
913 "same_quantum($self, x, y, /)\n--\n\n\
914 Return True if the two operands have the same exponent.\n\
915 \n");
916
917 PyDoc_STRVAR(doc_ctx_scaleb,
918 "scaleb($self, x, y, /)\n--\n\n\
919 Return the first operand after adding the second value to its exp.\n\
920 \n");
921
922 PyDoc_STRVAR(doc_ctx_shift,
923 "shift($self, x, y, /)\n--\n\n\
924 Return a copy of x, shifted by y places.\n\
925 \n");
926
927 PyDoc_STRVAR(doc_ctx_sqrt,
928 "sqrt($self, x, /)\n--\n\n\
929 Square root of a non-negative number to context precision.\n\
930 \n");
931
932 PyDoc_STRVAR(doc_ctx_subtract,
933 "subtract($self, x, y, /)\n--\n\n\
934 Return the difference between x and y.\n\
935 \n");
936
937 PyDoc_STRVAR(doc_ctx_to_eng_string,
938 "to_eng_string($self, x, /)\n--\n\n\
939 Convert a number to a string, using engineering notation.\n\
940 \n");
941
942 PyDoc_STRVAR(doc_ctx_to_integral,
943 "to_integral($self, x, /)\n--\n\n\
944 Identical to to_integral_value(x).\n\
945 \n");
946
947 PyDoc_STRVAR(doc_ctx_to_integral_exact,
948 "to_integral_exact($self, x, /)\n--\n\n\
949 Round to an integer. Signal if the result is rounded or inexact.\n\
950 \n");
951
952 PyDoc_STRVAR(doc_ctx_to_integral_value,
953 "to_integral_value($self, x, /)\n--\n\n\
954 Round to an integer.\n\
955 \n");
956
957 PyDoc_STRVAR(doc_ctx_to_sci_string,
958 "to_sci_string($self, x, /)\n--\n\n\
959 Convert a number to a string using scientific notation.\n\
960 \n");
961
962
963 #endif /* DOCSTRINGS_H */
964
965
966