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