| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="lib.html" title='Python Library Reference' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='index' href='genindex.html' title='Index' /> |
| 10 | <link rel='last' href='about.html' title='About this document...' /> |
| 11 | <link rel='help' href='about.html' title='About this document...' /> |
| 12 | <link rel="next" href="decimal-signals.html" /> |
| 13 | <link rel="prev" href="node178.html" /> |
| 14 | <link rel="parent" href="module-decimal.html" /> |
| 15 | <link rel="next" href="decimal-signals.html" /> |
| 16 | <meta name='aesop' content='information' /> |
| 17 | <title>5.6.3 Context objects </title> |
| 18 | </head> |
| 19 | <body> |
| 20 | <DIV CLASS="navigation"> |
| 21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 23 | <tr> |
| 24 | <td class='online-navigation'><a rel="prev" title="5.6.2 Decimal objects" |
| 25 | href="node178.html"><img src='../icons/previous.png' |
| 26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 27 | <td class='online-navigation'><a rel="parent" title="5.6 decimal " |
| 28 | href="module-decimal.html"><img src='../icons/up.png' |
| 29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 30 | <td class='online-navigation'><a rel="next" title="5.6.4 Signals" |
| 31 | href="decimal-signals.html"><img src='../icons/next.png' |
| 32 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 33 | <td align="center" width="100%">Python Library Reference</td> |
| 34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 35 | href="contents.html"><img src='../icons/contents.png' |
| 36 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 38 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 39 | <td class='online-navigation'><a rel="index" title="Index" |
| 40 | href="genindex.html"><img src='../icons/index.png' |
| 41 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 42 | </tr></table> |
| 43 | <div class='online-navigation'> |
| 44 | <b class="navlabel">Previous:</b> |
| 45 | <a class="sectref" rel="prev" href="node178.html">5.6.2 Decimal objects</A> |
| 46 | <b class="navlabel">Up:</b> |
| 47 | <a class="sectref" rel="parent" href="module-decimal.html">5.6 decimal </A> |
| 48 | <b class="navlabel">Next:</b> |
| 49 | <a class="sectref" rel="next" href="decimal-signals.html">5.6.4 Signals</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H2><A NAME="SECTION007630000000000000000"></A><A NAME="decimal-decimal"></A> |
| 56 | <BR> |
| 57 | 5.6.3 Context objects |
| 58 | </H2> |
| 59 | |
| 60 | <P> |
| 61 | Contexts are environments for arithmetic operations. They govern precision, |
| 62 | set rules for rounding, determine which signals are treated as exceptions, and |
| 63 | limit the range for exponents. |
| 64 | |
| 65 | <P> |
| 66 | Each thread has its own current context which is accessed or changed using |
| 67 | the <tt class="function">getcontext()</tt> and <tt class="function">setcontext()</tt> functions: |
| 68 | |
| 69 | <P> |
| 70 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 71 | <td><nobr><b><tt id='l2h-1208' xml:id='l2h-1208' class="function">getcontext</tt></b>(</nobr></td> |
| 72 | <td><var></var>)</td></tr></table></dt> |
| 73 | <dd> |
| 74 | Return the current context for the active thread. |
| 75 | </dl> |
| 76 | |
| 77 | <P> |
| 78 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 79 | <td><nobr><b><tt id='l2h-1209' xml:id='l2h-1209' class="function">setcontext</tt></b>(</nobr></td> |
| 80 | <td><var>c</var>)</td></tr></table></dt> |
| 81 | <dd> |
| 82 | Set the current context for the active thread to <var>c</var>. |
| 83 | </dl> |
| 84 | |
| 85 | <P> |
| 86 | New contexts can formed using the <tt class="class">Context</tt> constructor described below. |
| 87 | In addition, the module provides three pre-made contexts: |
| 88 | |
| 89 | <P> |
| 90 | <dl><dt><b><span class="typelabel">class</span> <tt id='l2h-1210' xml:id='l2h-1210' class="class">BasicContext</tt></b> |
| 91 | <dd> |
| 92 | This is a standard context defined by the General Decimal Arithmetic |
| 93 | Specification. Precision is set to nine. Rounding is set to |
| 94 | <tt class="constant">ROUND_HALF_UP</tt>. All flags are cleared. All traps are enabled |
| 95 | (treated as exceptions) except <tt class="constant">Inexact</tt>, <tt class="constant">Rounded</tt>, and |
| 96 | <tt class="constant">Subnormal</tt>. |
| 97 | |
| 98 | <P> |
| 99 | Because many of the traps are enabled, this context is useful for debugging. |
| 100 | </dl> |
| 101 | |
| 102 | <P> |
| 103 | <dl><dt><b><span class="typelabel">class</span> <tt id='l2h-1211' xml:id='l2h-1211' class="class">ExtendedContext</tt></b> |
| 104 | <dd> |
| 105 | This is a standard context defined by the General Decimal Arithmetic |
| 106 | Specification. Precision is set to nine. Rounding is set to |
| 107 | <tt class="constant">ROUND_HALF_EVEN</tt>. All flags are cleared. No traps are enabled |
| 108 | (so that exceptions are not raised during computations). |
| 109 | |
| 110 | <P> |
| 111 | Because the trapped are disabled, this context is useful for applications |
| 112 | that prefer to have result value of <tt class="constant">NaN</tt> or <tt class="constant">Infinity</tt> |
| 113 | instead of raising exceptions. This allows an application to complete a |
| 114 | run in the presence of conditions that would otherwise halt the program. |
| 115 | </dl> |
| 116 | |
| 117 | <P> |
| 118 | <dl><dt><b><span class="typelabel">class</span> <tt id='l2h-1212' xml:id='l2h-1212' class="class">DefaultContext</tt></b> |
| 119 | <dd> |
| 120 | This context is used by the <tt class="class">Context</tt> constructor as a prototype for |
| 121 | new contexts. Changing a field (such a precision) has the effect of |
| 122 | changing the default for new contexts creating by the <tt class="class">Context</tt> |
| 123 | constructor. |
| 124 | |
| 125 | <P> |
| 126 | This context is most useful in multi-threaded environments. Changing one of |
| 127 | the fields before threads are started has the effect of setting system-wide |
| 128 | defaults. Changing the fields after threads have started is not recommended |
| 129 | as it would require thread synchronization to prevent race conditions. |
| 130 | |
| 131 | <P> |
| 132 | In single threaded environments, it is preferable to not use this context |
| 133 | at all. Instead, simply create contexts explicitly as described below. |
| 134 | |
| 135 | <P> |
| 136 | The default values are precision=28, rounding=ROUND_HALF_EVEN, and enabled |
| 137 | traps for Overflow, InvalidOperation, and DivisionByZero. |
| 138 | </dl> |
| 139 | |
| 140 | <P> |
| 141 | In addition to the three supplied contexts, new contexts can be created |
| 142 | with the <tt class="class">Context</tt> constructor. |
| 143 | |
| 144 | <P> |
| 145 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 146 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-1213' xml:id='l2h-1213' class="class">Context</tt></b>(</nobr></td> |
| 147 | <td><var>prec=None, rounding=None, traps=None, |
| 148 | flags=None, Emin=None, Emax=None, capitals=1</var>)</td></tr></table></dt> |
| 149 | <dd> |
| 150 | Creates a new context. If a field is not specified or is <tt class="constant">None</tt>, |
| 151 | the default values are copied from the <tt class="constant">DefaultContext</tt>. If the |
| 152 | <var>flags</var> field is not specified or is <tt class="constant">None</tt>, all flags are |
| 153 | cleared. |
| 154 | |
| 155 | <P> |
| 156 | The <var>prec</var> field is a positive integer that sets the precision for |
| 157 | arithmetic operations in the context. |
| 158 | |
| 159 | <P> |
| 160 | The <var>rounding</var> option is one of: |
| 161 | |
| 162 | <UL> |
| 163 | <LI><tt class="constant">ROUND_CEILING</tt> (towards <tt class="constant">Infinity</tt>), |
| 164 | </LI> |
| 165 | <LI><tt class="constant">ROUND_DOWN</tt> (towards zero), |
| 166 | </LI> |
| 167 | <LI><tt class="constant">ROUND_FLOOR</tt> (towards <tt class="constant">-Infinity</tt>), |
| 168 | </LI> |
| 169 | <LI><tt class="constant">ROUND_HALF_DOWN</tt> (to nearest with ties going towards zero), |
| 170 | </LI> |
| 171 | <LI><tt class="constant">ROUND_HALF_EVEN</tt> (to nearest with ties going to nearest even integer), |
| 172 | </LI> |
| 173 | <LI><tt class="constant">ROUND_HALF_UP</tt> (to nearest with ties going away from zero), or |
| 174 | </LI> |
| 175 | <LI><tt class="constant">ROUND_UP</tt> (away from zero). |
| 176 | |
| 177 | </LI> |
| 178 | </UL> |
| 179 | |
| 180 | <P> |
| 181 | The <var>traps</var> and <var>flags</var> fields list any signals to be set. |
| 182 | Generally, new contexts should only set traps and leave the flags clear. |
| 183 | |
| 184 | <P> |
| 185 | The <var>Emin</var> and <var>Emax</var> fields are integers specifying the outer |
| 186 | limits allowable for exponents. |
| 187 | |
| 188 | <P> |
| 189 | The <var>capitals</var> field is either <tt class="constant">0</tt> or <tt class="constant">1</tt> (the |
| 190 | default). If set to <tt class="constant">1</tt>, exponents are printed with a capital |
| 191 | <tt class="constant">E</tt>; otherwise, a lowercase <tt class="constant">e</tt> is used: |
| 192 | <tt class="constant">Decimal('6.02e+23')</tt>. |
| 193 | </dl> |
| 194 | |
| 195 | <P> |
| 196 | The <tt class="class">Context</tt> class defines several general purpose methods as well as a |
| 197 | large number of methods for doing arithmetic directly in a given context. |
| 198 | |
| 199 | <P> |
| 200 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 201 | <td><nobr><b><tt id='l2h-1214' xml:id='l2h-1214' class="method">clear_flags</tt></b>(</nobr></td> |
| 202 | <td><var></var>)</td></tr></table></dt> |
| 203 | <dd> |
| 204 | Resets all of the flags to <tt class="constant">0</tt>. |
| 205 | </dl> |
| 206 | |
| 207 | <P> |
| 208 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 209 | <td><nobr><b><tt id='l2h-1215' xml:id='l2h-1215' class="method">copy</tt></b>(</nobr></td> |
| 210 | <td><var></var>)</td></tr></table></dt> |
| 211 | <dd> |
| 212 | Return a duplicate of the context. |
| 213 | </dl> |
| 214 | |
| 215 | <P> |
| 216 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 217 | <td><nobr><b><tt id='l2h-1216' xml:id='l2h-1216' class="method">create_decimal</tt></b>(</nobr></td> |
| 218 | <td><var>num</var>)</td></tr></table></dt> |
| 219 | <dd> |
| 220 | Creates a new Decimal instance from <var>num</var> but using <var>self</var> as |
| 221 | context. Unlike the <tt class="class">Decimal</tt> constructor, the context precision, |
| 222 | rounding method, flags, and traps are applied to the conversion. |
| 223 | |
| 224 | <P> |
| 225 | This is useful because constants are often given to a greater precision than |
| 226 | is needed by the application. Another benefit is that rounding immediately |
| 227 | eliminates unintended effects from digits beyond the current precision. |
| 228 | In the following example, using unrounded inputs means that adding zero |
| 229 | to a sum can change the result: |
| 230 | |
| 231 | <P> |
| 232 | <div class="verbatim"><pre> |
| 233 | >>> getcontext().prec = 3 |
| 234 | >>> Decimal("3.4445") + Decimal("1.0023") |
| 235 | Decimal("4.45") |
| 236 | >>> Decimal("3.4445") + Decimal(0) + Decimal("1.0023") |
| 237 | Decimal("4.44") |
| 238 | </pre></div> |
| 239 | |
| 240 | <P> |
| 241 | </dl> |
| 242 | |
| 243 | <P> |
| 244 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 245 | <td><nobr><b><tt id='l2h-1217' xml:id='l2h-1217' class="method">Etiny</tt></b>(</nobr></td> |
| 246 | <td><var></var>)</td></tr></table></dt> |
| 247 | <dd> |
| 248 | Returns a value equal to "<tt class="samp">Emin - prec + 1</tt>" which is the minimum |
| 249 | exponent value for subnormal results. When underflow occurs, the |
| 250 | exponent is set to <tt class="constant">Etiny</tt>. |
| 251 | </dl> |
| 252 | |
| 253 | <P> |
| 254 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 255 | <td><nobr><b><tt id='l2h-1218' xml:id='l2h-1218' class="method">Etop</tt></b>(</nobr></td> |
| 256 | <td><var></var>)</td></tr></table></dt> |
| 257 | <dd> |
| 258 | Returns a value equal to "<tt class="samp">Emax - prec + 1</tt>". |
| 259 | </dl> |
| 260 | |
| 261 | <P> |
| 262 | The usual approach to working with decimals is to create <tt class="class">Decimal</tt> |
| 263 | instances and then apply arithmetic operations which take place within the |
| 264 | current context for the active thread. An alternate approach is to use |
| 265 | context methods for calculating within a specific context. The methods are |
| 266 | similar to those for the <tt class="class">Decimal</tt> class and are only briefly recounted |
| 267 | here. |
| 268 | |
| 269 | <P> |
| 270 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 271 | <td><nobr><b><tt id='l2h-1219' xml:id='l2h-1219' class="method">abs</tt></b>(</nobr></td> |
| 272 | <td><var>x</var>)</td></tr></table></dt> |
| 273 | <dd> |
| 274 | Returns the absolute value of <var>x</var>. |
| 275 | </dl> |
| 276 | |
| 277 | <P> |
| 278 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 279 | <td><nobr><b><tt id='l2h-1220' xml:id='l2h-1220' class="method">add</tt></b>(</nobr></td> |
| 280 | <td><var>x, y</var>)</td></tr></table></dt> |
| 281 | <dd> |
| 282 | Return the sum of <var>x</var> and <var>y</var>. |
| 283 | </dl> |
| 284 | |
| 285 | <P> |
| 286 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 287 | <td><nobr><b><tt id='l2h-1221' xml:id='l2h-1221' class="method">compare</tt></b>(</nobr></td> |
| 288 | <td><var>x, y</var>)</td></tr></table></dt> |
| 289 | <dd> |
| 290 | Compares values numerically. |
| 291 | |
| 292 | <P> |
| 293 | Like <tt class="method">__cmp__()</tt> but returns a decimal instance: |
| 294 | <div class="verbatim"><pre> |
| 295 | a or b is a NaN ==> Decimal("NaN") |
| 296 | a < b ==> Decimal("-1") |
| 297 | a == b ==> Decimal("0") |
| 298 | a > b ==> Decimal("1") |
| 299 | </pre></div> |
| 300 | </dl> |
| 301 | |
| 302 | <P> |
| 303 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 304 | <td><nobr><b><tt id='l2h-1222' xml:id='l2h-1222' class="method">divide</tt></b>(</nobr></td> |
| 305 | <td><var>x, y</var>)</td></tr></table></dt> |
| 306 | <dd> |
| 307 | Return <var>x</var> divided by <var>y</var>. |
| 308 | </dl> |
| 309 | |
| 310 | <P> |
| 311 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 312 | <td><nobr><b><tt id='l2h-1223' xml:id='l2h-1223' class="method">divmod</tt></b>(</nobr></td> |
| 313 | <td><var>x, y</var>)</td></tr></table></dt> |
| 314 | <dd> |
| 315 | Divides two numbers and returns the integer part of the result. |
| 316 | </dl> |
| 317 | |
| 318 | <P> |
| 319 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 320 | <td><nobr><b><tt id='l2h-1224' xml:id='l2h-1224' class="method">max</tt></b>(</nobr></td> |
| 321 | <td><var>x, y</var>)</td></tr></table></dt> |
| 322 | <dd> |
| 323 | Compare two values numerically and return the maximum. |
| 324 | |
| 325 | <P> |
| 326 | If they are numerically equal then the left-hand operand is chosen as the |
| 327 | result. |
| 328 | </dl> |
| 329 | |
| 330 | <P> |
| 331 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 332 | <td><nobr><b><tt id='l2h-1225' xml:id='l2h-1225' class="method">min</tt></b>(</nobr></td> |
| 333 | <td><var>x, y</var>)</td></tr></table></dt> |
| 334 | <dd> |
| 335 | Compare two values numerically and return the minimum. |
| 336 | |
| 337 | <P> |
| 338 | If they are numerically equal then the left-hand operand is chosen as the |
| 339 | result. |
| 340 | </dl> |
| 341 | |
| 342 | <P> |
| 343 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 344 | <td><nobr><b><tt id='l2h-1226' xml:id='l2h-1226' class="method">minus</tt></b>(</nobr></td> |
| 345 | <td><var>x</var>)</td></tr></table></dt> |
| 346 | <dd> |
| 347 | Minus corresponds to the unary prefix minus operator in Python. |
| 348 | </dl> |
| 349 | |
| 350 | <P> |
| 351 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 352 | <td><nobr><b><tt id='l2h-1227' xml:id='l2h-1227' class="method">multiply</tt></b>(</nobr></td> |
| 353 | <td><var>x, y</var>)</td></tr></table></dt> |
| 354 | <dd> |
| 355 | Return the product of <var>x</var> and <var>y</var>. |
| 356 | </dl> |
| 357 | |
| 358 | <P> |
| 359 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 360 | <td><nobr><b><tt id='l2h-1228' xml:id='l2h-1228' class="method">normalize</tt></b>(</nobr></td> |
| 361 | <td><var>x</var>)</td></tr></table></dt> |
| 362 | <dd> |
| 363 | Normalize reduces an operand to its simplest form. |
| 364 | |
| 365 | <P> |
| 366 | Essentially a <tt class="method">plus</tt> operation with all trailing zeros removed from |
| 367 | the result. |
| 368 | </dl> |
| 369 | |
| 370 | <P> |
| 371 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 372 | <td><nobr><b><tt id='l2h-1229' xml:id='l2h-1229' class="method">plus</tt></b>(</nobr></td> |
| 373 | <td><var>x</var>)</td></tr></table></dt> |
| 374 | <dd> |
| 375 | Plus corresponds to the unary prefix plus operator in Python. This |
| 376 | operation applies the context precision and rounding, so it is |
| 377 | <em>not</em> an identity operation. |
| 378 | </dl> |
| 379 | |
| 380 | <P> |
| 381 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 382 | <td><nobr><b><tt id='l2h-1230' xml:id='l2h-1230' class="method">power</tt></b>(</nobr></td> |
| 383 | <td><var>x, y</var><big>[</big><var>, modulo</var><big>]</big><var></var>)</td></tr></table></dt> |
| 384 | <dd> |
| 385 | Return "<tt class="samp">x ** y</tt>" to the <var>modulo</var> if given. |
| 386 | |
| 387 | <P> |
| 388 | The right-hand operand must be a whole number whose integer part (after any |
| 389 | exponent has been applied) has no more than 9 digits and whose fractional |
| 390 | part (if any) is all zeros before any rounding. The operand may be positive, |
| 391 | negative, or zero; if negative, the absolute value of the power is used, and |
| 392 | the left-hand operand is inverted (divided into 1) before use. |
| 393 | |
| 394 | <P> |
| 395 | If the increased precision needed for the intermediate calculations exceeds |
| 396 | the capabilities of the implementation then an <tt class="constant">InvalidOperation</tt> |
| 397 | condition is signaled. |
| 398 | |
| 399 | <P> |
| 400 | If, when raising to a negative power, an underflow occurs during the |
| 401 | division into 1, the operation is not halted at that point but continues. |
| 402 | </dl> |
| 403 | |
| 404 | <P> |
| 405 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 406 | <td><nobr><b><tt id='l2h-1231' xml:id='l2h-1231' class="method">quantize</tt></b>(</nobr></td> |
| 407 | <td><var>x, y</var>)</td></tr></table></dt> |
| 408 | <dd> |
| 409 | Returns a value equal to <var>x</var> after rounding and having the exponent of |
| 410 | <var>y</var>. |
| 411 | |
| 412 | <P> |
| 413 | Unlike other operations, if the length of the coefficient after the quantize |
| 414 | operation would be greater than precision, then an |
| 415 | <tt class="constant">InvalidOperation</tt> is signaled. This guarantees that, unless there |
| 416 | is an error condition, the quantized exponent is always equal to that of the |
| 417 | right-hand operand. |
| 418 | |
| 419 | <P> |
| 420 | Also unlike other operations, quantize never signals Underflow, even |
| 421 | if the result is subnormal and inexact. |
| 422 | </dl> |
| 423 | |
| 424 | <P> |
| 425 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 426 | <td><nobr><b><tt id='l2h-1232' xml:id='l2h-1232' class="method">remainder</tt></b>(</nobr></td> |
| 427 | <td><var>x, y</var>)</td></tr></table></dt> |
| 428 | <dd> |
| 429 | Returns the remainder from integer division. |
| 430 | |
| 431 | <P> |
| 432 | The sign of the result, if non-zero, is the same as that of the original |
| 433 | dividend. |
| 434 | </dl> |
| 435 | |
| 436 | <P> |
| 437 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 438 | <td><nobr><b><tt id='l2h-1233' xml:id='l2h-1233' class="method">remainder_near</tt></b>(</nobr></td> |
| 439 | <td><var>x, y</var>)</td></tr></table></dt> |
| 440 | <dd> |
| 441 | Computed the modulo as either a positive or negative value depending |
| 442 | on which is closest to zero. For instance, |
| 443 | "<tt class="samp">Decimal(10).remainder_near(6)</tt>" returns <code>Decimal("-2")</code> |
| 444 | which is closer to zero than <code>Decimal("4")</code>. |
| 445 | |
| 446 | <P> |
| 447 | If both are equally close, the one chosen will have the same sign |
| 448 | as <var>self</var>. |
| 449 | </dl> |
| 450 | |
| 451 | <P> |
| 452 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 453 | <td><nobr><b><tt id='l2h-1234' xml:id='l2h-1234' class="method">same_quantum</tt></b>(</nobr></td> |
| 454 | <td><var>x, y</var>)</td></tr></table></dt> |
| 455 | <dd> |
| 456 | Test whether <var>x</var> and <var>y</var> have the same exponent or whether both are |
| 457 | <tt class="constant">NaN</tt>. |
| 458 | </dl> |
| 459 | |
| 460 | <P> |
| 461 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 462 | <td><nobr><b><tt id='l2h-1235' xml:id='l2h-1235' class="method">sqrt</tt></b>(</nobr></td> |
| 463 | <td><var></var>)</td></tr></table></dt> |
| 464 | <dd> |
| 465 | Return the square root to full precision. |
| 466 | </dl> |
| 467 | |
| 468 | <P> |
| 469 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 470 | <td><nobr><b><tt id='l2h-1236' xml:id='l2h-1236' class="method">subtract</tt></b>(</nobr></td> |
| 471 | <td><var>x, y</var>)</td></tr></table></dt> |
| 472 | <dd> |
| 473 | Return the difference between <var>x</var> and <var>y</var>. |
| 474 | </dl> |
| 475 | |
| 476 | <P> |
| 477 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 478 | <td><nobr><b><tt id='l2h-1237' xml:id='l2h-1237' class="method">to_eng_string</tt></b>(</nobr></td> |
| 479 | <td><var></var>)</td></tr></table></dt> |
| 480 | <dd> |
| 481 | Convert to engineering-type string. |
| 482 | |
| 483 | <P> |
| 484 | Engineering notation has an exponent which is a multiple of 3, so there |
| 485 | are up to 3 digits left of the decimal place. For example, converts |
| 486 | <code>Decimal('123E+1')</code> to <code>Decimal("1.23E+3")</code> |
| 487 | </dl> |
| 488 | |
| 489 | <P> |
| 490 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 491 | <td><nobr><b><tt id='l2h-1238' xml:id='l2h-1238' class="method">to_integral</tt></b>(</nobr></td> |
| 492 | <td><var>x</var>)</td></tr></table></dt> |
| 493 | <dd> |
| 494 | Rounds to the nearest integer without signaling <tt class="constant">Inexact</tt> |
| 495 | or <tt class="constant">Rounded</tt>. |
| 496 | </dl> |
| 497 | |
| 498 | <P> |
| 499 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 500 | <td><nobr><b><tt id='l2h-1239' xml:id='l2h-1239' class="method">to_sci_string</tt></b>(</nobr></td> |
| 501 | <td><var></var>)</td></tr></table></dt> |
| 502 | <dd> |
| 503 | Converts a number to a string using scientific notation. |
| 504 | </dl> |
| 505 | |
| 506 | <P> |
| 507 | |
| 508 | <DIV CLASS="navigation"> |
| 509 | <div class='online-navigation'> |
| 510 | <p></p><hr /> |
| 511 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 512 | <tr> |
| 513 | <td class='online-navigation'><a rel="prev" title="5.6.2 Decimal objects" |
| 514 | href="node178.html"><img src='../icons/previous.png' |
| 515 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 516 | <td class='online-navigation'><a rel="parent" title="5.6 decimal " |
| 517 | href="module-decimal.html"><img src='../icons/up.png' |
| 518 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 519 | <td class='online-navigation'><a rel="next" title="5.6.4 Signals" |
| 520 | href="decimal-signals.html"><img src='../icons/next.png' |
| 521 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 522 | <td align="center" width="100%">Python Library Reference</td> |
| 523 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 524 | href="contents.html"><img src='../icons/contents.png' |
| 525 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 526 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 527 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 528 | <td class='online-navigation'><a rel="index" title="Index" |
| 529 | href="genindex.html"><img src='../icons/index.png' |
| 530 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 531 | </tr></table> |
| 532 | <div class='online-navigation'> |
| 533 | <b class="navlabel">Previous:</b> |
| 534 | <a class="sectref" rel="prev" href="node178.html">5.6.2 Decimal objects</A> |
| 535 | <b class="navlabel">Up:</b> |
| 536 | <a class="sectref" rel="parent" href="module-decimal.html">5.6 decimal </A> |
| 537 | <b class="navlabel">Next:</b> |
| 538 | <a class="sectref" rel="next" href="decimal-signals.html">5.6.4 Signals</A> |
| 539 | </div> |
| 540 | </div> |
| 541 | <hr /> |
| 542 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 543 | </DIV> |
| 544 | <!--End of Navigation Panel--> |
| 545 | <ADDRESS> |
| 546 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 547 | </ADDRESS> |
| 548 | </BODY> |
| 549 | </HTML> |