prePEP: Decimal data type

Batista, Facundo FBatista at uniFON.com.ar
Fri Oct 31 13:36:38 EST 2003


Here I send it.

Suggestions and all kinds of recomendations are more than welcomed.

If it all goes ok, it'll be a PEP when I finish writing/modifying the code.

Thank you.

.	Facundo


------------------------------------------------------------------------

PEP: XXXX
Title: Decimal data type
Version: $Revision: 0.1 $
Last-Modified: $Date: 2003/10/31 15:25:00 $
Author: Facundo Batista <fbatista at unifon.com.ar>
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 17-Oct-2003
Python-Version: 2.3.3


Abstract
========

The idea is to have a Decimal data type, for every use where decimals are
needed but floating point is too inexact.

The Decimal data type should support the Python standard functions and
operations and must comply the decimal arithmetic ANSI standard X3.274-1996.


Rationale
=========

I must separate the requeriments in two sections.  The first is to comply
with the ANSI standard.  All the needings for this are specified in the
Mike Cowlishaw's work at http://www2.hursley.ibm.com/decimal/.  Cowlishaw's
also provided a **lot** of test cases.  The second section of requeriments
(standard Python functions support, usability, etc) are detailed in the
`Requirements`_ section.  

Here I'll include all the decisions made and why, and all the subjects still
being discussed.  The requirements will be numbered, to simplify discussion
on each point.

This work is based on code and test functions written by Eric Price, Aahz
and
Tim Peters.  Actually I'll work on the Decimal.py code in the sandbox (at
python/nondist/sandbox/decimal in SourceForge).  Some of the explanations of
this PEP are taken from the Cowlishaw's work.


Items In Discussion
-------------------

When in a case like ``Decimal op otherType`` (see point 12 in Requirements_
for details), what should happen?

    if otherType is an int or long:
    
        a. an exception is raised
        b. otherType is converted to Decimal 
        c. Decimal is converted to int or long (with ``int()`` or
``long()``)
        
    if otherType is a float:
    
        d. an exception is raised
        e. otherType is converted to Decimal (rounding? see next item in
           discussion)
        f. Decimal is converted to float (with ``float()``)
        
    if otherType is a string:
    
        g. an exception is raised
        h. otherType is converted to Decimal
        i. Decimal is converted to string (bizarre, huh?)


When passing floating point to the constructor, what should happen?

    j. ``Decimal(1.1) == Decimal('1.1')``
    k. ``Decimal(1.1) ==
Decimal('110000000000000008881784197001252...e-51')``


Requirements        
============

1. The syntax should be ``Decimal(value)``.

2. The value could be of the type:

       - another Decimal
       - int or long
       - float
       - string 

3. To exist a Context.  The context represents the user-selectable
parameters
   and rules which govern the results of arithmetic operations.  In the
   context the user defines:

       - what will happen with the exceptional conditions.
       - what precision will be used
       - what rounding method will be used

4. The Context must be omnipresent, meaning that changes to it affects all
   the current and future Decimal instances.

5. The exceptional conditions should be grouped into signals, which could be
   controlled individually.  The context should contain a flag and a
   trap-enabler for each signal.  The signals should be: clamped,
   division-by-zero, inexact, invalid-operation, overflow, rounded,
subnormal
   and underflow.

6. For each of the signals, the corresponding flag should be set to 1 when
   the signal occurs.  It is only reset to 0 by explicit user action.

7. For each of the signals, the corresponding trap-enabler will indicate
   which action is to be taken when the signal occurs.  If 0, a defined
   result should be supplied, and execution should continue.  If 1, the
   execution of the operation should end and an exception should be raised.

8. The precision (maximum number of significant digits that can result from
   an arithmetic operation) must be positive (greater than 0).

9. To have different kinds of rounding; you can choose the algorithm through
   context:
    
       - ``round-down``: (Round toward 0, truncate) The discarded digits are
         ignored; the result is unchanged::
          
             1.123 --> 1.12
             1.128 --> 1.12
             1.125 --> 1.12
             1.135 --> 1.13

       - ``round-half-up``: If the discarded digits represent greater than
or
         equal to half (0.5) then the result should be incremented by 1
         (rounded up); otherwise the discarded digits are ignored::
          
             1.123 --> 1.12
             1.128 --> 1.13
             1.125 --> 1.13
             1.135 --> 1.14

       - ``round-half-even``: If the discarded digits represent greater than
         half (0.5) then the result coefficient should be incremented by 1
         (rounded up); if they represent less than half, then the result is
         not adjusted (that is, the discarded digits are ignored); otherwise
         the result is unaltered if its rightmost digit is even, or
         incremented by 1 (rounded up) if its rightmost digit is odd (to
make
         an even digit)::
          
             1.123 --> 1.12
             1.128 --> 1.13
             1.125 --> 1.12
             1.135 --> 1.14

       - ``round-ceiling``: If all of the discarded digits are zero or if
the
         sign is negative the result is unchanged; otherwise, the result
         should be incremented by 1 (rounded up)::
          
             1.123 --> 1.13
             1.128 --> 1.13
             -1.123 --> -1.12
             -1.128 --> -1.12

       - ``round-floor``: If all of the discarded digits are zero or if the
         sign is positive the result is unchanged; otherwise, the absolute
         value of the result should be incremented by 1::

             1.123 --> 1.12
             1.128 --> 1.12
             -1.123 --> -1.13
             -1.128 --> -1.13

       - ``round-half-down``: If the discarded digits represent greater than
         half (0.5) then the result should be incremented by 1 (rounded up);
         otherwise the discarded digits are ignored::

             1.123 --> 1.12
             1.128 --> 1.13
             1.125 --> 1.12
             1.135 --> 1.13

       - ``round-up``: (Round away from 0) If all of the discarded digits
are
         zero the result is unchanged. Otherwise, the result should be
         incremented by 1 (rounded up)::

             1.123 --> 1.13
             1.128 --> 1.13
             1.125 --> 1.13
             1.135 --> 1.14

10. Strings with floats in engineering notation will be supported.

11. Calling repr() should do round trip, meaning that::
   
       m = Decimal(...)
       m == eval(repr(m))

12. To support the basic aritmetic (``+, -, *, /, //, **, %, divmod``) and
    comparison (``==, !=, <, >, <=, >=, cmp``) operators in the following
    cases:
   
       - Decimal op Decimal
       - Decimal op otherType
       - otherType op Decimal
       - Decimal op= Decimal
       - Decimal op= otherType
   
    Check `Items In Discussion`_ to see what types could OtherType be, and
    what happens in each case.
   
13. To support unary operators (``-, +, abs``).

14. To support the built-in methods:

        - min, max
        - float, int, long
        - str, repr
        - hash
        - copy, deepcopy
        - bool (0 is false, otherwise true)

15. To be immutable.


Reference Implementation
========================

To be included later:

    - code
    - test code
    - documentation


Copyright
=========

This document has been placed in the public domain.





More information about the Python-list mailing list