add hg and python

1 files changed, 1313 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libdecimal.tex b/sys/src/cmd/python/Doc/lib/libdecimal.tex
new file mode 100644
index 000000000..127eb1d47
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libdecimal.tex
@@ -0,0 +1,1313 @@
+\section{\module{decimal} ---
+         Decimal floating point arithmetic}
+
+\declaremodule{standard}{decimal}
+\modulesynopsis{Implementation of the General Decimal Arithmetic 
+Specification.}
+
+\moduleauthor{Eric Price}{eprice at tjhsst.edu}
+\moduleauthor{Facundo Batista}{facundo at taniquetil.com.ar}
+\moduleauthor{Raymond Hettinger}{python at rcn.com}
+\moduleauthor{Aahz}{aahz at pobox.com}
+\moduleauthor{Tim Peters}{tim.one at comcast.net}
+
+\sectionauthor{Raymond D. Hettinger}{python at rcn.com}
+
+\versionadded{2.4}
+
+The \module{decimal} module provides support for decimal floating point
+arithmetic.  It offers several advantages over the \class{float()} datatype:
+
+\begin{itemize}
+
+\item Decimal numbers can be represented exactly.  In contrast, numbers like
+\constant{1.1} do not have an exact representation in binary floating point.
+End users typically would not expect \constant{1.1} to display as
+\constant{1.1000000000000001} as it does with binary floating point.
+
+\item The exactness carries over into arithmetic.  In decimal floating point,
+\samp{0.1 + 0.1 + 0.1 - 0.3} is exactly equal to zero.  In binary floating
+point, result is \constant{5.5511151231257827e-017}.  While near to zero, the
+differences prevent reliable equality testing and differences can accumulate.
+For this reason, decimal would be preferred in accounting applications which
+have strict equality invariants.
+
+\item The decimal module incorporates a notion of significant places so that
+\samp{1.30 + 1.20} is \constant{2.50}.  The trailing zero is kept to indicate
+significance.  This is the customary presentation for monetary applications. For
+multiplication, the ``schoolbook'' approach uses all the figures in the
+multiplicands.  For instance, \samp{1.3 * 1.2} gives \constant{1.56} while
+\samp{1.30 * 1.20} gives \constant{1.5600}.
+
+\item Unlike hardware based binary floating point, the decimal module has a user
+settable precision (defaulting to 28 places) which can be as large as needed for
+a given problem:
+
+\begin{verbatim}
+>>> getcontext().prec = 6
+>>> Decimal(1) / Decimal(7)
+Decimal("0.142857")
+>>> getcontext().prec = 28
+>>> Decimal(1) / Decimal(7)
+Decimal("0.1428571428571428571428571429")
+\end{verbatim}
+
+\item Both binary and decimal floating point are implemented in terms of published
+standards.  While the built-in float type exposes only a modest portion of its
+capabilities, the decimal module exposes all required parts of the standard.
+When needed, the programmer has full control over rounding and signal handling.
+
+\end{itemize}
+
+
+The module design is centered around three concepts:  the decimal number, the
+context for arithmetic, and signals.
+
+A decimal number is immutable.  It has a sign, coefficient digits, and an
+exponent.  To preserve significance, the coefficient digits do not truncate
+trailing zeroes.  Decimals also include special values such as
+\constant{Infinity}, \constant{-Infinity}, and \constant{NaN}.  The standard
+also differentiates \constant{-0} from \constant{+0}.
+                                                   
+The context for arithmetic is an environment specifying precision, rounding
+rules, limits on exponents, flags indicating the results of operations,
+and trap enablers which determine whether signals are treated as
+exceptions.  Rounding options include \constant{ROUND_CEILING},
+\constant{ROUND_DOWN}, \constant{ROUND_FLOOR}, \constant{ROUND_HALF_DOWN},
+\constant{ROUND_HALF_EVEN}, \constant{ROUND_HALF_UP}, and \constant{ROUND_UP}.
+
+Signals are groups of exceptional conditions arising during the course of
+computation.  Depending on the needs of the application, signals may be
+ignored, considered as informational, or treated as exceptions. The signals in
+the decimal module are: \constant{Clamped}, \constant{InvalidOperation},
+\constant{DivisionByZero}, \constant{Inexact}, \constant{Rounded},
+\constant{Subnormal}, \constant{Overflow}, and \constant{Underflow}.
+
+For each signal there is a flag and a trap enabler.  When a signal is
+encountered, its flag is incremented from zero and, then, if the trap enabler
+is set to one, an exception is raised.  Flags are sticky, so the user
+needs to reset them before monitoring a calculation.
+
+
+\begin{seealso}
+  \seetext{IBM's General Decimal Arithmetic Specification,
+           \citetitle[http://www2.hursley.ibm.com/decimal/decarith.html]
+           {The General Decimal Arithmetic Specification}.}
+
+  \seetext{IEEE standard 854-1987,
+           \citetitle[http://www.cs.berkeley.edu/\textasciitilde ejr/projects/754/private/drafts/854-1987/dir.html]
+           {Unofficial IEEE 854 Text}.} 
+\end{seealso}
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Quick-start Tutorial \label{decimal-tutorial}}
+
+The usual start to using decimals is importing the module, viewing the current
+context with \function{getcontext()} and, if necessary, setting new values
+for precision, rounding, or enabled traps:
+
+\begin{verbatim}
+>>> from decimal import *
+>>> getcontext()
+Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
+        capitals=1, flags=[], traps=[Overflow, InvalidOperation,
+        DivisionByZero])
+
+>>> getcontext().prec = 7       # Set a new precision
+\end{verbatim}
+
+
+Decimal instances can be constructed from integers, strings, or tuples.  To
+create a Decimal from a \class{float}, first convert it to a string.  This
+serves as an explicit reminder of the details of the conversion (including
+representation error).  Decimal numbers include special values such as
+\constant{NaN} which stands for ``Not a number'', positive and negative
+\constant{Infinity}, and \constant{-0}.        
+
+\begin{verbatim}
+>>> Decimal(10)
+Decimal("10")
+>>> Decimal("3.14")
+Decimal("3.14")
+>>> Decimal((0, (3, 1, 4), -2))
+Decimal("3.14")
+>>> Decimal(str(2.0 ** 0.5))
+Decimal("1.41421356237")
+>>> Decimal("NaN")
+Decimal("NaN")
+>>> Decimal("-Infinity")
+Decimal("-Infinity")
+\end{verbatim}
+
+
+The significance of a new Decimal is determined solely by the number
+of digits input.  Context precision and rounding only come into play during
+arithmetic operations.
+
+\begin{verbatim}
+>>> getcontext().prec = 6
+>>> Decimal('3.0')
+Decimal("3.0")
+>>> Decimal('3.1415926535')
+Decimal("3.1415926535")
+>>> Decimal('3.1415926535') + Decimal('2.7182818285')
+Decimal("5.85987")
+>>> getcontext().rounding = ROUND_UP
+>>> Decimal('3.1415926535') + Decimal('2.7182818285')
+Decimal("5.85988")
+\end{verbatim}
+
+
+Decimals interact well with much of the rest of Python.  Here is a small
+decimal floating point flying circus:
+    
+\begin{verbatim}    
+>>> data = map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split())
+>>> max(data)
+Decimal("9.25")
+>>> min(data)
+Decimal("0.03")
+>>> sorted(data)
+[Decimal("0.03"), Decimal("1.00"), Decimal("1.34"), Decimal("1.87"),
+ Decimal("2.35"), Decimal("3.45"), Decimal("9.25")]
+>>> sum(data)
+Decimal("19.29")
+>>> a,b,c = data[:3]
+>>> str(a)
+'1.34'
+>>> float(a)
+1.3400000000000001
+>>> round(a, 1)     # round() first converts to binary floating point
+1.3
+>>> int(a)
+1
+>>> a * 5
+Decimal("6.70")
+>>> a * b
+Decimal("2.5058")
+>>> c % a
+Decimal("0.77")
+\end{verbatim}
+
+The \method{quantize()} method rounds a number to a fixed exponent.  This
+method is useful for monetary applications that often round results to a fixed
+number of places:
+
+\begin{verbatim} 
+>>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
+Decimal("7.32")
+>>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)
+Decimal("8")
+\end{verbatim}
+
+As shown above, the \function{getcontext()} function accesses the current
+context and allows the settings to be changed.  This approach meets the
+needs of most applications.
+
+For more advanced work, it may be useful to create alternate contexts using
+the Context() constructor.  To make an alternate active, use the
+\function{setcontext()} function.
+
+In accordance with the standard, the \module{Decimal} module provides two
+ready to use standard contexts, \constant{BasicContext} and
+\constant{ExtendedContext}. The former is especially useful for debugging
+because many of the traps are enabled:
+
+\begin{verbatim}
+>>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)
+>>> setcontext(myothercontext)
+>>> Decimal(1) / Decimal(7)
+Decimal("0.142857142857142857142857142857142857142857142857142857142857")
+
+>>> ExtendedContext
+Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
+        capitals=1, flags=[], traps=[])
+>>> setcontext(ExtendedContext)
+>>> Decimal(1) / Decimal(7)
+Decimal("0.142857143")
+>>> Decimal(42) / Decimal(0)
+Decimal("Infinity")
+
+>>> setcontext(BasicContext)
+>>> Decimal(42) / Decimal(0)
+Traceback (most recent call last):
+  File "<pyshell#143>", line 1, in -toplevel-
+    Decimal(42) / Decimal(0)
+DivisionByZero: x / 0
+\end{verbatim}
+
+
+Contexts also have signal flags for monitoring exceptional conditions
+encountered during computations.  The flags remain set until explicitly
+cleared, so it is best to clear the flags before each set of monitored
+computations by using the \method{clear_flags()} method.
+
+\begin{verbatim}
+>>> setcontext(ExtendedContext)
+>>> getcontext().clear_flags()
+>>> Decimal(355) / Decimal(113)
+Decimal("3.14159292")
+>>> getcontext()
+Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
+        capitals=1, flags=[Inexact, Rounded], traps=[])
+\end{verbatim}
+
+The \var{flags} entry shows that the rational approximation to \constant{Pi}
+was rounded (digits beyond the context precision were thrown away) and that
+the result is inexact (some of the discarded digits were non-zero).
+
+Individual traps are set using the dictionary in the \member{traps}
+field of a context:
+
+\begin{verbatim}
+>>> Decimal(1) / Decimal(0)
+Decimal("Infinity")
+>>> getcontext().traps[DivisionByZero] = 1
+>>> Decimal(1) / Decimal(0)
+Traceback (most recent call last):
+  File "<pyshell#112>", line 1, in -toplevel-
+    Decimal(1) / Decimal(0)
+DivisionByZero: x / 0
+\end{verbatim}
+
+Most programs adjust the current context only once, at the beginning of the
+program.  And, in many applications, data is converted to \class{Decimal} with
+a single cast inside a loop.  With context set and decimals created, the bulk
+of the program manipulates the data no differently than with other Python
+numeric types.
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Decimal objects \label{decimal-decimal}}
+
+\begin{classdesc}{Decimal}{\optional{value \optional{, context}}}
+  Constructs a new \class{Decimal} object based from \var{value}.
+
+  \var{value} can be an integer, string, tuple, or another \class{Decimal}
+  object. If no \var{value} is given, returns \code{Decimal("0")}.  If
+  \var{value} is a string, it should conform to the decimal numeric string
+  syntax:
+    
+  \begin{verbatim}
+    sign           ::=  '+' | '-'
+    digit          ::=  '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
+    indicator      ::=  'e' | 'E'
+    digits         ::=  digit [digit]...
+    decimal-part   ::=  digits '.' [digits] | ['.'] digits
+    exponent-part  ::=  indicator [sign] digits
+    infinity       ::=  'Infinity' | 'Inf'
+    nan            ::=  'NaN' [digits] | 'sNaN' [digits]
+    numeric-value  ::=  decimal-part [exponent-part] | infinity
+    numeric-string ::=  [sign] numeric-value | [sign] nan  
+  \end{verbatim}
+
+  If \var{value} is a \class{tuple}, it should have three components,
+  a sign (\constant{0} for positive or \constant{1} for negative),
+  a \class{tuple} of digits, and an integer exponent. For example,
+  \samp{Decimal((0, (1, 4, 1, 4), -3))} returns \code{Decimal("1.414")}.
+
+  The \var{context} precision does not affect how many digits are stored.
+  That is determined exclusively by the number of digits in \var{value}. For
+  example, \samp{Decimal("3.00000")} records all five zeroes even if the
+  context precision is only three.
+
+  The purpose of the \var{context} argument is determining what to do if
+  \var{value} is a malformed string.  If the context traps
+  \constant{InvalidOperation}, an exception is raised; otherwise, the
+  constructor returns a new Decimal with the value of \constant{NaN}.
+
+  Once constructed, \class{Decimal} objects are immutable.
+\end{classdesc}
+
+Decimal floating point objects share many properties with the other builtin
+numeric types such as \class{float} and \class{int}.  All of the usual
+math operations and special methods apply.  Likewise, decimal objects can
+be copied, pickled, printed, used as dictionary keys, used as set elements,
+compared, sorted, and coerced to another type (such as \class{float}
+or \class{long}).
+
+In addition to the standard numeric properties, decimal floating point objects
+also have a number of specialized methods:
+
+\begin{methoddesc}{adjusted}{}
+  Return the adjusted exponent after shifting out the coefficient's rightmost
+  digits until only the lead digit remains: \code{Decimal("321e+5").adjusted()}
+  returns seven.  Used for determining the position of the most significant
+  digit with respect to the decimal point.
+\end{methoddesc}
+
+\begin{methoddesc}{as_tuple}{}
+  Returns a tuple representation of the number:
+  \samp{(sign, digittuple, exponent)}.
+\end{methoddesc}
+
+\begin{methoddesc}{compare}{other\optional{, context}}
+  Compares like \method{__cmp__()} but returns a decimal instance:
+  \begin{verbatim}
+        a or b is a NaN ==> Decimal("NaN")
+        a < b           ==> Decimal("-1")
+        a == b          ==> Decimal("0")
+        a > b           ==> Decimal("1")
+  \end{verbatim}
+\end{methoddesc}
+
+\begin{methoddesc}{max}{other\optional{, context}}
+  Like \samp{max(self, other)} except that the context rounding rule
+  is applied before returning and that \constant{NaN} values are
+  either signalled or ignored (depending on the context and whether
+  they are signaling or quiet).
+\end{methoddesc}
+
+\begin{methoddesc}{min}{other\optional{, context}}
+  Like \samp{min(self, other)} except that the context rounding rule
+  is applied before returning and that \constant{NaN} values are
+  either signalled or ignored (depending on the context and whether
+  they are signaling or quiet).
+\end{methoddesc}
+
+\begin{methoddesc}{normalize}{\optional{context}}
+  Normalize the number by stripping the rightmost trailing zeroes and
+  converting any result equal to \constant{Decimal("0")} to
+  \constant{Decimal("0e0")}. Used for producing canonical values for members
+  of an equivalence class. For example, \code{Decimal("32.100")} and
+  \code{Decimal("0.321000e+2")} both normalize to the equivalent value
+  \code{Decimal("32.1")}.
+\end{methoddesc}                                              
+
+\begin{methoddesc}{quantize}
+  {exp \optional{, rounding\optional{, context\optional{, watchexp}}}}
+  Quantize makes the exponent the same as \var{exp}.  Searches for a
+  rounding method in \var{rounding}, then in \var{context}, and then
+  in the current context.
+
+  If \var{watchexp} is set (default), then an error is returned whenever
+  the resulting exponent is greater than \member{Emax} or less than
+  \member{Etiny}.
+\end{methoddesc} 
+
+\begin{methoddesc}{remainder_near}{other\optional{, context}}
+  Computes the modulo as either a positive or negative value depending
+  on which is closest to zero.  For instance,
+  \samp{Decimal(10).remainder_near(6)} returns \code{Decimal("-2")}
+  which is closer to zero than \code{Decimal("4")}.
+
+  If both are equally close, the one chosen will have the same sign
+  as \var{self}.
+\end{methoddesc}  
+
+\begin{methoddesc}{same_quantum}{other\optional{, context}}
+  Test whether self and other have the same exponent or whether both
+  are \constant{NaN}.
+\end{methoddesc}
+
+\begin{methoddesc}{sqrt}{\optional{context}}
+  Return the square root to full precision.
+\end{methoddesc}                    
+ 
+\begin{methoddesc}{to_eng_string}{\optional{context}}
+  Convert to an engineering-type string.
+
+  Engineering notation has an exponent which is a multiple of 3, so there
+  are up to 3 digits left of the decimal place.  For example, converts
+  \code{Decimal('123E+1')} to \code{Decimal("1.23E+3")}
+\end{methoddesc}  
+
+\begin{methoddesc}{to_integral}{\optional{rounding\optional{, context}}}                   
+  Rounds to the nearest integer without signaling \constant{Inexact}
+  or \constant{Rounded}.  If given, applies \var{rounding}; otherwise,
+  uses the rounding method in either the supplied \var{context} or the
+  current context.
+\end{methoddesc} 
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%            
+\subsection{Context objects \label{decimal-decimal}}
+
+Contexts are environments for arithmetic operations.  They govern precision,
+set rules for rounding, determine which signals are treated as exceptions, and
+limit the range for exponents.
+
+Each thread has its own current context which is accessed or changed using
+the \function{getcontext()} and \function{setcontext()} functions:
+
+\begin{funcdesc}{getcontext}{}
+  Return the current context for the active thread.
+\end{funcdesc}            
+
+\begin{funcdesc}{setcontext}{c}
+  Set the current context for the active thread to \var{c}.
+\end{funcdesc}  
+
+Beginning with Python 2.5, you can also use the \keyword{with} statement
+and the \function{localcontext()} function to temporarily change the
+active context.
+
+\begin{funcdesc}{localcontext}{\optional{c}}
+  Return a context manager that will set the current context for
+  the active thread to a copy of \var{c} on entry to the with-statement
+  and restore the previous context when exiting the with-statement. If
+  no context is specified, a copy of the current context is used.
+  \versionadded{2.5}
+
+  For example, the following code sets the current decimal precision
+  to 42 places, performs a calculation, and then automatically restores
+  the previous context:
+\begin{verbatim}
+    from __future__ import with_statement
+    from decimal import localcontext
+
+    with localcontext() as ctx:
+        ctx.prec = 42   # Perform a high precision calculation
+        s = calculate_something()
+    s = +s  # Round the final result back to the default precision
+\end{verbatim}
+\end{funcdesc}
+
+New contexts can also be created using the \class{Context} constructor
+described below. In addition, the module provides three pre-made
+contexts:
+
+\begin{classdesc*}{BasicContext}
+  This is a standard context defined by the General Decimal Arithmetic
+  Specification.  Precision is set to nine.  Rounding is set to
+  \constant{ROUND_HALF_UP}.  All flags are cleared.  All traps are enabled
+  (treated as exceptions) except \constant{Inexact}, \constant{Rounded}, and
+  \constant{Subnormal}.
+
+  Because many of the traps are enabled, this context is useful for debugging.
+\end{classdesc*}
+
+\begin{classdesc*}{ExtendedContext}
+  This is a standard context defined by the General Decimal Arithmetic
+  Specification.  Precision is set to nine.  Rounding is set to
+  \constant{ROUND_HALF_EVEN}.  All flags are cleared.  No traps are enabled
+  (so that exceptions are not raised during computations).
+
+  Because the trapped are disabled, this context is useful for applications
+  that prefer to have result value of \constant{NaN} or \constant{Infinity}
+  instead of raising exceptions.  This allows an application to complete a
+  run in the presence of conditions that would otherwise halt the program.
+\end{classdesc*}
+
+\begin{classdesc*}{DefaultContext}
+  This context is used by the \class{Context} constructor as a prototype for
+  new contexts.  Changing a field (such a precision) has the effect of
+  changing the default for new contexts creating by the \class{Context}
+  constructor.
+
+  This context is most useful in multi-threaded environments.  Changing one of
+  the fields before threads are started has the effect of setting system-wide
+  defaults.  Changing the fields after threads have started is not recommended
+  as it would require thread synchronization to prevent race conditions.
+
+  In single threaded environments, it is preferable to not use this context
+  at all.  Instead, simply create contexts explicitly as described below.
+
+  The default values are precision=28, rounding=ROUND_HALF_EVEN, and enabled
+  traps for Overflow, InvalidOperation, and DivisionByZero.
+\end{classdesc*}
+
+
+In addition to the three supplied contexts, new contexts can be created
+with the \class{Context} constructor.
+
+\begin{classdesc}{Context}{prec=None, rounding=None, traps=None,
+        flags=None, Emin=None, Emax=None, capitals=1}
+  Creates a new context.  If a field is not specified or is \constant{None},
+  the default values are copied from the \constant{DefaultContext}.  If the
+  \var{flags} field is not specified or is \constant{None}, all flags are
+  cleared.
+
+  The \var{prec} field is a positive integer that sets the precision for
+  arithmetic operations in the context.
+
+  The \var{rounding} option is one of:
+  \begin{itemize}
+  \item \constant{ROUND_CEILING} (towards \constant{Infinity}),
+  \item \constant{ROUND_DOWN} (towards zero),
+  \item \constant{ROUND_FLOOR} (towards \constant{-Infinity}),
+  \item \constant{ROUND_HALF_DOWN} (to nearest with ties going towards zero),
+  \item \constant{ROUND_HALF_EVEN} (to nearest with ties going to nearest even integer),
+  \item \constant{ROUND_HALF_UP} (to nearest with ties going away from zero), or
+  \item \constant{ROUND_UP} (away from zero).
+  \end{itemize}
+
+  The \var{traps} and \var{flags} fields list any signals to be set.
+  Generally, new contexts should only set traps and leave the flags clear.
+
+  The \var{Emin} and \var{Emax} fields are integers specifying the outer
+  limits allowable for exponents.
+
+  The \var{capitals} field is either \constant{0} or \constant{1} (the
+  default). If set to \constant{1}, exponents are printed with a capital
+  \constant{E}; otherwise, a lowercase \constant{e} is used:
+  \constant{Decimal('6.02e+23')}.
+\end{classdesc}
+
+The \class{Context} class defines several general purpose methods as well as a
+large number of methods for doing arithmetic directly in a given context.
+
+\begin{methoddesc}{clear_flags}{}
+  Resets all of the flags to \constant{0}.
+\end{methoddesc}  
+
+\begin{methoddesc}{copy}{}
+  Return a duplicate of the context.
+\end{methoddesc}  
+
+\begin{methoddesc}{create_decimal}{num}
+  Creates a new Decimal instance from \var{num} but using \var{self} as
+  context. Unlike the \class{Decimal} constructor, the context precision,
+  rounding method, flags, and traps are applied to the conversion.
+
+  This is useful because constants are often given to a greater precision than
+  is needed by the application.  Another benefit is that rounding immediately
+  eliminates unintended effects from digits beyond the current precision.
+  In the following example, using unrounded inputs means that adding zero
+  to a sum can change the result:
+
+  \begin{verbatim}
+    >>> getcontext().prec = 3
+    >>> Decimal("3.4445") + Decimal("1.0023")
+    Decimal("4.45")
+    >>> Decimal("3.4445") + Decimal(0) + Decimal("1.0023")
+    Decimal("4.44")
+  \end{verbatim}
+      
+\end{methoddesc} 
+
+\begin{methoddesc}{Etiny}{}
+  Returns a value equal to \samp{Emin - prec + 1} which is the minimum
+  exponent value for subnormal results.  When underflow occurs, the
+  exponent is set to \constant{Etiny}.
+\end{methoddesc} 
+
+\begin{methoddesc}{Etop}{}
+  Returns a value equal to \samp{Emax - prec + 1}.
+\end{methoddesc} 
+
+
+The usual approach to working with decimals is to create \class{Decimal}
+instances and then apply arithmetic operations which take place within the
+current context for the active thread.  An alternate approach is to use
+context methods for calculating within a specific context.  The methods are
+similar to those for the \class{Decimal} class and are only briefly recounted
+here.
+
+\begin{methoddesc}{abs}{x}
+  Returns the absolute value of \var{x}.
+\end{methoddesc}
+
+\begin{methoddesc}{add}{x, y}
+  Return the sum of \var{x} and \var{y}.
+\end{methoddesc}
+   
+\begin{methoddesc}{compare}{x, y}
+  Compares values numerically.
+  
+  Like \method{__cmp__()} but returns a decimal instance:
+  \begin{verbatim}
+        a or b is a NaN ==> Decimal("NaN")
+        a < b           ==> Decimal("-1")
+        a == b          ==> Decimal("0")
+        a > b           ==> Decimal("1")
+  \end{verbatim}                                          
+\end{methoddesc}
+
+\begin{methoddesc}{divide}{x, y}
+  Return \var{x} divided by \var{y}.
+\end{methoddesc}   
+  
+\begin{methoddesc}{divmod}{x, y}
+  Divides two numbers and returns the integer part of the result.
+\end{methoddesc} 
+
+\begin{methoddesc}{max}{x, y}
+  Compare two values numerically and return the maximum.
+
+  If they are numerically equal then the left-hand operand is chosen as the
+  result.
+\end{methoddesc} 
+ 
+\begin{methoddesc}{min}{x, y}
+  Compare two values numerically and return the minimum.
+
+  If they are numerically equal then the left-hand operand is chosen as the
+  result.
+\end{methoddesc}
+
+\begin{methoddesc}{minus}{x}
+  Minus corresponds to the unary prefix minus operator in Python.
+\end{methoddesc}
+
+\begin{methoddesc}{multiply}{x, y}
+  Return the product of \var{x} and \var{y}.
+\end{methoddesc}
+
+\begin{methoddesc}{normalize}{x}
+  Normalize reduces an operand to its simplest form.
+
+  Essentially a \method{plus} operation with all trailing zeros removed from
+  the result.
+\end{methoddesc}
+  
+\begin{methoddesc}{plus}{x}
+  Plus corresponds to the unary prefix plus operator in Python.  This
+  operation applies the context precision and rounding, so it is
+  \emph{not} an identity operation.
+\end{methoddesc}
+
+\begin{methoddesc}{power}{x, y\optional{, modulo}}
+  Return \samp{x ** y} to the \var{modulo} if given.
+
+  The right-hand operand must be a whole number whose integer part (after any
+  exponent has been applied) has no more than 9 digits and whose fractional
+  part (if any) is all zeros before any rounding. The operand may be positive,
+  negative, or zero; if negative, the absolute value of the power is used, and
+  the left-hand operand is inverted (divided into 1) before use.
+
+  If the increased precision needed for the intermediate calculations exceeds
+  the capabilities of the implementation then an \constant{InvalidOperation}
+  condition is signaled.
+
+  If, when raising to a negative power, an underflow occurs during the
+  division into 1, the operation is not halted at that point but continues. 
+\end{methoddesc}
+
+\begin{methoddesc}{quantize}{x, y}
+  Returns a value equal to \var{x} after rounding and having the exponent of
+  \var{y}.
+
+  Unlike other operations, if the length of the coefficient after the quantize
+  operation would be greater than precision, then an
+  \constant{InvalidOperation} is signaled. This guarantees that, unless there
+  is an error condition, the quantized exponent is always equal to that of the
+  right-hand operand.
+
+  Also unlike other operations, quantize never signals Underflow, even
+  if the result is subnormal and inexact.  
+\end{methoddesc} 
+
+\begin{methoddesc}{remainder}{x, y}
+  Returns the remainder from integer division.
+
+  The sign of the result, if non-zero, is the same as that of the original
+  dividend. 
+\end{methoddesc}
+ 
+\begin{methoddesc}{remainder_near}{x, y}
+  Computed the modulo as either a positive or negative value depending
+  on which is closest to zero.  For instance,
+  \samp{Decimal(10).remainder_near(6)} returns \code{Decimal("-2")}
+  which is closer to zero than \code{Decimal("4")}.
+
+  If both are equally close, the one chosen will have the same sign
+  as \var{self}.
+\end{methoddesc}
+
+\begin{methoddesc}{same_quantum}{x, y}
+  Test whether \var{x} and \var{y} have the same exponent or whether both are
+  \constant{NaN}.
+\end{methoddesc}
+
+\begin{methoddesc}{sqrt}{x}
+  Return the square root of \var{x} to full precision.
+\end{methoddesc}                    
+
+\begin{methoddesc}{subtract}{x, y}
+  Return the difference between \var{x} and \var{y}.
+\end{methoddesc}
+ 
+\begin{methoddesc}{to_eng_string}{}
+  Convert to engineering-type string.
+
+  Engineering notation has an exponent which is a multiple of 3, so there
+  are up to 3 digits left of the decimal place.  For example, converts
+  \code{Decimal('123E+1')} to \code{Decimal("1.23E+3")}
+\end{methoddesc}  
+
+\begin{methoddesc}{to_integral}{x}                  
+  Rounds to the nearest integer without signaling \constant{Inexact}
+  or \constant{Rounded}.                                        
+\end{methoddesc} 
+
+\begin{methoddesc}{to_sci_string}{x}
+  Converts a number to a string using scientific notation.
+\end{methoddesc} 
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%            
+\subsection{Signals \label{decimal-signals}}
+
+Signals represent conditions that arise during computation.
+Each corresponds to one context flag and one context trap enabler.
+
+The context flag is incremented whenever the condition is encountered.
+After the computation, flags may be checked for informational
+purposes (for instance, to determine whether a computation was exact).
+After checking the flags, be sure to clear all flags before starting
+the next computation.
+
+If the context's trap enabler is set for the signal, then the condition
+causes a Python exception to be raised.  For example, if the
+\class{DivisionByZero} trap is set, then a \exception{DivisionByZero}
+exception is raised upon encountering the condition.
+
+
+\begin{classdesc*}{Clamped}
+    Altered an exponent to fit representation constraints.
+
+    Typically, clamping occurs when an exponent falls outside the context's
+    \member{Emin} and \member{Emax} limits.  If possible, the exponent is
+    reduced to fit by adding zeroes to the coefficient.
+\end{classdesc*}
+
+\begin{classdesc*}{DecimalException}
+    Base class for other signals and a subclass of
+    \exception{ArithmeticError}.
+\end{classdesc*}
+
+\begin{classdesc*}{DivisionByZero}
+    Signals the division of a non-infinite number by zero.
+
+    Can occur with division, modulo division, or when raising a number to a
+    negative power.  If this signal is not trapped, returns
+    \constant{Infinity} or \constant{-Infinity} with the sign determined by
+    the inputs to the calculation.
+\end{classdesc*}
+
+\begin{classdesc*}{Inexact}
+    Indicates that rounding occurred and the result is not exact.
+
+    Signals when non-zero digits were discarded during rounding. The rounded
+    result is returned.  The signal flag or trap is used to detect when
+    results are inexact.
+\end{classdesc*}
+
+\begin{classdesc*}{InvalidOperation}
+    An invalid operation was performed.
+
+    Indicates that an operation was requested that does not make sense.
+    If not trapped, returns \constant{NaN}.  Possible causes include:
+
+    \begin{verbatim}
+        Infinity - Infinity
+        0 * Infinity
+        Infinity / Infinity
+        x % 0
+        Infinity % x
+        x._rescale( non-integer )
+        sqrt(-x) and x > 0
+        0 ** 0
+        x ** (non-integer)
+        x ** Infinity      
+    \end{verbatim}    
+\end{classdesc*}
+
+\begin{classdesc*}{Overflow}
+    Numerical overflow.
+
+    Indicates the exponent is larger than \member{Emax} after rounding has
+    occurred.  If not trapped, the result depends on the rounding mode, either
+    pulling inward to the largest representable finite number or rounding
+    outward to \constant{Infinity}.  In either case, \class{Inexact} and
+    \class{Rounded} are also signaled.   
+\end{classdesc*}
+
+\begin{classdesc*}{Rounded}
+    Rounding occurred though possibly no information was lost.
+
+    Signaled whenever rounding discards digits; even if those digits are
+    zero (such as rounding \constant{5.00} to \constant{5.0}).   If not
+    trapped, returns the result unchanged.  This signal is used to detect
+    loss of significant digits.
+\end{classdesc*}
+
+\begin{classdesc*}{Subnormal}
+    Exponent was lower than \member{Emin} prior to rounding.
+          
+    Occurs when an operation result is subnormal (the exponent is too small).
+    If not trapped, returns the result unchanged.
+\end{classdesc*}
+
+\begin{classdesc*}{Underflow}
+    Numerical underflow with result rounded to zero.
+
+    Occurs when a subnormal result is pushed to zero by rounding.
+    \class{Inexact} and \class{Subnormal} are also signaled.
+\end{classdesc*}
+
+The following table summarizes the hierarchy of signals:
+
+\begin{verbatim}    
+    exceptions.ArithmeticError(exceptions.StandardError)
+        DecimalException
+            Clamped
+            DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
+            Inexact
+                Overflow(Inexact, Rounded)
+                Underflow(Inexact, Rounded, Subnormal)
+            InvalidOperation
+            Rounded
+            Subnormal
+\end{verbatim}            
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Floating Point Notes \label{decimal-notes}}
+
+\subsubsection{Mitigating round-off error with increased precision}
+
+The use of decimal floating point eliminates decimal representation error
+(making it possible to represent \constant{0.1} exactly); however, some
+operations can still incur round-off error when non-zero digits exceed the
+fixed precision.
+
+The effects of round-off error can be amplified by the addition or subtraction
+of nearly offsetting quantities resulting in loss of significance.  Knuth
+provides two instructive examples where rounded floating point arithmetic with
+insufficient precision causes the breakdown of the associative and
+distributive properties of addition:
+
+\begin{verbatim}
+# Examples from Seminumerical Algorithms, Section 4.2.2.
+>>> from decimal import Decimal, getcontext
+>>> getcontext().prec = 8
+
+>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
+>>> (u + v) + w
+Decimal("9.5111111")
+>>> u + (v + w)
+Decimal("10")
+
+>>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
+>>> (u*v) + (u*w)
+Decimal("0.01")
+>>> u * (v+w)
+Decimal("0.0060000")
+\end{verbatim}
+
+The \module{decimal} module makes it possible to restore the identities
+by expanding the precision sufficiently to avoid loss of significance:
+
+\begin{verbatim}
+>>> getcontext().prec = 20
+>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
+>>> (u + v) + w
+Decimal("9.51111111")
+>>> u + (v + w)
+Decimal("9.51111111")
+>>> 
+>>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
+>>> (u*v) + (u*w)
+Decimal("0.0060000")
+>>> u * (v+w)
+Decimal("0.0060000")
+\end{verbatim}
+
+\subsubsection{Special values}
+
+The number system for the \module{decimal} module provides special
+values including \constant{NaN}, \constant{sNaN}, \constant{-Infinity},
+\constant{Infinity}, and two zeroes, \constant{+0} and \constant{-0}.
+
+Infinities can be constructed directly with:  \code{Decimal('Infinity')}. Also,
+they can arise from dividing by zero when the \exception{DivisionByZero}
+signal is not trapped.  Likewise, when the \exception{Overflow} signal is not
+trapped, infinity can result from rounding beyond the limits of the largest
+representable number.
+
+The infinities are signed (affine) and can be used in arithmetic operations
+where they get treated as very large, indeterminate numbers.  For instance,
+adding a constant to infinity gives another infinite result.
+
+Some operations are indeterminate and return \constant{NaN}, or if the
+\exception{InvalidOperation} signal is trapped, raise an exception.  For
+example, \code{0/0} returns \constant{NaN} which means ``not a number''.  This
+variety of \constant{NaN} is quiet and, once created, will flow through other
+computations always resulting in another \constant{NaN}.  This behavior can be
+useful for a series of computations that occasionally have missing inputs ---
+it allows the calculation to proceed while flagging specific results as
+invalid.     
+
+A variant is \constant{sNaN} which signals rather than remaining quiet
+after every operation.  This is a useful return value when an invalid
+result needs to interrupt a calculation for special handling.
+
+The signed zeros can result from calculations that underflow.
+They keep the sign that would have resulted if the calculation had
+been carried out to greater precision.  Since their magnitude is
+zero, both positive and negative zeros are treated as equal and their
+sign is informational.
+
+In addition to the two signed zeros which are distinct yet equal,
+there are various representations of zero with differing precisions
+yet equivalent in value.  This takes a bit of getting used to.  For
+an eye accustomed to normalized floating point representations, it
+is not immediately obvious that the following calculation returns
+a value equal to zero:          
+
+\begin{verbatim}
+>>> 1 / Decimal('Infinity')
+Decimal("0E-1000000026")
+\end{verbatim}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Working with threads \label{decimal-threads}}
+
+The \function{getcontext()} function accesses a different \class{Context}
+object for each thread.  Having separate thread contexts means that threads
+may make changes (such as \code{getcontext.prec=10}) without interfering with
+other threads.
+
+Likewise, the \function{setcontext()} function automatically assigns its target
+to the current thread.
+
+If \function{setcontext()} has not been called before \function{getcontext()},
+then \function{getcontext()} will automatically create a new context for use
+in the current thread.
+
+The new context is copied from a prototype context called
+\var{DefaultContext}. To control the defaults so that each thread will use the
+same values throughout the application, directly modify the
+\var{DefaultContext} object. This should be done \emph{before} any threads are
+started so that there won't be a race condition between threads calling
+\function{getcontext()}. For example:
+
+\begin{verbatim}
+# Set applicationwide defaults for all threads about to be launched
+DefaultContext.prec = 12
+DefaultContext.rounding = ROUND_DOWN
+DefaultContext.traps = ExtendedContext.traps.copy()
+DefaultContext.traps[InvalidOperation] = 1
+setcontext(DefaultContext)
+
+# Afterwards, the threads can be started
+t1.start()
+t2.start()
+t3.start()
+ . . .
+\end{verbatim}
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Recipes \label{decimal-recipes}}
+
+Here are a few recipes that serve as utility functions and that demonstrate
+ways to work with the \class{Decimal} class:
+
+\begin{verbatim}
+def moneyfmt(value, places=2, curr='', sep=',', dp='.',
+             pos='', neg='-', trailneg=''):
+    """Convert Decimal to a money formatted string.
+
+    places:  required number of places after the decimal point
+    curr:    optional currency symbol before the sign (may be blank)
+    sep:     optional grouping separator (comma, period, space, or blank)
+    dp:      decimal point indicator (comma or period)
+             only specify as blank when places is zero
+    pos:     optional sign for positive numbers: '+', space or blank
+    neg:     optional sign for negative numbers: '-', '(', space or blank
+    trailneg:optional trailing minus indicator:  '-', ')', space or blank
+
+    >>> d = Decimal('-1234567.8901')
+    >>> moneyfmt(d, curr='$')
+    '-$1,234,567.89'
+    >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')
+    '1.234.568-'
+    >>> moneyfmt(d, curr='$', neg='(', trailneg=')')
+    '($1,234,567.89)'
+    >>> moneyfmt(Decimal(123456789), sep=' ')
+    '123 456 789.00'
+    >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')
+    '<.02>'
+
+    """
+    q = Decimal((0, (1,), -places))    # 2 places --> '0.01'
+    sign, digits, exp = value.quantize(q).as_tuple()
+    assert exp == -places    
+    result = []
+    digits = map(str, digits)
+    build, next = result.append, digits.pop
+    if sign:
+        build(trailneg)
+    for i in range(places):
+        if digits:
+            build(next())
+        else:
+            build('0')
+    build(dp)
+    i = 0
+    while digits:
+        build(next())
+        i += 1
+        if i == 3 and digits:
+            i = 0
+            build(sep)
+    build(curr)
+    if sign:
+        build(neg)
+    else:
+        build(pos)
+    result.reverse()
+    return ''.join(result)
+
+def pi():
+    """Compute Pi to the current precision.
+
+    >>> print pi()
+    3.141592653589793238462643383
+    
+    """
+    getcontext().prec += 2  # extra digits for intermediate steps
+    three = Decimal(3)      # substitute "three=3.0" for regular floats
+    lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24
+    while s != lasts:
+        lasts = s
+        n, na = n+na, na+8
+        d, da = d+da, da+32
+        t = (t * n) / d
+        s += t
+    getcontext().prec -= 2
+    return +s               # unary plus applies the new precision
+
+def exp(x):
+    """Return e raised to the power of x.  Result type matches input type.
+
+    >>> print exp(Decimal(1))
+    2.718281828459045235360287471
+    >>> print exp(Decimal(2))
+    7.389056098930650227230427461
+    >>> print exp(2.0)
+    7.38905609893
+    >>> print exp(2+0j)
+    (7.38905609893+0j)
+    
+    """
+    getcontext().prec += 2
+    i, lasts, s, fact, num = 0, 0, 1, 1, 1
+    while s != lasts:
+        lasts = s    
+        i += 1
+        fact *= i
+        num *= x     
+        s += num / fact   
+    getcontext().prec -= 2        
+    return +s
+
+def cos(x):
+    """Return the cosine of x as measured in radians.
+
+    >>> print cos(Decimal('0.5'))
+    0.8775825618903727161162815826
+    >>> print cos(0.5)
+    0.87758256189
+    >>> print cos(0.5+0j)
+    (0.87758256189+0j)
+    
+    """
+    getcontext().prec += 2
+    i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1
+    while s != lasts:
+        lasts = s    
+        i += 2
+        fact *= i * (i-1)
+        num *= x * x
+        sign *= -1
+        s += num / fact * sign 
+    getcontext().prec -= 2        
+    return +s
+
+def sin(x):
+    """Return the sine of x as measured in radians.
+
+    >>> print sin(Decimal('0.5'))
+    0.4794255386042030002732879352
+    >>> print sin(0.5)
+    0.479425538604
+    >>> print sin(0.5+0j)
+    (0.479425538604+0j)
+    
+    """
+    getcontext().prec += 2
+    i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1
+    while s != lasts:
+        lasts = s    
+        i += 2
+        fact *= i * (i-1)
+        num *= x * x
+        sign *= -1
+        s += num / fact * sign 
+    getcontext().prec -= 2        
+    return +s
+
+\end{verbatim}                                             
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Decimal FAQ \label{decimal-faq}}
+
+Q.  It is cumbersome to type \code{decimal.Decimal('1234.5')}.  Is there a way
+to minimize typing when using the interactive interpreter?
+
+A.  Some users abbreviate the constructor to just a single letter:
+
+\begin{verbatim}
+>>> D = decimal.Decimal
+>>> D('1.23') + D('3.45')
+Decimal("4.68")
+\end{verbatim}
+
+
+Q.  In a fixed-point application with two decimal places, some inputs
+have many places and need to be rounded.  Others are not supposed to have
+excess digits and need to be validated.  What methods should be used?
+
+A.  The \method{quantize()} method rounds to a fixed number of decimal places.
+If the \constant{Inexact} trap is set, it is also useful for validation:
+
+\begin{verbatim}
+>>> TWOPLACES = Decimal(10) ** -2       # same as Decimal('0.01')
+
+>>> # Round to two places
+>>> Decimal("3.214").quantize(TWOPLACES)
+Decimal("3.21")
+
+>>> # Validate that a number does not exceed two places 
+>>> Decimal("3.21").quantize(TWOPLACES, context=Context(traps=[Inexact]))
+Decimal("3.21")
+
+>>> Decimal("3.214").quantize(TWOPLACES, context=Context(traps=[Inexact]))
+Traceback (most recent call last):
+   ...
+Inexact: Changed in rounding
+\end{verbatim}
+
+
+Q.  Once I have valid two place inputs, how do I maintain that invariant
+throughout an application?
+
+A.  Some operations like addition and subtraction automatically preserve fixed
+point.  Others, like multiplication and division, change the number of decimal
+places and need to be followed-up with a \method{quantize()} step.
+
+
+Q.  There are many ways to express the same value.  The numbers
+\constant{200}, \constant{200.000}, \constant{2E2}, and \constant{.02E+4} all
+have the same value at various precisions. Is there a way to transform them to
+a single recognizable canonical value?
+
+A.  The \method{normalize()} method maps all equivalent values to a single
+representative:
+
+\begin{verbatim}
+>>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
+>>> [v.normalize() for v in values]
+[Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2")]
+\end{verbatim}
+
+
+Q.  Some decimal values always print with exponential notation.  Is there
+a way to get a non-exponential representation?
+
+A.  For some values, exponential notation is the only way to express
+the number of significant places in the coefficient.  For example,
+expressing \constant{5.0E+3} as \constant{5000} keeps the value
+constant but cannot show the original's two-place significance.
+
+
+Q.  Is there a way to convert a regular float to a \class{Decimal}?
+
+A.  Yes, all binary floating point numbers can be exactly expressed as a
+Decimal.  An exact conversion may take more precision than intuition would
+suggest, so trapping \constant{Inexact} will signal a need for more precision:
+
+\begin{verbatim}
+def floatToDecimal(f):
+    "Convert a floating point number to a Decimal with no loss of information"
+    # Transform (exactly) a float to a mantissa (0.5 <= abs(m) < 1.0) and an
+    # exponent.  Double the mantissa until it is an integer.  Use the integer
+    # mantissa and exponent to compute an equivalent Decimal.  If this cannot
+    # be done exactly, then retry with more precision.
+
+    mantissa, exponent = math.frexp(f)
+    while mantissa != int(mantissa):
+        mantissa *= 2.0
+        exponent -= 1
+    mantissa = int(mantissa)
+
+    oldcontext = getcontext()
+    setcontext(Context(traps=[Inexact]))
+    try:
+        while True:
+            try:
+               return mantissa * Decimal(2) ** exponent
+            except Inexact:
+                getcontext().prec += 1
+    finally:
+        setcontext(oldcontext)
+\end{verbatim}
+
+
+Q.  Why isn't the \function{floatToDecimal()} routine included in the module?
+
+A.  There is some question about whether it is advisable to mix binary and
+decimal floating point.  Also, its use requires some care to avoid the
+representation issues associated with binary floating point:
+
+\begin{verbatim}
+>>> floatToDecimal(1.1)
+Decimal("1.100000000000000088817841970012523233890533447265625")
+\end{verbatim}
+
+
+Q.  Within a complex calculation, how can I make sure that I haven't gotten a
+spurious result because of insufficient precision or rounding anomalies.
+
+A.  The decimal module makes it easy to test results.  A best practice is to
+re-run calculations using greater precision and with various rounding modes.
+Widely differing results indicate insufficient precision, rounding mode
+issues, ill-conditioned inputs, or a numerically unstable algorithm.
+
+
+Q.  I noticed that context precision is applied to the results of operations
+but not to the inputs.  Is there anything to watch out for when mixing
+values of different precisions?
+
+A.  Yes.  The principle is that all values are considered to be exact and so
+is the arithmetic on those values.  Only the results are rounded.  The
+advantage for inputs is that ``what you type is what you get''.  A
+disadvantage is that the results can look odd if you forget that the inputs
+haven't been rounded:
+
+\begin{verbatim}
+>>> getcontext().prec = 3
+>>> Decimal('3.104') + D('2.104')
+Decimal("5.21")
+>>> Decimal('3.104') + D('0.000') + D('2.104')
+Decimal("5.20")
+\end{verbatim}
+
+The solution is either to increase precision or to force rounding of inputs
+using the unary plus operation:
+
+\begin{verbatim}
+>>> getcontext().prec = 3
+>>> +Decimal('1.23456789')      # unary plus triggers rounding
+Decimal("1.23")
+\end{verbatim}
+
+Alternatively, inputs can be rounded upon creation using the
+\method{Context.create_decimal()} method:
+
+\begin{verbatim}
+>>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
+Decimal("1.2345")
+\end{verbatim}